{"id":27233300,"url":"https://github.com/bgreni/kelvin","last_synced_at":"2026-02-08T03:32:33.873Z","repository":{"id":285680152,"uuid":"958970212","full_name":"bgreni/Kelvin","owner":"bgreni","description":"A powerful, type-safe dimensional analysis library in Mojo","archived":false,"fork":false,"pushed_at":"2025-07-04T03:00:34.000Z","size":298,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-04T04:18:26.558Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Mojo","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bgreni.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":"github:[bgreni]"},"created_at":"2025-04-02T03:59:53.000Z","updated_at":"2025-07-04T03:00:37.000Z","dependencies_parsed_at":"2025-04-24T18:35:23.410Z","dependency_job_id":"a156bee3-68b4-488a-a7db-fe916b332a7f","html_url":"https://github.com/bgreni/Kelvin","commit_stats":null,"previous_names":["bgreni/kelvin"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bgreni/Kelvin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreni%2FKelvin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreni%2FKelvin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreni%2FKelvin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreni%2FKelvin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bgreni","download_url":"https://codeload.github.com/bgreni/Kelvin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgreni%2FKelvin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268297331,"owners_count":24228123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-10T14:19:18.014Z","updated_at":"2026-02-08T03:32:33.840Z","avatar_url":"https://github.com/bgreni.png","language":"Mojo","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kelvin\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n![ci_badge](https://github.com/bgreni/Kelvin/actions/workflows/CI.yml/badge.svg)\n![CodeQL](https://github.com/bgreni/Kelvin/workflows/CodeQL/badge.svg)\n\nA powerful dimensional analysis library written in Mojo for all your scientific computing needs.\nHeavily inspired by [uom](https://docs.rs/uom/latest/uom/index.html).\n\n## Defining a Quantity\n\nTo define a specific unit, you simply need to create an comptime to `Quantity` with\nthe particular dimensions defined. Each dimension also requires a `Ratio` and a\nsuffix string. The ratio defines the relationship between it and the unitary amount.\nAll dimensions that do not exist for a given quantity are given `Dimension.Invalid`.\n\n```mojo\n# Base unit for time, `Second`\ncomptime Meter = Quantity[\n    Dimensions[\n        Dimension[1, Ratio.Unitary, \"m\"](), # Length\n        Dimension.Invalid, # Mass\n        Dimension.Invalid, # Time\n        Dimension.Invalid, # Electric current\n        Dimension.Invalid, # Temperature\n        Dimension.Invalid, # Substance Amount\n        Dimension.Invalid, # Luminosity\n        Angle.Invalid, # Angle\n    ](),\n    ...,\n]\n\n# Use Ratio.Kilo to create a `Kilometer`\ncomptime Kilometer = Quantity[\n    Dimensions[\n        Dimension[1, Ratio.Kilo, \"km\"](),\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Angle.Invalid,\n    ](),\n    ...,\n]\n\n# Quantity with a weird conversion ratio\ncomptime Mile = Quantity[\n    Dimensions[\n        Dimension[1, Ratio[1609344, 1000]().simplify(), \"mile\"](),\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Dimension.Invalid,\n        Angle.Invalid,\n    ](),\n    ...,\n]\n```\n\nWith these simple units defined, we can use arithmetic syntax on the `Dimensions`\nstruct to create derivative units very easily. Here we can define Velocity in\na single line of code.\n\n```mojo\ncomptime MetersPerSecond = Quantity[Meter.D / Second.D, ...,]\ncomptime MetersSquared = Quantity[Meter.D**2, ...,]\n\ncomptime kg = Kilogram.D\ncomptime m = Meter.D\ncomptime s = Second.D\ncomptime Newton = Quantity[kg * m * (s ** -2)]\n```\n\n`Quantity` uses the mojo builtin `SIMD` type, so users can also supply a vector width\nparameter after the DType.\n\n```mojo\ncomptime SIMDSeconds = Second[_, 4]\ncomptime SIMDMeter = Meter[_, 4]\nprint(SIMDMeter(40) / SIMDSeconds(10)) # [4.0, 4.0, 4.0, 4.0] m^1 s^-1\n```\n\n## Numerical Type\n\nQuantity accepts a `DType` parameter to define the numerical type and bitwidth\nof the underlying value. The default is `DType.float64`.\n\n```mojo\nvar s = Second(10.0) # Will be a float64\n\ncomptime IntSecond = Second[DType.int64]\nvar is = IntSecond(10) # will be int64\n```\n\n## Quantity Arithmetic\n\nSince the dimensions of a quantity are a dynamic part of the type system,\nwe can also do type-safe quantity multiplication and division. Though they\nmust have matching scale on all valid dimensions\n\n```mojo\nvar velocity: MetersPerSecond = Meter(10) / Second(2)\nvar area: MetersSquared = Meter(10) * Meter(20)\n\nvar a = Meter(10) * Mile(20) # Nope\n\n# Power must be an IntLiteral so it's compile time known\narea = Meter(10) ** 2\n```\n\nAddition and subtraction are only defined on matching quantities.\n\n```mojo\nvar a = Meter(10) + Meter(10)\nvar b = Meter(10) + Mile(20) # Nope\nvar c = Meter(10) + Second(10) # Nope\n```\n\nYou can also use scalar values for multiplication and division.\n\n```mojo\nvar m = Meter(10)\nm = m * 5\nm /= 5\n```\n\n## Quantity Conversions\n\nQuantities with matching dimensions, but different scale can be casted to one\nanother.\n\n```mojo\nvar m = Minute(cast_from=Second(600))\nvar s = Second(cast_from=m)\n```\n\n## Sharp Edges\n\n### Dimensions operations are unchecked\n\nDimensional type safety is only implemented at the `Quantity` level, due to\nthe usage of `@always_inline('builtin')` throughout `Dimensions, Dimension, Ratio and Angle`\nto keep compile times fast, and there is currently no way of adding additional contraints\nto methods that use that decorator. The result is expressions like these are erroneously allowed.\n\n```mojo\ncomptime BadUnit = Meter.D * Mile.D # Bad\n\nvar a = Meter(10) * Mile(10) # Reject properly due to using Quantity\n```\n\nYou are still protected from surprising behavior when doing actual calculations, but\ncare must be taken when defining new units.\n\n### Integer Rounding\n\nWhen using integer value representations, operations are subject to integer rounding\nrules. If precision is important, please use a float point representation\n\n```mojo\ncomptime IntSeconds = Second[DType.int64]\n\nvar a = IntSeconds(11) / IntSeconds(3) # returns IntSeconds(3)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgreni%2Fkelvin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbgreni%2Fkelvin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgreni%2Fkelvin/lists"}