API reference

This is the lookup door. It enumerates the public modules of jaxstro 0.1.0, what each owns, where traced runtime ends, and where to audit the claim. Public subpackages are eager top-level attributes; jaxconfig remains a direct module because configuration is an explicit action.

The API is astro-first but intentionally science-general. A public symbol belongs here when it is reusable below domain packages, has explicit unit or boundary semantics, and can point to tests or validation evidence for the behavior it claims.

import jaxstro
from jaxstro import (
    astrometry,
    atmospheres,
    constants,
    coords,
    geometry,
    numerics,
    params,
    provenance,
    quantity,
    spatial,
    testing,
    units,
)
from jaxstro.jaxconfig import enable_high_precision

jaxstro.units is the current ecosystem contract. jaxstro.quantity is implemented and available for evaluation, but ecosystem adoption and any replacement cutover remain deferred. The statuses below describe current evidence boundaries, not a hidden migration schedule.

The generated Scientific contract registry registry is the machine-checked source for ownership, maturity, JAX-transform, AD, limitation, and evidence claims. This page retains signatures and usage context rather than duplicating that matrix.

Selected modules¶

jaxstro.constants¶

CGS constants with sourced values. A few that downstream packages rely on:

Provenance discipline — every constant cites its authority — is principle 9.

MSUN_G is deliberately not labelled an IAU nominal solar mass: Resolution B3 defines the exact nominal solar mass parameter $(GM)_\odot^\mathrm{N}$, while the retained gram value is a rounded compatibility conversion using jaxstro’s frozen CODATA-2018 $G$. The nominal radius, luminosity, and effective temperature are B3 conversion constants, not measurements of the time-varying Sun.

jaxstro.numerics.rootfinding¶

bracket_expand, bisect, bisect_many, newton, newton_with_grad, newton_ppf, and monotone_inverse_interp. The value-first safeguarded surface exports BracketState, BracketProposal, RootTrace, BracketedRootResult, initialize_bracket, update_bracket, propose_bracketed, and safeguarded_bracketed_root, and map_safeguarded_bracketed_root, with deterministic PROPOSAL_NONE, PROPOSAL_SECANT, PROPOSAL_MIDPOINT, PROPOSAL_LO_ENDPOINT, and PROPOSAL_HI_ENDPOINT, and PROPOSAL_INVERSE_QUADRATIC identifiers. The checkpointable low-level step surface additionally exports BracketHistory, BracketedRootState, initialize_bracketed_root_state, and advance_bracketed_root. Terminal status identifiers are ROOT_STATUS_RUNNING, ROOT_STATUS_EXACT_LO, ROOT_STATUS_EXACT_HI, ROOT_STATUS_EXACT_INTERIOR, ROOT_STATUS_WIDTH_CONVERGED, ROOT_STATUS_MISSING_BRACKET, ROOT_STATUS_NONFINITE_EVALUATION, and ROOT_STATUS_MAX_STEPS. It exposes fixed-shape evidence and typed failure state but makes no implicit-root derivative claim. Behavior, field definitions, and differentiability caveats are in Root-finding.

The separate derivative-certificate vocabulary exports ImplicitRootAssumptions, ImplicitRootCertificate, ImplicitRootResult, DERIVATIVE_STATUS_CERTIFIED, DERIVATIVE_STATUS_PRIMAL_FAILED, DERIVATIVE_STATUS_ASSUMPTIONS_REJECTED, DERIVATIVE_STATUS_NONFINITE, DERIVATIVE_STATUS_RESIDUAL_TOO_LARGE, DERIVATIVE_STATUS_SLOPE_ILL_CONDITIONED, and DERIVATIVE_STATUS_BRACKET_TOO_WIDE. These types do not change the value-first semantics of safeguarded_bracketed_root. The explicitly gated implicit_bracketed_root accepts f(x, args) and exposes an implicit function theorem (IFT) derivative only when every certificate predicate passes; rejected values and attempted derivatives are NaN while the nested primal diagnostics remain available.

initialize_bracket(lo, hi, f_lo, f_hi) -> BracketState
update_bracket(state, x, fx, *, valid=True) -> BracketState
propose_bracketed(state, *, safeguard_fraction=0.1) -> BracketProposal
safeguarded_bracketed_root(
    f,
    lo,
    hi,
    *,
    max_steps,
    atol=0.0,
    rtol=1.0e-8,
    safeguard_fraction=0.1,
) -> BracketedRootResult

BracketState fields are lo, hi, f_lo, f_hi, and bracketed. BracketProposal fields are x, kind, and safeguarded; the last field is true exactly when midpoint fallback replaced a rejected secant. RootTrace fields are proposal, residual, lo, hi, f_lo, f_hi, proposal_kind, executed, admissible, converged, and status. BracketedRootResult fields are root, residual, status, converged, bracketed, n_evaluations, residual_scale, final_bracket, and trace.

jaxstro.numerics.interpolation¶

interp1d(...) is the clamped linear baseline. cubic_hermite_interp(...) evaluates cubic Hermite interpolation from supplied node derivatives; natural_cubic_spline_coeffs(...) computes natural cubic spline coefficients; eval_cubic_spline(...) evaluates those coefficients; NaturalCubicSpline1D wraps a natural spline table as a PyTree; pchip_slopes(...) constructs shape-preserving slopes; monotone_cubic_interp(...) combines those slopes with the Hermite evaluator; and MonotoneTabulatedFunction1D wraps a monotone table as a PyTree. The method page is Cubic interpolation.

jaxstro.numerics.regular_grid¶

regular_grid_interp(points, values, xi, boundary="clamp") performs static-rank multilinear interpolation on a tensor-product grid. bilinear_interp(...) and trilinear_interp(...) are convenience wrappers. Grid axes occupy the leading dimensions of values; every trailing dimension is a payload axis. Boundary policy is explicit: clamp, whole-payload fill, or eager reject. Value-dependent axis/query rejection is skipped while traced. The method page is Regular-grid interpolation.

jaxstro.numerics.grids¶

log_grid(...) and geometric_bin_edges(...) construct positive logarithmic grids; bin_centers(...) and geometric_bin_centers(...) compute arithmetic or geometric centers; conservative_rebin(...) redistributes integrated bin totals onto new edges while preserving total overlap. The method page is Grids and sampling utilities.

jaxstro.numerics.meshes¶

structured_edges_1d(...), Mesh1D(...), face_geometry_1d(...), and cell_neighbors_1d(...) cover structured 1D mesh geometry. divergence_1d(...) and cell_to_face_average(...) provide small finite-volume stencil helpers. conservative_remap_1d(...) remaps cell averages while preserving integrated totals over the overlapping domain. The method page is Structured 1D meshes.

jaxstro.numerics.integration¶

trapz, cumulative_trapz (dx-outside uniform path), simpson, and cumulative_simpson panel-endpoint sums. The trapezoid ordering choice is in Newton–Cotes integration; fixed-node and Simpson-panel rules are in Fixed-node quadrature.

jaxstro.numerics.quadrature¶

gauss_legendre_nodes(n), gauss_laguerre_nodes(n), gauss_hermite_nodes(n) (probabilists’), clenshaw_curtis_nodes(n), hermite_e_basis, and Hermite expansion coefficients. Nodes are generated once on the host and frozen to constants; gradients flow through the integrand values, not the nodes (principle 7). The method page is Fixed-node quadrature.

jaxstro.numerics.splines¶

bspline_basis(knots, x, degree=3) evaluates all basis functions; bspline_design_matrix(knots, x, degree=3) gives the explicit sample-matrix spelling; bspline_eval(knots, coeffs, x, degree=3, axis=-1) contracts basis values with supplied coefficients; bspline_eval_deboor(...) evaluates the same spline through de Boor recursion; bspline_derivative(...), bspline_antiderivative(...), and bspline_integral(...) cover calculus helpers; bspline_roughness_penalty(...) supplies an integrated squared derivative penalty; fit_bspline_lstsq(...) fits coefficients for fixed knots; adaptive_open_uniform_knots(...) places interior knots at sample quantiles; tensor_product_design_matrix(...) builds row-wise tensor-product designs; and BSpline1D wraps knots and coefficients as a PyTree. The method page is B-splines.

jaxstro.numerics.linear_algebra¶

weighted_lstsq(...) solves ordinary or weighted dense least-squares problems; qr_solve(...) and svd_solve(...) expose explicit full-rank and truncated-SVD solve policies; covariance_matrix(...), correlation_from_covariance(...), and correlation_matrix(...) provide finite covariance/correlation helpers; and is_positive_definite(...), add_diagonal_jitter(...), and positive_definite_jitter(...) cover small dense positive-definite diagnostics. Concrete weighted calls reject non-finite weights and nonpositive covariance normalization; covariance-to-correlation conversion rejects non-square, non-finite, or negative-variance inputs. Value-dependent checks are skipped while traced. The method page is Linear algebra helpers.

jaxstro.numerics.distributions¶

normal_logpdf(...), normal_cdf(...), and normal_ppf(...) cover normal kernels. lognormal_*, powerlaw_*, and truncated_normal_* provide logpdf, CDF, and inverse-CDF helpers for positive lognormal, finite-support power-law, and truncated-normal families. The power-law signatures are unchanged, while normalization, logpdf, CDF, and PPF now share a smooth removable-singularity formulation through alpha=-1, including the alpha derivative. The method page is Distribution kernels.

jaxstro.numerics.autodiff¶

jvp(...), vjp(...), jacobian_vector_product(...), vector_jacobian_product(...), hvp(...), gauss_newton_product(...), and empirical_fisher_product(...) expose common derivative products as named helpers over JAX primitives. The method page is Autodiff products.

jaxstro.geometry¶

normalize(...) and angular_distance(...) cover vector geometry. rotation_matrix(...), quaternion_from_axis_angle(...), quaternion_multiply(...), quaternion_conjugate(...), and quaternion_rotate(...) cover axis-angle and quaternion rotations. rigid_transform(...), invert_rigid(...), and compose_rigid(...) cover 3D rigid transforms with explicit composition order. The method page is Geometry helpers.

jaxstro.numerics.optimization¶

squared_loss(...), huber_loss(...), and pseudo_huber_loss(...) provide elementwise residual losses. objective_summary(...) reports scalar squared-loss diagnostics for residual vectors, optionally with weights. armijo_backtracking(...) is a fixed-iteration Armijo line-search helper whose objective and scan length are static under JIT. relative_step_norm(...), gradient_inf_norm(...), and convergence_summary(...) provide optimizer-agnostic stopping diagnostics. The method page is Optimization helpers.

jaxstro.numerics.ode¶

euler_step(...), midpoint_step(...), and rk4_step(...) expose one-step updates for first-order systems with call signature rhs(y, t). euler(...), midpoint(...), rk4(...), and solve_fixed_step(...) return ODEResult(t, y) histories including the initial state. velocity_verlet(...) returns VerletResult(t, q, v) for separable second-order systems with acceleration callback a(q, t). The method page is Fixed-step ODE integration.

jaxstro.numerics.operators¶

DenseOperator(...) and DiagonalOperator(...) are primitive PyTree operators with matvec, rmatvec, shape, and to_dense methods. scale(...), add(...), compose(...), transpose(...), and block_diag(...) build scaled, summed, product, transpose-view, and block-diagonal operators. The method page is Linear operators.

jaxstro.numerics.special¶

planck_lambda_cgs(...), log_planck_lambda_cgs(...), planck_nu_cgs(...), and log_planck_nu_cgs(...) provide explicit-CGS Planck radiance kernels. log_normalize(...) and normalize_log_weights(...) handle stable log-weight normalization. legendre_basis(...), chebyshev_t_basis(...), and laguerre_basis(...) evaluate orthogonal polynomial bases with the degree axis last. The method page is Special functions.

jaxstro.numerics.sampling¶

inverse_cdf_draw(...) maps a uniform deviate through a tabulated inverse CDF. stratified_uniform(...) draws one uniform sample from each equal-width stratum with deterministic shape. The method pages are Root-finding and Grids and sampling utilities.

jaxstro.numerics.random¶

key_stream(...) and fold_in_stream(...) make JAX PRNG key flow explicit. seed_manifest(...) renders deterministic seed metadata. systematic_resample(...), stratified_resample(...), and residual_resample(...) return shape-stable resampled indices from nonnegative weights. Their public wrappers reject invalid concrete eager inputs; traced callers own the finite/nonnegative value precondition. The method page is Random streams and resampling.

jaxstro.atmospheres¶

AtmosphereParams names physical grid coordinates. AtmosphereQuery combines those coordinates with an exact product_id, a fixed SpectralPlan, and the requested parameter plane. AtmosphereLibrary.from_local(...) discovers local artifacts; prepare(query) returns a PreparationResult containing either a filesystem-free PreparedAtmosphere or a structured SpectrumStatusCode.

AtmosphereAdapterRegistry routes exact products to NewEraBackend, BoszBackend, SonoraBackend, or TlustyBackend. ProductDescriptor records the topology and evidence-selected interpolation policy; ArtifactReport records artifact validity and identity. Sonora and BSTAR adapters are present but fail closed with POLICY_NOT_VALIDATED through the registry. OSTAR product IDs are composition-scoped, as are the six BSTAR vturb=2 and eleven BSTAR vturb=10 standard/CN products.

jaxstro.spectra¶

SpectralAxis records coordinate, unit, point/bin sampling, optional edges, and resolving power. Spectrum pairs an axis with explicit SpectralSemantic and mandatory SpectrumProvenance. SpectralPlan declares the fixed output axis and resampling method. SpectrumResult, SpectrumStatus, and SpectrumStatusCode keep expected scientific gaps array-compatible.

convert_spectrum(...), resample_spectrum(...), and the wavelength/frequency transforms preserve explicit density semantics. PreparedRectilinearStencil and PreparedSimplexStencil evaluate fixed host-selected topologies with an evidence-selected FluxInterpolation policy. There is no jaxstro.atmospheres.spectra compatibility alias.

The dataset matrix is in Atmosphere capabilities, the ownership and physical semantics are in Spectra data architecture, and the request recipe is in Query atmosphere spectra.

jaxstro.testing¶

jaxstro.testing contains validation utilities rather than model primitives. The grad-audit engine classifies curated differentiability cases, while the finite-difference diagnostics expose reusable central-difference gradients, Jacobians, directional derivatives, and structured AD-vs-FD comparison reports. EvidenceAnchor, MethodEvidence, and NumericalTrustReport describe method-level evidence, and trust_report_to_json(...), trust_report_to_markdown(...), and default_numerics_trust_report(...) render deterministic trust summaries. These helpers are intended for test suites and validation scripts.

The provenance-card surface is also public: ProvenanceCard, validate_card(...), render_card(...), and render_registry(...) validate already-parsed mappings and deterministically render MyST pages. YAML/JSON parsing and repository file policy stay with caller tooling, keeping the installed module dependency-light. The generated source-backed provenance cards demonstrate this API.

jaxstro.provenance¶

hash_artifact(...) records SHA-256 file digests and sizes. environment_snapshot(...) captures a small explicit Python/platform/package snapshot. MethodManifest, manifest_to_json(...), and manifest_to_markdown(...) provide deterministic method-run records for validation reports and downstream workflow logs. These runtime manifests answer what a run consumed; they do not establish the source behind a scientific claim. The architecture page is Provenance architecture.