unitx 0.13.4__tar.gz → 0.14.2__tar.gz

unitx-0.14.2/.github/consumers/arrays.py

@@ -0,0 +1,35 @@
+"""Check array runtime and inferred types using the installed wheel."""
+
+from typing import assert_type
+
+import numpy as np
+from numpy.typing import NDArray
+
+from unitx import LogQuantity, LogUnit, Quantity, Unit
+from unitx.exceptions import DimensionError
+from unitx.si import si
+
+
+def check_arrays(values: NDArray[np.float64]) -> None:
+    level = LogQuantity(values, si.dBm)
+    assert_type(level, LogQuantity[NDArray[np.float64]])
+    assert_type(level.unit, LogUnit)
+    assert level.value is values
+    np.testing.assert_allclose(level.to_quantity(si.W).value, [0.001, 0.1, 1.0])
+
+    distance = Quantity(values.copy(), si.m)
+    assert_type(distance, Quantity[NDArray[np.float64]])
+    assert_type(distance.unit, Unit)
+    np.testing.assert_allclose(distance.to(si.cm).value, values * 100)
+    saved = distance.value.copy()
+    try:
+        distance[:] = Quantity(values, si.s)
+    except DimensionError:
+        pass
+    else:
+        error_message = 'An incompatible assignment must fail.'
+        raise AssertionError(error_message)
+    np.testing.assert_array_equal(distance.value, saved)
+
+
+check_arrays(np.asarray([0.0, 20.0, 30.0], dtype=np.float64))

unitx-0.14.2/.github/consumers/pyrightconfig.json

@@ -0,0 +1,4 @@
+{
+  "pythonVersion": "3.12",
+  "typeCheckingMode": "strict"
+}

unitx-0.14.2/.github/consumers/scalars.py

@@ -0,0 +1,90 @@
+"""Check the installed wheel before optional NumPy is installed."""
+
+import os
+import pickle
+import sys
+from datetime import datetime, timedelta, timezone
+from decimal import Decimal
+from fractions import Fraction
+from importlib.metadata import distribution
+from importlib.util import find_spec
+from pathlib import Path
+from typing import Final, assert_type
+
+import unitx
+from unitx import AffineQuantity, LogQuantity, Quantity, Registry, Unit, UnitCatalog, math, time
+from unitx.factor import Factor
+from unitx.imperial import imperial
+from unitx.serialization import from_dict, to_dict
+from unitx.si import si
+
+installed = distribution('unitx')
+package_root = Path(str(installed.locate_file('unitx')))
+assert installed.version == os.environ['EXPECTED_VERSION']
+assert Path(unitx.__file__).resolve() == (package_root / '__init__.py').resolve()
+assert (package_root / 'py.typed').is_file()
+assert find_spec('numpy') is None
+
+distance = Quantity(Decimal('1.25'), si.m)
+assert_type(distance.to(si.cm), Quantity[Decimal])
+assert distance.value_in(si.cm) == Decimal(125)
+assert Quantity(1, si.cm).value_in(si.m) == Fraction(1, 100)
+assert 2 * Unit(si.m, scale=Factor(3)) == 6 * si.m
+
+root = math.sqrt(9 * si.m**2)
+assert_type(root, Quantity[float])
+assert root == 3 * si.m
+assert math.sin(90 * si.deg).value == 1.0
+assert math.hypot(3 * si.m, 400 * si.cm) == 5 * si.m
+
+stamp = time.time()
+start = time.perf_counter()
+elapsed = time.perf_counter() - start
+assert_type(stamp, AffineQuantity[int])
+assert_type(start, AffineQuantity[int])
+assert_type(elapsed.unit, Unit)
+assert type(stamp.value) is int and stamp.unit.delta_unit == si.ns
+assert type(elapsed.value) is int and elapsed.unit == si.ns and elapsed.value >= 0
+local_zone = timezone(timedelta(hours=8))
+instant = datetime(2000, 1, 1, 12, 34, 56, 123456, tzinfo=local_zone)
+point = time.from_datetime(instant)
+assert_type(point, AffineQuantity[int])
+assert_type(time.to_datetime(point), datetime)
+utc_instant = time.to_datetime(point)
+local_instant = time.to_datetime(point, tz=local_zone)
+assert utc_instant == instant and utc_instant.tzinfo is timezone.utc
+assert local_instant == instant and local_instant.tzinfo is local_zone
+assert time.to_datetime(AffineQuantity(1500, si.ns)) == datetime(
+    1970, 1, 1, 0, 0, 0, 2, tzinfo=timezone.utc
+)
+duration = time.from_timedelta(timedelta(microseconds=123456))
+assert_type(duration, Quantity[int])
+assert duration == 123456 * si.us
+assert time.to_timedelta(Quantity(Decimal('0.0000015'), si.s)) == timedelta(microseconds=2)
+
+celsius = 20 @ si.degC
+level = 30 @ si.dBm
+assert_type(celsius, AffineQuantity[int])
+assert_type(level, LogQuantity[int])
+assert celsius.to_quantity(si.K) == Fraction(5863, 20) * si.K
+assert (32 @ imperial.degF).to(si.degC) == 0 @ si.degC
+assert level.to_quantity(si.W) == 1 * si.W
+assert LogQuantity.from_quantity(1 * si.W, si.dBm) == level
+
+registry = Registry([si.m])
+with registry.defining():
+    span = (2 * si.m).define('installedSpan')
+
+
+class laboratory(UnitCatalog, units=(span,)):
+    length: Final = span
+
+
+assert_type(laboratory.parse('installedSpan'), Unit)
+assert laboratory.parse('installedSpan') == span
+quantity = 3 * span
+assert from_dict(to_dict(quantity), registry=registry) == quantity
+for value in (quantity, celsius, level):
+    assert pickle.loads(pickle.dumps(value)) == value
+assert 'numpy' not in sys.modules
+assert 'sympy' not in sys.modules

unitx-0.14.2/.github/workflows/ci.yml

@@ -0,0 +1,141 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+      - name: Install documentation dependencies
+        run: python -m pip install -r docs/requirements.txt
+      - name: Build documentation with strict link checks
+        run: python -m mkdocs build --strict
+
+  test:
+    name: Test Python ${{ matrix.python-version }} (${{ matrix.backend }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14", "3.15"]
+        backend: ["builtin", "sympy"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Install SymPy
+        if: matrix.backend == 'sympy'
+        run: python -m pip install sympy
+
+      - name: Run Ruff
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run tests
+        run: |
+          pytest -q
+          python -m doctest README.md docs/*.md docs/catalogues/*.md
+
+  numpy:
+    name: NumPy ${{ matrix.numpy }} (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: '3.12'
+            numpy: '2.1.*'
+          - python-version: '3.14'
+            numpy: 'latest'
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and dependencies
+        run: python -m pip install -e '.[test,numpy]' 'matplotlib>=3.9'
+      - name: Select minimum NumPy
+        if: matrix.numpy != 'latest'
+        run: python -m pip install 'numpy==${{ matrix.numpy }}'
+      - name: Run tests and typing
+        run: |
+          pytest -q
+          python -m doctest README.md docs/*.md docs/catalogues/*.md
+
+  installed:
+    name: Installed wheel (Python 3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install build and type-check dependencies
+        run: python -m pip install build twine 'pyright>=1.1.414'
+
+      - name: Build and check distributions
+        id: version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path('pyproject.toml').read_text())['project']['version']
+          with Path(os.environ['GITHUB_OUTPUT']).open('a') as output:
+              output.write(f'version={version}\n')
+          PY
+          python -m build
+          python -m twine check --strict dist/*
+
+      - name: Install built wheel and copy consumers outside the checkout
+        run: |
+          python -m pip install --no-deps dist/*.whl
+          mkdir -p "$RUNNER_TEMP/unitx-consumers"
+          cp .github/consumers/*.py .github/consumers/pyrightconfig.json "$RUNNER_TEMP/unitx-consumers/"
+
+      - name: Check installed scalar runtime and types without NumPy
+        working-directory: ${{ runner.temp }}/unitx-consumers
+        env:
+          EXPECTED_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          python -I scalars.py
+          python -m pyright --project pyrightconfig.json --pythonpath "$(command -v python)" scalars.py
+
+      - name: Install optional NumPy
+        run: python -m pip install 'numpy>=2.1'
+
+      - name: Check installed NumPy runtime and types
+        working-directory: ${{ runner.temp }}/unitx-consumers
+        run: |
+          python -I arrays.py
+          python -m pyright --project pyrightconfig.json --pythonpath "$(command -v python)" arrays.py

{unitx-0.13.4 → unitx-0.14.2}/.github/workflows/release.yml

@@ -54,7 +54,7 @@ jobs:
           python -m ruff check .
           python -m ruff format --check .
           python -m pytest -q
-          python -m doctest README.md docs/*.md
+          python -m doctest README.md docs/*.md docs/catalogues/*.md
 
       - name: Build wheel and source distribution
         run: python -m build
@@ -62,28 +62,28 @@ jobs:
       - name: Check distribution metadata
         run: python -m twine check --strict dist/*
 
-      - name: Install built wheel
-        run: python -m pip install --force-reinstall --no-deps dist/*.whl
+      - name: Install built wheel and copy consumers outside the checkout
+        run: |
+          python -m pip install --force-reinstall --no-deps dist/*.whl
+          mkdir -p "$RUNNER_TEMP/unitx-consumers"
+          cp .github/consumers/*.py .github/consumers/pyrightconfig.json "$RUNNER_TEMP/unitx-consumers/"
 
-      - name: Check installed package
-        working-directory: ${{ runner.temp }}
+      - name: Check installed scalar runtime and types without NumPy
+        working-directory: ${{ runner.temp }}/unitx-consumers
         env:
           EXPECTED_VERSION: ${{ steps.version.outputs.version }}
         run: |
-          python - <<'PY'
-          import os
-          from fractions import Fraction
-          from importlib.metadata import version
-          from importlib.resources import files
+          python -I scalars.py
+          python -m pyright --project pyrightconfig.json --pythonpath "$(command -v python)" scalars.py
 
-          from unitx.quantity import Quantity
-          from unitx.unit import Unit
+      - name: Install optional NumPy
+        run: python -m pip install 'numpy>=2.1'
 
-          assert version('unitx') == os.environ['EXPECTED_VERSION']
-          assert files('unitx').joinpath('py.typed').is_file()
-          assert Quantity(1, 'cm').to('m').value == Fraction(1, 100)
-          assert 2 * Unit('m') == Quantity(200, 'cm')
-          PY
+      - name: Check installed NumPy runtime and types
+        working-directory: ${{ runner.temp }}/unitx-consumers
+        run: |
+          python -I arrays.py
+          python -m pyright --project pyrightconfig.json --pythonpath "$(command -v python)" arrays.py
 
       - name: Store distributions
         uses: actions/upload-artifact@v5

{unitx-0.13.4 → unitx-0.14.2}/.gitignore

@@ -71,9 +71,6 @@ instance/
 # Sphinx documentation
 docs/_build/
 
-# Local design discussion, not public documentation
-/docs/design-affine-log.md
-
 # PyBuilder
 .pybuilder/
 target/

unitx-0.14.2/.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: '3.12'
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

{unitx-0.13.4 → unitx-0.14.2}/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 ## [Unreleased]
 
+## [0.14.2] - 2026-10-24
+
+### Documentation
+
+- Add a MkDocs site with pinned build requirements, Mermaid diagrams,
+  Read the Docs configuration and strict CI checks for internal links and anchors.
+  Hosting can use an available project name; no documentation domain is assumed.
+- Fix the README's logarithmic-guide link for package-index rendering.
+
+### Internal
+
+- Execute the README's Python code blocks directly and check the blackbody
+  plot's units, curve count and numerical data.
+- Extend installed-wheel runtime and type consumers with mathematical functions,
+  integer clock readings, duration arithmetic and datetime precision checks.
+- Add reproducible scalar benchmarks for parsing, conversion, comparison and
+  exact factors, recording the environment and timing parameters as JSON.
+
+## [0.14.1] - 2026-10-24
+
+### Documentation
+
+- Clarify concurrent Registry reads, application synchronization during
+  registration, the absence of a freeze/snapshot API, and custom-definition
+  sharing within and across processes.
+
+## [0.14.0] - 2026-10-24
+
+### Added
+
+- `Registry` provides independent parsing environments, atomic `include(*units)`
+  and explicit `with registry.defining():` blocks with configurable prefix defaults.
+  `UnitCatalog` collects read-only unit attributes and provides catalogue parsing.
+- `unitx.imperial` supplies British Imperial, historical English and US customary
+  catalogues with independent spellings and exact documented scales, including
+  US survey feet, thermochemical Btu, circular mil and conventional water/mercury
+  pressure units. Importing a catalogue does not change default parsing.
+
+### Changed
+
+- **Breaking:** `Unit` now stores its complete exact extra scale; `ScaledUnit` is
+  removed. Construct scaled units with `Unit(base, scale=...)` or Factor operands.
+- **Breaking:** `.define()` creates standalone definitions outside an explicit
+  Registry block. Extend default parsing explicitly with `default_registry`.
+  Formal identity follows shared definition objects rather than symbols;
+  independent same-name definitions remain distinct. Import `UnitDefinition`
+  and `PrefixPolicy` from `unitx.unitdefinition`; registry table exports are removed.
+- **Breaking:** `LogUnit` and `LogQuantity` replace logarithmic uses of AffineUnit
+  and AffineQuantity. Point `.to()` stays within its coordinate family; use
+  `.to_quantity()` and `LogQuantity.from_quantity()` at physical boundaries.
+- **Breaking:** Dimension equality includes the internal logarithmic axis.
+  Use `.physical` for seven-axis physical comparisons; separate `log_degree`
+  attributes are removed.
+- **Breaking:** Fahrenheit and Rankine move from SI/default parsing to
+  `imperial.degF` and `imperial.degR`.
+- **Breaking:** Scalar JSON uses format 2 with definition IDs and an optional
+  receiving Registry; format 1 and older pickle payloads are unsupported.
+  Reconstruction requires existing definitions and checks their metadata.
+- Logarithmic coordinates retain exact `reference` and `at` anchors; `origin`
+  is a derived numerical view. Affine defining readings that require an
+  unrepresentable symbolic origin sum are rejected; supply the origin at `at=0`.
+
+### Fixed
+
+- Preserve private coordinate mappings through retained linear projections,
+  and reconstruct private coordinate/point reprs even when their symbols coincide
+  with default logarithmic difference units.
+
 ## [0.13.4] - 2026-10-23
 
 ### Fixed

{unitx-0.13.4 → unitx-0.14.2}/CONTRIBUTING.md

@@ -23,11 +23,16 @@ Pytest collects runtime tests and source doctests. `tests/test_typing.py` runs
 Pyright against scalar and optional NumPy consumers, including scalar checks
 with NumPy absent. The [typing guide](docs/typing.md) explains the boundaries.
 CI covers Python 3.12–3.15, built-in/SymPy factorization and minimum/current NumPy.
+An additional CI job builds the distributions and checks their wheel with the
+consumers in `.github/consumers/`. It copies those scripts and their independent
+Pyright configuration outside the checkout, first checking scalar runtime and
+types without NumPy, then installing NumPy and checking array runtime and types.
+The release workflow runs the same consumers before uploading distributions.
 
 Run the executable Markdown examples as well:
 
 ```sh
-python -m doctest README.md docs/*.md
+python -m doctest README.md docs/*.md docs/catalogues/*.md
 ```
 
 Use tracked public guides for release validation; local ignored design notes
@@ -35,6 +40,33 @@ are not release documentation. Documentation examples should be reproducible
 and avoid modifying source files. Notebook source is checked and executed by
 the tests when its optional dependencies are present; see the
 [notebook policy](examples/README.md#keep-git-history-small).
+With NumPy and Matplotlib installed, the tests also execute the README's
+`python` code blocks in order and check the blackbody plot's numerical data.
+
+## Documentation site
+
+Build or preview the existing Markdown guides with MkDocs:
+
+```sh
+python -m pip install -r docs/requirements.txt
+python -m mkdocs build --strict
+python -m mkdocs serve
+```
+
+The build writes to the ignored `site/` directory. CI checks the strict build,
+including internal links and anchors. `.readthedocs.yaml` uses the same pinned
+MkDocs requirement; connect the repository to a Read the Docs project to host
+it. These configuration files alone do not create or publish a hosted site.
+Mermaid diagrams load a pinned JavaScript module from jsDelivr in the browser;
+building the HTML does not require that CDN. Repository files outside `docs/`
+use GitHub links so they also work on a hosted documentation site.
+
+## Performance measurements
+
+Run the [scalar and NumPy benchmarks](benchmarks/README.md) when investigating
+performance changes. Their JSON reports record the environment and per-call
+timings; compare runs under the same conditions rather than setting CI timing
+thresholds.
 
 ## Keep changes reviewable
 

{unitx-0.13.4 → unitx-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.13.4
+Version: 0.14.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
@@ -102,13 +102,14 @@ Use `.isclose()` for approximate comparisons.
 Use `@` for an absolute coordinate reading and `*` for a linear difference:
 
 ```pycon
+>>> from unitx.imperial import imperial
 >>> 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))
+>>> print(room.to(imperial.degF))
 68 °F
 >>> print(room + 5 * si.K)
 25 °C
@@ -119,13 +120,15 @@ True
 
 ```
 
-Points are `AffineQuantity` objects; differences are `Quantity` objects.
+Linear affine points are `AffineQuantity` objects and logarithmic readings are
+`LogQuantity` 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.
+for temperatures and [logarithmic quantities](https://github.com/DaitTHU/unitx/blob/main/docs/logarithmic.md) for
+dBm/dBW/dBV and ratio rules.
 
 ## Mathematical functions and time
 
@@ -240,7 +243,7 @@ or go directly to a topic:
 | Topic | Guide |
 | --- | --- |
 | Construction, arithmetic, conversion and unit expressions | [Units and quantities](https://github.com/DaitTHU/unitx/blob/main/docs/units.md) |
-| Ready-to-use units, constants and spelling conventions | [Catalogue](https://github.com/DaitTHU/unitx/blob/main/docs/catalogue.md) |
+| Ready-to-use units, constants and spelling conventions | [Catalogue](https://github.com/DaitTHU/unitx/blob/main/docs/catalogues/README.md) |
 | Exact extra scales and process-local registration | [Custom units](https://github.com/DaitTHU/unitx/blob/main/docs/custom-units.md) |
 | Fraction, Decimal, equality, powers and tolerances | [Scalar numerical behavior](https://github.com/DaitTHU/unitx/blob/main/docs/scalars.md) |
 | Notebook, text, LaTeX, HTML and siunitx output | [Display and formatting](https://github.com/DaitTHU/unitx/blob/main/docs/display.md) |

{unitx-0.13.4 → unitx-0.14.2}/README.md

@@ -74,13 +74,14 @@ Use `.isclose()` for approximate comparisons.
 Use `@` for an absolute coordinate reading and `*` for a linear difference:
 
 ```pycon
+>>> from unitx.imperial import imperial
 >>> 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))
+>>> print(room.to(imperial.degF))
 68 °F
 >>> print(room + 5 * si.K)
 25 °C
@@ -91,13 +92,15 @@ True
 
 ```
 
-Points are `AffineQuantity` objects; differences are `Quantity` objects.
+Linear affine points are `AffineQuantity` objects and logarithmic readings are
+`LogQuantity` 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.
+for temperatures and [logarithmic quantities](https://github.com/DaitTHU/unitx/blob/main/docs/logarithmic.md) for
+dBm/dBW/dBV and ratio rules.
 
 ## Mathematical functions and time
 
@@ -212,7 +215,7 @@ or go directly to a topic:
 | Topic | Guide |
 | --- | --- |
 | Construction, arithmetic, conversion and unit expressions | [Units and quantities](https://github.com/DaitTHU/unitx/blob/main/docs/units.md) |
-| Ready-to-use units, constants and spelling conventions | [Catalogue](https://github.com/DaitTHU/unitx/blob/main/docs/catalogue.md) |
+| Ready-to-use units, constants and spelling conventions | [Catalogue](https://github.com/DaitTHU/unitx/blob/main/docs/catalogues/README.md) |
 | Exact extra scales and process-local registration | [Custom units](https://github.com/DaitTHU/unitx/blob/main/docs/custom-units.md) |
 | Fraction, Decimal, equality, powers and tolerances | [Scalar numerical behavior](https://github.com/DaitTHU/unitx/blob/main/docs/scalars.md) |
 | Notebook, text, LaTeX, HTML and siunitx output | [Display and formatting](https://github.com/DaitTHU/unitx/blob/main/docs/display.md) |

unitx-0.14.2/benchmarks/README.md

@@ -0,0 +1,30 @@
+# Performance measurements
+
+Install the checkout in the environment to be measured, then run from the
+repository root:
+
+```sh
+python -m pip install -e .
+python benchmarks/scalars.py --repeat 7 --number 1000
+```
+
+The scalar script measures fresh expression parsing, Fraction/Decimal
+conversion, cross-unit equality and ordering, factor construction, rational
+powers and symbolic cancellation. Input quantities and factors are prepared
+outside the timed operations; each parsing call constructs a new parser.
+The JSON output records median seconds per call, Python/platform, the selected
+factorization backend, Decimal precision and timing parameters. SymPy is used
+automatically when installed; compare backends in separate environments.
+
+Array write measurements require the optional NumPy dependency:
+
+```sh
+python -m pip install -e '.[numpy]'
+python benchmarks/numpy_writes.py --size 1000000 --repeat 7 --number 20
+```
+
+That script also reports peak traced allocations for each operation. Timing
+and allocation tracing are separate measurements. Run baseline and candidate
+with the same interpreter, dependencies, arguments and machine conditions.
+These are development measurements, not performance guarantees; CI does not
+enforce timing thresholds.

unitx-0.14.2/benchmarks/scalars.py

@@ -0,0 +1,68 @@
+"""Time scalar parsing, conversion, comparison and exact factor operations.
+
+Run from an installed checkout: python benchmarks/scalars.py
+Each parse creates a new UnitParser; conversion inputs are prepared beforehand.
+Results describe this process and machine, not a cross-machine performance claim.
+"""
+
+import argparse
+import json
+import platform
+import statistics
+import timeit
+from decimal import Decimal, getcontext
+from fractions import Fraction
+
+from unitx import Quantity, Unit, pi
+from unitx.factor import Factor, factorint
+from unitx.si import si
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--repeat', type=int, default=7)
+    parser.add_argument('--number', type=int, default=1000)
+    options = parser.parse_args()
+    if options.repeat < 1 or options.number < 1:
+        parser.error('--repeat and --number must be positive integers.')
+
+    rational = Quantity(Fraction(1, 3), si.m)
+    decimal = Quantity(Decimal('1.25'), si.m)
+    equivalent = Quantity(Fraction(100, 3), si.cm)
+    greater = Quantity(Fraction(101, 3), si.cm)
+    base = Factor(2) * pi
+    radical = base ** Fraction(1, 3)
+    cases = {
+        'parse_expression': lambda: Unit('kg m2/s3'),
+        'convert_fraction': lambda: rational.value_in(si.cm),
+        'convert_decimal': lambda: decimal.value_in(si.cm),
+        'equal_cross_unit': lambda: rational == equivalent,
+        'order_cross_unit': lambda: rational < greater,
+        'factor_construct': lambda: Factor(Fraction(123456, 1001)),
+        'factor_rational_power': lambda: base ** Fraction(1, 3),
+        'factor_cancel': lambda: radical**3 / base,
+    }
+    results = {}
+    for name, operation in cases.items():
+        operation()
+        samples = timeit.repeat(operation, repeat=options.repeat, number=options.number)
+        results[name] = {'seconds': statistics.median(samples) / options.number}
+    backend = 'sympy' if factorint.__module__.startswith('sympy') else 'builtin'
+    print(
+        json.dumps(
+            {
+                'python': platform.python_version(),
+                'platform': platform.platform(),
+                'factorization_backend': backend,
+                'decimal_precision': getcontext().prec,
+                'repeat': options.repeat,
+                'number': options.number,
+                'cases': results,
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == '__main__':
+    main()