unitx 0.8.2__tar.gz → 0.8.4__tar.gz

{unitx-0.8.2 → unitx-0.8.4}/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.8.4] - 2026-10-20
+
+### Added
+
+- Support prod and multiply.reduce with exact product units, scalar initial
+  values (including Quantities), boolean input masks, and staged output writes.
+  Require equal selected counts for dimensional outputs; normalize dimensionless
+  inputs before reduction. Document empty products and accumulator dtype rules.
+- Support trapezoid integration with Quantity ordinates, coordinates, or scalar
+  spacing. Combine their units directly, preserving native coordinate order
+  and axis behavior without manual value extraction or unit reconstruction.
+
+### Improved
+
+- Keep Python-comparison-to-ufunc mapping in the optional NumPy adapter and
+  replace redundant Fractionable type guards with direct isinstance checks.
+
+### Examples
+
+- Replace the blackbody script with a notebook and add damped motion, free
+  Gaussian wave-packet propagation, optical attenuation, and correlated
+  measurement-uncertainty notebooks. Keep calculations as Quantities and derive
+  plot labels from their units. Check execution, typing, and output-free notebook
+  files without adding Jupyter as a library or test dependency.
+
+## [0.8.3] - 2026-10-20
+
+### Added
+
+- Support unit-aware `out` for sum, mean, median, std, var, cumsum,
+  concatenate, stack, and add.reduce/accumulate. Require the exact result shape,
+  preserve target identity, unit, and dtype, and stage computation, conversion,
+  and casting before writing. Argmin/argmax accept bare integer ndarray outputs.
+- Document function/reduction output casting and add regressions for scaled
+  units, positional outputs, overlapping/strided buffers, and unchanged outputs
+  on failure, plus installed-consumer type checks.
+
 ## [0.8.2] - 2026-10-20
 
 ### Fixed

{unitx-0.8.2 → unitx-0.8.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.8.2
-Summary: A modern, intuitive Python library for units, quantities, and dimensional analysis.
+Version: 0.8.4
+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
@@ -28,31 +28,37 @@ Description-Content-Type: text/markdown
 [![Python versions](https://img.shields.io/pypi/pyversions/unitx)](https://pypi.org/project/unitx/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Write physical formulas with units and constants. `unitx` combines unit
-conversion and dimensional analysis with Python scalar arithmetic and optional
-NumPy arrays. Unit scales and rational exponents retain their exact structure.
+A modern, intuitive unit library for Python 3.12+.
+Exact unit algebra, expressive type hints, and NumPy integration.
+
+Write physical formulas with units and constants in Python. `unitx` provides
+unit conversion and dimensional analysis for Python scalars and integrates
+with NumPy array arithmetic, broadcasting, and supported functions.
+Unit scales and rational exponents retain their exact structure.
 
 The library is in early development; public APIs may change during the 0.x series.
 
 ## Install
 
-Python **3.12 or later** is required. The scalar library has no mandatory
-runtime dependencies:
+Python **3.12 or later** is required. Install unitx with:
 
 ```sh
-python -m pip install unitx
+pip install unitx
 ```
 
-For arrays, install NumPy support. Add Matplotlib to run the plotting example:
+There are no mandatory runtime dependencies. If you already use NumPy **2.1
+or later**, this installation also lets you use units in your NumPy calculations.
+For NumPy work in a new environment or with an older NumPy version, use the
+following command to install unitx and a compatible NumPy version:
 
 ```sh
-python -m pip install 'unitx[numpy]' matplotlib
+pip install 'unitx[numpy]'
 ```
 
-For development, install into the same interpreter that runs your code:
+For development, install into your active Python environment:
 
 ```sh
-python -m pip install -e '.[test,numpy]'
+pip install -e '.[test,numpy]'
 ```
 
 This README describes the current source tree. For an older release, consult
@@ -60,8 +66,17 @@ its matching Git tag.
 
 ## Start with units and constants
 
-`si` provides units; `SI` provides physical constants. Both are read-only
-namespaces in `unitx.si`:
+The `unitx.si` submodule provides ready-to-use units and physical constants
+based on the International System of Units (SI), through two read-only
+namespaces:
+
+- `si` contains units such as `si.m`, `si.s`, and `si.MeV`, including common
+  prefixes and non-SI units.
+- `SI` contains physical constants expressed in SI units, such as the speed
+  of light `SI.c` and the Planck constant `SI.h`.
+
+In the import below, `unitx.si` is the module path; the imported `si` and `SI`
+are the namespaces you use directly in formulas:
 
 ```pycon
 >>> from unitx.si import SI, si
@@ -85,10 +100,13 @@ division combine units; addition and subtraction align compatible quantities
 to the left operand's unit. Incompatible conversions and arithmetic raise
 `DimensionError`.
 
-## NumPy example: blackbody radiation
+## Units in NumPy: blackbody radiation
 
-Broadcast a column of wavelengths against three temperatures, then plot
-Planck's spectral radiance:
+Attach units to NumPy arrays, then use broadcasting and NumPy functions to
+evaluate a physical formula. Here, a column of wavelengths and three
+temperatures broadcast to give Planck's spectral radiance.
+
+Add `matplotlib` to your environment to plot the result:
 
 ```python
 import numpy as np
@@ -121,7 +139,7 @@ values in the catalogue and enter NumPy calculations as floats.
 `.value_in(unit)` also converts it to a chosen unit. Implicit unit removal with
 `np.asarray(quantity)` or `np.array(quantity)` raises TypeError.
 
-The [runnable example](examples/blackbody.py) uses `np.asarray([...]) * unit`
+The [blackbody notebook](examples/blackbody.ipynb) uses `np.asarray([...]) * unit`
 without an explicit dtype. This automatic construction inference is checked
 with NumPy 2.5 stubs and Pyright; the example also runs on NumPy 2.1. Older
 NumPy stubs may still infer Any for this expression. NumPy's own stubs can
@@ -131,6 +149,11 @@ infer different types for `np.array` and `np.asarray`;
 shape/dtype inference and wrapped return types for every NumPy function are not
 promised. See the [supported operations, storage rules, and typing limits](docs/numpy.md).
 
+The [physics notebooks](examples/README.md) also cover damped motion, Gaussian
+wave-packet spreading, optical attenuation, and correlated measurement uncertainty.
+They include explanations and numerical checks; plots are generated when run,
+keeping saved notebooks small.
+
 ## Values and conversion
 
 Use `Quantity` and `Unit` directly when constructing values from strings:
@@ -219,7 +242,7 @@ copying, and serialization.
 
 ## Scope and types
 
-- Supported magnitudes are Python scalars and optional plain numeric NumPy
+- Supported magnitudes are Python scalars and plain numeric NumPy
   arrays/scalars. Other array backends, ndarray subclasses, object arrays,
   and implicit list/tuple magnitudes are unsupported.
 - Conversion uses multiplication by a scale. Offset temperature scales such
@@ -250,9 +273,9 @@ with `_` are internal.
 Run the checks from the repository root:
 
 ```sh
-python -m pytest -q
-python -m ruff check .
-python -m ruff format --check .
+pytest -q
+ruff check .
+ruff format --check .
 python -m doctest README.md docs/units.md docs/scalars.md
 ```
 

{unitx-0.8.2 → unitx-0.8.4}/README.md

@@ -4,31 +4,37 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/unitx)](https://pypi.org/project/unitx/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Write physical formulas with units and constants. `unitx` combines unit
-conversion and dimensional analysis with Python scalar arithmetic and optional
-NumPy arrays. Unit scales and rational exponents retain their exact structure.
+A modern, intuitive unit library for Python 3.12+.
+Exact unit algebra, expressive type hints, and NumPy integration.
+
+Write physical formulas with units and constants in Python. `unitx` provides
+unit conversion and dimensional analysis for Python scalars and integrates
+with NumPy array arithmetic, broadcasting, and supported functions.
+Unit scales and rational exponents retain their exact structure.
 
 The library is in early development; public APIs may change during the 0.x series.
 
 ## Install
 
-Python **3.12 or later** is required. The scalar library has no mandatory
-runtime dependencies:
+Python **3.12 or later** is required. Install unitx with:
 
 ```sh
-python -m pip install unitx
+pip install unitx
 ```
 
-For arrays, install NumPy support. Add Matplotlib to run the plotting example:
+There are no mandatory runtime dependencies. If you already use NumPy **2.1
+or later**, this installation also lets you use units in your NumPy calculations.
+For NumPy work in a new environment or with an older NumPy version, use the
+following command to install unitx and a compatible NumPy version:
 
 ```sh
-python -m pip install 'unitx[numpy]' matplotlib
+pip install 'unitx[numpy]'
 ```
 
-For development, install into the same interpreter that runs your code:
+For development, install into your active Python environment:
 
 ```sh
-python -m pip install -e '.[test,numpy]'
+pip install -e '.[test,numpy]'
 ```
 
 This README describes the current source tree. For an older release, consult
@@ -36,8 +42,17 @@ its matching Git tag.
 
 ## Start with units and constants
 
-`si` provides units; `SI` provides physical constants. Both are read-only
-namespaces in `unitx.si`:
+The `unitx.si` submodule provides ready-to-use units and physical constants
+based on the International System of Units (SI), through two read-only
+namespaces:
+
+- `si` contains units such as `si.m`, `si.s`, and `si.MeV`, including common
+  prefixes and non-SI units.
+- `SI` contains physical constants expressed in SI units, such as the speed
+  of light `SI.c` and the Planck constant `SI.h`.
+
+In the import below, `unitx.si` is the module path; the imported `si` and `SI`
+are the namespaces you use directly in formulas:
 
 ```pycon
 >>> from unitx.si import SI, si
@@ -61,10 +76,13 @@ division combine units; addition and subtraction align compatible quantities
 to the left operand's unit. Incompatible conversions and arithmetic raise
 `DimensionError`.
 
-## NumPy example: blackbody radiation
+## Units in NumPy: blackbody radiation
 
-Broadcast a column of wavelengths against three temperatures, then plot
-Planck's spectral radiance:
+Attach units to NumPy arrays, then use broadcasting and NumPy functions to
+evaluate a physical formula. Here, a column of wavelengths and three
+temperatures broadcast to give Planck's spectral radiance.
+
+Add `matplotlib` to your environment to plot the result:
 
 ```python
 import numpy as np
@@ -97,7 +115,7 @@ values in the catalogue and enter NumPy calculations as floats.
 `.value_in(unit)` also converts it to a chosen unit. Implicit unit removal with
 `np.asarray(quantity)` or `np.array(quantity)` raises TypeError.
 
-The [runnable example](examples/blackbody.py) uses `np.asarray([...]) * unit`
+The [blackbody notebook](examples/blackbody.ipynb) uses `np.asarray([...]) * unit`
 without an explicit dtype. This automatic construction inference is checked
 with NumPy 2.5 stubs and Pyright; the example also runs on NumPy 2.1. Older
 NumPy stubs may still infer Any for this expression. NumPy's own stubs can
@@ -107,6 +125,11 @@ infer different types for `np.array` and `np.asarray`;
 shape/dtype inference and wrapped return types for every NumPy function are not
 promised. See the [supported operations, storage rules, and typing limits](docs/numpy.md).
 
+The [physics notebooks](examples/README.md) also cover damped motion, Gaussian
+wave-packet spreading, optical attenuation, and correlated measurement uncertainty.
+They include explanations and numerical checks; plots are generated when run,
+keeping saved notebooks small.
+
 ## Values and conversion
 
 Use `Quantity` and `Unit` directly when constructing values from strings:
@@ -195,7 +218,7 @@ copying, and serialization.
 
 ## Scope and types
 
-- Supported magnitudes are Python scalars and optional plain numeric NumPy
+- Supported magnitudes are Python scalars and plain numeric NumPy
   arrays/scalars. Other array backends, ndarray subclasses, object arrays,
   and implicit list/tuple magnitudes are unsupported.
 - Conversion uses multiplication by a scale. Offset temperature scales such
@@ -226,9 +249,9 @@ with `_` are internal.
 Run the checks from the repository root:
 
 ```sh
-python -m pytest -q
-python -m ruff check .
-python -m ruff format --check .
+pytest -q
+ruff check .
+ruff format --check .
 python -m doctest README.md docs/units.md docs/scalars.md
 ```
 

{unitx-0.8.2 → unitx-0.8.4}/docs/numpy.md

@@ -79,14 +79,15 @@ methods, mixed array types, and keywords fail explicitly.
 | power, float_power / `**` | Dimensional bases require a finite real scalar exponent; dimensionless bases/exponents normalize their scales |
 | sin, cos, tan, exp, expm1, log, log2, log10, log1p | Require coherent dimensionless values; return dimensionless Quantity |
 | isfinite, isnan, isinf, signbit | Bare boolean results |
-| add.reduce, add.accumulate | Preserve unit; accept axis and dtype, plus keepdims for reduce |
+| add.reduce, add.accumulate | Preserve unit; accept axis, dtype, out, plus keepdims for reduce |
+| multiply.reduce | Product unit rules below; accepts axis, dtype, keepdims, initial, where, out |
 
 Ufunc `__call__` accepts `where`, `dtype`, `casting`, `order`, `subok`, and
 single-output `out` as described below. Each kernel validates its own options.
 `where` is a bare boolean scalar
 or plain boolean ndarray; masked-out positions without an output buffer follow
 NumPy's uninitialized-result behavior. Numeric outputs must stay in the
-supported dtype domain. Product reductions, at, outer, and reduceat are
+supported dtype domain. Product accumulation, at, outer, and reduceat are
 unsupported. Python `**` also accepts Fraction/Decimal exponents, retaining
 exact unit exponents while passing a float exponent to the NumPy kernel.
 Angles retain unitx's dimensionless model: deg/rad normalize before these
@@ -95,25 +96,89 @@ functions, including exp/log. Python scalar numerical semantics remain native.
 | NumPy function | Unit/result rule | Supported options |
 | --- | --- | --- |
 | reshape, transpose | Preserve unit | shape/order/copy; axes |
-| concatenate, stack | Convert to first Quantity's unit; bare arrays remain dimensionless | axis, dtype, casting |
-| sum, mean | Preserve unit | axis, dtype, keepdims |
-| median | Preserve unit | axis, keepdims; overwrite_input=False |
-| std, var | Preserve unit / square unit | axis, dtype, ddof, keepdims |
-| cumsum | Preserve unit | axis, dtype |
-| argmin, argmax | Bare indices | axis, keepdims |
+| concatenate, stack | Convert to first Quantity's unit; bare arrays remain dimensionless | axis, dtype, casting, out; dtype and out are mutually exclusive |
+| sum, mean | Preserve unit | axis, dtype, keepdims, out |
+| prod | Product unit rules below | axis, dtype, keepdims, initial, where, out |
+| median | Preserve unit | axis, keepdims, out; overwrite_input=False |
+| std, var | Preserve unit / square unit | axis, dtype, ddof, keepdims, out |
+| cumsum | Preserve unit | axis, dtype, out |
+| argmin, argmax | Bare indices | axis, keepdims, out |
+| trapezoid | Multiply ordinate and coordinate units | x, scalar dx, axis; no out |
 | isclose, allclose | Bare mask / Python bool | rtol, atol, equal_nan |
 
 Supply the first magnitude argument positionally; concatenate/stack take a
 sequence. Options follow each supported signature, including positional out
-checks. Function and reduction `out` and overwrite_input=True are rejected. Unsupported
-initial, statistical where, mean, correction, and other keywords raise TypeError.
+checks. Function and reduction outputs follow the rules below;
+overwrite_input=True is rejected. Reduction/statistical `where` and `initial`
+are supported only for prod/multiply.reduce. Unsupported mean, correction,
+and other keywords raise TypeError.
 There is no `__setitem__`; `q += other` creates a result and rebinds q.
 
-## Ufunc output buffers
+`np.trapezoid(y, x=x)` accepts a Quantity for y, x, or both and returns a
+Quantity with unit `y.unit * x.unit`; bare inputs are dimensionless. With
+`x=None`, scalar `dx` supplies the coordinate unit instead (default: dimensionless
+1). NumPy dispatches this function on y and x, so at least one of those must be
+a Quantity to enter unitx; a Quantity supplied only as dx is insufficient.
+Explicit x makes dx irrelevant. Numeric arrays, scalar spacing, axis handling,
+coordinate order (including reversed or nonmonotonic x), broadcasting, and
+empty intervals follow [NumPy trapezoid](https://numpy.org/doc/stable/reference/generated/numpy.trapezoid.html).
+No coordinate sorting, interpolation, dtype option, or output buffer is added.
+
+## Product reductions
+
+`np.prod(q)` reduces all axes by default; `np.multiply.reduce(q)` defaults to
+axis 0, following NumPy. Both accept scalar, negative, or tuple axes, `axis=None`,
+`axis=()`, and `keepdims`. For dimensional input with unit U, each result has
+unit `U**N`, where N is the number of selected input elements in that slice.
+Zero-valued elements still count. All output slices must have the same N;
+otherwise unitx raises DimensionError because a single Quantity cannot hold
+different dimensions. `where` accepts the same bare boolean masks as ufunc
+calls and broadcasts to the input shape. It selects input elements; every
+output position is written when an output buffer is supplied.
+
+An empty or fully masked product has value 1 and unit `U**0`, before applying
+`initial`. If the output itself has no elements, the unit uses the nominal
+reduced-axis extent; scalar `where=False` sets that extent to zero.
+Dimensionless inputs, including deg and km/m, first convert to coherent
+dimensionless values and produce unit `Unit()`. Their masked slices may have
+different counts because the result still has a single coherent unit.
+
+`initial` is a bare numeric scalar or a scalar Quantity, including NumPy
+scalars and zero-dimensional arrays. A bare initial is dimensionless; a
+Quantity initial contributes its own unit once, so the result unit is
+`U**N * initial.unit`. An explicit zero still contributes its declared unit.
+The default is dimensionless 1. `initial=None` uses NumPy's first-element
+semantics and fails for empty reductions. NumPy controls the accumulator dtype,
+including casting the initial value to that dtype; initial does not select
+a wider numerical domain. Decimal/Fraction initial values enter NumPy as floats.
 
-Supported single-output ufunc calls accept a Quantity whose magnitude is a
+```python
+lengths = Quantity(np.array([[2.0, 3, 4], [5, 6, 7]]), 'm')
+selected = np.array([True, False, True])
+areas = np.prod(lengths, axis=1, where=selected)
+assert areas.unit == Unit('m2')
+np.testing.assert_array_equal(areas.value, [8, 35])
+weighted = np.multiply.reduce(lengths, axis=1, where=selected, initial=Quantity(2, 's'))
+assert weighted.unit == Unit('m2 s')
+```
+
+Both entry points support the output rules below, including exact result
+shape and unchanged targets on computation, unit, shape, or casting errors.
+`cumprod` and `multiply.accumulate` remain unsupported: partial products
+generally require different units at different positions. The supported
+axis, empty-product, initial, and mask behavior follows
+[NumPy prod](https://numpy.org/doc/stable/reference/generated/numpy.prod.html)
+and [ufunc.reduce](https://numpy.org/doc/stable/reference/generated/numpy.ufunc.reduce.html),
+with the additional single-unit and explicit-output rules described here.
+
+## Output buffers
+
+Supported single-output ufunc calls, add.reduce/accumulate, multiply.reduce, and the numeric
+functions listed with `out` above accept a Quantity whose magnitude is a
 writable plain numeric ndarray. `out=target`, `out=(target,)`, and positional
-outputs return that same target. Its magnitude object, dtype, and unit stay
+outputs for ufuncs return that same target; functions accept `out=target` or
+the positional output argument in their NumPy signature, without a tuple.
+The target's magnitude object, dtype, and unit stay
 fixed. Zero-dimensional, empty, and noncontiguous output arrays are supported.
 NumPy scalars and Python scalars cannot serve as output buffers.
 
@@ -127,7 +192,10 @@ converts that result to the target unit and casts it into a staging buffer.
 The numerical kernel uses the input dtypes and any explicit `dtype`; the
 target dtype is used for the final cast. This is not a promise of NumPy's
 output-dependent kernel selection or allocation-free execution. Both the
-result and `where` mask must broadcast to the target shape. Only true mask
+result and `where` mask must broadcast to the target shape for ufunc calls.
+Function and reduction outputs must have exactly the ordinary result's shape,
+including axes retained by `keepdims`; they do not broadcast into a larger
+target. Only true mask
 positions are written; false positions retain their original target values.
 Unit conversion also skips false positions. Input/output overlap and shared
 slices are handled through temporaries; a mask sharing output storage is copied.
@@ -138,6 +206,8 @@ length target. `ScaledUnit` factors participate in the conversion. Every numeric
 result, including a coherent or scaled dimensionless result, requires a Quantity
 target; writing it to a bare ndarray would discard its unit. Boolean predicates
 and comparisons instead accept only a bare boolean ndarray output.
+`argmin` and `argmax` accept only a bare integer ndarray output, with the
+same exact shape requirement as other function outputs.
 
 Final casting uses `casting='same_kind'` by default, or the explicitly requested
 NumPy casting policy. It does not silently enable `unsafe`; nonintegral unit
@@ -148,8 +218,24 @@ The final copy is not a general transaction against concurrent changes or
 external buffer failures. Temporaries cost memory proportional to the result
 and target; `out` provides controlled writes, not a zero-allocation guarantee.
 
-`out=None` and `out=(None,)` allocate ordinary results. Multiple-output ufuncs,
-ufunc reductions with an output, and function outputs remain unsupported.
+Functions and supported reductions/accumulations use `same_kind` for the final cast and do
+not accept a new `casting` keyword. Concatenate and stack use their existing
+`casting` option for the final write as well as the kernel; their `dtype` and
+`out` options cannot be combined. Index outputs also use `same_kind`, including
+its allowance for integer narrowing. These policies intentionally do not
+reproduce every function's native output casting rule. An explicit `dtype`
+controls the temporary numerical computation for supported reductions; the
+target dtype does not select the accumulator or kernel dtype.
+
+```python
+totals = Quantity(np.empty(3), 'cm')
+assert np.sum(q, axis=0, out=totals) is totals
+indices = np.empty(3, dtype=np.intp)
+assert np.argmax(q, axis=0, out=indices) is indices
+```
+
+`out=None` and ufunc `out=(None,)` allocate ordinary results.
+Multiple-output ufuncs and product accumulations remain unsupported.
 Output writes preserve the magnitude's type and dtype, so the covariant
 `Quantity[T]` contract remains valid; no setter or arbitrary replacement of T
 is introduced. NumPy's own stubs do not accept Quantity outputs or infer wrapped
@@ -196,7 +282,9 @@ NumPy's many arithmetic overloads against Scalar's own return protocol.
 `_numpy_typing.py` imports concrete NumPy types only for static analysis; core
 runtime imports still do not load NumPy. Strict scalar-consumer checks also
 run with NumPy absent. Checking the full library's optional NumPy annotations
-requires NumPy; `pyrightconfig.scalar.json` checks scalar consumers without it.
+requires NumPy; `pyright tests/typing` checks scalar consumers without it.
+All checks share `pyrightconfig.json`; the test runner selects the input
+directories and skips optional cases when their dependencies are unavailable.
 
 NumPy's left-operand and function stubs do not generally describe every
 unit-aware dispatch. With NumPy 2.5 stubs and Pyright 1.1.414, the documented

unitx-0.8.4/examples/README.md

@@ -0,0 +1,52 @@
+# Physics notebooks
+
+These notebooks use unitx for dimensional calculations and NumPy for numerical
+work. Each contains a model, assumptions, plots, and numerical checks. The
+material parameters and measurement draws are illustrative, not experimental data.
+
+| Notebook | Topic | unitx features |
+| --- | --- | --- |
+| [Blackbody radiation](blackbody.ipynb) | Planck spectra and Wien peak checks | Constants, broadcasting, spectral-density conversion |
+| [Damped oscillator](damped_oscillator.ipynb) | Release from rest and energy loss | Dimensionless ufunc arguments, energy units, comparisons |
+| [Gaussian wave packet](gaussian_wavepacket.ipynb) | Free electron propagation and uncertainty | Probability-density units, quantum constants, unit-aware integration |
+| [Optical attenuation](optical_attenuation.ipynb) | Transmission through absorbing layers | prod/multiply.reduce, input masks, Quantity initial, fixed-unit out |
+| [Pendulum uncertainty](pendulum_uncertainty.ipynb) | Correlated input uncertainties and Monte Carlo propagation | Mean/std/var units, mixed measurement units, explicit quantiles |
+
+## Run
+
+Use Python 3.12 or newer. From the repository root, install the current checkout
+and notebook tools in the environment you will select as the Jupyter kernel:
+
+```sh
+python -m pip install -e '.[numpy]' matplotlib jupyterlab
+jupyter lab examples/
+```
+
+Open a notebook and run all cells from the beginning. These notebooks require
+unitx 0.8.4 or newer for product reductions and unit-aware integration.
+The examples do not download datasets or write files. Keep physical quantities in calculations;
+plot their `.value` and derive labels from their `.unit`. Convert only to choose
+a useful display scale or to align units at a numerical boundary. Quantiles use
+an explicit numerical boundary and reattach the input unit, without naming a
+variable after its unit. Display equations use `$$...$$`.
+
+## Keep Git history small
+
+Commit only notebook source and minimal kernel metadata. Clear all outputs and
+execution counts before committing; do not embed figures, widget state, or
+attachments. Figures are regenerated when cells run. The test suite checks this
+policy and executes the numerical examples when NumPy and Matplotlib are present.
+
+To clear a notebook after running it, use JupyterLab's **Clear Outputs of All
+Cells**, then save it. For a command-line cleanup using nbconvert:
+
+```sh
+python -m pip install nbconvert
+jupyter nbconvert --clear-output --inplace examples/*.ipynb
+```
+
+The notebooks use ordinary Python code cells. Their code is also extracted for
+the existing Pyright example check, without committing duplicate `.py` exports.
+Assertions on NumPy results also check that dispatch retains the Quantity
+wrapper. NumPy's stubs cannot describe every wrapped result; the optical
+example documents local suppressions for its Quantity `initial` and `out` call.