Files
MeanField_SERiF/docs/xml/dir_f4279ff9f0ade9101a3d0c95da9106b0.xml

92 lines
14 KiB
XML
Raw Permalink Normal View History

<?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&apos;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&lt;Density&gt;{</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&lt;</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>&gt;{}});</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&lt;Term&gt;</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>