ucon 0.5.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

ucon/units.py

@@ -28,7 +28,7 @@ Notes
 The design allows for future extensibility: users can register their own units,
 systems, or aliases dynamically, without modifying the core definitions.
 """
-from ucon.core import Dimension, Unit
+from ucon.core import Dimension, Unit, UnitSystem
 
 
 none = Unit()
@@ -49,6 +49,7 @@ joule_per_kelvin = Unit(name='joule_per_kelvin', dimension=Dimension.entropy, al
 kelvin = Unit(name='kelvin', dimension=Dimension.temperature, aliases=('K',))
 kilogram = Unit(name='kilogram', dimension=Dimension.mass, aliases=('kg',))
 liter = Unit(name='liter', dimension=Dimension.volume, aliases=('L', 'l'))
+candela = Unit(name='candela', dimension=Dimension.luminous_intensity, aliases=('cd',))
 lumen = Unit(name='lumen', dimension=Dimension.luminous_intensity, aliases=('lm',))
 lux = Unit(name='lux', dimension=Dimension.illuminance, aliases=('lx',))
 meter = Unit(name='meter', dimension=Dimension.length, aliases=('m',))
@@ -141,6 +142,32 @@ basis_point = Unit(name='basis_point', dimension=Dimension.ratio, aliases=('bp',
 webers = weber
 
 
+# -- Predefined Unit Systems -----------------------------------------------
+si = UnitSystem(
+    name="SI",
+    bases={
+        Dimension.length: meter,
+        Dimension.mass: kilogram,
+        Dimension.time: second,
+        Dimension.temperature: kelvin,
+        Dimension.current: ampere,
+        Dimension.amount_of_substance: mole,
+        Dimension.luminous_intensity: candela,
+    }
+)
+
+imperial = UnitSystem(
+    name="Imperial",
+    bases={
+        Dimension.length: foot,
+        Dimension.mass: pound,
+        Dimension.time: second,
+        Dimension.temperature: fahrenheit,
+    }
+)
+# --------------------------------------------------------------------------
+
+
 def have(name: str) -> bool:
     assert name, "Must provide a unit name to check"
     assert isinstance(name, str), "Unit name must be a string"

{ucon-0.5.1.dist-info → ucon-0.5.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.5.1
+Version: 0.5.2
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -92,6 +92,9 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 | **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
 | **`Map`** hierarchy           | `ucon.maps`                             | Composable conversion morphisms: `LinearMap`, `AffineMap`, `ComposedMap`.                           | Defining conversion functions between units (e.g., meter→foot, celsius→kelvin).                                        |
 | **`ConversionGraph`**         | `ucon.graph`                            | Registry of unit conversion edges with BFS path composition.                                        | Converting between units via `Number.to(target)`; managing default and custom graphs.                                  |
+| **`UnitSystem`**              | `ucon.core`                             | Named mapping from dimensions to base units (e.g., SI, Imperial).                                   | Defining coherent unit systems; grouping base units by dimension.                                                      |
+| **`BasisTransform`**          | `ucon.core`                             | Matrix-based transformation between dimensional exponent spaces.                                    | Converting between incompatible dimensional structures; exact arithmetic with `Fraction`.                              |
+| **`RebasedUnit`**             | `ucon.core`                             | A unit rebased to another system's dimension, preserving provenance.                                | Cross-basis conversions; tracking original unit through basis changes.                                                 |
 | **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI, imperial, information, and derived units).                    | Quick access to standard physical units (`units.meter`, `units.foot`, `units.byte`, etc.).                             |
 
 ### Under the Hood
@@ -235,6 +238,83 @@ length_ft = length.to(units.foot)
 print(length_ft)  # <4.048... ± 0.0164... ft>
 ```
 
+Unit systems and basis transforms enable conversions between incompatible dimensional structures.
+This goes beyond simple unit conversion (meter → foot) into structural transformation:
+
+```python
+from fractions import Fraction
+from ucon import BasisTransform, Dimension, Unit, UnitSystem, units
+from ucon.graph import ConversionGraph
+from ucon.maps import LinearMap
+
+# The realm of Valdris has three fundamental dimensions:
+#   - Aether (A): magical energy substrate
+#   - Resonance (R): vibrational frequency of magic
+#   - Substance (S): physical matter
+#
+# These combine into SI dimensions via a transformation matrix:
+#
+#   | L |   | 2  0  0 |   | A |
+#   | M | = | 1  0  1 | × | R |
+#   | T |   |-2 -1  0 |   | S |
+#
+# Reading the columns:
+#   - 1 aether contributes: L², M, T⁻²  (energy-like)
+#   - 1 resonance contributes: T⁻¹      (frequency-like)
+#   - 1 substance contributes: M         (mass-like)
+
+# Fantasy base units
+mote = Unit(name='mote', dimension=Dimension.energy, aliases=('mt',))
+chime = Unit(name='chime', dimension=Dimension.frequency, aliases=('ch',))
+ite = Unit(name='ite', dimension=Dimension.mass, aliases=('it',))
+
+valdris = UnitSystem(
+    name="Valdris",
+    bases={
+        Dimension.energy: mote,
+        Dimension.frequency: chime,
+        Dimension.mass: ite,
+    }
+)
+
+# The basis transform encodes how Valdris dimensions compose into SI
+valdris_to_si = BasisTransform(
+    src=valdris,
+    dst=units.si,
+    src_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
+    dst_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
+    matrix=(
+        (2, 0, 0),    # energy: 2 × aether
+        (1, 0, 1),    # frequency: aether + substance
+        (-2, -1, 0),  # mass: -2×aether - resonance
+    ),
+)
+
+# Physical calibration: how many SI units per fantasy unit
+graph = ConversionGraph()
+graph.connect_systems(
+    basis_transform=valdris_to_si,
+    edges={
+        (mote, units.joule): LinearMap(42),           # 1 mote = 42 J
+        (chime, units.hertz): LinearMap(7),           # 1 chime = 7 Hz
+        (ite, units.kilogram): LinearMap(Fraction(1, 2)),  # 1 ite = 0.5 kg
+    }
+)
+
+# Game engine converts between physics systems
+energy_map = graph.convert(src=mote, dst=units.joule)
+energy_map(10)  # 420 joules from 10 motes
+
+# Inverse: display real-world values in game units
+joule_to_mote = graph.convert(src=units.joule, dst=mote)
+joule_to_mote(420)  # 10 motes
+
+# The transform is invertible with exact Fraction arithmetic
+valdris_to_si.is_invertible  # True
+```
+
+This enables fantasy game physics, or any field where the dimensional structure differs from SI.
+
 ---
 
 ## Roadmap Highlights
@@ -245,8 +325,9 @@ print(length_ft)  # <4.048... ± 0.0164... ft>
 | **0.4.x** | Conversion System | `ConversionGraph`, `Number.to()`, callable units | ✅ Complete |
 | **0.5.0** | Dimensionless Units | Pseudo-dimensions for angle, solid angle, ratio | ✅ Complete |
 | **0.5.x** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
-| **0.5.x** | Unit Systems | `BasisMap`, `UnitSystem` | 🚧 In Progress |
-| **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.5.x** | Unit Systems | `BasisTransform`, `UnitSystem`, cross-basis conversion | ✅ Complete |
+| **0.6.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.7.x** | NumPy Arrays | Vectorized conversion and arithmetic | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 

{ucon-0.5.1.dist-info → ucon-0.5.2.dist-info}/RECORD

@@ -1,24 +1,29 @@
 tests/ucon/__init__.py,sha256=9BAHYTs27Ed3VgqiMUH4XtVttAmOPgK0Zvj-dUNo7D8,119
 tests/ucon/test_algebra.py,sha256=NnoQOSMW8NJlOTnbr3M_5epvnDPXpVTgO21L2LcytRY,8503
+tests/ucon/test_basis_transform.py,sha256=P7ccr9wgDPCwCmsj4dceu3V0A72qFbTavjzm9kB3xP8,16710
 tests/ucon/test_core.py,sha256=bmwSRWPlhwossy5NJ9rcPWujFmzBBPOeZzPAzN1acFg,32631
 tests/ucon/test_default_graph_conversions.py,sha256=rkcDcSV1_kZeuPf4ModHDpgfkOPZS32xcKq7KPDRN-0,15760
 tests/ucon/test_dimensionless_units.py,sha256=K6BrIPOFL9IO_ksR8t_oJUXmjTgqBUzMdgaV-hZc52w,8410
+tests/ucon/test_graph_basis_transform.py,sha256=5-WglJaR1N_mJlqR6i8NuxLJ_FASqb5a8WoO_177smU,8249
 tests/ucon/test_quantity.py,sha256=md5nbmy0u2cFBdqNeu-ROhoj29vYrIlGm_AjlmCttgc,24519
+tests/ucon/test_rebased_unit.py,sha256=n2mksEYSJ8UJJXXwlgaLKg3THaf7_LKzWB7kwjoaXEU,5150
 tests/ucon/test_uncertainty.py,sha256=KkJw2dJR0EToxPpBN24x735jr9fv6a2myxjvhOH4MPU,9649
+tests/ucon/test_unit_system.py,sha256=gRc3fMvo9ded1tBUQWLKpcbpBepMAb7gPu8XvFzQZaM,5860
 tests/ucon/test_units.py,sha256=SILymDtDNDyxEhkYQubrfkakKCMexwEwjyHfhrkDrMI,869
+tests/ucon/test_vector_fraction.py,sha256=fTgxlV9aSP15sA4gATTXBzIDbtKXwWqG1Ip0o-V2B4Y,6369
 tests/ucon/conversion/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/ucon/conversion/test_graph.py,sha256=fs0aP6qNf8eE1uI7SoGSCW2XAkHYb7T9aaI-kzmO02c,16955
 tests/ucon/conversion/test_map.py,sha256=DVFQ3xwp16Nuy9EtZRjKlWbkXfRUcM1mOzFrS4HhOaw,13886
-ucon/__init__.py,sha256=jaFcNFZC5gxHKzM8OkS1pLxltp6ToLRVpuuhJQY9FKQ,2000
-ucon/algebra.py,sha256=4JiT_SHHep86Sv3tVkgKsRY95lBRASMkyH4vOUA-gfM,7459
-ucon/core.py,sha256=nuDmSuGiG3xUW_kRpOWu9FDhNmKE0aJPwpj30lMdrgo,49464
-ucon/graph.py,sha256=lPoYSvHNGBZxeZ-4dyZIu2OS5R1JTo0qPZ9wd0vg-s4,15566
+ucon/__init__.py,sha256=M_sijIUYPvU87Jtnq_O2X7TS4x9RW1LHZJ8bbm3gfk0,2255
+ucon/algebra.py,sha256=6QrPyD23L93XSrnIORcYEx2CLDv4WDcrh6H_hxeeOus,8668
+ucon/core.py,sha256=j2Xw73-Xuh0CkaUYEv5ljsxjt-XdthiH-EbqUBgG1a8,63139
+ucon/graph.py,sha256=Ec0Q2QiAGUm2RaxrKnpFHtwpNvTf4PYbvo62BWtGJG8,21159
 ucon/maps.py,sha256=tWP4ayYCEazJzf81EP1_fmtADhg18D1eHldudAMEY0U,5460
 ucon/quantity.py,sha256=GBxZ_96nocx-8F-usNWGbPvWHRhRgdZzqfH9Sx69iC4,465
-ucon/units.py,sha256=u1ILwGllzNiwGLadlg5jguKPyFV1u-CZSUMgUDWTen4,7509
-ucon-0.5.1.dist-info/licenses/LICENSE,sha256=LtimSYBSw1L_X6n1-VEdZRdwuROzPumrMUNX21asFuI,11356
-ucon-0.5.1.dist-info/licenses/NOTICE,sha256=bh4fBOItio3kM4hSNYhqfFpcaAvOoixjD7Du8im-sYA,1079
-ucon-0.5.1.dist-info/METADATA,sha256=dkjXacaxxZbFq9vIBfJJ-2koy03T9Ozf_nimaNm2mwQ,13554
-ucon-0.5.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-ucon-0.5.1.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
-ucon-0.5.1.dist-info/RECORD,,
+ucon/units.py,sha256=MWCJhicK6jQb71fREyW_HSfGFKL8KEQej2JnySL_MjE,8285
+ucon-0.5.2.dist-info/licenses/LICENSE,sha256=LtimSYBSw1L_X6n1-VEdZRdwuROzPumrMUNX21asFuI,11356
+ucon-0.5.2.dist-info/licenses/NOTICE,sha256=bh4fBOItio3kM4hSNYhqfFpcaAvOoixjD7Du8im-sYA,1079
+ucon-0.5.2.dist-info/METADATA,sha256=CTRgYp67awjnjy7ZzKL2opd81T2RK1feQ6AXMnXmSj4,17200
+ucon-0.5.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ucon-0.5.2.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
+ucon-0.5.2.dist-info/RECORD,,