nutils-units 0.1__tar.gz

nutils_units-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evalf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nutils_units-0.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: nutils-units
+Version: 0.1
+Summary: Nutils Units: object wrappers for dimensional computations
+Author-email: Evalf <info@evalf.com>
+License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Nutils Units
+
+The nutils.units module provides a way to track dimensions of numerical objects
+and their change as the objects pass through functions. Its purposes are
+twofold:
+
+1. Numerical type checking, safeguarding against such mistakes as adding two
+   objects of different dimensions together.
+2. Unit consistency, ensuring that different metric systems can coexist without
+   crashing into Mars.
+
+Units offers three API levels: core, metric and typing, with each building on
+top of the former.
+
+## Core
+
+The core API offers the `Monomial` class, which wraps an object to assign it
+physical dimensions. A dimension is identified by a string, such as "L" for
+length. By wrapping the unit float we define the reference length for our
+calculations to be one meter.
+
+```python
+>>> from nutils.units.core import Monomial
+>>> meter = Monomial(1., "L")
+
+```
+
+Once the initial unit is seeded, we can build on it to define derived units:
+
+```python
+>>> inch = meter * 0.0254
+
+```
+
+This demonstrates that `Monomial` objects support numerical manipulation such
+as multiplication. These manipulations extend to (supported) external packages
+such as numpy:
+
+```python
+>>> import numpy as np
+>>> v1 = np.array([1, -2]) * meter
+>>> v2 = np.array([3, 1]) * inch
+>>> array = np.stack([v1, v2])
+>>> np.linalg.det(array)
+np.float64(0.17779999999999999)[L2]
+
+```
+
+The [L2] in the string representation indicates that the result has dimension
+length squared, i.e. area. The value before it is the representation of the
+wrapped object, but its value is shielded by the wrapper. The wrapper falls
+away when an operation yields a dimensionless result, for instance by dividing
+out a unit:
+
+```python
+>>> array / meter
+array([[ 1.    , -2.    ],
+       [ 0.0762,  0.0254]])
+
+```
+
+Crucially, dimensionless results do not depend on the definition of our
+reference lengths, as any scaling cancels out by definition. We could have
+defined our meter to be `Monomial(np.pi, "L")` instead and still obtained the
+same result up to rounding errors. The numerical value of the reference length
+is merely a conduit for the internal manipulations.
+
+## Metric
+
+The metric API adds support for units via the `parse` function. This returns a
+`UMonomial` object that has access to a predefined set of units, using the SI
+base units as internal reference measures.
+
+```python
+>>> from nutils.units.metric import parse
+>>> length = parse('2cm')
+>>> width = parse('3.5in')
+>>> force = parse('5N')
+
+```
+
+We can then manipulate the `UMonomial` objects as before.
+
+```
+>>> area = length * width
+>>> pressure = force / area
+>>> pressure / 'kPa'
+2.8121484814398205
+
+```
+
+Note that in dividing out the unit we omitted `parse`, which is a convenience
+shorthand for this precise situation. For added convenience, the `UMonomial`
+class also supports direct string formatting of the wrapped value.
+
+```python
+>>> f'pressure: {pressure:.1kPa}'
+'pressure: 2.8kPa'
+
+```
+
+The units registry is an append-only state machine that is part of the metric
+module. Additional units can be added if necessary via the `units.register`
+function.
+
+```python
+>>> from nutils.units.metric import units
+>>> units.register("lbf", parse("4.448222N"), prefix="")
+>>> units.register("psi", parse("lbf/in2"), prefix="")
+>>> f'pressure: {pressure:.1psi}'
+'pressure: 0.4psi'
+
+```
+
+## Typing
+
+The typing API adds specific types for scalar quantities.
+
+```python
+>>> from nutils.units.typing import Length, Time, Velocity
+>>> Velocity('.4km/h')
+Quantity[L/T](.4km/h)
+
+```
+
+The `Quantity` types function similarly to `parse`, with two differences: 1.
+the object reduces back to its original string argument, with potential uses
+for object introspection, and 2. it protects against using wrong units.
+
+```python
+>>> Velocity('.4km/g')
+Traceback (most recent call last):
+    ...
+nutils.units.error.DimensionError: cannot parse .4km/g as L/T
+
+```
+
+Derived quantities can be formed by operating directly on the types:
+
+```python
+>>> Velocity == Length / Time
+True
+
+```
+
+The quantity types can be used as function annotations for general readability
+a for the potential aid external introspection tools.
+
+```python
+>>> def distance(velocity: Velocity, time: Time):
+...     return velocity * time
+
+```
+
+Note that the return value of this function is not a `Length` but a general
+`UMonomial`, as the result of a numerical operation does not have an inherent
+unit.

nutils_units-0.1/README.md

@@ -0,0 +1,157 @@
+# Nutils Units
+
+The nutils.units module provides a way to track dimensions of numerical objects
+and their change as the objects pass through functions. Its purposes are
+twofold:
+
+1. Numerical type checking, safeguarding against such mistakes as adding two
+   objects of different dimensions together.
+2. Unit consistency, ensuring that different metric systems can coexist without
+   crashing into Mars.
+
+Units offers three API levels: core, metric and typing, with each building on
+top of the former.
+
+## Core
+
+The core API offers the `Monomial` class, which wraps an object to assign it
+physical dimensions. A dimension is identified by a string, such as "L" for
+length. By wrapping the unit float we define the reference length for our
+calculations to be one meter.
+
+```python
+>>> from nutils.units.core import Monomial
+>>> meter = Monomial(1., "L")
+
+```
+
+Once the initial unit is seeded, we can build on it to define derived units:
+
+```python
+>>> inch = meter * 0.0254
+
+```
+
+This demonstrates that `Monomial` objects support numerical manipulation such
+as multiplication. These manipulations extend to (supported) external packages
+such as numpy:
+
+```python
+>>> import numpy as np
+>>> v1 = np.array([1, -2]) * meter
+>>> v2 = np.array([3, 1]) * inch
+>>> array = np.stack([v1, v2])
+>>> np.linalg.det(array)
+np.float64(0.17779999999999999)[L2]
+
+```
+
+The [L2] in the string representation indicates that the result has dimension
+length squared, i.e. area. The value before it is the representation of the
+wrapped object, but its value is shielded by the wrapper. The wrapper falls
+away when an operation yields a dimensionless result, for instance by dividing
+out a unit:
+
+```python
+>>> array / meter
+array([[ 1.    , -2.    ],
+       [ 0.0762,  0.0254]])
+
+```
+
+Crucially, dimensionless results do not depend on the definition of our
+reference lengths, as any scaling cancels out by definition. We could have
+defined our meter to be `Monomial(np.pi, "L")` instead and still obtained the
+same result up to rounding errors. The numerical value of the reference length
+is merely a conduit for the internal manipulations.
+
+## Metric
+
+The metric API adds support for units via the `parse` function. This returns a
+`UMonomial` object that has access to a predefined set of units, using the SI
+base units as internal reference measures.
+
+```python
+>>> from nutils.units.metric import parse
+>>> length = parse('2cm')
+>>> width = parse('3.5in')
+>>> force = parse('5N')
+
+```
+
+We can then manipulate the `UMonomial` objects as before.
+
+```
+>>> area = length * width
+>>> pressure = force / area
+>>> pressure / 'kPa'
+2.8121484814398205
+
+```
+
+Note that in dividing out the unit we omitted `parse`, which is a convenience
+shorthand for this precise situation. For added convenience, the `UMonomial`
+class also supports direct string formatting of the wrapped value.
+
+```python
+>>> f'pressure: {pressure:.1kPa}'
+'pressure: 2.8kPa'
+
+```
+
+The units registry is an append-only state machine that is part of the metric
+module. Additional units can be added if necessary via the `units.register`
+function.
+
+```python
+>>> from nutils.units.metric import units
+>>> units.register("lbf", parse("4.448222N"), prefix="")
+>>> units.register("psi", parse("lbf/in2"), prefix="")
+>>> f'pressure: {pressure:.1psi}'
+'pressure: 0.4psi'
+
+```
+
+## Typing
+
+The typing API adds specific types for scalar quantities.
+
+```python
+>>> from nutils.units.typing import Length, Time, Velocity
+>>> Velocity('.4km/h')
+Quantity[L/T](.4km/h)
+
+```
+
+The `Quantity` types function similarly to `parse`, with two differences: 1.
+the object reduces back to its original string argument, with potential uses
+for object introspection, and 2. it protects against using wrong units.
+
+```python
+>>> Velocity('.4km/g')
+Traceback (most recent call last):
+    ...
+nutils.units.error.DimensionError: cannot parse .4km/g as L/T
+
+```
+
+Derived quantities can be formed by operating directly on the types:
+
+```python
+>>> Velocity == Length / Time
+True
+
+```
+
+The quantity types can be used as function annotations for general readability
+a for the potential aid external introspection tools.
+
+```python
+>>> def distance(velocity: Velocity, time: Time):
+...     return velocity * time
+
+```
+
+Note that the return value of this function is not a `Length` but a general
+`UMonomial`, as the result of a numerical operation does not have an inherent
+unit.

nutils_units-0.1/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "nutils-units"
+readme = "README.md"
+authors = [
+    { name = "Evalf", email = "info@evalf.com" },
+]
+requires-python = '>=3.10'
+description = "Nutils Units: object wrappers for dimensional computations"
+license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
+dynamic = ["version"]
+classifiers = [
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "nutils.units.__version__"}
+readme = {file = ["README"]}

nutils_units-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nutils_units-0.1/src/nutils/units/__init__.py

@@ -0,0 +1,3 @@
+"Nutils Units: object wrappers for dimensional computations"
+
+__version__ = "0.1"

nutils_units-0.1/src/nutils/units/_dispatch.py

@@ -0,0 +1,70 @@
+from inspect import getmodule
+from functools import partial, partialmethod
+
+
+class DispatchTable(dict):
+    """Table of handler functions.
+
+    The dispatch table is a dictionary that maps the fully qualified name of a
+    callable to a handler function that should be called with the callable as
+    the first positional argument, followed by its arguments. Handlers are
+    registered via the .register method:
+
+    >>> dispatch_table = DispatchTable()
+    >>> @dispatch_table.register("math.sqrt")
+    ... def handle_root(op, x):
+    ...     return str(op(float(x)))
+
+    In this (rather contrived) example we create a handler that extends the
+    math.sqrt function to operate on string arguments. To obtain the relevant
+    handler we use the .bind method:
+
+    >>> import math
+    >>> f = dispatch_table.bind(math.sqrt)
+    >>> f("4")
+    '2.0'
+
+    Note that by registering the fully qualified name of the callable, rather
+    than the callable itself, we are able to prepare a table for any number of
+    external functions without ever importing any third party modules.
+    """
+
+    def register(self, qualname):
+        return partial(_setitem_retvalue, self, qualname)
+
+    def bind(self, func):
+        return partial(self[get_qualname(func)], func)
+
+    def bind_method(self, func):
+        return partialmethod(self.bind(func))
+
+    def bind_method_and_reverse(self, func):
+        bound = self.bind(func)
+        return partialmethod(bound), partialmethod(_swap, bound)
+
+    def call_or_notimp(self, func, args, kwargs):
+        try:
+            bound = self.bind(func)
+        except KeyError:
+            return NotImplemented
+        else:
+            return bound(*args, **kwargs)
+
+
+def get_qualname(func):
+    """Get the qualified domain name of a callable.
+
+    This function returns the string to be used in DispatchTable.register to
+    identify a callable.
+    """
+
+    return getmodule(func).__name__ + "." + func.__qualname__
+
+
+def _setitem_retvalue(d, k, v):
+    d[k] = v
+    return v
+
+
+def _swap(self, func, arg):
+    return func(arg, self)

nutils_units-0.1/src/nutils/units/_powers.py

@@ -0,0 +1,157 @@
+from fractions import Fraction
+
+
+class Powers:
+    """Immutable counter with fractional values.
+
+    This class is similar to `collections.Counter`, with two key differences:
+
+    - Values are instances of `fractions.Fraction`;
+    - The collection is immutable.
+
+    A `Powers` instance can be created from a string, which sets its counter
+    equal to 1:
+    >>> Powers("A")
+    Powers(A)
+
+    We can then use multiplication and division to scale all counts:
+    >>> Powers("A") * 3
+    Powers(A3)
+
+    And we can use addition and subtraction to combine powers:
+    >>> Powers("A") * 3 + Powers("B") / 2
+    Powers(A3*B1/2)
+
+    Note that the different items are separated by a `*`. Note what happens
+    when we reach a negative count:
+    >>> Powers("A") * 3 - Powers("B") * 2
+    Powers(A3/B2)
+
+    Rather than making the power negatve, we switch the `*` for a `/`. This
+    notation reflects the interpretation of counts as monomial powers.
+
+    When we created a power from a string before, we actually made use of the
+    fact that we can parse back the entire string representation now
+    established:
+    >>> Powers("A3/B2")
+    Powers(A3/B2)
+
+    Alternatively we can create it from a dictionary:
+    >>> Powers({"A": Fraction(3), "B": Fraction(-2)})
+    Powers(A3/B2)
+
+    Or even from an existing powers object:
+    >>> Powers(Powers("A"))
+    Powers(A)
+    """
+
+    def __init__(self, d):
+        if isinstance(d, Powers):
+            self.__d = d.__d
+        elif isinstance(d, str):
+            self.__d = _split_factors(d)
+        elif isinstance(d, dict) and all(
+            isinstance(k, str) and isinstance(v, Fraction) for k, v in d.items()
+        ):
+            self.__d = {k: v for k, v in d.items() if v}
+        else:
+            raise ValueError(f"cannot create Powers from {d!r}")
+
+    def __hash__(self):
+        return hash(tuple(sorted(self.__d.items())))
+
+    def __eq__(self, other):
+        return self is other or isinstance(other, Powers) and self.__d == other.__d
+
+    def __add__(self, other):
+        if not isinstance(other, Powers):
+            return NotImplemented
+        d = self.__d.copy()
+        for name, n in other.__d.items():
+            d[name] = d.get(name, 0) + n
+        return Powers(d)
+
+    def __sub__(self, other):
+        if not isinstance(other, Powers):
+            return NotImplemented
+        d = self.__d.copy()
+        for name, n in other.__d.items():
+            d[name] = d.get(name, 0) - n
+        return Powers(d)
+
+    def __mul__(self, other):
+        if isinstance(other, float):
+            tmp = Fraction(other).limit_denominator()
+            if other == float(tmp):
+                other = tmp
+        if not isinstance(other, (int, Fraction)):
+            try:
+                other = other.__index__()
+            except Exception:
+                return NotImplemented
+        return Powers({name: n * other for name, n in self.__d.items()})
+
+    def __truediv__(self, other):
+        if isinstance(other, float):
+            tmp = Fraction(other).limit_denominator()
+            if other == float(tmp):
+                other = tmp
+        if not isinstance(other, (int, Fraction)):
+            return NotImplemented
+        return Powers({name: n / other for name, n in self.__d.items()})
+
+    def __neg__(self):
+        return Powers({name: -n for name, n in self.__d.items()})
+
+    def __bool__(self):
+        return bool(self.__d)
+
+    def items(self):
+        return self.__d.items()
+
+    def __str__(self):
+        return _join_factors(self.__d)
+
+    def __repr__(self):
+        return f"Powers({self})"
+
+
+def _split_factors(s):
+    items = []
+    for factors in s.split("*"):
+        numer, *denoms = factors.split("/")
+        if numer:
+            base = numer.rstrip("0123456789")
+            num = Fraction(int(numer[len(base) :] or 1))
+            items.append((base, num))
+        elif items:  # s contains "*/"
+            raise ValueError
+        for denom in denoms:
+            base = denom.rstrip("0123456789")
+            if base:
+                num = -Fraction(int(denom[len(base) :] or 1))
+            else:  # fractional power
+                base, num = items.pop()
+                num /= int(denom)
+            items.append((base, num))
+    return dict(items)
+
+
+def _join_factors(factors):
+    s = ""
+    for base, power in sorted(
+        factors.items(), key=lambda item: item[::-1], reverse=True
+    ):
+        if power < 0:
+            power = -power
+            s += "/"
+        else:
+            s += "*"
+        s += base
+        if power != 1:
+            s += (
+                str(power)
+                if power.denominator == 1
+                else f"{power.numerator}/{power.denominator}"
+            )
+    return s.lstrip("*")

nutils_units-0.1/src/nutils/units/_units.py

@@ -0,0 +1,58 @@
+PREFIX = dict(
+    Y=1e24,
+    Z=1e21,
+    E=1e18,
+    P=1e15,
+    T=1e12,
+    G=1e9,
+    M=1e6,
+    k=1e3,
+    h=1e2,
+    d=1e-1,
+    c=1e-2,
+    m=1e-3,
+    μ=1e-6,
+    n=1e-9,
+    p=1e-12,
+    f=1e-15,
+    a=1e-18,
+    z=1e-21,
+    y=1e-24,
+)
+
+
+class Units:
+    """Registry of numerical values.
+
+    The Units object is a registry of numerical values. Values can be assigned
+    under any name that is not previously used, and cannot be removed.
+
+    >>> u = Units()
+    >>> u.register("m", 5.)
+    >>> u.m
+    5.0
+
+    Intended for units, the registry by default adds all metric prefixes with
+    approprately scaled values. If "m" represents the number 5, then "km"
+    represents 1000 times that number:
+
+    >>> u.km
+    5000.0
+
+    Attempting to redefine a previously assigned value results in an error and
+    leaves the registry unmodified.
+
+    >>> u.register("am", 10.)
+    Traceback (most recent call last):
+      ...
+    ValueError: registration failed: unit collides with 'am'
+    """
+
+    def register(self, name, value, prefix=tuple(PREFIX)):
+        d = self.__dict__
+        new = [(name, value)]
+        new.extend((p + name, value * PREFIX[p]) for p in prefix)
+        collisions = ", ".join(repr(s) for s, v in new if s in d and d[s] != v)
+        if collisions:
+            raise ValueError(f"registration failed: unit collides with {collisions}")
+        d.update(new)