ucon 0.3.3rc2__tar.gz → 0.3.5__tar.gz

ucon-0.3.5/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright © 2025 The Radiativity Company
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ucon-0.3.5/NOTICE

@@ -0,0 +1,28 @@
+ucon — A dimensional analysis and unit algebra library
+© 2025 The Radiativity Company
+
+Licensed under the Apache License, Version 2.0.
+You may not use this project except in compliance with the License.
+A copy of the License is included in the LICENSE file or at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+This NOTICE file is part of the ucon distribution.
+
+ucon implements:
+  • A compositional unit algebra (UnitFactor, UnitProduct, UnitForm)
+  • A dimension algebra based on vector-space operations
+  • Expression-level scale separation for unit provenance
+  • A foundation for ConversionGraph-based unit transformations
+
+Portions of this software may incorporate or depend upon
+third-party libraries. Attribution notices for those components,
+if required, are included here or in the accompanying documentation.
+
+The Radiativity Company retains all trademark rights to the names:
+  • "ucon"
+  • "The Radiativity Company"
+  • "Project Calico"
+
+This file is for attribution purposes only and does not modify
+the terms of the Apache License, Version 2.0.

{ucon-0.3.3rc2 → ucon-0.3.5}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.3rc2
+Version: 0.3.5
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
 Maintainer: Emmanuel I. Obi
 Maintainer-email: withtwoemms@gmail.com
-License: MIT
+License: Apache-2.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Software Development :: Build Tools
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: NOTICE
 Dynamic: author
 Dynamic: classifier
 Dynamic: description
@@ -54,8 +55,8 @@ Dynamic: summary
 It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
 
 - Dimensional analysis through `Number` and `Ratio`
-- Scale-aware arithmetic and conversions
-- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
+- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - A clean foundation for physics, chemistry, data modeling, and beyond
 
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -69,20 +70,22 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
-| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
-| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
-| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
-| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible units; representing physical quantities like 5 m/s.    |
-| **`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).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
+| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
+| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
+| **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
+| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
+| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
 
 ### Under the Hood
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -90,24 +93,22 @@ Python already has mature libraries for handling units and physical quantities
 
 | Library   | Focus                                                   | Limitation                                                                                                             |
 | --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn't inspectable or type-safe. |
 | **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
 | **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
 
 Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
 
-That’s the gap `ucon` fills.
+That's the gap `ucon` fills.
 
 It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
 This allows you to:
 - Represent dimensional meaning explicitly (`Dimension`, `Vector`);
 - Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
-- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
-- Serialize and validate measurements with Pydantic integration;
 - Extend the system with custom unit registries and conversion families.
 
 Where Pint, Unum, and SymPy focus on _how_ to compute with units,
-`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn't just track names: it enforces physics:
 ```python
 from ucon import Number, units
 
@@ -135,39 +136,50 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, Units, Ratio
+from ucon import Number, Scale, units
+from ucon.quantity import Ratio
 
 # Two milliliters of bromine
-two_mL_bromine = Number(unit=Units.liter, scale=Scale.milli, quantity=2)
+mL = Scale.milli * units.liter
+two_mL_bromine = Number(quantity=2, unit=mL)
 
 # Density of bromine: 3.119 g/mL
 bromine_density = Ratio(
-    numerator=Number(unit=Units.gram, quantity=3.119),
-    denominator=Number(unit=Units.liter, scale=Scale.milli),
+    numerator=Number(unit=units.gram, quantity=3.119),
+    denominator=Number(unit=mL),
 )
 
 # Multiply to find mass
-grams_bromine = two_mL_bromine * bromine_density
-print(grams_bromine)  # <6.238 gram>
+grams_bromine = bromine_density.evaluate() * two_mL_bromine
+print(grams_bromine)  # <6.238 g>
 ```
 
-Scale conversion is automatic and precise:
-
+Scale prefixes compose naturally:
 ```python
-grams_bromine.to(Scale.milli)  # <6238.0 milligram>
-grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
+mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
+
+print(km.shorthand)  # 'km'
+print(mg.shorthand)  # 'mg'
+
+# Scale arithmetic
+print(km.fold_scale())  # 1000.0
+print(mg.fold_scale())  # 0.001
 ```
 
+> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
+> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
+
 ---
 
 ## Roadmap Highlights
 
-| Version | Theme | Focus |
-|----------|-------|--------|
-| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
-| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
-| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
+| Version | Theme | Focus | Status |
+|----------|-------|--------|--------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 
@@ -180,13 +192,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (agains all supported python versions) before committing:
+Then run the full test suite (against all supported python versions) before committing:
 
 ```bash
 nox -s test
 ```
 ---
 
-> “If it can be measured, it can be represented.
+> "If it can be measured, it can be represented.
 If it can be represented, it can be validated.
-If it can be validated, it can be trusted.”
+If it can be validated, it can be trusted."

{ucon-0.3.3rc2 → ucon-0.3.5}/README.md

@@ -18,8 +18,8 @@
 It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
 
 - Dimensional analysis through `Number` and `Ratio`
-- Scale-aware arithmetic and conversions
-- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
+- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - A clean foundation for physics, chemistry, data modeling, and beyond
 
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -33,20 +33,22 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
-| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
-| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
-| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
-| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible units; representing physical quantities like 5 m/s.    |
-| **`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).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
+| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
+| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
+| **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
+| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
+| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
 
 ### Under the Hood
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -54,24 +56,22 @@ Python already has mature libraries for handling units and physical quantities
 
 | Library   | Focus                                                   | Limitation                                                                                                             |
 | --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn't inspectable or type-safe. |
 | **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
 | **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
 
 Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
 
-That’s the gap `ucon` fills.
+That's the gap `ucon` fills.
 
 It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
 This allows you to:
 - Represent dimensional meaning explicitly (`Dimension`, `Vector`);
 - Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
-- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
-- Serialize and validate measurements with Pydantic integration;
 - Extend the system with custom unit registries and conversion families.
 
 Where Pint, Unum, and SymPy focus on _how_ to compute with units,
-`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn't just track names: it enforces physics:
 ```python
 from ucon import Number, units
 
@@ -99,39 +99,50 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, Units, Ratio
+from ucon import Number, Scale, units
+from ucon.quantity import Ratio
 
 # Two milliliters of bromine
-two_mL_bromine = Number(unit=Units.liter, scale=Scale.milli, quantity=2)
+mL = Scale.milli * units.liter
+two_mL_bromine = Number(quantity=2, unit=mL)
 
 # Density of bromine: 3.119 g/mL
 bromine_density = Ratio(
-    numerator=Number(unit=Units.gram, quantity=3.119),
-    denominator=Number(unit=Units.liter, scale=Scale.milli),
+    numerator=Number(unit=units.gram, quantity=3.119),
+    denominator=Number(unit=mL),
 )
 
 # Multiply to find mass
-grams_bromine = two_mL_bromine * bromine_density
-print(grams_bromine)  # <6.238 gram>
+grams_bromine = bromine_density.evaluate() * two_mL_bromine
+print(grams_bromine)  # <6.238 g>
 ```
 
-Scale conversion is automatic and precise:
-
+Scale prefixes compose naturally:
 ```python
-grams_bromine.to(Scale.milli)  # <6238.0 milligram>
-grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
+mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
+
+print(km.shorthand)  # 'km'
+print(mg.shorthand)  # 'mg'
+
+# Scale arithmetic
+print(km.fold_scale())  # 1000.0
+print(mg.fold_scale())  # 0.001
 ```
 
+> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
+> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
+
 ---
 
 ## Roadmap Highlights
 
-| Version | Theme | Focus |
-|----------|-------|--------|
-| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
-| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
-| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
+| Version | Theme | Focus | Status |
+|----------|-------|--------|--------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 
@@ -144,13 +155,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (agains all supported python versions) before committing:
+Then run the full test suite (against all supported python versions) before committing:
 
 ```bash
 nox -s test
 ```
 ---
 
-> “If it can be measured, it can be represented.
+> "If it can be measured, it can be represented.
 If it can be represented, it can be validated.
-If it can be validated, it can be trusted.”
+If it can be validated, it can be trusted."