beta-parameterization 3.0.0__tar.gz → 4.0.1__tar.gz

{beta_parameterization-3.0.0 → beta_parameterization-4.0.1}/CHANGELOG.md

@@ -3,6 +3,96 @@
 All notable changes to this project are documented here. Versions follow
 semantic versioning; the format follows [Keep a Changelog](https://keepachangelog.com).
 
+## 4.0.0
+
+Adoption of the two-tier shape parameterization contract on
+`shape_core_mod` (fortran-foundations 3.0.0). The incremental tier is gone:
+one-shot functions plus one read-only cache, built once and shared across
+threads. Every public surface — Fortran, C, C++, Python — changes; nothing in
+3.x compiles against 4.0.0 unchanged.
+
+### Changed (breaking)
+
+- **One cache type.** `tables_t` is renamed `cache_t`; the mutable 3.x
+  `cache_t`, `cache_init_shared_s`, the shared-tables mode and the `target`
+  requirement are removed. `cache_init_s(cache, max_params, thetas, status)`.
+  C: `beta_param_cache_create(max_params, thetas, n_thetas, status)`; the
+  `tables` handle and `beta_param_cache_create_shared` are removed. C++:
+  `Tables` is removed, `Cache(max_params, thetas)`. Python:
+  `Cache(max_params, thetas)`.
+- **Caches are immutable and shareable.** Every compute takes the cache
+  read-only (`intent(in)`, `const` handle, `const` method) and is `pure` in
+  Fortran. Any number of threads may compute on one cache. The 3.0.0
+  thread-confinement rule is withdrawn.
+- **Options are per call.** `conserve_volume` and `apply_com` move from cache
+  creation to each compute, after `params` and before the outputs. One cache
+  serves every combination. `cache_radius_grid_unchecked_s` takes `apply_com`
+  only: it never volume-scales.
+- **`max_params` replaces `n_params`.** A cache accepts any vector of
+  `1 .. max_params` entries, up to 64 (the 8-parameter cap is gone). Missing
+  trailing parameters are zero.
+- **Node sets are built from a cache**:
+  `node_set_build_s(node_set, cache, thetas, status)`; argument order of the
+  node compute is `(cache, params, node_set, conserve_volume, apply_com, radii,
+  dr_dthetas, status)`. A node set serves a cache when it was built from a
+  cache with at least that cache's `max_params`
+  (`BETA_PARAM_ERROR_NODE_SET_MISMATCH` otherwise) — judged on the two
+  objects, no longer on the vector length.
+- **Status codes.** Code 6 (`SHAPE_ERROR_TABLES_NOT_INITIALIZED`) is retired
+  and never reused; an uninitialized cache passed to `node_set_build_s` now
+  returns 2. An empty one-shot vector returns 4 (was 5). `max_params > 64` at
+  init returns 1. C: a negative `n_thetas` returns 3 (was 5).
+- **Getters.** `cache_n_params_f` becomes `cache_max_params_f`; C++
+  `Cache::n_params()` becomes `max_params()`; Python `Cache.n_params` becomes
+  `max_params`, and the `conserve_volume` / `apply_com` attributes are gone.
+
+### Removed
+
+- The recompute engine and everything built on it: `cache_recompute_count_f`,
+  the `BETA_PARAM_I_*` indices, the dependency map, the minimality test suite.
+- `SHAPE_CACHE_MAX_PARAMS`, `SHAPE_STANDALONE_MAX_PARAMS`
+  (use `SHAPE_MAX_PARAMS`), `BETA_PARAM_CACHE_MAX_PARAMS`, Python
+  `CACHE_MAX_PARAMS`, `Status.tables_not_initialized`.
+
+### Added
+
+- **Trailing zeros are trimmed.** Both tiers reduce a vector to its last
+  nonzero entry before any arithmetic, so a short vector and its zero-padded
+  form return identical bits. Interior zeros are kept.
+- **README.md** with the shape definition, both tiers in Fortran, C and
+  Python, build instructions and version pins.
+- **CI on push and pull request** (`.github/workflows/tests.yml`): every suite
+  in Debug and Release, pytest against the built library, and the
+  manylinux2014 wheel build.
+- Test suites for the contract's families: `equivalence` (one-shot ≡ cached,
+  short ≡ zero-padded), `statelessness`, `boundary`, and a concurrency suite
+  running eight threads on one shared cache.
+
+### Fixed
+
+- **COM correction on a non-positive volume integral.** With `apply_com`, a
+  shape far outside the valid domain (for example `[0, -20]`) made the Newton
+  step take the cube root of a negative number: a floating-point trap in Debug
+  builds, and in Release a result that depended on a NaN comparison. The
+  iteration now reports non-convergence (103). Without `apply_com` such a
+  shape is still rejected by the validity gate (100).
+- **C API stack overflow on a large wrong size.** Marshalling buffers were
+  caller-sized automatic arrays; under Release a large wrong size argument
+  overflowed the stack before the size was checked. They are heap-allocated
+  now: the call returns `BETA_PARAM_ERROR_INVALID_BUFFER_SIZE`.
+- **Allocation failure in cache or node-set build** returns
+  `SHAPE_ERROR_INVALID_GRID` (3) instead of terminating the process.
+
+### Build
+
+- The library's own objects are compiled with `-fno-lto`. Under
+  `-flto -ffast-math` the summation kernels were inlined into each caller and
+  optimized per call site, so the same call could return different last bits
+  from different call sites. Without LTO every caller executes one machine-code
+  body per kernel, which is what makes the bitwise guarantees hold. Cost: about
+  30% on shape evaluation time. Consumers keep LTO for their own code.
+- fortran-foundations pin 2.4.0 → 3.0.0.
+
 ## 3.0.0
 
 Adoption of the three-tier shape parameterization contract against

{beta_parameterization-3.0.0 → beta_parameterization-4.0.1}/CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.20)
 include(FetchContent)
 
 project(beta-parameterization
-        VERSION 3.0.0
+        VERSION 4.0.0
         LANGUAGES Fortran CXX
         DESCRIPTION "Beta parameterization for nuclear physics applications"
 )
@@ -14,19 +14,19 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 
 # --- Fetch GCC compiler options package ---
 FetchContent_Declare(
-        GCC-Compiler-Options
-        GIT_REPOSITORY https://github.com/AleksanderAugustyn/GCC-Compiler-Options.git
+        gcc-compiler-options
+        GIT_REPOSITORY https://github.com/AleksanderAugustyn/gcc-compiler-options.git
         GIT_TAG 2.0.0
 )
-FetchContent_MakeAvailable(GCC-Compiler-Options)
+FetchContent_MakeAvailable(gcc-compiler-options)
 
 # --- Fetch foundational Fortran modules ---
 FetchContent_Declare(
-        Fortran-Foundations
-        GIT_REPOSITORY https://github.com/AleksanderAugustyn/Fortran-Foundations.git
-        GIT_TAG 2.4.0
+        fortran-foundations
+        GIT_REPOSITORY https://github.com/AleksanderAugustyn/fortran-foundations.git
+        GIT_TAG 3.0.0
 )
-FetchContent_MakeAvailable(Fortran-Foundations)
+FetchContent_MakeAvailable(fortran-foundations)
 
 # --- Preprocessor & build type ---
 set(CMAKE_Fortran_PREPROCESS ON)
@@ -35,7 +35,7 @@ if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
     set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "RelWithDebInfo" "Release")
 endif ()
 
-# --- Compiler flags via GCC-Compiler-Options ---
+# --- Compiler flags via gcc-compiler-options ---
 include(GCCCompilerOptions/FortranCompilerOptions)
 create_fortran_library_interface(TARGET beta_parameterization_flags)
 
@@ -46,6 +46,16 @@ set(BETA_PARAM_SOURCES
         src/beta_parameterization_c_api_mod.f08
 )
 
+# --- No LTO for the library's own objects ---
+# Release builds use -flto=auto -ffast-math. With LTO the summation kernels are
+# inlined into every caller and optimized per call site, so the same call can
+# return different last bits from different call sites — which breaks the
+# contract's bitwise guarantees (one-shot == cached, statelessness,
+# concurrency). Compiled without LTO, each kernel is ONE machine-code body that
+# every caller executes. Consumers keep LTO for their own code.
+# Source-file property so it lands after the flags-interface options (last wins).
+set_source_files_properties(${BETA_PARAM_SOURCES} PROPERTIES COMPILE_OPTIONS "-fno-lto")
+
 # --- Static library target ---
 add_library(beta_parameterization STATIC ${BETA_PARAM_SOURCES})
 target_link_libraries(beta_parameterization
@@ -118,8 +128,8 @@ set_target_properties(beta_param_test_utils PROPERTIES
 target_include_directories(beta_param_test_utils PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/mod_files_tests>)
 
-set(BETA_PARAM_TEST_SUITES status lifecycle resolve outputs standalone bitwise minimality
-        interleave boundary property golden)
+set(BETA_PARAM_TEST_SUITES status lifecycle resolve outputs standalone property golden
+        equivalence statelessness boundary)
 foreach (suite IN LISTS BETA_PARAM_TEST_SUITES)
     add_executable(beta_param_${suite}_test tests/beta_param_${suite}_test.f08)
     target_link_libraries(beta_param_${suite}_test PRIVATE
@@ -159,7 +169,8 @@ add_executable(c_api_smoke_test tests/c_api_smoke_test.cpp)
 target_link_libraries(c_api_smoke_test PRIVATE beta_parameterization_cxx)
 add_test(NAME c_api_smoke COMMAND c_api_smoke_test)
 
-# Thread model of 3.0.0: shared tables, per-thread caches, via the C++ wrapper.
+# Contract family 3 (concurrency): many threads on one shared cache, via the
+# C++ wrapper.
 find_package(Threads REQUIRED)
 add_executable(thread_stress_test tests/thread_stress_test.cpp)
 target_link_libraries(thread_stress_test PRIVATE

beta_parameterization-4.0.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: beta-parameterization
+Version: 4.0.1
+Summary: Python bindings for the beta (Legendre) nuclear-shape parameterization library
+License-Expression: MIT
+License-File: LICENSE
+Project-URL: Homepage, https://github.com/AleksanderAugustyn/beta-parameterization
+Project-URL: Repository, https://github.com/AleksanderAugustyn/beta-parameterization
+Project-URL: Changelog, https://github.com/AleksanderAugustyn/beta-parameterization/blob/master/CHANGELOG.md
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Description-Content-Type: text/markdown
+
+# beta-parameterization
+
+Axially symmetric nuclear shapes in the spherical-harmonic (beta) expansion: a Fortran 2018 library with a C API, a C++20 wrapper and a Python wheel. It implements the two-tier shape parameterization contract shared with its sibling libraries.
+
+## The shape
+
+The surface radius, in units of the spherical radius R₀, is
+
+    R(θ) = c · [ 1 + Σ_{λ=1}^{n} β_λ · C_λ · P_λ(cos θ) ],    C_λ = √((2λ+1) / 4π)
+
+so that `C_λ · P_λ(cos θ)` is the spherical harmonic Y_λ0. `params(λ)` is β_λ0; position λ always means order λ. Up to 64 orders are supported.
+
+Two per-call options change the shape:
+
+- `apply_com` — β₁ is replaced by the value that puts the centre of mass at the origin (Newton iteration, tolerance 10⁻⁵ R₀).
+- `conserve_volume` — the scale `c = (2 / ∫ R³ d cos θ)^(1/3)` restores the volume of the unit sphere. Without it, `c = 1`.
+
+A shape is valid when R > 10⁻⁶ at both poles and on an internal 512-node Gauss-Legendre grid. An invalid shape returns a status code and zero-filled outputs.
+
+## Two tiers
+
+1. **One-shot.** One call computes one shape. All workspace is internal and discarded on return. For scripts and one-off plots.
+2. **Read-only cache.** Build a cache once for a theta grid, then request any number of shapes against it. The cache holds only what does not depend on the parameters (Legendre tables, quadrature). It is immutable after creation and may be shared across threads. For loops and hot paths.
+
+Both tiers return bitwise-identical results. Nothing parameter-dependent is stored: every call is independent of the calls before it.
+
+Rules common to both tiers:
+
+- A cache accepts `1 .. max_params` parameters per call; a one-shot call accepts `1 .. 64`.
+- Missing trailing parameters are zero. A short vector and its zero-padded form give identical bits.
+- Thetas are in radians, at least two, none at a pole (the open grid `θ_i = i·π/(n+1)` is the usual choice). Pole radii come from `resolve_shape`.
+- Inputs must be finite and of physical magnitude. Release builds use fast-math and cannot detect NaN, and with `apply_com` the quadrature overflows for |β| beyond about 10⁷⁰.
+- Every output is zero-filled on a nonzero status.
+
+### Fortran
+
+```fortran
+program beta_example
+    use precision_utilities_mod, only: ik, rk
+    use beta_parameterization_mod, only: cache_t, cache_init_s, cache_free_s, &
+            cache_radius_grid_s, cache_resolve_shape_s, &
+            compute_radius_grid_standalone_s, SHAPE_VALID
+    implicit none
+
+    integer(kind = ik), parameter :: N = 180_ik
+    real(kind = rk), parameter :: PI = 3.141592653589793_rk
+    type(cache_t) :: cache
+    real(kind = rk) :: thetas(N), radii(N)
+    real(kind = rk) :: beta10, r_north, r_south, volume_factor
+    integer(kind = ik) :: i, status
+
+    do i = 1_ik, N
+        thetas(i) = real(i, rk) * PI / real(N + 1_ik, rk)   ! open grid: no pole nodes
+    end do
+
+    ! Tier 1: one-shot. params = (beta1, beta2), both options on.
+    call compute_radius_grid_standalone_s([0.0_rk, 0.25_rk], thetas, .true., .true., &
+            radii, status)
+    if (status /= SHAPE_VALID) error stop 'one-shot failed'
+
+    ! Tier 2: build once, share, compute many.
+    call cache_init_s(cache, 8_ik, thetas, status)          ! max_params = 8
+    call cache_radius_grid_s(cache, [0.0_rk, 0.25_rk], .true., .true., radii, status)
+    call cache_resolve_shape_s(cache, [0.0_rk, 0.25_rk], .true., .true., &
+            beta10, r_north, r_south, volume_factor, status)
+    call cache_free_s(cache)
+end program beta_example
+```
+
+Cached outputs: `cache_radius_grid_s`, `cache_radius_and_derivative_s`, `cache_resolve_shape_s` (corrected β₁, pole radii, volume factor), `cache_node_radius_and_derivative_s` (radius and derivative at a `node_set_t`: extra thetas built from the cache with `node_set_build_s`), and `cache_radius_grid_unchecked_s` (no validity gate and no volume scaling: the outline of a shape the checked path rejects). To evaluate several theta grids in one call, build one node set over their concatenation.
+
+### C
+
+```c
+#include "beta_parameterization.h"
+#include <stdio.h>
+
+int main(void) {
+    enum { N = 180 };
+    const double pi = 3.141592653589793;
+    double thetas[N], radii[N];
+    const double params[2] = {0.0, 0.25};
+    for (int i = 0; i < N; ++i) thetas[i] = (i + 1) * pi / (N + 1);
+
+    /* Tier 1: one-shot. */
+    int status = beta_param_radius_grid_standalone(params, 2, thetas, N, 1, 1, radii);
+    if (status != BETA_PARAM_VALID) {
+        printf("%s\n", beta_param_status_message(status));
+        return 1;
+    }
+
+    /* Tier 2: build once, share, compute many. */
+    beta_param_cache_t* cache = beta_param_cache_create(8, thetas, N, &status);
+    if (cache == NULL) {
+        printf("%s\n", beta_param_status_message(status));
+        return 1;
+    }
+    status = beta_param_cache_radius_grid(cache, params, 2, 1, 1, radii, N);
+    beta_param_cache_destroy(cache);
+    return status;
+}
+```
+
+C++20 callers can use the RAII wrapper in `beta_parameterization.hpp` (`beta_param::Cache`, `beta_param::NodeSet`, `const` compute methods, `std::span` arguments).
+
+### Python
+
+```python
+import beta_parameterization as bp
+
+thetas = bp.theta_grid(180)                     # open grid, no pole nodes
+
+# Tier 1: one-shot.
+res = bp.radius_grid([0.0, 0.25], thetas, conserve_volume=True, apply_com=True)
+assert res.ok, res.message
+
+# Tier 2: build once, share, compute many.
+with bp.Cache(8, thetas) as cache:              # max_params = 8
+    res = cache.radius_and_derivative([0.0, 0.25], conserve_volume=True, apply_com=True)
+    shape = cache.resolve_shape([0.0, 0.25], conserve_volume=True, apply_com=True)
+    print(res.radii[:3], shape.volume_factor)
+```
+
+Shape-validation failures come back as results carrying a `Status`; `BetaParamError` is raised only for usage errors (failed create, closed handle, non-1-D input).
+
+## Status codes
+
+| Code | Name | Meaning |
+|---|---|---|
+| 0 | `SHAPE_VALID` | success |
+| 1 | `SHAPE_ERROR_TOO_MANY_PARAMS` | `max_params` or a one-shot vector exceeds 64 |
+| 2 | `SHAPE_ERROR_CACHE_NOT_INITIALIZED` | uninitialized cache (or NULL handle) |
+| 3 | `SHAPE_ERROR_INVALID_GRID` | fewer than 2 thetas, or a table that cannot be allocated |
+| 4 | `SHAPE_ERROR_WRONG_PARAM_COUNT` | vector length outside `1..max_params`, or an empty one-shot vector |
+| 5 | `SHAPE_ERROR_INVALID_INIT` | `max_params < 1` |
+| 100 | `BETA_PARAM_ERROR_NORTH_POLE` | radius not positive at θ = 0 |
+| 101 | `BETA_PARAM_ERROR_SOUTH_POLE` | radius not positive at θ = π |
+| 102 | `BETA_PARAM_ERROR_INTERIOR_NEGATIVE` | radius not positive in the interior |
+| 103 | `BETA_PARAM_ERROR_COM_NOT_CONVERGED` | centre-of-mass correction did not converge |
+| 104 | `BETA_PARAM_ERROR_INVALID_BUFFER_SIZE` | output buffer size does not match the theta or node count |
+| 105 | `BETA_PARAM_ERROR_POLE_NODE` | a theta at or beyond a pole |
+| 106 | `BETA_PARAM_ERROR_NODE_SET_MISMATCH` | node set unbuilt, or built for a smaller cache |
+
+Codes 0–5 are shared by every shape parameterization library; the C header and the Python `Status` enum mirror all of them under `BETA_PARAM_*` names.
+
+## Building
+
+Requires GCC (gfortran, g++) and CMake ≥ 3.20. Dependencies are fetched by CMake.
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+ctest --test-dir build --output-on-failure
+```
+
+As a CMake dependency:
+
+```cmake
+FetchContent_Declare(
+        beta-parameterization
+        GIT_REPOSITORY https://github.com/AleksanderAugustyn/beta-parameterization.git
+        GIT_TAG 4.0.0
+)
+FetchContent_MakeAvailable(beta-parameterization)
+target_link_libraries(my_target PRIVATE BetaParameterization::beta_parameterization)
+```
+
+Targets: `BetaParameterization::beta_parameterization` (static, Fortran), `::beta_parameterization_shared` (shared, C API), `::beta_parameterization_cxx` (header-only C++ wrapper over the shared library).
+
+Python:
+
+```bash
+pip install beta-parameterization==4.0.0
+```
+
+The wheel is self-contained (manylinux2014, x86-64). To run the Python tests against a local build instead: `BETA_PARAM_LIB=$PWD/build/libbeta_parameterization.so PYTHONPATH=python python -m pytest python/tests`.
+
+## Dependencies
+
+| Dependency | Version |
+|---|---|
+| [fortran-foundations](https://github.com/AleksanderAugustyn/fortran-foundations) | 3.0.0 |
+| [gcc-compiler-options](https://github.com/AleksanderAugustyn/gcc-compiler-options) | 2.0.0 |
+| numpy (wheel only) | ≥ 1.21 |
+
+## Design
+
+- **Stateless computes.** A cache holds only parameter-independent tables. Every compute takes it read-only and is `pure`; per-call scratch lives on the stack. One cache serves every thread and every option combination.
+- **One pipeline.** A one-shot call builds a local cache and runs the cached routine, so the two tiers cannot drift apart.
+- **Reproducible bits.** The library's own objects are compiled without link-time optimization. Under `-flto -ffast-math` a kernel inlined into two call sites may round differently in each; without LTO every caller executes the same machine code, and equal inputs give equal bits.
+- **No stops.** Every failure is a status code; nothing in the library calls `error stop`.

beta_parameterization-4.0.1/README.md

@@ -0,0 +1,191 @@
+# beta-parameterization
+
+Axially symmetric nuclear shapes in the spherical-harmonic (beta) expansion: a Fortran 2018 library with a C API, a C++20 wrapper and a Python wheel. It implements the two-tier shape parameterization contract shared with its sibling libraries.
+
+## The shape
+
+The surface radius, in units of the spherical radius R₀, is
+
+    R(θ) = c · [ 1 + Σ_{λ=1}^{n} β_λ · C_λ · P_λ(cos θ) ],    C_λ = √((2λ+1) / 4π)
+
+so that `C_λ · P_λ(cos θ)` is the spherical harmonic Y_λ0. `params(λ)` is β_λ0; position λ always means order λ. Up to 64 orders are supported.
+
+Two per-call options change the shape:
+
+- `apply_com` — β₁ is replaced by the value that puts the centre of mass at the origin (Newton iteration, tolerance 10⁻⁵ R₀).
+- `conserve_volume` — the scale `c = (2 / ∫ R³ d cos θ)^(1/3)` restores the volume of the unit sphere. Without it, `c = 1`.
+
+A shape is valid when R > 10⁻⁶ at both poles and on an internal 512-node Gauss-Legendre grid. An invalid shape returns a status code and zero-filled outputs.
+
+## Two tiers
+
+1. **One-shot.** One call computes one shape. All workspace is internal and discarded on return. For scripts and one-off plots.
+2. **Read-only cache.** Build a cache once for a theta grid, then request any number of shapes against it. The cache holds only what does not depend on the parameters (Legendre tables, quadrature). It is immutable after creation and may be shared across threads. For loops and hot paths.
+
+Both tiers return bitwise-identical results. Nothing parameter-dependent is stored: every call is independent of the calls before it.
+
+Rules common to both tiers:
+
+- A cache accepts `1 .. max_params` parameters per call; a one-shot call accepts `1 .. 64`.
+- Missing trailing parameters are zero. A short vector and its zero-padded form give identical bits.
+- Thetas are in radians, at least two, none at a pole (the open grid `θ_i = i·π/(n+1)` is the usual choice). Pole radii come from `resolve_shape`.
+- Inputs must be finite and of physical magnitude. Release builds use fast-math and cannot detect NaN, and with `apply_com` the quadrature overflows for |β| beyond about 10⁷⁰.
+- Every output is zero-filled on a nonzero status.
+
+### Fortran
+
+```fortran
+program beta_example
+    use precision_utilities_mod, only: ik, rk
+    use beta_parameterization_mod, only: cache_t, cache_init_s, cache_free_s, &
+            cache_radius_grid_s, cache_resolve_shape_s, &
+            compute_radius_grid_standalone_s, SHAPE_VALID
+    implicit none
+
+    integer(kind = ik), parameter :: N = 180_ik
+    real(kind = rk), parameter :: PI = 3.141592653589793_rk
+    type(cache_t) :: cache
+    real(kind = rk) :: thetas(N), radii(N)
+    real(kind = rk) :: beta10, r_north, r_south, volume_factor
+    integer(kind = ik) :: i, status
+
+    do i = 1_ik, N
+        thetas(i) = real(i, rk) * PI / real(N + 1_ik, rk)   ! open grid: no pole nodes
+    end do
+
+    ! Tier 1: one-shot. params = (beta1, beta2), both options on.
+    call compute_radius_grid_standalone_s([0.0_rk, 0.25_rk], thetas, .true., .true., &
+            radii, status)
+    if (status /= SHAPE_VALID) error stop 'one-shot failed'
+
+    ! Tier 2: build once, share, compute many.
+    call cache_init_s(cache, 8_ik, thetas, status)          ! max_params = 8
+    call cache_radius_grid_s(cache, [0.0_rk, 0.25_rk], .true., .true., radii, status)
+    call cache_resolve_shape_s(cache, [0.0_rk, 0.25_rk], .true., .true., &
+            beta10, r_north, r_south, volume_factor, status)
+    call cache_free_s(cache)
+end program beta_example
+```
+
+Cached outputs: `cache_radius_grid_s`, `cache_radius_and_derivative_s`, `cache_resolve_shape_s` (corrected β₁, pole radii, volume factor), `cache_node_radius_and_derivative_s` (radius and derivative at a `node_set_t`: extra thetas built from the cache with `node_set_build_s`), and `cache_radius_grid_unchecked_s` (no validity gate and no volume scaling: the outline of a shape the checked path rejects). To evaluate several theta grids in one call, build one node set over their concatenation.
+
+### C
+
+```c
+#include "beta_parameterization.h"
+#include <stdio.h>
+
+int main(void) {
+    enum { N = 180 };
+    const double pi = 3.141592653589793;
+    double thetas[N], radii[N];
+    const double params[2] = {0.0, 0.25};
+    for (int i = 0; i < N; ++i) thetas[i] = (i + 1) * pi / (N + 1);
+
+    /* Tier 1: one-shot. */
+    int status = beta_param_radius_grid_standalone(params, 2, thetas, N, 1, 1, radii);
+    if (status != BETA_PARAM_VALID) {
+        printf("%s\n", beta_param_status_message(status));
+        return 1;
+    }
+
+    /* Tier 2: build once, share, compute many. */
+    beta_param_cache_t* cache = beta_param_cache_create(8, thetas, N, &status);
+    if (cache == NULL) {
+        printf("%s\n", beta_param_status_message(status));
+        return 1;
+    }
+    status = beta_param_cache_radius_grid(cache, params, 2, 1, 1, radii, N);
+    beta_param_cache_destroy(cache);
+    return status;
+}
+```
+
+C++20 callers can use the RAII wrapper in `beta_parameterization.hpp` (`beta_param::Cache`, `beta_param::NodeSet`, `const` compute methods, `std::span` arguments).
+
+### Python
+
+```python
+import beta_parameterization as bp
+
+thetas = bp.theta_grid(180)                     # open grid, no pole nodes
+
+# Tier 1: one-shot.
+res = bp.radius_grid([0.0, 0.25], thetas, conserve_volume=True, apply_com=True)
+assert res.ok, res.message
+
+# Tier 2: build once, share, compute many.
+with bp.Cache(8, thetas) as cache:              # max_params = 8
+    res = cache.radius_and_derivative([0.0, 0.25], conserve_volume=True, apply_com=True)
+    shape = cache.resolve_shape([0.0, 0.25], conserve_volume=True, apply_com=True)
+    print(res.radii[:3], shape.volume_factor)
+```
+
+Shape-validation failures come back as results carrying a `Status`; `BetaParamError` is raised only for usage errors (failed create, closed handle, non-1-D input).
+
+## Status codes
+
+| Code | Name | Meaning |
+|---|---|---|
+| 0 | `SHAPE_VALID` | success |
+| 1 | `SHAPE_ERROR_TOO_MANY_PARAMS` | `max_params` or a one-shot vector exceeds 64 |
+| 2 | `SHAPE_ERROR_CACHE_NOT_INITIALIZED` | uninitialized cache (or NULL handle) |
+| 3 | `SHAPE_ERROR_INVALID_GRID` | fewer than 2 thetas, or a table that cannot be allocated |
+| 4 | `SHAPE_ERROR_WRONG_PARAM_COUNT` | vector length outside `1..max_params`, or an empty one-shot vector |
+| 5 | `SHAPE_ERROR_INVALID_INIT` | `max_params < 1` |
+| 100 | `BETA_PARAM_ERROR_NORTH_POLE` | radius not positive at θ = 0 |
+| 101 | `BETA_PARAM_ERROR_SOUTH_POLE` | radius not positive at θ = π |
+| 102 | `BETA_PARAM_ERROR_INTERIOR_NEGATIVE` | radius not positive in the interior |
+| 103 | `BETA_PARAM_ERROR_COM_NOT_CONVERGED` | centre-of-mass correction did not converge |
+| 104 | `BETA_PARAM_ERROR_INVALID_BUFFER_SIZE` | output buffer size does not match the theta or node count |
+| 105 | `BETA_PARAM_ERROR_POLE_NODE` | a theta at or beyond a pole |
+| 106 | `BETA_PARAM_ERROR_NODE_SET_MISMATCH` | node set unbuilt, or built for a smaller cache |
+
+Codes 0–5 are shared by every shape parameterization library; the C header and the Python `Status` enum mirror all of them under `BETA_PARAM_*` names.
+
+## Building
+
+Requires GCC (gfortran, g++) and CMake ≥ 3.20. Dependencies are fetched by CMake.
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+ctest --test-dir build --output-on-failure
+```
+
+As a CMake dependency:
+
+```cmake
+FetchContent_Declare(
+        beta-parameterization
+        GIT_REPOSITORY https://github.com/AleksanderAugustyn/beta-parameterization.git
+        GIT_TAG 4.0.0
+)
+FetchContent_MakeAvailable(beta-parameterization)
+target_link_libraries(my_target PRIVATE BetaParameterization::beta_parameterization)
+```
+
+Targets: `BetaParameterization::beta_parameterization` (static, Fortran), `::beta_parameterization_shared` (shared, C API), `::beta_parameterization_cxx` (header-only C++ wrapper over the shared library).
+
+Python:
+
+```bash
+pip install beta-parameterization==4.0.0
+```
+
+The wheel is self-contained (manylinux2014, x86-64). To run the Python tests against a local build instead: `BETA_PARAM_LIB=$PWD/build/libbeta_parameterization.so PYTHONPATH=python python -m pytest python/tests`.
+
+## Dependencies
+
+| Dependency | Version |
+|---|---|
+| [fortran-foundations](https://github.com/AleksanderAugustyn/fortran-foundations) | 3.0.0 |
+| [gcc-compiler-options](https://github.com/AleksanderAugustyn/gcc-compiler-options) | 2.0.0 |
+| numpy (wheel only) | ≥ 1.21 |
+
+## Design
+
+- **Stateless computes.** A cache holds only parameter-independent tables. Every compute takes it read-only and is `pure`; per-call scratch lives on the stack. One cache serves every thread and every option combination.
+- **One pipeline.** A one-shot call builds a local cache and runs the cached routine, so the two tiers cannot drift apart.
+- **Reproducible bits.** The library's own objects are compiled without link-time optimization. Under `-flto -ffast-math` a kernel inlined into two call sites may round differently in each; without LTO every caller executes the same machine code, and equal inputs give equal bits.
+- **No stops.** Every failure is a status code; nothing in the library calls `error stop`.