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

beta_parameterization-3.0.0/CHANGELOG.md

@@ -0,0 +1,242 @@
+# Changelog
+
+All notable changes to this project are documented here. Versions follow
+semantic versioning; the format follows [Keep a Changelog](https://keepachangelog.com).
+
+## 3.0.0
+
+Adoption of the three-tier shape parameterization contract against
+`shape_core_mod` (fortran-foundations 2.4.0). Every public surface — Fortran,
+C, C++, Python — changes. Read the breaking-change list before upgrading;
+nothing in 2.x compiles against 3.0.0 unchanged.
+
+### BREAKING: thread-safety promise withdrawn
+
+**The 2.x guarantee that one cache serves concurrent computes from many threads
+is gone.** It was never true once the cache started tracking recompute state.
+
+| object | 3.0.0 rule |
+|---|---|
+| `tables_t` / `beta_param_tables_t*` / `Tables` | immutable after creation; share across threads for concurrent reads |
+| `node_set_t` / `beta_param_node_set_t*` / `NodeSet` | immutable after build; share across threads for concurrent reads |
+| `cache_t` / `beta_param_cache_t*` / `Cache` / Python `Cache` | **THREAD-CONFINED**; every compute mutates it; concurrent use from more than one thread is undefined |
+
+The supported pattern is one shared `tables_t` plus one cache per thread, built
+with `cache_init_shared_s` / `beta_param_cache_create_shared()` /
+`Tables`-taking `Cache` constructor. Callers that fanned out one 2.x cache
+across an OpenMP region **must** hoist a per-thread cache; the old code will
+race silently. C++ `Cache` compute methods are no longer `const` — the compiler
+catches most of these at the call site.
+
+**Fortran callers of `cache_init_shared_s` MUST declare their `tables_t` with
+the `target` attribute.** The cache stores a pointer to it, and a pointer
+associated with a non-target dummy becomes undefined when that procedure
+returns (F2018 8.5.17). Without `target` the code compiles, links and usually
+appears to work — then reads freed memory. Declare
+`type(tables_t), target :: tables`.
+
+### Added
+
+- **In-library volume conservation.** `conserve_volume` is a cache/standalone
+  creation flag. The factor `c = (2 / Σᵢ wᵢ Rᵢ³)^(1/3)` is computed on the
+  internal GL-512 set over the COM-corrected, unscaled shape, after validation,
+  and applied to radii, dR/dθ and the polar radii — never to β-space values.
+  Consumers that rescaled shapes themselves (wmmm's
+  `compute_volume_factor_from_dense_f`) should drop their copy.
+- `apply_com` as a creation flag, replacing the separate
+  `*_with_com_shift` entry points.
+- `tables_t` — a shared, immutable tables level (normalization constants,
+  Gauss-Legendre set, Legendre tables at the primary thetas) with
+  `tables_init_s` / `tables_free_s` / `tables_max_l_f` / `tables_n_thetas_f`.
+- `status_message_f(status)` (C: `beta_param_status_message`) — one pure lookup
+  returning a fixed string per code.
+- `cache_radius_grid_unchecked_s` — the rendering/diagnostic path: no validity
+  gate, no volume scaling, usage errors only, so a rejected shape still yields
+  its outline. Its radii are UNSCALED even on a `conserve_volume` cache; mixing
+  it with the checked path draws two outlines of different size for one shape.
+- `cache_recompute_count_f` plus the public intermediate indices
+  `BETA_PARAM_I_RESOLVED`, `_I_MIN_RADIUS`, `_I_VOLUME`, `_I_RADII`, `_I_DERIV`
+  — always-on recompute counters for cache-minimality testing.
+- `BETA_PARAM_ERROR_NODE_SET_MISMATCH` (106) for an unbuilt node set or one
+  whose `max_l` is below the cache's `n_params`.
+- Public constants for the two tier caps, so callers can check before creating
+  anything: `SHAPE_CACHE_MAX_PARAMS` (8) and `SHAPE_STANDALONE_MAX_PARAMS` (64)
+  re-exported from Fortran, `BETA_PARAM_CACHE_MAX_PARAMS` (8) and
+  `BETA_PARAM_MAX_PARAMS_LIMIT` (64) in the C header,
+  `beta_param::cache_max_params` / `beta_param::max_params_limit` in the C++
+  header, and `CACHE_MAX_PARAMS` (8) / `MAX_BETA_PARAMS_LIMIT` (64) in Python.
+- The documented dependency map lives in the module header of
+  `src/beta_parameterization_mod.f08`: five intermediates, every mask = all
+  `n_params` bits.
+
+### Changed
+
+- **BREAKING: the cached tier now caps `n_params` at 8, down from 64.** A cache
+  carries the recompute engine, whose per-intermediate dependency masks are
+  fixed-width, so `shape_core`'s `SHAPE_CACHE_MAX_PARAMS` = 8 is the hard limit.
+  `cache_init_s` / `cache_init_shared_s` reject `n_params > 8` with
+  `SHAPE_ERROR_TOO_MANY_PARAMS` (1) and `n_params < 1` with
+  `SHAPE_ERROR_INVALID_INIT` (5) — the engine check runs before any table is
+  built, so nothing is allocated. **The standalone tier is unaffected and still
+  accepts up to 64** (`SHAPE_STANDALONE_MAX_PARAMS`): it constructs no engine.
+  2.x accepted `max_beta_params` up to 64 for the cache, so any consumer that
+  created a cache with more than 8 parameters — wmmm's
+  `number_of_deformation_parameters = 20` is the known case — fails at cache
+  creation and must either reduce its parameter count or move to the standalone
+  tier. Beta PES calculations realistically stay within 8 dimensions; wmmm's
+  20 existed for fos→beta conversion, which is obsolete now that fos works on
+  the radius grid directly.
+- **BREAKING: the internal uniform grid is gone.** 2.x caches took `n_grid` and
+  generated their own uniform theta grid. 3.0.0 takes an explicit **primary
+  theta set** — `tables_init_s(tables, max_l, thetas, status)`,
+  `cache_init_s(cache, n_params, thetas, ...)`. The caller owns the grid.
+  Pole values (θ = 0, π) are rejected as cache input; get them analytically
+  from `cache_resolve_shape_s`'s `r_north` / `r_south`.
+- **BREAKING: all `message` arguments removed** from every entry point in
+  Fortran, C, C++ and Python. Diagnostics are the integer status plus
+  `status_message_f`. No per-call message formatting exists anywhere.
+- **BREAKING (bitwise): the COM correction is now Newton's method** on the
+  numerator of the COM integral (`N(β10) = Σᵢ wᵢ xᵢ Rᵢ⁴`,
+  `N'(β10) = 4·C₁·Σᵢ wᵢ xᵢ² Rᵢ³`), replacing 2.x fixed-point iteration. The
+  tolerance (`|z_cm| < 1e-5`) and iteration cap (50) are unchanged, so the same
+  shapes converge — but **corrected β₁₀ and every downstream radius differ in
+  the last bits from 2.x**. Goldens were re-baselined; consumers pinning exact
+  values must re-baseline too.
+- **BREAKING: `beta_con` is off the public surface.** 2.x
+  `cache_resolve_shape` returned the resolved coefficient array and
+  `compute_radius_and_derivative` took it back as an argument. 3.0.0 keeps
+  resolved coefficients inside the cache as intermediate 1;
+  `cache_resolve_shape_s` returns only `corrected_beta10`, `r_north`, `r_south`
+  and `volume_factor`, and node evaluation takes `(cache, node_set, params)`.
+- Type-bound methods (`cache%init`, `cache%compute_radius_grid`, …) replaced by
+  free subroutines (`cache_init_s`, `cache_radius_grid_s`, …), matching the
+  contract's naming.
+- Standalone tier: `compute_radius_grid_standalone_s(params, thetas,
+  conserve_volume, apply_com, radii, status)` and
+  `compute_radius_and_derivative_standalone_s(...)`. `n_params = size(params)`,
+  accepted up to the **standalone** cap of 64
+  (`SHAPE_STANDALONE_MAX_PARAMS` = `MAX_BETA_PARAMS_LIMIT`); above →
+  `SHAPE_ERROR_TOO_MANY_PARAMS`, never silent truncation. The
+  `max_beta_params` padding argument is removed. Tier 1 never constructs an
+  engine, which is why it keeps the higher cap.
+- Failure semantics are now uniform: on ANY nonzero status inside a checked
+  cached compute the library zero-fills every output and invalidates the whole
+  engine, so the next call runs cold. Usage errors follow the contract's
+  normative order — a buffer-size mismatch (104) is reported before a node-set
+  mismatch (106).
+- Minimum fortran-foundations is **2.4.0** (`shape_core_mod`); gcc-opts stays at
+  **2.0.0**.
+
+### Changed: status codes
+
+Shared contract codes (0–99) come from `shape_core_mod`: `SHAPE_VALID` 0,
+`SHAPE_ERROR_TOO_MANY_PARAMS` 1, `SHAPE_ERROR_CACHE_NOT_INITIALIZED` 2,
+`SHAPE_ERROR_INVALID_GRID` 3 (theta floor: `size(thetas) >= 2`),
+`SHAPE_ERROR_WRONG_PARAM_COUNT` 4, `SHAPE_ERROR_INVALID_INIT` 5,
+`SHAPE_ERROR_TABLES_NOT_INITIALIZED` 6.
+
+Library codes are renamed `LEGENDRE_*` → `BETA_PARAM_ERROR_*` and renumbered
+≥ 100. This range is **append-only** from 3.0.0 on:
+
+| old (2.x) | new (3.0.0) |
+|---|---|
+| `LEGENDRE_ERROR_NORTH_POLE` 1 | `BETA_PARAM_ERROR_NORTH_POLE` 100 |
+| `LEGENDRE_ERROR_SOUTH_POLE` 2 | `BETA_PARAM_ERROR_SOUTH_POLE` 101 |
+| `LEGENDRE_ERROR_INTERIOR_NEGATIVE` 4 | `BETA_PARAM_ERROR_INTERIOR_NEGATIVE` 102 |
+| `LEGENDRE_ERROR_COM_NOT_CONVERGED` 7 | `BETA_PARAM_ERROR_COM_NOT_CONVERGED` 103 |
+| `LEGENDRE_ERROR_INVALID_BUFFER_SIZE` 8 | `BETA_PARAM_ERROR_INVALID_BUFFER_SIZE` 104 |
+| `LEGENDRE_ERROR_POLE_NODE` 9 | `BETA_PARAM_ERROR_POLE_NODE` 105 |
+| — (new) | `BETA_PARAM_ERROR_NODE_SET_MISMATCH` 106 |
+| `LEGENDRE_ERROR_EMPTY_PARAMS` 3 | → shared 4 (compute) / 5 (init) |
+| `LEGENDRE_ERROR_INVALID_MAX_PARAMS` 5 | → shared 5 / 3 / 2 by cause |
+| `LEGENDRE_ERROR_TOO_MANY_PARAMS` 6 | → shared 1 |
+| `LEGENDRE_ERROR_NO_UNIFORM_GRID` 10 | removed (no uniform grid) |
+
+Note that the old and new numbering overlap: 2.x code 1 meant "north pole",
+3.0.0 code 1 means "too many params". Callers comparing raw integers must be
+updated, not merely recompiled.
+
+### Changed: C API
+
+Handle-based, with statuses reported through out-parameters instead of
+in-band returns:
+
+- `beta_param_tables_create(max_l, thetas, n_thetas, int* status)` /
+  `beta_param_tables_destroy` — new handle type `beta_param_tables_t*`.
+- `beta_param_cache_create(n_params, thetas, n_thetas, conserve_volume,
+  apply_com, int* status)` and
+  `beta_param_cache_create_shared(tables, n_params, conserve_volume, apply_com,
+  int* status)` — both return `NULL` on failure and write the rejecting code to
+  the nullable `status` out-param. The 2.x `n_grid` + `message` arguments are
+  gone.
+- Computes drop the `compute_` infix and the `_with_com_shift` variants:
+  `beta_param_cache_radius_grid`, `_radius_and_derivative`,
+  `_radius_grid_unchecked`, `_resolve_shape`, `_node_radius_and_derivative`,
+  `beta_param_radius_grid_standalone`, `_radius_and_derivative_standalone`.
+  Each returns the status code directly.
+- `beta_param_status_message(int)` returns a static string; no caller-supplied
+  message buffers anywhere.
+- Lifetime rule: a tables handle passed to `beta_param_cache_create_shared()`
+  or `beta_param_node_set_create()` must outlive everything built from it;
+  `beta_param_cache_destroy()` never frees shared tables.
+
+### Changed: C++ header
+
+`beta_parameterization.hpp` (C++20, header-only) exposes `Tables`, `Cache` and
+`NodeSet` RAII wrappers. `Cache` is move-only and thread-confined; its compute
+methods are non-`const`. Status strings come from `beta_param_status_message`.
+The 2.x concurrent-compute documentation is replaced, not amended.
+
+### Changed: Python wheel
+
+- **BREAKING: `NodeSet` is removed.** BetaRender's single-set usage maps onto
+  the primary theta set. Node sets return to Python only when a consumer needs
+  a genuine second set — the same principle that keeps `tables_t` out of
+  Python.
+- **BREAKING: `theta_grid(n)` is now the OPEN uniform grid**
+  `theta_i = i·π/(n+1), i = 1..n`. The 2.x closed `linspace(0, π, n)` includes
+  both poles, which the pole guard now rejects as cache input. Close plotted
+  curves with the analytic `r_north` / `r_south` from `resolve_shape`.
+- Module-level tier 1: `radius_grid(params, thetas, conserve_volume=False,
+  apply_com=False)`, `radius_and_derivative(...)`.
+- `Cache(n_params, thetas, conserve_volume=False, apply_com=False)` with
+  `.radius_grid`, `.radius_and_derivative`, `.radius_grid_unchecked`,
+  `.resolve_shape`. Thread-confined.
+- **Returns are result objects, not exceptions**: `RadiusGridResult`,
+  `RadiusDerivativeResult`, `ResolvedShape`, each with `.ok`, `.status` and a
+  `.message` property. Shape-validation failures come back as a status-carrying
+  result; `BetaParamError` is raised only for usage errors (closed handle,
+  non-1-D params, create failure).
+- The `Status` enum is renumbered per the table above.
+
+### Removed
+
+- Concurrent-compute-on-one-cache support (see the breaking section above).
+- The internally generated uniform theta grid and
+  `LEGENDRE_ERROR_NO_UNIFORM_GRID`.
+- All `message` output arguments and the message-formatting code behind them.
+- `*_with_com_shift` entry points (Fortran, C), superseded by the `apply_com`
+  creation flag.
+- `beta_con` from every public signature.
+- The `max_beta_params` padding argument on the standalone entry points.
+- Python `NodeSet`.
+
+### Migration sketch
+
+```fortran
+! 2.x
+call cache%init(max_beta_params = 4_ik, n_grid = 80_ik, error_code = ec, message = msg)
+call cache%compute_radius_grid_with_com_shift(params, radii, ec, msg)
+call cache%destroy()
+
+! 3.0.0 — the caller owns the theta set; flags are set once, at creation
+thetas = [(i * PI / 81.0_rk, i = 1, 80)]          ! open grid: no poles
+call cache_init_s(cache, n_params = 4_ik, thetas = thetas, &
+        conserve_volume = .false., apply_com = .true., status = status)
+call cache_radius_grid_s(cache, params, radii, status)
+call cache_free_s(cache)
+```
+
+## 2.3.4 and earlier
+
+No changelog was kept before 3.0.0. See the git history.

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

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.20)
 include(FetchContent)
 
 project(beta-parameterization
-        VERSION 2.3.4
+        VERSION 3.0.0
         LANGUAGES Fortran CXX
         DESCRIPTION "Beta parameterization for nuclear physics applications"
 )
@@ -24,7 +24,7 @@ FetchContent_MakeAvailable(GCC-Compiler-Options)
 FetchContent_Declare(
         Fortran-Foundations
         GIT_REPOSITORY https://github.com/AleksanderAugustyn/Fortran-Foundations.git
-        GIT_TAG 2.3.2
+        GIT_TAG 2.4.0
 )
 FetchContent_MakeAvailable(Fortran-Foundations)
 
@@ -118,7 +118,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 core com error breakdown golden node_set)
+set(BETA_PARAM_TEST_SUITES status lifecycle resolve outputs standalone bitwise minimality
+        interleave boundary property golden)
 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
@@ -134,19 +135,35 @@ endforeach ()
 set_source_files_properties(tests/beta_param_golden_test.f08 PROPERTIES
         COMPILE_OPTIONS "-Wno-conversion-extra;-Wno-error=conversion-extra")
 
+# Capture tool for the golden baseline: an executable, never a test.
 add_executable(golden_capture tests/golden_capture.f08)
 target_link_libraries(golden_capture PRIVATE
         beta_parameterization beta_param_test_utils beta_parameterization_flags)
 set_target_properties(golden_capture PROPERTIES
         Fortran_MODULE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/mod_files_tests/capture)
 
+# PES-range sweep: 1.55M shapes, far too slow for ctest. An executable driven
+# by an explicit custom target, never registered with add_test.
+add_executable(beta_pes_sweep tests/beta_pes_sweep.f08)
+target_link_libraries(beta_pes_sweep PRIVATE
+        beta_parameterization beta_param_test_utils beta_parameterization_flags)
+set_target_properties(beta_pes_sweep PROPERTIES
+        Fortran_MODULE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/mod_files_tests/sweep)
+add_custom_target(test_beta_pes_sweep
+        COMMAND beta_pes_sweep
+        DEPENDS beta_pes_sweep
+        COMMENT "Running the PES-range sweep (1.55M + 172.8k shapes)")
+
+# C API smoke test: links the SHARED library, the binary the bindings load.
 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.
 find_package(Threads REQUIRED)
 add_executable(thread_stress_test tests/thread_stress_test.cpp)
-target_link_libraries(thread_stress_test PRIVATE beta_parameterization_cxx Threads::Threads)
+target_link_libraries(thread_stress_test PRIVATE
+        beta_parameterization_cxx Threads::Threads)
 add_test(NAME thread_stress COMMAND thread_stress_test)
 
 endif ()

{beta_parameterization-2.3.5 → beta_parameterization-3.0.0}/PKG-INFO

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

beta_parameterization-3.0.0/include/beta_parameterization.h

@@ -0,0 +1,263 @@
+/**
+ * @file beta_parameterization.h
+ * @brief C API for the Fortran beta parameterization library (v3.0.0).
+ *
+ * Three handle types, from shared to per-shape:
+ *   - `beta_param_tables_t`   — everything determined by `max_l` and the
+ *     primary theta set (normalization constants, Gauss-Legendre tables,
+ *     Legendre tables at the primary thetas). Built once, shared read-only.
+ *   - `beta_param_node_set_t` — an extra set of evaluation thetas with its own
+ *     Legendre tables, sized to one tables handle. Immutable after creation.
+ *   - `beta_param_cache_t`    — per-shape working state: the recompute engine
+ *     and every per-shape buffer. Mutated by every compute call.
+ *
+ * Two tiers of computation:
+ *   - Cached: create a cache once, call the `beta_param_cache_*` functions for
+ *     many shapes. Only the intermediates invalidated by the changed
+ *     parameters are recomputed.
+ *   - Standalone: one-off calls that build, use and discard their own tables.
+ *
+ * Thread safety (BREAKING CHANGE at 3.0.0 — the 2.x promise is withdrawn):
+ *   A `beta_param_cache_t*` is THREAD-CONFINED. It is mutated by every compute
+ *   call; concurrent use of one cache from more than one thread is undefined.
+ *   Give every thread its own cache. `beta_param_tables_t*` and
+ *   `beta_param_node_set_t*` are immutable after creation and may be shared
+ *   across threads for concurrent reads, including as the backing tables of
+ *   per-thread caches created with beta_param_cache_create_shared().
+ *
+ * Lifetime:
+ *   A tables handle passed to beta_param_cache_create_shared() or
+ *   beta_param_node_set_create() MUST outlive every cache and node set built
+ *   from it — the cache/node set holds a reference, not a copy. Destroy order:
+ *   node sets and caches first, their tables last.
+ *
+ * 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 and the cache is returned to a cold state — the next call
+ *   recomputes from scratch. No partially updated results are ever visible.
+ *   A NULL handle passed into a compute function returns
+ *   BETA_PARAM_ERROR_CACHE_NOT_INITIALIZED (2).
+ *
+ * Precondition — finite input:
+ *   `params` and `thetas` must be finite. Non-finite input is undefined
+ *   behavior: the library cannot detect NaN under fast-math, so validation
+ *   comparisons silently pass and the call returns BETA_PARAM_VALID (0) with
+ *   NaN outputs. Screen inputs before calling.
+ */
+
+#ifndef BETA_PARAMETERIZATION_H
+#define BETA_PARAMETERIZATION_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* --- Limits --- */
+/** Highest Legendre order a tables handle may be built for. */
+#define BETA_PARAM_MAX_PARAMS_LIMIT 64
+/** Highest n_params a cache (cached tier) accepts. */
+#define BETA_PARAM_CACHE_MAX_PARAMS 8
+
+/* --- Shared contract status codes (0-99, identical numbers in every
+ *     shape-parameterization library) --- */
+#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
+#define BETA_PARAM_ERROR_TABLES_NOT_INITIALIZED 6
+
+/* --- Library status codes (>= 100, append-only after 3.0.0) --- */
+#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_tables beta_param_tables_t;
+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);
+
+/* --- Tables lifecycle --- */
+
+/**
+ * Build the shared immutable level. Returns NULL on failure.
+ *
+ * @param max_l     1 .. BETA_PARAM_MAX_PARAMS_LIMIT
+ * @param thetas    Primary theta set in radians; at least 2 entries, none at
+ *                  or beyond a pole (cos(theta)^2 == 1 in double precision)
+ * @param n_thetas  Number of entries in thetas
+ * @param status    Nullable; receives BETA_PARAM_VALID or the rejecting code
+ */
+beta_param_tables_t* beta_param_tables_create(
+        int max_l, const double* thetas, int n_thetas, int* status);
+
+/** Destroy a tables handle. NULL-safe. Every cache and node set built from it
+ *  must already be destroyed. */
+void beta_param_tables_destroy(beta_param_tables_t* tables);
+
+/* --- Cache lifecycle --- */
+
+/**
+ * Create a cache that owns private tables built with max_l = n_params.
+ * Returns NULL on failure.
+ *
+ * @param n_params         1 .. BETA_PARAM_CACHE_MAX_PARAMS; the exact length
+ *                         every later params array must have
+ * @param thetas           Primary theta set in radians (see tables_create)
+ * @param n_thetas         Number of entries in thetas
+ * @param conserve_volume  Nonzero: rescale radii to fixed volume
+ * @param apply_com        Nonzero: apply the centre-of-mass correction
+ * @param status           Nullable; receives the rejecting code on failure
+ */
+beta_param_cache_t* beta_param_cache_create(
+        int n_params, const double* thetas, int n_thetas,
+        int conserve_volume, int apply_com, int* status);
+
+/**
+ * Create a cache over caller-owned shared tables. Returns NULL on failure.
+ * The tables handle MUST outlive the cache; it is referenced, not copied, and
+ * beta_param_cache_destroy() never frees it.
+ *
+ * @param tables           Tables handle; n_params must not exceed its max_l
+ * @param n_params         1 .. BETA_PARAM_CACHE_MAX_PARAMS
+ * @param conserve_volume  Nonzero: rescale radii to fixed volume
+ * @param apply_com        Nonzero: apply the centre-of-mass correction
+ * @param status           Nullable; receives the rejecting code on failure
+ */
+beta_param_cache_t* beta_param_cache_create_shared(
+        const beta_param_tables_t* tables, int n_params,
+        int conserve_volume, int apply_com, int* status);
+
+/** Destroy a cache. NULL-safe. Shared tables are left untouched. */
+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 `tables`. 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.
+ *
+ * @param tables    Tables handle; 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_tables_t* tables, 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 ---
+ *
+ * Every one of these mutates the cache (thread-confined, see above). `params`
+ * must hold exactly the cache's n_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. Radii and derivatives are
+ * COM-corrected and volume-scaled per the cache's flags.
+ */
+
+/** R(theta) at the cache's primary thetas. `n_radii` must equal that count. */
+int beta_param_cache_radius_grid(
+        beta_param_cache_t* cache, const double* params, int n_params,
+        double* radii, int n_radii);
+
+/** R(theta) and dR/dtheta at the cache's primary thetas. */
+int beta_param_cache_radius_and_derivative(
+        beta_param_cache_t* cache, const double* params, int n_params,
+        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 only (not
+ * initialized, wrong parameter count, buffer size, COM non-convergence), 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 even on a cache created with
+ * conserve_volume = 1 — this path never computes the volume factor. Mixing it
+ * with beta_param_cache_radius_grid() on such a cache 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(
+        beta_param_cache_t* cache, const double* params, int n_params,
+        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 the
+ * cache was created with conserve_volume = 0.
+ */
+int beta_param_cache_resolve_shape(
+        beta_param_cache_t* cache, const double* params, int n_params,
+        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 be built
+ * from tables whose max_l is at least the cache's n_params, else
+ * BETA_PARAM_ERROR_NODE_SET_MISMATCH. `n_nodes` must equal the node set's node
+ * count. This evaluation is not cached; the resolve/validation/volume
+ * intermediates behind it are.
+ */
+int beta_param_cache_node_radius_and_derivative(
+        beta_param_cache_t* cache, const beta_param_node_set_t* node_set,
+        const double* params, int n_params,
+        double* radii, double* dr_dthetas, int n_nodes);
+
+/* --- Standalone computes (tier 1) ---
+ *
+ * One-off: tables are built, used and discarded per call — no handle, nothing
+ * to free, no engine. `n_params` may be 1 .. BETA_PARAM_MAX_PARAMS_LIMIT (the
+ * cached-tier cap does not apply); above that,
+ * BETA_PARAM_ERROR_TOO_MANY_PARAMS, never silent truncation. Output buffers
+ * hold n_thetas doubles. Outputs are zero-filled on failure.
+ */
+
+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 */