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

{beta_parameterization-3.0.0 → beta_parameterization-4.0.0}/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.0}/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-3.0.0 → beta_parameterization-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beta-parameterization
-Version: 3.0.0
+Version: 4.0.0
 Summary: Python bindings for the beta (Legendre) nuclear-shape parameterization library
 License-Expression: MIT
 License-File: LICENSE

beta_parameterization-4.0.0/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`.

beta_parameterization-4.0.0/include/beta_parameterization.h

@@ -0,0 +1,243 @@
+/**
+ * @file beta_parameterization.h
+ * @brief C API for the Fortran beta parameterization library (v4.0.0).
+ *
+ * Two tiers of computation:
+ *   - One-shot: the `*_standalone` functions compute one shape per call. All
+ *     workspace is internal and discarded on return.
+ *   - Read-only cache: create a `beta_param_cache_t` once, then call the
+ *     `beta_param_cache_*` functions for any number of shapes.
+ *
+ * Two handle types:
+ *   - `beta_param_cache_t`    — everything determined by `max_params` and the
+ *     primary theta set (normalization constants, Gauss-Legendre tables,
+ *     Legendre tables at the primary thetas).
+ *   - `beta_param_node_set_t` — an extra set of evaluation thetas with its own
+ *     Legendre tables, built from a cache.
+ *
+ * Thread safety:
+ *   Both handles are immutable after creation. Every compute function takes
+ *   them `const` and may be called concurrently, from any number of threads,
+ *   on the same handles. Create and destroy must not race with any other call
+ *   on the same handle. The library holds no mutable global state.
+ *
+ * Lifetime:
+ *   A cache must outlive every node set built from it. Destroy order: node
+ *   sets first, their cache last. A node set serves a cache only if it was
+ *   built from a cache with at least that cache's `max_params`.
+ *
+ * Parameters:
+ *   A cached call accepts 1 .. max_params parameters; a one-shot call accepts
+ *   1 .. BETA_PARAM_MAX_PARAMS_LIMIT. Missing trailing parameters are zero: a
+ *   short vector and its zero-padded form give bitwise-identical results.
+ *   `conserve_volume` and `apply_com` are per-call options (nonzero = on); one
+ *   cache serves every combination.
+ *
+ * Diagnostics:
+ *   There are no message buffers. `_create` functions return NULL on failure
+ *   and write the reason to the nullable `int* status` out-parameter (pass
+ *   NULL to ignore it). Every other function returns the status code directly;
+ *   BETA_PARAM_VALID (0) means success. beta_param_status_message() maps a code
+ *   to a fixed, static, null-terminated string; the returned pointer is owned
+ *   by the library, never freed by the caller, and is safe to read from any
+ *   thread.
+ *
+ * Failure behavior:
+ *   On any nonzero status from a compute function, every output buffer is
+ *   zero-filled. No state exists, so the next call is unaffected. A NULL
+ *   handle passed into a compute function returns
+ *   BETA_PARAM_ERROR_CACHE_NOT_INITIALIZED (2).
+ *
+ * Size arguments:
+ *   Every size argument must be the ACTUAL extent of the caller's buffer. A
+ *   wrong size that is honest about the caller's own memory is reported with a
+ *   status code, however large; a stated size larger than the real buffer is
+ *   undefined behavior. Negative counts are treated as zero.
+ *
+ * Precondition — finite input:
+ *   `params` and `thetas` must be finite. Non-finite input is undefined
+ *   behavior: the library cannot detect NaN under fast-math, so no check
+ *   rejects it, and no particular result is promised. A call may return
+ *   BETA_PARAM_VALID (0) with NaN outputs; a NaN trailing parameter is
+ *   trimmed like a zero, giving the finite outputs of the shorter vector; a
+ *   Debug build may trap. Screen inputs before calling. Magnitudes must be
+ *   physical as well: with `apply_com` the centre-of-mass quadrature evaluates
+ *   R^4 before any validity gate and overflows for |beta| beyond about 1e70.
+ */
+
+#ifndef BETA_PARAMETERIZATION_H
+#define BETA_PARAMETERIZATION_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* --- Limits --- */
+/** Longest parameter vector either tier accepts; the highest `max_params`. */
+#define BETA_PARAM_MAX_PARAMS_LIMIT 64
+
+/* --- Shared contract status codes (0-99, identical numbers in every
+ *     shape-parameterization library; 6 is retired and never reused) --- */
+#define BETA_PARAM_VALID                        0
+#define BETA_PARAM_ERROR_TOO_MANY_PARAMS        1
+#define BETA_PARAM_ERROR_CACHE_NOT_INITIALIZED  2
+#define BETA_PARAM_ERROR_INVALID_GRID           3
+#define BETA_PARAM_ERROR_WRONG_PARAM_COUNT      4
+#define BETA_PARAM_ERROR_INVALID_INIT           5
+
+/* --- Library status codes (>= 100, append-only) --- */
+#define BETA_PARAM_ERROR_NORTH_POLE          100
+#define BETA_PARAM_ERROR_SOUTH_POLE          101
+#define BETA_PARAM_ERROR_INTERIOR_NEGATIVE   102
+#define BETA_PARAM_ERROR_COM_NOT_CONVERGED   103
+#define BETA_PARAM_ERROR_INVALID_BUFFER_SIZE 104
+#define BETA_PARAM_ERROR_POLE_NODE           105
+#define BETA_PARAM_ERROR_NODE_SET_MISMATCH   106
+
+/* --- Opaque handles --- */
+typedef struct beta_param_cache beta_param_cache_t;
+typedef struct beta_param_node_set beta_param_node_set_t;
+
+/* --- Diagnostics --- */
+
+/**
+ * Fixed description of a status code. Never NULL; unknown codes map to an
+ * "unknown status code" string. The pointer is to static storage: do not free
+ * it, and it stays valid for the life of the process.
+ */
+const char* beta_param_status_message(int status);
+
+/* --- Cache lifecycle --- */
+
+/**
+ * Build the read-only cache. Returns NULL on failure.
+ *
+ * @param max_params  Longest parameter vector the cache accepts,
+ *                    1 .. BETA_PARAM_MAX_PARAMS_LIMIT; also the Legendre order
+ *                    of its tables. Below 1: BETA_PARAM_ERROR_INVALID_INIT;
+ *                    above the limit: BETA_PARAM_ERROR_TOO_MANY_PARAMS.
+ * @param thetas      Primary theta set in radians; at least 2 entries
+ *                    (BETA_PARAM_ERROR_INVALID_GRID), none at or beyond a pole
+ *                    (cos(theta)^2 == 1 in double precision;
+ *                    BETA_PARAM_ERROR_POLE_NODE)
+ * @param n_thetas    Number of entries in thetas
+ * @param status      Nullable; receives BETA_PARAM_VALID or the rejecting code
+ */
+beta_param_cache_t* beta_param_cache_create(
+        int max_params, const double* thetas, int n_thetas, int* status);
+
+/** Destroy a cache. NULL-safe. Every node set built from it must already be
+ *  destroyed. */
+void beta_param_cache_destroy(beta_param_cache_t* cache);
+
+/* --- Node-set lifecycle --- */
+
+/**
+ * Build an extra evaluation set (thetas plus Legendre P_k and P_k' tables)
+ * sized to `cache`. Returns NULL on failure — including a pole node, which is
+ * rejected with BETA_PARAM_ERROR_POLE_NODE; use the resolve_shape polar radii
+ * for the poles instead. A NULL cache gives
+ * BETA_PARAM_ERROR_CACHE_NOT_INITIALIZED.
+ *
+ * @param cache     Cache handle; supplies max_params. Must outlive the node
+ *                  set.
+ * @param thetas    Node angles in radians; any order, need not be uniform
+ * @param n_thetas  Number of nodes (at least 2)
+ * @param status    Nullable; receives the rejecting code on failure
+ */
+beta_param_node_set_t* beta_param_node_set_create(
+        const beta_param_cache_t* cache, const double* thetas, int n_thetas,
+        int* status);
+
+/** Destroy a node set. NULL-safe. */
+void beta_param_node_set_destroy(beta_param_node_set_t* node_set);
+
+/* --- Cached computes ---
+ *
+ * None of these modifies the cache. `params` holds 1 .. max_params entries,
+ * else BETA_PARAM_ERROR_WRONG_PARAM_COUNT. Output buffer lengths must equal
+ * the cache's theta count (or the node set's node count), else
+ * BETA_PARAM_ERROR_INVALID_BUFFER_SIZE. `conserve_volume` and `apply_com` are
+ * nonzero to switch the option on.
+ */
+
+/** R(theta) at the cache's primary thetas. `n_radii` must equal that count. */
+int beta_param_cache_radius_grid(
+        const beta_param_cache_t* cache, const double* params, int n_params,
+        int conserve_volume, int apply_com, double* radii, int n_radii);
+
+/** R(theta) and dR/dtheta at the cache's primary thetas. */
+int beta_param_cache_radius_and_derivative(
+        const beta_param_cache_t* cache, const double* params, int n_params,
+        int conserve_volume, int apply_com,
+        double* radii, double* dr_dthetas, int n_radii);
+
+/**
+ * R(theta) at the primary thetas with NO validation gates and NO volume
+ * scaling — the rendering/diagnostic path. It reports usage errors and a
+ * failed COM correction only, so a shape rejected by the checked path still
+ * yields its (partly negative) outline instead of a zero-filled buffer.
+ *
+ * CAUTION: the radii are UNSCALED — this path never computes the volume
+ * factor, which is why it takes no `conserve_volume`. Mixing it with
+ * beta_param_cache_radius_grid(..., conserve_volume = 1, ...) draws two
+ * outlines of different size for one shape; scale by
+ * beta_param_cache_resolve_shape()'s volume_factor if the sizes must agree.
+ */
+int beta_param_cache_radius_grid_unchecked(
+        const beta_param_cache_t* cache, const double* params, int n_params,
+        int apply_com, double* radii, int n_radii);
+
+/**
+ * Resolve a shape without evaluating a grid: the COM-corrected beta10, the
+ * analytic polar radii, and the applied volume factor.
+ *
+ * `corrected_beta10` is a beta-space value and is never volume-scaled;
+ * `r_north` and `r_south` are scaled. `volume_factor` is exactly 1.0 when
+ * conserve_volume = 0.
+ */
+int beta_param_cache_resolve_shape(
+        const beta_param_cache_t* cache, const double* params, int n_params,
+        int conserve_volume, int apply_com,
+        double* corrected_beta10, double* r_north, double* r_south,
+        double* volume_factor);
+
+/**
+ * R(theta) and dR/dtheta at a node set's thetas. The node set must come from
+ * a cache with at least this cache's max_params, else
+ * BETA_PARAM_ERROR_NODE_SET_MISMATCH; a node set built from this cache always
+ * qualifies. `n_nodes` must equal the node set's node count. To fold several
+ * theta grids into one call, build one node set over their concatenation.
+ */
+int beta_param_cache_node_radius_and_derivative(
+        const beta_param_cache_t* cache, const double* params, int n_params,
+        const beta_param_node_set_t* node_set,
+        int conserve_volume, int apply_com,
+        double* radii, double* dr_dthetas, int n_nodes);
+
+/* --- One-shot computes (tier 1) ---
+ *
+ * A cache is built, used and discarded per call — no handle, nothing to free.
+ * `n_params` may be 1 .. BETA_PARAM_MAX_PARAMS_LIMIT: above that,
+ * BETA_PARAM_ERROR_TOO_MANY_PARAMS, never silent truncation; below 1,
+ * BETA_PARAM_ERROR_WRONG_PARAM_COUNT. Output buffers hold n_thetas doubles.
+ * Outputs are zero-filled on failure. Results are bitwise identical to the
+ * cached functions on a cache with max_params >= n_params.
+ */
+
+int beta_param_radius_grid_standalone(
+        const double* params, int n_params,
+        const double* thetas, int n_thetas,
+        int conserve_volume, int apply_com, double* radii);
+
+int beta_param_radius_and_derivative_standalone(
+        const double* params, int n_params,
+        const double* thetas, int n_thetas,
+        int conserve_volume, int apply_com,
+        double* radii, double* dr_dthetas);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BETA_PARAMETERIZATION_H */