unitx 0.8.3__tar.gz → 0.8.4__tar.gz

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

@@ -1,5 +1,30 @@
 # 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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.8.3
-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.3 → 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.3 → unitx-0.8.4}/docs/numpy.md

@@ -80,13 +80,14 @@ methods, mixed array types, and keywords fail explicitly.
 | 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, 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
@@ -97,22 +98,82 @@ functions, including exp/log. Python scalar numerical semantics remain native.
 | reshape, transpose | Preserve unit | shape/order/copy; axes |
 | 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 outputs follow the rules below;
-overwrite_input=True is rejected. Unsupported initial, reduction/statistical
-where, mean, correction, and other keywords raise TypeError.
+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.
 
+`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.
+
+```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, and the numeric
+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 for ufuncs return that same target; functions accept `out=target` or
@@ -157,7 +218,7 @@ 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.
 
-Functions and add.reduce/accumulate use `same_kind` for the final cast and do
+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
@@ -174,7 +235,7 @@ assert np.argmax(q, axis=0, out=indices) is indices
 ```
 
 `out=None` and ufunc `out=(None,)` allocate ordinary results.
-Multiple-output ufuncs and product reductions remain unsupported.
+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
@@ -221,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.

unitx-0.8.4/examples/blackbody.ipynb

@@ -0,0 +1,143 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "blackbody-00",
+   "metadata": {},
+   "source": [
+    "# Blackbody spectral radiance\n",
+    "\n",
+    "Compare thermal spectra at three temperatures with wavelength on one array\n",
+    "axis and temperature on the other. This is the notebook version of the\n",
+    "README example. Run the setup in [examples/README.md](README.md) first.\n",
+    "\n",
+    "For an ideal blackbody, the spectral radiance per unit wavelength is\n",
+    "$$\n",
+    "B_\\lambda(T)=\\frac{2hc^2}{\\lambda^5}\n",
+    "\\left[\\exp\\!\\left(\\frac{hc}{\\lambda k_B T}\\right)-1\\right]^{-1}.\n",
+    "$$\n",
+    "Here $h$ is Planck's constant, $c$ is the speed of light, $k_B$ is Boltzmann's\n",
+    "constant, and $T$ is absolute temperature. The exponential argument is\n",
+    "dimensionless. Radiance is per unit solid angle; it is not the hemispheric\n",
+    "radiant exitance, which has an additional factor of $\\pi$ for this model.\n",
+    "\n",
+    "Reference: [CIE, Planck's law](https://cie.co.at/eilvterm/17-24-005)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "blackbody-01",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from matplotlib import pyplot as plt\n",
+    "\n",
+    "from unitx.si import SI, si"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "blackbody-02",
+   "metadata": {},
+   "source": [
+    "## Broadcast over wavelengths and temperatures\n",
+    "\n",
+    "The wavelength array has shape `(100, 1)` and the temperature array `(3,)`.\n",
+    "Each expression below produces a `(100, 3)` Quantity with one uniform unit.\n",
+    "`expm1` evaluates $\\exp(x)-1$ accurately near zero. The selected range also\n",
+    "keeps the short-wavelength exponential within floating-point range."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "blackbody-03",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "lam = np.linspace(0.01, 3, 100)[:, None] * si.um  # wavelengths in microns\n",
+    "T = np.asarray([3000, 4000, 5000]) * si.K  # temperatures in Kelvin\n",
+    "\n",
+    "nu = SI.c / lam\n",
+    "radiance = 2 * SI.h * SI.c**2 / (lam**5 * np.expm1(SI.h * nu / (SI.kB * T)))\n",
+    "radiance = radiance.to('kW/sr/m2/nm')  # spectral radiance per unit wavelength\n",
+    "\n",
+    "print('Radiance shape:', radiance.shape)\n",
+    "print('Radiance unit:', radiance.unit)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "blackbody-04",
+   "metadata": {},
+   "source": [
+    "## Plot with explicit numerical exits\n",
+    "\n",
+    "Matplotlib receives values in the units written on the axes. The spectral\n",
+    "density conversion includes the change from per metre to per nanometre."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "blackbody-05",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=(7, 4), layout='constrained')\n",
+    "ax.plot(lam.value, radiance.value)\n",
+    "ax.set(\n",
+    "    xlabel=f'Wavelength [{lam.unit}]',\n",
+    "    ylabel=f'Spectral radiance [{radiance.unit}]',\n",
+    "    title='Blackbody radiation',\n",
+    ")\n",
+    "ax.legend([f'T = {temperature}' for temperature in T])\n",
+    "ax.grid(True)\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "blackbody-06",
+   "metadata": {},
+   "source": [
+    "## Check the wavelength peaks\n",
+    "\n",
+    "Wien's displacement law gives $\\lambda_{\\max}T=b$, with `SI.b` provided by\n",
+    "unitx. A grid maximum has finite wavelength resolution; compare it to the\n",
+    "continuous prediction with an absolute tolerance tied to the grid spacing.\n",
+    "This is the peak of $B_\\lambda$, not the peak of $B_\\nu$ mapped to wavelength."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "blackbody-07",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "assert radiance.shape == (100, 3)\n",
+    "assert np.all(np.isfinite(radiance.value)) and np.all(radiance.value >= 0)\n",
+    "lambda_peak = lam[np.argmax(radiance.value, axis=0), 0]\n",
+    "lambda_formula = SI.b / T\n",
+    "assert np.all(lambda_peak.isclose(lambda_formula, rel_tol=0, abs_tol=0.02 * si.um))\n",
+    "print('Grid peaks:', lambda_peak)\n",
+    "print('Wien prediction:', lambda_formula.to(lambda_peak.unit))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}