pyrebasis 0.1.0__tar.gz

pyrebasis-0.1.0/Cargo.lock

@@ -0,0 +1,345 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "622f3fc73690be383c7214310406f28a90e6edeadc3cea882f9d71e495b9711a"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc74980687109a3b14c72fd458107bf0baa1da1a1a805e178d15501ba9b86d9d"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
+
+[[package]]
+name = "either"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
+[[package]]
+name = "ndarray"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "882ed72dce9365842bf196bdeedf5055305f11fc8c03dee7bb0194a6cad34841"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+ "rayon",
+]
+
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "numpy"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a5b15d63a5ff39e378daed0e1340d3a5964703ea9712eb09a0dc66fade996f4"
+dependencies = [
+ "libc",
+ "ndarray 0.17.2",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "rebasis"
+version = "0.1.0"
+dependencies = [
+ "libm",
+ "ndarray 0.16.1",
+ "rayon",
+ "thiserror",
+]
+
+[[package]]
+name = "rebasis-py"
+version = "0.1.0"
+dependencies = [
+ "ndarray 0.16.1",
+ "numpy",
+ "pyo3",
+ "pyo3-build-config",
+ "rebasis",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "thiserror"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

pyrebasis-0.1.0/Cargo.toml

@@ -0,0 +1,23 @@
+[workspace]
+members = ["rebasis", "rebasis-py"]
+resolver = "3"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+license = "MIT"
+repository = "https://github.com/usask-arg/rebasis"
+
+[workspace.dependencies]
+# 0.16 matches sasktran2, which will depend on the core crate.
+ndarray = { version = "0.16", features = ["rayon"] }
+rayon = "1.10"
+thiserror = "2"
+
+[profile.release]
+lto = "fat"
+codegen-units = 1
+
+[profile.test]
+opt-level = 2

pyrebasis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rebasis contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyrebasis-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: pyrebasis
+Version: 0.1.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: sphinx>=8 ; extra == 'docs'
+Requires-Dist: furo>=2024.8 ; extra == 'docs'
+Requires-Dist: myst-nb>=1.1 ; extra == 'docs'
+Requires-Dist: numpydoc>=1.8 ; extra == 'docs'
+Requires-Dist: ipykernel>=6.29 ; extra == 'docs'
+Requires-Dist: matplotlib>=3.8 ; extra == 'docs'
+Requires-Dist: xarray>=2024.7 ; extra == 'docs'
+Requires-Dist: pytest>=8 ; extra == 'test'
+Requires-Dist: xarray>=2024.7 ; extra == 'test'
+Requires-Dist: xarray>=2024.7 ; extra == 'xarray'
+Provides-Extra: docs
+Provides-Extra: test
+Provides-Extra: xarray
+License-File: LICENSE
+Summary: Linear maps between function bases: instrument line shapes, regridding, projection
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://usask-arg.github.io/rebasis/
+Project-URL: Repository, https://github.com/usask-arg/rebasis
+
+# rebasis
+
+[![CI](https://github.com/usask-arg/rebasis/actions/workflows/ci.yml/badge.svg)](https://github.com/usask-arg/rebasis/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-usask--arg.github.io%2Frebasis-blue)](https://usask-arg.github.io/rebasis/)
+
+Linear maps between function bases, with a Rust core and a Python interface.
+
+```bash
+pip install pyrebasis        # import rebasis
+cargo add rebasis            # the Rust crate
+```
+
+The PyPI distribution is `pyrebasis` because `rebasis` there is an unrelated project; the import
+name is `rebasis`. Documentation: <https://usask-arg.github.io/rebasis/>.
+
+A quantity is represented as f(x) = Σ_j f_j B_j(x). rebasis computes the sparse matrices that
+turn the coefficients f_j into:
+
+| operation | what it computes | typical use |
+|---|---|---|
+| `measure(kernels, basis)` | g_i = ∫ K_i f / ∫ K_i | instrument line shape applied to a high-resolution spectrum |
+| `evaluate(basis, x)` | g_i = f(x_i) | interpolation, plotting a reconstruction |
+| `project(src, dst)` | best L2 fit Σ g_i G_i ≈ f | conservative regridding, up- or down-sampling |
+| `Fit(kernels, model)` | model coefficients whose measurements match data | smooth conservative upsampling, smoothing splines, inverting `measure` |
+
+Inner products are exact for piecewise polynomials (boxes, hats, B-splines, tabulated shapes) and
+accurate to rounding for the analytic line shapes; there are no tolerance or resolution
+parameters.
+
+```python
+import numpy as np
+import rebasis as rb
+
+wavel = np.linspace(300, 310, 100_001)  # high-resolution model grid
+hires = rb.Space.hats(wavel)  # radiance = linear interpolant of the samples
+ils = rb.Space.voigts(np.arange(301, 309, 0.1), fwhm_gaussian=0.4, fwhm_lorentzian=0.05)
+
+W = rb.measure(ils, hires)  # scipy.sparse.csr_array, (80, 100001)
+measured = W @ radiance  # or rb.apply_along(W, radiance, axis=...)
+
+coarse = rb.Space.boxes(np.arange(300, 310.01, 0.5))
+binned = rb.regrid(radiance, hires, coarse)  # conservative; bounded=True to avoid overshoot
+```
+
+## Spaces
+
+Elements are shapes, not densities: everything peaks at 1. Normalization is a property of the
+operation (`measure(..., normalization="integral" | "rowsum" | "none")`), not of the element, so
+the same space can serve as a basis in one call and as kernels in another. Per-element widths
+can be scalars or arrays.
+
+**Bases**
+
+- `Space.hats(nodes)`: piecewise linear; coefficients are values at the nodes. The basis for a
+  function known by samples.
+- `Space.boxes(edges)`, `Space.boxes_from_centers(centers)`: piecewise constant; coefficients
+  are bin averages.
+- `Space.bsplines_clamped(breakpoints, degree)`, `Space.bsplines(knots, degree)`: B-splines of
+  degree 0 to 3.
+- `Space.deltas(x)`: point evaluation as kernels, point masses as a basis.
+
+**Line shapes** (`cutoff` is the half width of the truncated support, in the unit given)
+
+| constructor | shape | cutoff unit |
+|---|---|---|
+| `gaussians(c, sigma= \| fwhm=)` | Gaussian | σ (default 6) |
+| `lorentzians(c, hwhm= \| fwhm=)` | Lorentzian | HWHM (100) |
+| `voigts(c, sigma= \| fwhm_gaussian=, gamma= \| fwhm_lorentzian=)` | Voigt (Faddeeva, ~3e-15) | Voigt HWHM (100) |
+| `pseudo_voigts(c, fwhm=, eta=)` | η·L + (1−η)·G | HWHM (100) |
+| `super_gaussians(c, fwhm=, power=, asymmetry=0)` | exp(−ln2·\|2t/w\|^p), optionally asymmetric | HWHM per side (6) |
+| `smoothed_boxes(c, width=, sigma= \| fwhm=)` | slit ⊗ Gaussian | σ past the box edge (6) |
+| `fts(c, max_opd=, apodization=)` | FTS line shape: `none` (sinc), `triangle` (sinc²), `hann`, `hamming`, `blackman`, `blackman_harris`, `norton_beer_weak/medium/strong`, or custom cosine-sum / Norton–Beer coefficients | 1/(2·max_opd) (100) |
+| `rectangles(c, width=)`, `triangles(c, fwhm=)`, `trapezoids(c, top_width=, bottom_width=)` | exact piecewise linear | |
+| `shifted(c, shape_x, shape_y, stretch=1, interp="linear" \| "pchip")` | one tabulated shape, stored once | |
+| `tabulated(c, x, y, interp=)` | a tabulated shape per channel | |
+
+`examples/lineshapes.py` plots all of them.
+
+## Regridding
+
+- `rb.regrid(data, src, dst, axis, method=...)`: `"project"` (conservative, default),
+  `"measure"` (`dst` as averaging kernels), `"interpolate"`, or `"fit"` (smooth conservative
+  upsampling of bin averages onto a spline `dst`).
+  - `bounded=True` gives the best L2 approximation that conserves the integral and creates no new
+    extrema: each coefficient stays within the range of the inputs it overlaps. It solves a
+    small banded quadratic program exactly, so corrections stay local.
+    `bounded="positive"` and `bounded=(lo, hi)` apply global bounds instead.
+  - `skipna=True` handles missing data.
+  - `weight="cos_lat_deg"` gives area weighting in latitude.
+- `rb.regrid_nd(data, {axis: (src, dst[, weight]), ...})`: tensor-product grids, one axis at a
+  time (exact for separable grids).
+- `rebasis.xarray.regrid(ds, {"lat": new_lat, "lon": new_lon}, weight={"lat": "cos_lat_deg"})`
+  regrids DataArrays and Datasets by dimension name.
+- `rb.Fit(kernels, model, smoothing=..., penalty="derivative", order=2)` is the general
+  penalized least-squares fit. The penalty is ∫(f⁽ʳ⁾)² (a smoothing spline) or coefficient
+  differences (P-splines).
+
+## Derivatives with respect to line-shape parameters
+
+`rb.measure_derivative(kernels, basis, parameter)` returns `(W, dW)`, where `dW` is ∂W/∂p with
+row i differentiated with respect to kernel i's parameter. For a spectrum `f`, `dW @ f` is the
+Jacobian of the measurements with respect to per-channel parameters (diagonal), or with respect
+to one parameter shared by all channels. The derivatives are exact: they include the moving
+truncation edges and the normalization, and they agree with finite differences to the accuracy
+of the finite differences.
+
+| parameter | kernels |
+|---|---|
+| `center` | all (spectral shift) |
+| `scale` | all but deltas: width · ∂/∂width, every width scaled together (squeeze or stretch) |
+| `sigma` | Gaussian, Voigt, smoothed box |
+| `gamma` | Lorentzian, Voigt |
+| `eta` | pseudo-Voigt |
+| `power`, `asymmetry` | super-Gaussian |
+| `half_width` | smoothed box |
+
+## Wavelength and wavenumber
+
+`space.to_wavenumber(jacobian=...)` (and `to_wavelength`, `reciprocal`, `affine`) uses each
+element exactly in another coordinate, e.g. an instrument response in nm against a model grid in
+cm⁻¹: `rb.measure(ils_nm.to_wavenumber(jacobian=True), hires_cminv)`. The required `jacobian` is
+`True` for kernels and spectral densities, `False` for plain functions.
+
+## Development
+
+```bash
+uv sync            # builds the extension (release profile)
+uv run pytest
+cargo test -p rebasis
+uv run --extra docs sphinx-build -W -b html docs docs/_build/html
+```
+
+The Rust crate `rebasis` (in `rebasis/`) has no Python dependency and is intended to be used
+directly by sasktran2; `rebasis-py/` holds the pyo3 bindings. `examples/` has a benchmark and
+figure scripts.
+

pyrebasis-0.1.0/README.md

@@ -0,0 +1,135 @@
+# rebasis
+
+[![CI](https://github.com/usask-arg/rebasis/actions/workflows/ci.yml/badge.svg)](https://github.com/usask-arg/rebasis/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-usask--arg.github.io%2Frebasis-blue)](https://usask-arg.github.io/rebasis/)
+
+Linear maps between function bases, with a Rust core and a Python interface.
+
+```bash
+pip install pyrebasis        # import rebasis
+cargo add rebasis            # the Rust crate
+```
+
+The PyPI distribution is `pyrebasis` because `rebasis` there is an unrelated project; the import
+name is `rebasis`. Documentation: <https://usask-arg.github.io/rebasis/>.
+
+A quantity is represented as f(x) = Σ_j f_j B_j(x). rebasis computes the sparse matrices that
+turn the coefficients f_j into:
+
+| operation | what it computes | typical use |
+|---|---|---|
+| `measure(kernels, basis)` | g_i = ∫ K_i f / ∫ K_i | instrument line shape applied to a high-resolution spectrum |
+| `evaluate(basis, x)` | g_i = f(x_i) | interpolation, plotting a reconstruction |
+| `project(src, dst)` | best L2 fit Σ g_i G_i ≈ f | conservative regridding, up- or down-sampling |
+| `Fit(kernels, model)` | model coefficients whose measurements match data | smooth conservative upsampling, smoothing splines, inverting `measure` |
+
+Inner products are exact for piecewise polynomials (boxes, hats, B-splines, tabulated shapes) and
+accurate to rounding for the analytic line shapes; there are no tolerance or resolution
+parameters.
+
+```python
+import numpy as np
+import rebasis as rb
+
+wavel = np.linspace(300, 310, 100_001)  # high-resolution model grid
+hires = rb.Space.hats(wavel)  # radiance = linear interpolant of the samples
+ils = rb.Space.voigts(np.arange(301, 309, 0.1), fwhm_gaussian=0.4, fwhm_lorentzian=0.05)
+
+W = rb.measure(ils, hires)  # scipy.sparse.csr_array, (80, 100001)
+measured = W @ radiance  # or rb.apply_along(W, radiance, axis=...)
+
+coarse = rb.Space.boxes(np.arange(300, 310.01, 0.5))
+binned = rb.regrid(radiance, hires, coarse)  # conservative; bounded=True to avoid overshoot
+```
+
+## Spaces
+
+Elements are shapes, not densities: everything peaks at 1. Normalization is a property of the
+operation (`measure(..., normalization="integral" | "rowsum" | "none")`), not of the element, so
+the same space can serve as a basis in one call and as kernels in another. Per-element widths
+can be scalars or arrays.
+
+**Bases**
+
+- `Space.hats(nodes)`: piecewise linear; coefficients are values at the nodes. The basis for a
+  function known by samples.
+- `Space.boxes(edges)`, `Space.boxes_from_centers(centers)`: piecewise constant; coefficients
+  are bin averages.
+- `Space.bsplines_clamped(breakpoints, degree)`, `Space.bsplines(knots, degree)`: B-splines of
+  degree 0 to 3.
+- `Space.deltas(x)`: point evaluation as kernels, point masses as a basis.
+
+**Line shapes** (`cutoff` is the half width of the truncated support, in the unit given)
+
+| constructor | shape | cutoff unit |
+|---|---|---|
+| `gaussians(c, sigma= \| fwhm=)` | Gaussian | σ (default 6) |
+| `lorentzians(c, hwhm= \| fwhm=)` | Lorentzian | HWHM (100) |
+| `voigts(c, sigma= \| fwhm_gaussian=, gamma= \| fwhm_lorentzian=)` | Voigt (Faddeeva, ~3e-15) | Voigt HWHM (100) |
+| `pseudo_voigts(c, fwhm=, eta=)` | η·L + (1−η)·G | HWHM (100) |
+| `super_gaussians(c, fwhm=, power=, asymmetry=0)` | exp(−ln2·\|2t/w\|^p), optionally asymmetric | HWHM per side (6) |
+| `smoothed_boxes(c, width=, sigma= \| fwhm=)` | slit ⊗ Gaussian | σ past the box edge (6) |
+| `fts(c, max_opd=, apodization=)` | FTS line shape: `none` (sinc), `triangle` (sinc²), `hann`, `hamming`, `blackman`, `blackman_harris`, `norton_beer_weak/medium/strong`, or custom cosine-sum / Norton–Beer coefficients | 1/(2·max_opd) (100) |
+| `rectangles(c, width=)`, `triangles(c, fwhm=)`, `trapezoids(c, top_width=, bottom_width=)` | exact piecewise linear | |
+| `shifted(c, shape_x, shape_y, stretch=1, interp="linear" \| "pchip")` | one tabulated shape, stored once | |
+| `tabulated(c, x, y, interp=)` | a tabulated shape per channel | |
+
+`examples/lineshapes.py` plots all of them.
+
+## Regridding
+
+- `rb.regrid(data, src, dst, axis, method=...)`: `"project"` (conservative, default),
+  `"measure"` (`dst` as averaging kernels), `"interpolate"`, or `"fit"` (smooth conservative
+  upsampling of bin averages onto a spline `dst`).
+  - `bounded=True` gives the best L2 approximation that conserves the integral and creates no new
+    extrema: each coefficient stays within the range of the inputs it overlaps. It solves a
+    small banded quadratic program exactly, so corrections stay local.
+    `bounded="positive"` and `bounded=(lo, hi)` apply global bounds instead.
+  - `skipna=True` handles missing data.
+  - `weight="cos_lat_deg"` gives area weighting in latitude.
+- `rb.regrid_nd(data, {axis: (src, dst[, weight]), ...})`: tensor-product grids, one axis at a
+  time (exact for separable grids).
+- `rebasis.xarray.regrid(ds, {"lat": new_lat, "lon": new_lon}, weight={"lat": "cos_lat_deg"})`
+  regrids DataArrays and Datasets by dimension name.
+- `rb.Fit(kernels, model, smoothing=..., penalty="derivative", order=2)` is the general
+  penalized least-squares fit. The penalty is ∫(f⁽ʳ⁾)² (a smoothing spline) or coefficient
+  differences (P-splines).
+
+## Derivatives with respect to line-shape parameters
+
+`rb.measure_derivative(kernels, basis, parameter)` returns `(W, dW)`, where `dW` is ∂W/∂p with
+row i differentiated with respect to kernel i's parameter. For a spectrum `f`, `dW @ f` is the
+Jacobian of the measurements with respect to per-channel parameters (diagonal), or with respect
+to one parameter shared by all channels. The derivatives are exact: they include the moving
+truncation edges and the normalization, and they agree with finite differences to the accuracy
+of the finite differences.
+
+| parameter | kernels |
+|---|---|
+| `center` | all (spectral shift) |
+| `scale` | all but deltas: width · ∂/∂width, every width scaled together (squeeze or stretch) |
+| `sigma` | Gaussian, Voigt, smoothed box |
+| `gamma` | Lorentzian, Voigt |
+| `eta` | pseudo-Voigt |
+| `power`, `asymmetry` | super-Gaussian |
+| `half_width` | smoothed box |
+
+## Wavelength and wavenumber
+
+`space.to_wavenumber(jacobian=...)` (and `to_wavelength`, `reciprocal`, `affine`) uses each
+element exactly in another coordinate, e.g. an instrument response in nm against a model grid in
+cm⁻¹: `rb.measure(ils_nm.to_wavenumber(jacobian=True), hires_cminv)`. The required `jacobian` is
+`True` for kernels and spectral densities, `False` for plain functions.
+
+## Development
+
+```bash
+uv sync            # builds the extension (release profile)
+uv run pytest
+cargo test -p rebasis
+uv run --extra docs sphinx-build -W -b html docs docs/_build/html
+```
+
+The Rust crate `rebasis` (in `rebasis/`) has no Python dependency and is intended to be used
+directly by sasktran2; `rebasis-py/` holds the pyo3 bindings. `examples/` has a benchmark and
+figure scripts.