Emily Boudreaux
6b57738330
Note for now much of the docs is LLM written. This was done to save time and focus on code development. The docs have been LOOSLEY reviewed. However, the code itself has been either fully written by hand or fully reviewed. Therefore, the docs should at the moment be seen as a loose resource rather than authoratiative (and this is on top of the general ability for docs to drift)
156 lines
28 KiB
XML
156 lines
28 KiB
XML
<?xml version='1.0' encoding='UTF-8' standalone='no'?>
|
|
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.13.2" xml:lang="en-US">
|
|
<compounddef id="dir_ae4e54e2b3dd44e066c26d6c78043d75" kind="dir">
|
|
<compoundname>src/include/serif/utils/serialize</compoundname>
|
|
<innerfile refid="archive_8hpp">archive.hpp</innerfile>
|
|
<innerfile refid="components_8hpp">components.hpp</innerfile>
|
|
<innerfile refid="utils_2serialize_2equations_8hpp">equations.hpp</innerfile>
|
|
<innerfile refid="utils_2serialize_2model_8hpp">model.hpp</innerfile>
|
|
<innerfile refid="numerics_8hpp">numerics.hpp</innerfile>
|
|
<innerfile refid="physics_8hpp">physics.hpp</innerfile>
|
|
<innerfile refid="record_8hpp">record.hpp</innerfile>
|
|
<innerfile refid="serialize_8hpp">serialize.hpp</innerfile>
|
|
<innerfile refid="utils_2serialize_2solver_8hpp">solver.hpp</innerfile>
|
|
<innerfile refid="utils_2serialize_2top_8hpp">top.hpp</innerfile>
|
|
<briefdescription>
|
|
</briefdescription>
|
|
<detaileddescription>
|
|
<para>An archive contains the information supplied to <computeroutput>pack(...)</computeroutput>. Each component describes its own scientific data through an external <computeroutput>Serializer<T></computeroutput> specialization. The archive handles files, encoding, indexing and provenance. The model, computational graph and numerical algorithms do not depend on this module.</para>
|
|
<para><programlisting filename=".cpp"><codeline><highlight class="preprocessor">#include<sp/>"<ref refid="serialize_8hpp" kindref="compound">serif/utils/serialize/serialize.hpp</ref>"</highlight><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="preprocessor">#include<sp/>"<ref refid="backend_2mfem_2serialize_2configuration_8hpp" kindref="compound">serif/backend/mfem/serialize/configuration.hpp</ref>"</highlight><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">namespace<sp/></highlight><highlight class="normal">serialization<sp/>=<sp/><ref refid="namespaceserif_1_1utils_1_1serialize" kindref="compound">serif::utils::serialize</ref>;</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>contents<sp/>=<sp/>serialization::pack(stellar_model,<sp/>discretization,<sp/>solution);</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>written<sp/>=<sp/>serialization::write(</highlight><highlight class="stringliteral">"star.serif"</highlight><highlight class="normal">,<sp/>contents,<sp/>{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>.author<sp/>=<sp/></highlight><highlight class="stringliteral">"Observer<sp/>name"</highlight><highlight class="normal">,</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>.comment<sp/>=<sp/></highlight><highlight class="stringliteral">"Equilibrium<sp/>at<sp/>the<sp/>end<sp/>of<sp/>the<sp/>rotation<sp/>sequence"</highlight><highlight class="normal">,</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>.metadata<sp/>=<sp/>{{</highlight><highlight class="stringliteral">"units"</highlight><highlight class="normal">,<sp/></highlight><highlight class="stringliteral">"G=M=R=1<sp/>code<sp/>units"</highlight><highlight class="normal">},<sp/>{</highlight><highlight class="stringliteral">"study"</highlight><highlight class="normal">,<sp/></highlight><highlight class="stringliteral">"rotation<sp/>sequence"</highlight><highlight class="normal">}}</highlight></codeline>
|
|
<codeline><highlight class="normal">});</highlight></codeline>
|
|
</programlisting></para>
|
|
<para><computeroutput>write</computeroutput> and reader operations return <computeroutput>std::expected<T, Error></computeroutput>. An error has a component <computeroutput>path</computeroutput> and an explanatory <computeroutput>message</computeroutput>. Check that result before using it. The sandbox demonstrates one way to keep error handling separate from the scientific workflow.</para>
|
|
<para><computeroutput>pack(solution)</computeroutput> is valid too. A result supplies its available model, accepted physical coefficients, diagnostics, normalization factors/reference scales, and supported Newton checkpoint. It cannot supply a mesh, a preconditioner recipe or settings that the result never retained. Passing the configured discretization and solver options preserves those additional inputs. Custom prescribed inputs, fixed displacement and assembly options should also be supplied when used.</para>
|
|
<para><computeroutput>pack</computeroutput> immediately owns encoded data. Changing a model or destroying its resources after packing does not change that snapshot. <computeroutput>named("comparison_star", value)</computeroutput> chooses a name when multiple objects have the same default role. Conflicting objects with the same name are an error; identical represented objects are deduplicated. An unregistered type appears as an <computeroutput>unsupported</computeroutput> entry containing an explanation. A partial archive remains useful for analysis, but does not claim full reconstruction.</para>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/utils/serialize/README.md_1autotoc_md10">
|
|
<title>Read only the information needed</title><para><programlisting filename=".cpp"><codeline><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>opened<sp/>=<sp/>serialization::Reader::open(</highlight><highlight class="stringliteral">"star.serif"</highlight><highlight class="normal">);</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keywordflow">if</highlight><highlight class="normal"><sp/>(!opened)<sp/>{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>Report<sp/>opened.error().path<sp/>and<sp/>opened.error().message.</highlight><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/></highlight><highlight class="keywordflow">return</highlight><highlight class="normal">;</highlight></codeline>
|
|
<codeline><highlight class="normal">}</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">auto</highlight><highlight class="normal">&<sp/>reader<sp/>=<sp/>*opened;</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">const</highlight><highlight class="normal"><sp/></highlight><highlight class="keyword">auto</highlight><highlight class="normal">&<sp/>available<sp/>=<sp/>reader.ledger();</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>author<sp/>=<sp/>reader.read<std::string>(</highlight><highlight class="stringliteral">"provenance/author"</highlight><highlight class="normal">);</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>coefficients<sp/>=<sp/>reader.read<std::vector<double>>(</highlight><highlight class="stringliteral">"solution/state/coefficients"</highlight><highlight class="normal">);</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>checkpoint<sp/>=<sp/>reader.read<Checkpoint>();</highlight></codeline>
|
|
</programlisting></para>
|
|
<para>Opening reads the fixed header and the ledger, not the coefficient or mesh payloads. <computeroutput>node(path)</computeroutput> returns an owned component subtree for inspection or a specialized reconstruction routine. <computeroutput>read<T>(path)</computeroutput> then applies <computeroutput>Serializer<T>::load</computeroutput>. Every selected section is length-checked and checksum-checked before use. <computeroutput>validate()</computeroutput> reads and checks all sections. A <computeroutput>Reader</computeroutput> owns an open stream and should not be shared between concurrent reads without external synchronization.</para>
|
|
<para>SERiF compatibility defaults to the same major version. Set <computeroutput>ReadOptions::version_tolerance</computeroutput> to <computeroutput>exact</computeroutput> to require the same version string or <computeroutput>any</computeroutput> for explicit recovery/inspection across major versions. These choices do not disable file-format checks, component-schema checks, coordinate validation or MFEM representation checks. The separate file-format version is currently <bold>1</bold>.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/utils/serialize/README.md_1autotoc_md11">
|
|
<title>Text and binary</title><para>Choose <computeroutput>.format = Format::text</computeroutput> for readable named sections, one number per line in array sections, and quoted strings. Text uses the classic locale and <computeroutput>max_digits10</computeroutput>; it preserves finite double values, including signed zero. Nonfinite doubles use <computeroutput>bits:</computeroutput> followed by their 16 hexadecimal IEEE-754 digits, preserving NaN payloads too. This is a sectioned scientific text format, not a rectangular CSV table.</para>
|
|
<para>The default binary encoding stores numerical arrays as little-endian fixed-width values. It never writes C++ structure padding, addresses, native <computeroutput>size_t</computeroutput> layout or virtual tables. Both formats represent the same component tree and preserve binary64 coefficient values exactly. A full model description is distinct from bitwise process memory: derived caches are rebuilt, and different hardware or library versions may produce different subsequent arithmetic.</para>
|
|
<para><computeroutput>tools/read_serif_archive.py</computeroutput> is a standard-library-only data inspector for either format:</para>
|
|
<para><programlisting filename=".sh"><codeline><highlight class="normal">python<sp/>tools/read_serif_archive.py<sp/>star.serif</highlight></codeline>
|
|
<codeline><highlight class="normal">python<sp/>tools/read_serif_archive.py<sp/>star.serif<sp/>--read<sp/>solution/state/coefficients<sp/>--csv</highlight></codeline>
|
|
</programlisting></para>
|
|
<para>The first command lists available fields and their offsets. The second exports ordinary <computeroutput>index,value</computeroutput> CSV for analysis. This inspector does not instantiate physical models or apply the C++ model loader's version and formulation compatibility policy.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/utils/serialize/README.md_1autotoc_md12">
|
|
<title>Header, ledger and data sections</title><para>The first <bold>512 bytes</bold> are an ASCII header beginning with <computeroutput>SERIF_ARCHIVE 1</computeroutput>. Its fields specify encoding, SERiF version, UTC write time, ledger offset/length, data offset, total file length, entry count and ledger checksum. Remaining header bytes are whitespace. All offsets are absolute <bold>byte offsets</bold>, including in text mode; files are always opened in binary stream mode to avoid newline translation.</para>
|
|
<para>The ledger starts immediately after the header. It has one row per component or field:</para>
|
|
<para><programlisting filename=".text"><codeline><highlight class="normal">#<sp/>path<sp/>schema<sp/>version<sp/>kind<sp/>count<sp/>offset<sp/>bytes<sp/>checksum</highlight></codeline>
|
|
</programlisting></para>
|
|
<para>Paths and schema names are quoted. Offsets and byte lengths have 20 decimal digits, allowing the complete ledger size to be known before payload positions are assigned. Rows are sorted by path; parent components precede their fields. A component-directory row has no payload. Text-mode data sections have visible <computeroutput># path</computeroutput> labels preceding the indexed payload. Binary payloads are contiguous.</para>
|
|
<para><table rows="10" cols="2"><row>
|
|
<entry thead="yes"><para>Kind </para>
|
|
</entry><entry thead="yes"><para>Representation </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>0 </para>
|
|
</entry><entry thead="no"><para>Component directory </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>1 </para>
|
|
</entry><entry thead="no"><para>Boolean, one byte in binary </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>2 </para>
|
|
</entry><entry thead="no"><para>Signed 64-bit integer </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>3 </para>
|
|
</entry><entry thead="no"><para>Unsigned 64-bit integer </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>4 </para>
|
|
</entry><entry thead="no"><para>IEEE-754 binary64 real </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>5 </para>
|
|
</entry><entry thead="no"><para>String bytes, UTF-8 by convention </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>6 </para>
|
|
</entry><entry thead="no"><para>Binary64 array </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>7 </para>
|
|
</entry><entry thead="no"><para>Signed 64-bit integer array </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para>8 </para>
|
|
</entry><entry thead="no"><para>Unsigned 64-bit integer array </para>
|
|
</entry></row>
|
|
</table>
|
|
</para>
|
|
<para>Binary numeric values occupy eight bytes except booleans. Counts give array extents or unescaped string byte lengths; scalar counts are one. <computeroutput>fnv1a64-v1</computeroutput> fingerprints detect accidental corruption and identify exact serialized resources. They are not cryptographic authentication. Readers enforce configurable index, payload, entry-count and nesting limits; raise those limits explicitly for unusually large models.</para>
|
|
<para>Writes use an exclusively created temporary file beside the destination. Only a complete, successfully closed file replaces the destination. A failed write retains the previous archive. This prevents partial publication; it is not a guarantee against filesystem or hardware failure after publication.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/utils/serialize/README.md_1autotoc_md13">
|
|
<title>Provenance and meshes</title><para>Every archive includes <computeroutput>provenance</computeroutput>: UTC time; SERiF version generated directly from Meson's project version through <computeroutput>serif/config.hpp.in</computeroutput>; compiler/build information; host OS, kernel, machine and architecture information where exposed; available library versions; author, comment and user metadata. The MFEM component adds the backend configuration, MFEM source information and exposed dependency versions. Runtime MPI information is queried only if MPI is already initialized. Missing platform facilities are not guessed.</para>
|
|
<para>Metadata keys use the same simple field-name alphabet as other component names: letters, digits, underscores, periods and hyphens. Author, comment and metadata values can contain Unicode, punctuation and line breaks. Record the unit convention explicitly: physical dimension tags do not identify SI, CGS or a particular code-unit conversion.</para>
|
|
<para>MFEM discretizations embed native reference meshes by default, including the separate logical mesh when deformation needs it. Use <computeroutput>save_discretization(finite_elements, {.embed_mesh = false})</computeroutput> to retain mesh identities and representation metadata while obtaining native mesh text from a caller-supplied resolver during restoration. A mismatched supplied mesh is rejected. The mesh payload itself uses enough decimal digits to recover stored coordinates; coefficients are saved in their original global/reduced numbering, with space, support and signed element-numbering information for validation.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/utils/serialize/README.md_1autotoc_md14">
|
|
<title>Resume an accepted Newton step</title><para>An observer may return <computeroutput>SolveControl::stop</computeroutput>. The request takes effect at a completed accepted boundary. <computeroutput>result.checkpoint()</computeroutput> contains the accepted state, original convergence reference, next line-search step, carried normalized correction and cumulative accepted history. It contains no live Jacobian, inverse or computational graph cache.</para>
|
|
<para>Save the checkpoint together with the model/discretization recipe, normalization, solver options and any additional physical inputs. After loading, <computeroutput>resume_equilibrium(...)</computeroutput> reconstructs and qualifies that state, rebuilds preparation, checks the represented residual against the saved boundary, and continues with the original convergence reference and iteration budget. Increasing the iteration budget is an explicit solver-option change.</para>
|
|
<para>Exact accepted-boundary checkpoint support currently covers <computeroutput>StandardNewton</computeroutput>, <computeroutput>NormalizedResidualMetric</computeroutput> and <computeroutput>FGMRES</computeroutput>. Other strategies continue to solve normally but explicitly report that their private history is not checkpointable. This is not yet a continuation-controller checkpoint. Restoring coefficients alone is a useful new initial guess, but does not preserve Newton history.</para>
|
|
<para>See <computeroutput>tests/sandbox/serialization_sandbox.cpp</computeroutput> for the complete save/load/resume example, <ref refid="md_src_2include_2serif_2utils_2serialize_2_c_o_m_p_o_n_e_n_t_s" kindref="compound">COMPONENTS.md</ref> for the supported scientific descriptions and custom-type rules, and the <ref refid="backend_2mfem_2serialize_2_r_e_a_d_m_e_8md" kindref="compound">MFEM serializer notes</ref> for backend reconstruction requirements.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/utils/serialize/README.md_1autotoc_md15">
|
|
<title>Add a component</title><para>Specialize <computeroutput>Serializer<T></computeroutput> with a stable <computeroutput>key</computeroutput>, <computeroutput>save(const T&) -> Node</computeroutput>, and <computeroutput>load(const Node&) -> Result<T></computeroutput>. <computeroutput>object</computeroutput>, <computeroutput>field</computeroutput>, <computeroutput>read_object</computeroutput> and <computeroutput>member<T></computeroutput> compose existing serializers. Plain configuration aggregates can use <computeroutput>StructSerializer<T></computeroutput> and an explicit <computeroutput>member_field</computeroutput> list. Keep physics validation with the component; existing <computeroutput>validate()</computeroutput> methods are reused during reconstruction. Schema versions default to one; an explicit <computeroutput>Serializer<T>::version</computeroutput> selects another supported version. When a schema changes, increase that version and add an explicit migration from the inspected old <computeroutput>Node</computeroutput> if needed. New formats do not require changing component serializers.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/utils/serialize/README.md_1autotoc_md16">
|
|
<title>Export a solved polytrope to TOP</title><para>The TOP exporter is a separate format writer in this serialization module. It accepts a stellar model together with the mesh and accepted physical state that realize it. The MFEM sampling adapter remains an explicit include:</para>
|
|
<para><programlisting filename=".cpp"><codeline><highlight class="preprocessor">#include<sp/>"<ref refid="backend_2mfem_2serialize_2top_8hpp" kindref="compound">serif/backend/mfem/serialize/top.hpp</ref>"</highlight><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">namespace<sp/></highlight><highlight class="normal">io<sp/>=<sp/><ref refid="namespaceserif_1_1utils_1_1serialize" kindref="compound">serif::utils::serialize</ref>;</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">const</highlight><highlight class="normal"><sp/></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>exported<sp/>=<sp/>io::export_top(</highlight><highlight class="stringliteral">"top-model"</highlight><highlight class="normal">,<sp/>stellar_model,<sp/>finite_elements,</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>solution.state(),<sp/>io::TopExportOptions{.radial_points<sp/>=<sp/>64,<sp/>.maximum_degree<sp/>=<sp/>16});</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="comment">//<sp/>Equivalent<sp/>when<sp/>the<sp/>result<sp/>retains<sp/>the<sp/>same<sp/>physical<sp/>model:</highlight><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="comment">//<sp/>const<sp/>auto<sp/>exported<sp/>=<sp/>io::export_top("top-model",<sp/>finite_elements,<sp/>solution,<sp/>options);</highlight><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keywordflow">if</highlight><highlight class="normal"><sp/>(!exported)<sp/>{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>Report<sp/>exported.error().path<sp/>and<sp/>exported.error().message.</highlight><highlight class="normal"></highlight></codeline>
|
|
<codeline><highlight class="normal">}</highlight></codeline>
|
|
</programlisting></para>
|
|
<para><computeroutput>StellarModel</computeroutput> describes physics; it deliberately does not contain a mesh or solution. No normalization factors should be applied before export: accepted state coefficients already represent physical quantities. Exporting an accepted state does not certify equilibrium convergence. The complete sandbox exports only after its solve converges:</para>
|
|
<para><programlisting filename=".sh"><codeline><highlight class="normal">./build/tests/sandbox/complete_sandbox<sp/>--angular-momentum<sp/>0.2<sp/>--surface-degree<sp/>8<sp/>\</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/>--surface-refinement<sp/>1<sp/>--equatorial-refinement<sp/>3<sp/>--export-top<sp/>top-model</highlight></codeline>
|
|
</programlisting></para>
|
|
<para>Use <computeroutput>--top-radial-points</computeroutput>, <computeroutput>--top-degree</computeroutput>, <computeroutput>--top-angular-points</computeroutput>, and <computeroutput>--top-azimuthal-points</computeroutput> to control export sampling independently of the FE mesh. Defaults are 64 Chebyshev radial points, even degree 16, 48 Gauss-Legendre angular points and 8 azimuthal samples. The parent directory must exist and the destination must not already exist. A failed export preserves any existing destination, and a successful directory is published only after every file has been written.</para>
|
|
<para>The current adapter supports the density formulation with the <computeroutput>Polytrope</computeroutput> EOS, <computeroutput>BarotropicDensityBalance</computeroutput>, <computeroutput>PrimalPoissonBalance</computeroutput>, <computeroutput>FixedAngularMomentum</computeroutput>, a solved uniform angular velocity and a zero-pressure moving surface. Unsupported physics, finite-pressure boundaries, invalid geometry and material negative densities return errors. A future realistic-EOS/finite-pressure interface needs a corresponding TOP reader; this writer does not pretend those models are vacuum polytropes.</para>
|
|
<para>The adapter reconstructs deformation using the existing geometry graph, samples the actual deformed finite-element surface and density, and accounts for nonconforming true DOFs. It uses the prescribed rotation axis and center. The source mesh and state remain unchanged. Central density is sampled and total mass is integrated from the state. Enthalpy is derived from the EOS only while writing TOP's external format; it does not become a SERiF primary field.</para>
|
|
<para>TOP represents a 2D, equatorially symmetric background. The exporter averages over azimuth and equatorial reflection at common surface-fitted radial coordinates, and projects both geometry and enthalpy onto normalized spherical harmonics. This is a measured approximation to the 3D FE representation. The returned <computeroutput>TopExportReport</computeroutput> and <computeroutput>metadata.txt</computeroutput> record source/projected radii, physical scales, symmetry and surface-projection discrepancies, sampled enthalpy angular truncation, surface enthalpy, mapping validity and tiny negative-density roundoff clamps. Defaults reject symmetry and surface-projection errors above 1e-3 and surface enthalpy above 1e-6 of its central value. Enthalpy angular truncation is reported relative to central enthalpy, without a rejection limit; it is distinct from the symmetry discrepancy. Geometry and projection checks are sampled diagnostics, not global error bounds. These are export admissibility limits, not seismic accuracy targets. Negative density is clamped only within 128 machine epsilons of the central density; larger negatives are rejected.</para>
|
|
<para>Output files are <computeroutput>lambda_eps</computeroutput>, <computeroutput>enthalpy_et_der</computeroutput>, <computeroutput>domains_boundaries</computeroutput>, plus <computeroutput>metadata.txt</computeroutput>. Radial derivatives are with respect to TOP's mapping coordinate, computed from the projected Chebyshev samples. No Bernoulli reconstruction, extra equilibrium solve or interior smoothing is performed. Finite-element interpolation noise can therefore affect those derivatives and the modes; vary export resolution at fixed FE solution before attributing a frequency change to the stellar equilibrium. For n > 1, deriving enthalpy from FE density can amplify surface regularity defects; accepting an export does not establish derivative or mode convergence. The actual-solver integration benchmark currently covers n=1.</para>
|
|
<para>Use TOP's recovered <computeroutput>poly_ester</computeroutput> reader and <computeroutput>eq_poly_ester_gamma2</computeroutput> for the selected n=1, Gamma1=2 benchmark. The files describe the equilibrium; the TOP equation module supplies Gamma1. TOP frequencies are angular frequencies divided by <computeroutput>sqrt(4*pi*G*rho_c)</computeroutput>; <computeroutput>angular_frequency_unit</computeroutput> in the report supplies that physical conversion in the input model's unit system. Divide by 2*pi to obtain cyclic frequency.</para>
|
|
<para>The backend-independent overload in <computeroutput><ref refid="utils_2serialize_2top_8hpp" kindref="compound">serif/utils/serialize/top.hpp</ref></computeroutput> accepts a <computeroutput>TopPolytropeSource</computeroutput> with physical surface-radius and enthalpy callbacks, allowing other sampling backends without an MFEM dependency. Analytic source and MFEM regressions are part of the serialization test suite. An optional test against the actual recovered TOP reader is available after building <computeroutput>top_export_fixture</computeroutput>:</para>
|
|
<para><programlisting filename=".sh"><codeline><highlight class="normal">source<sp/>/Users/tboudreaux/Programming/top/activate-top.sh</highlight></codeline>
|
|
<codeline><highlight class="normal">python<sp/>tests/serialize/top_reader.py<sp/>build/tests/serialize/top_export_fixture</highlight></codeline>
|
|
</programlisting></para>
|
|
<para>That optional check requires TOP's compiled <computeroutput>eq_poly_ester_gamma2</computeroutput> module. TOP is not a SERiF build dependency. </para>
|
|
</sect1>
|
|
</detaileddescription>
|
|
<location file="src/include/serif/utils/serialize/"/>
|
|
</compounddef>
|
|
</doxygen>
|