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)
92 lines
14 KiB
XML
92 lines
14 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_f4279ff9f0ade9101a3d0c95da9106b0" kind="dir">
|
|
<compoundname>src/include/serif/backend/mfem</compoundname>
|
|
<innerdir refid="dir_7f477ac1f4073d80fe2cf961b8371c78">src/include/serif/backend/mfem/discretization</innerdir>
|
|
<innerdir refid="dir_a06a86b96ba8029e601031e1f2191759">src/include/serif/backend/mfem/geometry</innerdir>
|
|
<innerdir refid="dir_868918a99b4e75b7dbed614771b99884">src/include/serif/backend/mfem/mapping</innerdir>
|
|
<innerdir refid="dir_1233560eb10cdcde82755d8d2adeb88b">src/include/serif/backend/mfem/model</innerdir>
|
|
<innerdir refid="dir_071310146d715fd89847bf9b7662fb48">src/include/serif/backend/mfem/operators</innerdir>
|
|
<innerdir refid="dir_b775f56dba5805041c07293ece4547b5">src/include/serif/backend/mfem/projection</innerdir>
|
|
<innerdir refid="dir_a6addf8d2b502bb84d626acd01a49eda">src/include/serif/backend/mfem/serialize</innerdir>
|
|
<innerdir refid="dir_dd439b85c0fa899b8964b586100d1f6d">src/include/serif/backend/mfem/shared</innerdir>
|
|
<innerdir refid="dir_518c5782990baa988ca590b53b43636d">src/include/serif/backend/mfem/solver</innerdir>
|
|
<innerfile refid="backend_2mfem_2runtime_8hpp">runtime.hpp</innerfile>
|
|
<innerfile refid="backend_2mfem_2types_8hpp">types.hpp</innerfile>
|
|
<briefdescription>
|
|
</briefdescription>
|
|
<detaileddescription>
|
|
<para>MFEM implementations live here and in the matching <computeroutput>src/lib/serif/backend/mfem</computeroutput> tree. Physics descriptions, equations, EOS relations, normalization rules, Newton acceptance, and continuation scheduling stay in their ordinary SERiF modules. The directory migration preserves physics-oriented namespaces; include paths identify the implementation backend. Helpers whose responsibility changed now follow their owner: <computeroutput>model::make_discretization</computeroutput>, <computeroutput>geometry::surface::AutomaticPressureSurface</computeroutput>, generic preconditioner diagonal regularization, and discretization element coordinates.</para>
|
|
<para><table rows="9" cols="2"><row>
|
|
<entry thead="yes"><para>Directory </para>
|
|
</entry><entry thead="yes"><para>Responsibility </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>discretization</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Bind physical terms to MFEM spaces; own coefficient ordering, element orientation, basis evaluation, quadrature, traces, and MFEM mesh extraction. </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>mapping</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Evaluate physical mappings and their variations from supplied reference geometry and current coefficients. </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>geometry</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Adapt surface and deformation descriptions to MFEM resources, including pressure traces and boundary metrics. </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>operators</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Integrate equation contributions and expose their linear actions, transposes, diagonals, and assembly. No EOS-specific pressure construction belongs here. </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>model</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Connect the preceding adapters into the model's computational graph and publish owning evaluated systems. The deformation-to-equation bridge belongs here. </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>solver</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Supply MFEM linear solvers, inverses, geometry admissibility, and stellar adapters to the common Newton and continuation algorithms. </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>projection</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Project reusable radial profiles into MFEM finite-element spaces. </para>
|
|
</entry></row>
|
|
<row>
|
|
<entry thead="no"><para><computeroutput>shared</computeroutput> </para>
|
|
</entry><entry thead="no"><para>Small backend facilities with multiple independent consumers: live mesh/space snapshots, boundary traversal, vector spans, and matrix/vector checks. </para>
|
|
</entry></row>
|
|
</table>
|
|
</para>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/backend/mfem/README.md_1autotoc_md1">
|
|
<title>Ownership and reuse</title><para>The computational graph owns immutable prepared data, including fixed geometry at equation quadrature points. A mapper does not own a second mutable reference-geometry cache. Standalone point and face mapping evaluate their own reference geometry directly. Accepted systems retain their preparation owners and remain independent of subsequent candidate preparation.</para>
|
|
<para>MFEM resources are externally mutable. Snapshot policies distinguish topology, material/boundary labels, finite-element layout, and physical/logical coordinate revisions. Input factories capture current revisions; reusing stale input metadata is rejected. Notify MFEM of direct coordinate changes (for example with <computeroutput>NodesUpdated</computeroutput>) and rebuild the input context after changing its resources. Revision tracking cannot detect unreported writes to external coordinate storage.</para>
|
|
<para>A <computeroutput>DofMap</computeroutput> owns the meaning of reduced coefficients. Public coefficient access validates that meaning. Internal element traversals obtain a validated <computeroutput>Elements</computeroutput> view once, then retain element bounds, support, and vector-size checks without rescanning all mesh attributes for every element. Do not mutate the mesh or space during a traversal. Element orientation is implemented once in <computeroutput>discretization/element_coordinates</computeroutput>.</para>
|
|
<para>Surface normalization and surface preconditioning share validated boundary traversal, but keep their different integrands: vector radial/harmonic metric diagonals versus scalar H1 mass and stiffness matrices. Likewise, model block selection preserves native child assembly and repeated ranges; restriction of an arbitrary preconditioner operator retains its separate unique-index contract.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/backend/mfem/README.md_1autotoc_md2">
|
|
<title>Core boundary</title><para><computeroutput>serif_core_lib</computeroutput> and <computeroutput>serif_core_dep</computeroutput> have no MFEM dependency. The core header check and the standard-vector Newton tests compile without MFEM include paths. The public <computeroutput>serif</computeroutput> library includes the core and adds this backend. Convenience entry headers may select MFEM adapters, while physical configuration and numerical algorithms remain available separately.</para>
|
|
<para>Continuation families, physical parameter laws, coordinate stepping, and the driver share <computeroutput><ref refid="namespaceserif_1_1solver_1_1continuation" kindref="compound">serif::solver::continuation</ref></computeroutput> in <computeroutput>solver/continuation</computeroutput>. Its entry header is backend independent; only stellar correction wiring and finite-element state transfer live in <computeroutput>backend/mfem/solver/continuation</computeroutput>.</para>
|
|
<para>The common Newton loop asks its vector adapter only for owned vectors and coefficient spans. The MFEM wrapper supplies linear-solve wiring; it does not duplicate acceptance, backtracking, or checkpoint ownership. A future backend should implement its discretization and execution adapters and reuse these common rules, rather than copy the nonlinear or continuation algorithms.</para>
|
|
<para>Current term bindings require serial, conforming three-dimensional MFEM spaces. Supported value, gradient, divergence, trace, and tensor/dense basis paths retain their explicit compile-time and runtime checks. This layout does not imply that every MFEM space or another finite-element library is already supported.</para>
|
|
</sect1>
|
|
<sect1 id="/Users/tboudreaux/Programming/4DSTAR/MeanField_SERiF/src/include/serif/backend/mfem/README.md_1autotoc_md3">
|
|
<title>Optional surface density reconstruction</title><para>Pass the numerical choice directly to the stellar factory, after any deformation:</para>
|
|
<para><programlisting filename=".cpp"><codeline><highlight class="keyword">namespace<sp/></highlight><highlight class="normal">reconstruction<sp/>=<sp/><ref refid="namespaceserif_1_1discretization_1_1reconstruction" kindref="compound">serif::discretization::reconstruction</ref>;</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">using<sp/></highlight><highlight class="normal">Density<sp/>=<sp/><ref refid="structserif_1_1discretization_1_1blocks_1_1density_1_1mass" kindref="compound">serif::discretization::blocks::density::mass</ref>;</highlight></codeline>
|
|
<codeline><highlight class="normal"></highlight><highlight class="keyword">auto</highlight><highlight class="normal"><sp/>finite_elements<sp/>=<sp/><ref refid="namespaceserif_1_1model_1ac5681e63c50dc5a136eaa699838cf332" kindref="member">serif::model::make_stellar_discretization</ref>(</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>star,<sp/>mesh_options,<sp/>moving_boundary,</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/>reconstruction::SurfacePower<Density>{</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>.density_exponent<sp/>=<sp/>n,</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/>.region<sp/>=<sp/>reconstruction::SurfaceAdjacent<</highlight></codeline>
|
|
<codeline><highlight class="normal"><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><ref refid="structserif_1_1discretization_1_1domain_1_1_stellar_surface_boundary" kindref="compound">serif::discretization::domain::StellarSurfaceBoundary</ref>>{}});</highlight></codeline>
|
|
</programlisting></para>
|
|
<para>Omitting the argument preserves ordinary interpolation. Exponent 1 takes that same path without a reconstruction plan. Stored coefficients remain physical nodal densities. Only material elements touching the selected boundary change: with inward reference coordinate <computeroutput>t=0</computeroutput> at the surface and <computeroutput>t=1</computeroutput> at their inner face, their zero-trace radial space becomes <computeroutput>t^n P_(p-1)</computeroutput>. Tangential interpolation and deeper elements remain ordinary. The full basis retains surface degrees of freedom and reproduces constants; the vacuum solve enforces their zero values explicitly.</para>
|
|
<para>The plan belongs to the field binding and is immutable throughout a solve. Its exponent is an explicit numerical choice; changing an EOS during continuation does not silently change the representation. A different profile, mesh or exponent requires a new binding and deliberate field transfer. Construction validates matching radial coordinates and the actual hanging-node constraints. Tangential/equatorial refinement is supported when those constraints preserve the reconstructed traces. Incompatible radial hanging layers fail with a SERiF diagnostic.</para>
|
|
<para><computeroutput>discretization::backend::mfem::FieldValues<Term></computeroutput> reads the same physical representation as the equation operators. Use it for arbitrary-point values, scalar H1 gradients or batches of samples. Its binding, coefficients and mesh resources must outlive the reader. Extra deformation/compactification maps must be supplied for physical gradients and H(div) values. Ordinary MFEM GridFunction interpolation of reconstructed nodal values is not the represented field.</para>
|
|
<para>Reference preparation replaces only the radial tensor factors; forward and transpose contractions retain the existing kernels. Automatic volume rules include a fractional-power allowance before quadrature-policy resolution, so an explicit fixed order remains authoritative. Gaussian quadrature is still approximate and should be checked by increasing its order for a new regime. Nonnegativity certifies the polynomial carrier with its positive weight and requires the selected zero-density trace. This implementation does not provide a certificate for finite-pressure surface lifting or a general EOS surface profile.</para>
|
|
<para>To add a numerical form, provide an ADL-visible <computeroutput>make_reconstruction(specification, binding)</computeroutput> overload, a specification with <computeroutput>using Term</computeroutput>, and an immutable <computeroutput>RadialProfile</computeroutput> that evaluates complete nodal functions and inward derivatives, including endpoints. The profile must preserve nodal values, constants and compatible face traces. Add its admissibility certificate and archive codec explicitly; missing capabilities report errors. No MFEM element subclass or physics-equation rewrite is required. The current surface-power form supports scalar H1 mass density only.</para>
|
|
<para>Weighted archive bindings use schema version 2; older readers reject them rather than reinterpret their coefficients. The live Rayfem adapter sends a higher-order sampled display field labeled <computeroutput>density (sampled)</computeroutput>. This display approximation is never used by the solver or TOP exporter. </para>
|
|
</sect1>
|
|
</detaileddescription>
|
|
<location file="src/include/serif/backend/mfem/"/>
|
|
</compounddef>
|
|
</doxygen>
|