unitx 0.13.0__tar.gz → 0.13.2__tar.gz

{unitx-0.13.0 → unitx-0.13.2}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.13.2] - 2026-10-22
+
+### Added
+
+- `unitx.time.from_datetime()` and `to_datetime()` explicitly convert aware
+  datetimes and Unix-referenced affine time points, including custom known
+  epoch coordinates. Import preserves integer ns; export rounds once to
+  microseconds with ties to even and defaults to UTC.
+- `SingleUnit.from_name(name)` constructs a single unit from a registered name
+  or name alias, including permitted prefixes, without accepting symbol spellings.
+
+### Changed
+
+- Clock functions in `unitx.time` return `AffineQuantity[int]` points in ns.
+  Point subtraction returns a duration Quantity; point addition and
+  multiplicative point arithmetic are rejected. Duration adapters are unchanged.
+  Clock domains remain untagged; only compare/subtract readings from the same context.
+- Clarify process-wide registration and unsupported concurrent registry access.
+- Expand the README with a runnable blackbody example and a theme-aware SVG plot.
+
+### Internal
+
+- Route name-only parsing through `SingleUnit.from_name()`, clarify recursive-descent
+  grammar, and remove a duplicate NumPy comparison branch.
+
+## [0.13.1] - 2026-10-22
+
+### Added
+
+- Public `unitx.si.au`, `nu` and `Planck` read-only namespaces of SI-valued
+  atomic, electron-mass natural, and Planck scales. These are physical
+  Quantities, not parser registrations or implicit conversion contexts.
+- Export the existing `Particle` namespace directly from `unitx.si`.
+
 ## [0.13.0] - 2026-10-21
 
 ### Added

unitx-0.13.0/README.md → unitx-0.13.2/PKG-INFO

@@ -1,3 +1,31 @@
+Metadata-Version: 2.5
+Name: unitx
+Version: 0.13.2
+Summary: Physical units, quantities, and unit conversion with exact unit algebra, type hints, and NumPy integration.
+Project-URL: Homepage, https://github.com/DaitTHU/unitx
+Project-URL: Documentation, https://github.com/DaitTHU/unitx/blob/main/docs/README.md
+Project-URL: Source, https://github.com/DaitTHU/unitx
+Project-URL: Changelog, https://github.com/DaitTHU/unitx/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/DaitTHU/unitx/issues
+Author: Dait
+License-Expression: MIT
+License-File: LICENSE
+Keywords: SI units,dimensional analysis,engineering,exact arithmetic,logarithmic units,numpy,physical constants,physical quantities,physics,quantity,scientific computing,temperature conversion,unit,unit algebra,unit conversion,units
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Provides-Extra: numpy
+Requires-Dist: numpy>=2.1; extra == 'numpy'
+Provides-Extra: test
+Requires-Dist: pyright>=1.1.414; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruff>=0.8; extra == 'test'
+Description-Content-Type: text/markdown
+
 # unitx
 
 [![PyPI version](https://img.shields.io/pypi/v/unitx)](https://pypi.org/project/unitx/)
@@ -74,7 +102,12 @@ Use `.isclose()` for approximate comparisons.
 Use `@` for an absolute coordinate reading and `*` for a linear difference:
 
 ```pycon
->>> room = 20 @ si.degC
+>>> difference = 20 * si.degC  # A temperature difference of 20 degrees
+>>> room = 20 @ si.degC  # A reading of 20 degrees Celsius
+>>> difference.value_in(si.K)
+20
+>>> room.value_in(si.K)
+Fraction(5863, 20)
 >>> print(room.to(si.degF))
 68 °F
 >>> print(room + 5 * si.K)
@@ -87,6 +120,9 @@ True
 ```
 
 Points are `AffineQuantity` objects; differences are `Quantity` objects.
+Multiplying by `si.degC` constructs a difference; use `@` or the explicit
+`AffineQuantity(20, si.degC)` constructor for an absolute reading.
+Adding two points raises `TypeError`; subtract them to obtain a difference.
 Use `.to_quantity()` to turn a point into an ordinary physical quantity for
 further arithmetic. Read the [point and difference guide](https://github.com/DaitTHU/unitx/blob/main/docs/affine.md)
 for temperature, dBm/dBW/dBV, and logarithmic ratio rules.
@@ -109,8 +145,13 @@ True
 ```
 
 `unitx.math` checks units for roots, trigonometry, exponentials, logarithms,
-`hypot`, and `atan2`. `unitx.time` returns integer nanosecond clock readings
-and adapts durations to `sleep` and `datetime.timedelta`.
+`hypot`, and `atan2`. `unitx.time` returns `AffineQuantity[int]` clock readings
+in nanoseconds; subtract readings from the same clock to obtain a Quantity
+duration. It also adapts durations to `sleep` and `datetime.timedelta`, and
+converts aware `datetime` objects to and from Unix time points with
+`time.from_datetime()` / `time.to_datetime()`.
+Readings do not carry clock, process, or thread identities; mixing clock
+contexts is not detected.
 See [standard-library enhancements](https://github.com/DaitTHU/unitx/blob/main/docs/stdlib.md)
 for the supported functions, numerical backends, and clock semantics.
 
@@ -136,6 +177,19 @@ units. Comparisons return boolean masks. Supported reductions, integration,
 gradients, and output buffers follow the [NumPy support matrix](https://github.com/DaitTHU/unitx/blob/main/docs/numpy.md).
 Array assignment and augmented arithmetic preserve the destination unit and dtype.
 
+Exact unit algebra preserves the scale `1/100` for centimetres to metres.
+Applying that scale to a numerical array follows NumPy's dtype, rounding, and
+overflow rules; it does not turn the array into exact rational numbers:
+
+```python
+from fractions import Fraction
+
+exact = Quantity(1, 'cm').value_in('m')
+approximate = Quantity(np.array([1.0]), 'cm').value_in('m')
+assert exact == Fraction(1, 100)
+assert Fraction(float(approximate[0])) != exact  # Binary float approximates 1/100
+```
+
 Use `.value` or `.value_in(unit)` at plotting and external-library boundaries.
 `np.asarray(quantity)` and `np.array(quantity)` raise TypeError to prevent
 implicit unit removal. NumPy's type stubs do not describe every wrapped
@@ -143,10 +197,40 @@ operation; see the [typing guide](https://github.com/DaitTHU/unitx/blob/main/doc
 
 The [physics notebooks](https://github.com/DaitTHU/unitx/blob/main/examples/README.md)
 cover blackbody radiation, damped motion, wave-packet spreading, attenuation,
-and measurement uncertainty. For example, Planck spectra combine physical
-constants, broadcasting, and spectral-density conversion:
+and measurement uncertainty.
+
+## Blackbody radiation
+
+Install plotting support with `pip install 'unitx[numpy]' matplotlib`, then run
+this complete example. Planck's formula keeps units and constants throughout;
+NumPy broadcasts the wavelength column against three temperatures. Convert the
+spectral radiance to a readable display unit before plotting:
+
+```python
+import numpy as np
+from matplotlib import pyplot as plt
+
+from unitx.si import SI, si
+
+wavelength = np.linspace(0.01, 3, 100)[:, None] * si.um
+temperature = np.array([3000, 4000, 5000]) * si.K
+exponent = SI.h * SI.c / (wavelength * SI.kB * temperature)
+radiance = 2 * SI.h * SI.c**2 / (wavelength**5 * np.expm1(exponent))
+radiance = radiance.to('kW/sr/m2/nm')
+
+fig, ax = plt.subplots(figsize=(7, 4), layout='constrained')
+ax.plot(wavelength.value, radiance.value)
+ax.set(
+    xlabel=f'Wavelength [{wavelength.unit}]',
+    ylabel=f'Spectral radiance [{radiance.unit}]',
+    title='Blackbody radiation',
+)
+ax.legend([f'T = {value}' for value in temperature], framealpha=1)
+ax.grid(True, alpha=0.25)
+plt.show()
+```
 
-![Blackbody spectral radiance](https://raw.githubusercontent.com/DaitTHU/unitx/main/docs/images/blackbody.png)
+![Blackbody spectral radiance at 3000, 4000 and 5000 K](https://raw.githubusercontent.com/DaitTHU/unitx/main/docs/images/blackbody.svg)
 
 ## Read more
 

unitx-0.13.0/PKG-INFO → unitx-0.13.2/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.5
-Name: unitx
-Version: 0.13.0
-Summary: A modern, intuitive unit library, with exact unit algebra, expressive type hints, and NumPy integration.
-Project-URL: Homepage, https://github.com/DaitTHU/unitx
-Project-URL: Issues, https://github.com/DaitTHU/unitx/issues
-Author: Dait
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Programming Language :: Python :: 3.15
-Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: >=3.12
-Provides-Extra: numpy
-Requires-Dist: numpy>=2.1; extra == 'numpy'
-Provides-Extra: test
-Requires-Dist: pyright>=1.1.414; extra == 'test'
-Requires-Dist: pytest>=8; extra == 'test'
-Requires-Dist: ruff>=0.8; extra == 'test'
-Description-Content-Type: text/markdown
-
 # unitx
 
 [![PyPI version](https://img.shields.io/pypi/v/unitx)](https://pypi.org/project/unitx/)
@@ -98,7 +74,12 @@ Use `.isclose()` for approximate comparisons.
 Use `@` for an absolute coordinate reading and `*` for a linear difference:
 
 ```pycon
->>> room = 20 @ si.degC
+>>> difference = 20 * si.degC  # A temperature difference of 20 degrees
+>>> room = 20 @ si.degC  # A reading of 20 degrees Celsius
+>>> difference.value_in(si.K)
+20
+>>> room.value_in(si.K)
+Fraction(5863, 20)
 >>> print(room.to(si.degF))
 68 °F
 >>> print(room + 5 * si.K)
@@ -111,6 +92,9 @@ True
 ```
 
 Points are `AffineQuantity` objects; differences are `Quantity` objects.
+Multiplying by `si.degC` constructs a difference; use `@` or the explicit
+`AffineQuantity(20, si.degC)` constructor for an absolute reading.
+Adding two points raises `TypeError`; subtract them to obtain a difference.
 Use `.to_quantity()` to turn a point into an ordinary physical quantity for
 further arithmetic. Read the [point and difference guide](https://github.com/DaitTHU/unitx/blob/main/docs/affine.md)
 for temperature, dBm/dBW/dBV, and logarithmic ratio rules.
@@ -133,8 +117,13 @@ True
 ```
 
 `unitx.math` checks units for roots, trigonometry, exponentials, logarithms,
-`hypot`, and `atan2`. `unitx.time` returns integer nanosecond clock readings
-and adapts durations to `sleep` and `datetime.timedelta`.
+`hypot`, and `atan2`. `unitx.time` returns `AffineQuantity[int]` clock readings
+in nanoseconds; subtract readings from the same clock to obtain a Quantity
+duration. It also adapts durations to `sleep` and `datetime.timedelta`, and
+converts aware `datetime` objects to and from Unix time points with
+`time.from_datetime()` / `time.to_datetime()`.
+Readings do not carry clock, process, or thread identities; mixing clock
+contexts is not detected.
 See [standard-library enhancements](https://github.com/DaitTHU/unitx/blob/main/docs/stdlib.md)
 for the supported functions, numerical backends, and clock semantics.
 
@@ -160,6 +149,19 @@ units. Comparisons return boolean masks. Supported reductions, integration,
 gradients, and output buffers follow the [NumPy support matrix](https://github.com/DaitTHU/unitx/blob/main/docs/numpy.md).
 Array assignment and augmented arithmetic preserve the destination unit and dtype.
 
+Exact unit algebra preserves the scale `1/100` for centimetres to metres.
+Applying that scale to a numerical array follows NumPy's dtype, rounding, and
+overflow rules; it does not turn the array into exact rational numbers:
+
+```python
+from fractions import Fraction
+
+exact = Quantity(1, 'cm').value_in('m')
+approximate = Quantity(np.array([1.0]), 'cm').value_in('m')
+assert exact == Fraction(1, 100)
+assert Fraction(float(approximate[0])) != exact  # Binary float approximates 1/100
+```
+
 Use `.value` or `.value_in(unit)` at plotting and external-library boundaries.
 `np.asarray(quantity)` and `np.array(quantity)` raise TypeError to prevent
 implicit unit removal. NumPy's type stubs do not describe every wrapped
@@ -167,10 +169,40 @@ operation; see the [typing guide](https://github.com/DaitTHU/unitx/blob/main/doc
 
 The [physics notebooks](https://github.com/DaitTHU/unitx/blob/main/examples/README.md)
 cover blackbody radiation, damped motion, wave-packet spreading, attenuation,
-and measurement uncertainty. For example, Planck spectra combine physical
-constants, broadcasting, and spectral-density conversion:
+and measurement uncertainty.
+
+## Blackbody radiation
+
+Install plotting support with `pip install 'unitx[numpy]' matplotlib`, then run
+this complete example. Planck's formula keeps units and constants throughout;
+NumPy broadcasts the wavelength column against three temperatures. Convert the
+spectral radiance to a readable display unit before plotting:
+
+```python
+import numpy as np
+from matplotlib import pyplot as plt
+
+from unitx.si import SI, si
+
+wavelength = np.linspace(0.01, 3, 100)[:, None] * si.um
+temperature = np.array([3000, 4000, 5000]) * si.K
+exponent = SI.h * SI.c / (wavelength * SI.kB * temperature)
+radiance = 2 * SI.h * SI.c**2 / (wavelength**5 * np.expm1(exponent))
+radiance = radiance.to('kW/sr/m2/nm')
+
+fig, ax = plt.subplots(figsize=(7, 4), layout='constrained')
+ax.plot(wavelength.value, radiance.value)
+ax.set(
+    xlabel=f'Wavelength [{wavelength.unit}]',
+    ylabel=f'Spectral radiance [{radiance.unit}]',
+    title='Blackbody radiation',
+)
+ax.legend([f'T = {value}' for value in temperature], framealpha=1)
+ax.grid(True, alpha=0.25)
+plt.show()
+```
 
-![Blackbody spectral radiance](https://raw.githubusercontent.com/DaitTHU/unitx/main/docs/images/blackbody.png)
+![Blackbody spectral radiance at 3000, 4000 and 5000 K](https://raw.githubusercontent.com/DaitTHU/unitx/main/docs/images/blackbody.svg)
 
 ## Read more
 

{unitx-0.13.0 → unitx-0.13.2}/docs/catalogue.md

@@ -10,9 +10,11 @@ True
 
 ```
 
-`unitx.si` is a module containing two read-only namespaces: lowercase `si`
-contains ready-to-use units and coordinate descriptors; uppercase `SI` contains
-physical-constant Quantities. Importing unitx initializes this catalogue.
+`unitx.si` provides read-only namespaces: lowercase `si` contains ready-to-use
+units and coordinate descriptors; uppercase `SI` contains physical-constant
+Quantities. `Particle` contains particle data, while `au`, `nu` and `Planck`
+contain physical unit scales expressed as SI Quantities.
+Importing unitx initializes this catalogue.
 
 ## Available groups
 
@@ -43,8 +45,8 @@ For the complete definitions see [unit source](../src/unitx/si/units.py) and
 
 `SI` includes the seven SI defining constants, plus constants such as hbar,
 G, mu0, epsilon0, me, mp, mn, alpha and the Wien displacement constants.
-Particle data are separately available from
-`from unitx.si.constants import Particle`.
+Particle data are available from `from unitx.si import Particle`; the existing
+`unitx.si.constants.Particle` import remains supported.
 
 Defining decimal values are stored using Decimal/int magnitudes. Measured
 constants carry the digits in the catalogue; Quantity does not attach an
@@ -59,6 +61,52 @@ from predefined `SI.hbar`, whose numerical magnitude is expressed in ordinary
 J s units. See [symbolic factors](scalars.md#symbolic-factors-and-pi) and
 [exact extra scales](custom-units.md#exact-extra-scales).
 
+## Atomic, natural and Planck scales
+
+```pycon
+>>> from unitx.si import Particle, Planck, au, nu
+>>> Particle.me is SI.me
+True
+>>> au.length is SI.a0
+True
+>>> # A physical length equal to three Bohr radii:
+>>> length = 3 * au.length
+>>> float((length / au.length).value_in(''))
+3.0
+>>> nu.velocity is SI.c
+True
+>>> Planck.length.unit == si.m
+True
+
+```
+
+| Namespace | Convention | Representative scales |
+| --- | --- | --- |
+| `au` | Hartree atomic units: ħ = e = mₑ = 4πε₀ = 1 | `length` (Bohr radius), `energy` (Hartree), `time`, `charge` |
+| `nu` | Electron-mass natural units: c = ħ = mₑ = ε₀ = 1 | `length` (reduced electron Compton wavelength), `energy`, `charge = sqrt(ε₀ ħ c)` |
+| `Planck` | c = ħ = G = kB = 1 | `mass`, `length`, `time`, `energy`, `temperature` |
+
+All three expose `velocity`, `action`, `mass`, `energy`, `momentum`, `length`
+and `time`. `au` and `nu` also expose `permittivity`, `force`, `charge`,
+`current`, `charge_density`, `electric_potential`, `electric_field`,
+`electric_dipole_moment`, `electric_quadrupole_moment`,
+`electric_polarizability`, `magnetic_flux_density`, `magnetic_dipole_moment`
+and `magnetizability`. `au` and `Planck` expose `temperature`.
+
+The atomic magnetic dipole scale is **twice** the Bohr magneton. In `nu`,
+the elementary charge has numerical value sqrt(4πα); other natural-unit
+conventions need not use the electron mass or this charge normalization.
+`Planck` uses ħ rather than h and does not select a charge convention.
+
+These attributes are **Quantities**, not Unit objects accepted as `.to()`
+targets. Divide by a scale and use `.value_in('')` to obtain a dimensionless
+number, or multiply a number by a scale to construct a physical quantity.
+The namespaces do not activate cross-dimension conversion or register new
+parser spellings. In particular, `si.au` and `Unit('au')` still mean the
+astronomical unit; `au.length` is the atomic length scale.
+All derived scales inherit the catalogue's finite numerical precision and
+lack of uncertainty propagation.
+
 ## Spelling and scale conventions
 
 Symbols and names are case-sensitive. Lowercase `k` is kilo and uppercase

{unitx-0.13.0 → unitx-0.13.2}/docs/custom-units.md

@@ -131,7 +131,18 @@ The registry and spelling rules live in `unitx.unitregistry`; parsing expression
 does not change unit definitions. A parser instance caches only a successful
 result; failed parses may be retried after a definition is added. Registration
 preserves existing valid spellings and validates before updating its indexes.
-Concurrent registry writes and isolated registry contexts are not supported.
+The registry is shared by all users of unitx in the current process; a Python
+attribute namespace does not create an isolated registry. Conflicting names or
+symbols raise `UnitRegistryError` rather than replace an existing definition.
+
+Registration is not thread-safe: validation and updates to the spelling indexes
+are not protected by a shared lock. Neither concurrent registration nor parsing
+while another thread registers a unit is supported. Register custom units during
+single-threaded initialization, before starting worker threads. Applications
+that register later must synchronize both registration and all registry reads.
+Validation failure leaves the indexes unchanged; this guarantee does not imply
+an atomic transaction for concurrent readers. Independent registry contexts
+are not provided.
 
 Quantity definitions require positive finite `int`, `Fraction`, `Decimal`, or
 `float` magnitudes. Prefer `Fraction` or `Decimal` for exact scales. Floats use