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)
265 lines
30 KiB
HTML
265 lines
30 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.13.2"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>SERiF: src/include/serif/utils/serialize Directory Reference</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<script type="text/javascript" src="clipboard.js"></script>
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<script type="text/javascript" src="resize.js"></script>
|
|
<script type="text/javascript" src="cookie.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<script type="text/x-mathjax-config">
|
|
MathJax.Hub.Config({
|
|
extensions: ["tex2jax.js"],
|
|
jax: ["input/TeX","output/HTML-CSS"],
|
|
});
|
|
</script>
|
|
<script type="text/javascript" async="async" src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
|
|
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
|
|
<link href="doxygen-extra.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr id="projectrow">
|
|
<td id="projectalign">
|
|
<div id="projectname">SERiF<span id="projectnumber"> v0.0.1a</span>
|
|
</div>
|
|
<div id="projectbrief">Stellar Evolution and Rotation in Four Dimensions</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.13.2 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() { codefold.init(0); });
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search',true);
|
|
$(function() { init_search(); });
|
|
});
|
|
/* @license-end */
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
|
<div id="nav-tree">
|
|
<div id="nav-tree-contents">
|
|
<div id="nav-sync" class="sync"></div>
|
|
</div>
|
|
</div>
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
|
class="ui-resizable-handle">
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function(){initNavTree('dir_ae4e54e2b3dd44e066c26d6c78043d75.html',''); initResizable(true); });
|
|
/* @license-end */
|
|
</script>
|
|
<div id="doc-content">
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="header">
|
|
<div class="headertitle"><div class="title">serialize Directory Reference</div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="dynheader">
|
|
Directory dependency graph for serialize:</div>
|
|
<div class="dyncontent">
|
|
<div class="center"><div class="zoom"><iframe scrolling="no" frameborder="0" src="dir_ae4e54e2b3dd44e066c26d6c78043d75_dep.svg" width="100%" height="434"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div></div>
|
|
</div>
|
|
<table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="files" name="files"></a>
|
|
Files</h2></td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="archive_8hpp.html">archive.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="components_8hpp.html">components.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="utils_2serialize_2equations_8hpp.html">equations.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="utils_2serialize_2model_8hpp.html">model.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="numerics_8hpp.html">numerics.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="physics_8hpp.html">physics.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="record_8hpp.html">record.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="serialize_8hpp.html">serialize.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="utils_2serialize_2solver_8hpp.html">solver.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top"><span class="icondoc"></span> </td><td class="memItemRight" valign="bottom"><a class="el" href="utils_2serialize_2top_8hpp.html">top.hpp</a></td></tr>
|
|
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table>
|
|
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
|
|
<p>An archive contains the information supplied to <code>pack(...)</code>. Each component describes its own scientific data through an external <code>Serializer<T></code> specialization. The archive handles files, encoding, indexing and provenance. The model, computational graph and numerical algorithms do not depend on this module.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="serialize_8hpp.html">serif/utils/serialize/serialize.hpp</a>"</span></div>
|
|
<div class="line"><span class="preprocessor">#include "<a class="code" href="backend_2mfem_2serialize_2configuration_8hpp.html">serif/backend/mfem/serialize/configuration.hpp</a>"</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">namespace </span>serialization = <a class="code hl_namespace" href="namespaceserif_1_1utils_1_1serialize.html">serif::utils::serialize</a>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">auto</span> contents = serialization::pack(stellar_model, discretization, solution);</div>
|
|
<div class="line"><span class="keyword">auto</span> written = serialization::write(<span class="stringliteral">"star.serif"</span>, contents, {</div>
|
|
<div class="line"> .author = <span class="stringliteral">"Observer name"</span>,</div>
|
|
<div class="line"> .comment = <span class="stringliteral">"Equilibrium at the end of the rotation sequence"</span>,</div>
|
|
<div class="line"> .metadata = {{<span class="stringliteral">"units"</span>, <span class="stringliteral">"G=M=R=1 code units"</span>}, {<span class="stringliteral">"study"</span>, <span class="stringliteral">"rotation sequence"</span>}}</div>
|
|
<div class="line">});</div>
|
|
<div class="ttc" id="abackend_2mfem_2serialize_2configuration_8hpp_html"><div class="ttname"><a href="backend_2mfem_2serialize_2configuration_8hpp.html">configuration.hpp</a></div></div>
|
|
<div class="ttc" id="anamespaceserif_1_1utils_1_1serialize_html"><div class="ttname"><a href="namespaceserif_1_1utils_1_1serialize.html">serif::utils::serialize</a></div><div class="ttdef"><b>Definition</b> discretization.hpp:220</div></div>
|
|
<div class="ttc" id="aserialize_8hpp_html"><div class="ttname"><a href="serialize_8hpp.html">serialize.hpp</a></div></div>
|
|
</div><!-- fragment --><p><code>write</code> and reader operations return <code>std::expected<T, Error></code>. An error has a component <code>path</code> and an explanatory <code>message</code>. Check that result before using it. The sandbox demonstrates one way to keep error handling separate from the scientific workflow.</p>
|
|
<p><code>pack(solution)</code> 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.</p>
|
|
<p><code>pack</code> immediately owns encoded data. Changing a model or destroying its resources after packing does not change that snapshot. <code>named("comparison_star", value)</code> 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 <code>unsupported</code> entry containing an explanation. A partial archive remains useful for analysis, but does not claim full reconstruction.</p>
|
|
<h1><a class="anchor" id="autotoc_md10"></a>
|
|
Read only the information needed</h1>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> opened = serialization::Reader::open(<span class="stringliteral">"star.serif"</span>);</div>
|
|
<div class="line"><span class="keywordflow">if</span> (!opened) {</div>
|
|
<div class="line"> <span class="comment">// Report opened.error().path and opened.error().message.</span></div>
|
|
<div class="line"> <span class="keywordflow">return</span>;</div>
|
|
<div class="line">}</div>
|
|
<div class="line"><span class="keyword">auto</span>& reader = *opened;</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span>& available = reader.ledger();</div>
|
|
<div class="line"><span class="keyword">auto</span> author = reader.read<std::string>(<span class="stringliteral">"provenance/author"</span>);</div>
|
|
<div class="line"><span class="keyword">auto</span> coefficients = reader.read<std::vector<double>>(<span class="stringliteral">"solution/state/coefficients"</span>);</div>
|
|
<div class="line"><span class="keyword">auto</span> checkpoint = reader.read<Checkpoint>();</div>
|
|
</div><!-- fragment --><p>Opening reads the fixed header and the ledger, not the coefficient or mesh payloads. <code>node(path)</code> returns an owned component subtree for inspection or a specialized reconstruction routine. <code>read<T>(path)</code> then applies <code>Serializer<T>::load</code>. Every selected section is length-checked and checksum-checked before use. <code>validate()</code> reads and checks all sections. A <code>Reader</code> owns an open stream and should not be shared between concurrent reads without external synchronization.</p>
|
|
<p>SERiF compatibility defaults to the same major version. Set <code>ReadOptions::version_tolerance</code> to <code>exact</code> to require the same version string or <code>any</code> 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 <b>1</b>.</p>
|
|
<h1><a class="anchor" id="autotoc_md11"></a>
|
|
Text and binary</h1>
|
|
<p>Choose <code>.format = Format::text</code> for readable named sections, one number per line in array sections, and quoted strings. Text uses the classic locale and <code>max_digits10</code>; it preserves finite double values, including signed zero. Nonfinite doubles use <code>bits:</code> followed by their 16 hexadecimal IEEE-754 digits, preserving NaN payloads too. This is a sectioned scientific text format, not a rectangular CSV table.</p>
|
|
<p>The default binary encoding stores numerical arrays as little-endian fixed-width values. It never writes C++ structure padding, addresses, native <code>size_t</code> 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.</p>
|
|
<p><code>tools/read_serif_archive.py</code> is a standard-library-only data inspector for either format:</p>
|
|
<div class="fragment"><div class="line">python tools/read_serif_archive.py star.serif</div>
|
|
<div class="line">python tools/read_serif_archive.py star.serif --read solution/state/coefficients --csv</div>
|
|
</div><!-- fragment --><p>The first command lists available fields and their offsets. The second exports ordinary <code>index,value</code> CSV for analysis. This inspector does not instantiate physical models or apply the C++ model loader's version and formulation compatibility policy.</p>
|
|
<h1><a class="anchor" id="autotoc_md12"></a>
|
|
Header, ledger and data sections</h1>
|
|
<p>The first <b>512 bytes</b> are an ASCII header beginning with <code>SERIF_ARCHIVE 1</code>. 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 <b>byte offsets</b>, including in text mode; files are always opened in binary stream mode to avoid newline translation.</p>
|
|
<p>The ledger starts immediately after the header. It has one row per component or field:</p>
|
|
<div class="fragment"><div class="line"># path schema version kind count offset bytes checksum</div>
|
|
</div><!-- fragment --><p>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 <code># path</code> labels preceding the indexed payload. Binary payloads are contiguous.</p>
|
|
<table class="markdownTable">
|
|
<tr class="markdownTableHead">
|
|
<th class="markdownTableHeadNone">Kind </th><th class="markdownTableHeadNone">Representation </th></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyNone">0 </td><td class="markdownTableBodyNone">Component directory </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyNone">1 </td><td class="markdownTableBodyNone">Boolean, one byte in binary </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyNone">2 </td><td class="markdownTableBodyNone">Signed 64-bit integer </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyNone">3 </td><td class="markdownTableBodyNone">Unsigned 64-bit integer </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyNone">4 </td><td class="markdownTableBodyNone">IEEE-754 binary64 real </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyNone">5 </td><td class="markdownTableBodyNone">String bytes, UTF-8 by convention </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyNone">6 </td><td class="markdownTableBodyNone">Binary64 array </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyNone">7 </td><td class="markdownTableBodyNone">Signed 64-bit integer array </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyNone">8 </td><td class="markdownTableBodyNone">Unsigned 64-bit integer array </td></tr>
|
|
</table>
|
|
<p>Binary numeric values occupy eight bytes except booleans. Counts give array extents or unescaped string byte lengths; scalar counts are one. <code>fnv1a64-v1</code> 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.</p>
|
|
<p>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.</p>
|
|
<h1><a class="anchor" id="autotoc_md13"></a>
|
|
Provenance and meshes</h1>
|
|
<p>Every archive includes <code>provenance</code>: UTC time; SERiF version generated directly from Meson's project version through <code>serif/config.hpp.in</code>; 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.</p>
|
|
<p>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.</p>
|
|
<p>MFEM discretizations embed native reference meshes by default, including the separate logical mesh when deformation needs it. Use <code>save_discretization(finite_elements, {.embed_mesh = false})</code> 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.</p>
|
|
<h1><a class="anchor" id="autotoc_md14"></a>
|
|
Resume an accepted Newton step</h1>
|
|
<p>An observer may return <code>SolveControl::stop</code>. The request takes effect at a completed accepted boundary. <code>result.checkpoint()</code> 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.</p>
|
|
<p>Save the checkpoint together with the model/discretization recipe, normalization, solver options and any additional physical inputs. After loading, <code>resume_equilibrium(...)</code> 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.</p>
|
|
<p>Exact accepted-boundary checkpoint support currently covers <code>StandardNewton</code>, <code>NormalizedResidualMetric</code> and <code>FGMRES</code>. 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.</p>
|
|
<p>See <code>tests/sandbox/serialization_sandbox.cpp</code> for the complete save/load/resume example, <a class="el" href="md_src_2include_2serif_2utils_2serialize_2_c_o_m_p_o_n_e_n_t_s.html">COMPONENTS.md</a> for the supported scientific descriptions and custom-type rules, and the <a class="el" href="backend_2mfem_2serialize_2_r_e_a_d_m_e_8md.html">MFEM serializer notes</a> for backend reconstruction requirements.</p>
|
|
<h1><a class="anchor" id="autotoc_md15"></a>
|
|
Add a component</h1>
|
|
<p>Specialize <code>Serializer<T></code> with a stable <code>key</code>, <code>save(const T&) -> Node</code>, and <code>load(const Node&) -> Result<T></code>. <code>object</code>, <code>field</code>, <code>read_object</code> and <code>member<T></code> compose existing serializers. Plain configuration aggregates can use <code>StructSerializer<T></code> and an explicit <code>member_field</code> list. Keep physics validation with the component; existing <code>validate()</code> methods are reused during reconstruction. Schema versions default to one; an explicit <code>Serializer<T>::version</code> selects another supported version. When a schema changes, increase that version and add an explicit migration from the inspected old <code>Node</code> if needed. New formats do not require changing component serializers.</p>
|
|
<h1><a class="anchor" id="autotoc_md16"></a>
|
|
Export a solved polytrope to TOP</h1>
|
|
<p>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:</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="backend_2mfem_2serialize_2top_8hpp.html">serif/backend/mfem/serialize/top.hpp</a>"</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">namespace </span>io = <a class="code hl_namespace" href="namespaceserif_1_1utils_1_1serialize.html">serif::utils::serialize</a>;</div>
|
|
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> exported = io::export_top(<span class="stringliteral">"top-model"</span>, stellar_model, finite_elements,</div>
|
|
<div class="line"> solution.state(), io::TopExportOptions{.radial_points = 64, .maximum_degree = 16});</div>
|
|
<div class="line"><span class="comment">// Equivalent when the result retains the same physical model:</span></div>
|
|
<div class="line"><span class="comment">// const auto exported = io::export_top("top-model", finite_elements, solution, options);</span></div>
|
|
<div class="line"><span class="keywordflow">if</span> (!exported) {</div>
|
|
<div class="line"> <span class="comment">// Report exported.error().path and exported.error().message.</span></div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="abackend_2mfem_2serialize_2top_8hpp_html"><div class="ttname"><a href="backend_2mfem_2serialize_2top_8hpp.html">top.hpp</a></div></div>
|
|
</div><!-- fragment --><p><code>StellarModel</code> 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:</p>
|
|
<div class="fragment"><div class="line">./build/tests/sandbox/complete_sandbox --angular-momentum 0.2 --surface-degree 8 \</div>
|
|
<div class="line"> --surface-refinement 1 --equatorial-refinement 3 --export-top top-model</div>
|
|
</div><!-- fragment --><p>Use <code>--top-radial-points</code>, <code>--top-degree</code>, <code>--top-angular-points</code>, and <code>--top-azimuthal-points</code> 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.</p>
|
|
<p>The current adapter supports the density formulation with the <code>Polytrope</code> EOS, <code>BarotropicDensityBalance</code>, <code>PrimalPoissonBalance</code>, <code>FixedAngularMomentum</code>, 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.</p>
|
|
<p>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.</p>
|
|
<p>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 <code>TopExportReport</code> and <code>metadata.txt</code> 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.</p>
|
|
<p>Output files are <code>lambda_eps</code>, <code>enthalpy_et_der</code>, <code>domains_boundaries</code>, plus <code>metadata.txt</code>. 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.</p>
|
|
<p>Use TOP's recovered <code>poly_ester</code> reader and <code>eq_poly_ester_gamma2</code> 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 <code>sqrt(4*pi*G*rho_c)</code>; <code>angular_frequency_unit</code> in the report supplies that physical conversion in the input model's unit system. Divide by 2*pi to obtain cyclic frequency.</p>
|
|
<p>The backend-independent overload in <code><a class="el" href="utils_2serialize_2top_8hpp.html">serif/utils/serialize/top.hpp</a></code> accepts a <code>TopPolytropeSource</code> 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 <code>top_export_fixture</code>:</p>
|
|
<div class="fragment"><div class="line">source /Users/tboudreaux/Programming/top/activate-top.sh</div>
|
|
<div class="line">python tests/serialize/top_reader.py build/tests/serialize/top_export_fixture</div>
|
|
</div><!-- fragment --><p>That optional check requires TOP's compiled <code>eq_poly_ester_gamma2</code> module. TOP is not a SERiF build dependency. </p>
|
|
</div><!-- contents -->
|
|
</div><!-- doc-content -->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<li class="navelem"><a class="el" href="dir_68267d1309a1af8e8297ef4c3efbcdba.html">src</a></li><li class="navelem"><a class="el" href="dir_b0856f6b0d80ccb263b2f415c91f9e17.html">include</a></li><li class="navelem"><a class="el" href="dir_e3fc9bd9804296f8660ca61563b995c5.html">serif</a></li><li class="navelem"><a class="el" href="dir_0fcf4c89a1274e6563f11975b8f6a431.html">utils</a></li><li class="navelem"><a class="el" href="dir_ae4e54e2b3dd44e066c26d6c78043d75.html">serialize</a></li>
|
|
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|