Emily Boudreaux
7ab8641f51
There are loads of things (solutions, models, solver descriptions, mesh's, etc..) which need to be exported from SERiF and then either reimported into SERiF or into some other program. This module is responsible for all of that. Generally with the goal of feeling like the fmt / new format module in C++23 and on (e.g. by specializing formatting structs) Note that LLM's made signifigant contributions to this module (ChatGPT 6 astra max and Claude Opus 5.5 Medium). All code has been reviewd manually
5.1 KiB
Scientific component records
These serializers describe physics and numerical choices separately from a file format. physics.hpp, equations.hpp, model.hpp, and numerics.hpp are backend independent. Each component has a stable schema name and version; nested components use the same Serializer<T> protocol as user extensions.
Supported components
- Polytropic EOS parameters; fixed mass, central density and angular momentum prescriptions; isobaric surfaces.
- Concrete barotropic equation leaves, sums, differences, scales, equation registries and explicit equilibrium compositions. EOS references are restored with an owning immutable EOS, rather than a saved address.
- Stellar models and physical stellar states. State records retain both state/residual coordinate orders, sizes and exact floating-point coefficients, including scalar and surface coordinates. Built-in coordinate IDs are explicit rather than compiler-generated names. Custom coordinates register
TermIdentity<T>or provideT::stable_id. - Nodal radial and normalized real spherical-harmonic surface descriptions, their centers and harmonic cutoffs, and interior/vacuum extension prescriptions. These descriptions accompany the state coefficients; a layout alone cannot determine which surface basis was used. The MFEM serializer supplies the associated reference mesh and surface ownership.
- Standard Newton, line-search and FGMRES controls; built-in normalization selections, Lane–Emden controls, resolved reference scales, explicit normalization plans and frozen diagonal factors.
- Configured discretizations (archive entry
configuration) combine the model, finite-element description, normalization and preconditioner. The MFEMrestore_configurationhelper reconstructs their mesh ownership and resolved model composition. - Composed block, gravity, surface, coupled and bordered preconditioner recipes, including their physical coordinate selections and nested numerical controls. Prepared matrices and inverse caches are reconstructed by numerical preparation.
- Owned prescribed-input contexts whose physical keys, values and tracking policies have serializers. Borrowed inputs retain inspectable values and report the need to reconstruct and rebind their owner.
- Quadrature role and fallback controls. Form-specific overrides remain inspectable, but their borrowed runtime descriptors require a separate owning descriptor registry before automatic reconstruction can be supported.
Plain option records use an explicit member list in StructSerializer<T>; it is not object-memory serialization or automatic reflection. Existing validate() methods run after reconstruction, and supported bare numerical recipes additionally check their parameter domains. Matrix-, mesh- and solution-dependent validity still belongs to numerical preparation.
Authored definitions and restored physics
decode<Model>(record) reconstructs the original compiled model type only when its authored equation definition has a loader. Arbitrary lambda captures, function pointers, runtime EOS views and custom computation closures cannot be recreated merely from type names or numeric fingerprints. They produce explicit unsupported records; register a named callable with a serializer when reconstruction is required.
A stellar model also saves its resolved concrete equilibrium equations when they are available. restore_stellar_model<OriginalModel>(record) returns an owning RestoredStellarModel<OriginalModel> with that explicit composition. It can reproduce the saved current physics without retaining the original callback. It does not recreate a program that regenerates equations for different EOS parameters or continuation stages. The original authored-definition limitation remains visible in the archive.
Template loading validates a schema that is already compiled into the application. It does not instantiate arbitrary new C++ types from strings in a file. A runtime loader needs an explicit application catalog of supported compiled formulations.
Reproducibility boundaries
Archive the solve configuration alongside the result: a solved star does not retain every original solver option, prescribed input, integration policy or preconditioner recipe. Preserve requested choices and resolved choices, including the preconditioner composition, reference scales and actual normalization factors. Saving only “use the default” permits a future library version to choose differently.
Quantity tags identify physical meanings, not SI, CGS or code-unit scales. The enclosing archive must provide the unit convention and provenance; normalization reference values do not supply a complete unit system. The polytropic constant's units also depend on its index.
Stored numeric coefficients and public surface parameters round-trip without formatting loss. Validated constructors may recompute derived values, including rotation-axis normalization. Scientific reconstruction therefore does not promise bit-for-bit object memory, derived arithmetic across compiler/library versions, or an identical floating-point trajectory. Exact solver restart has a separate checkpoint contract and supported-policy checks.