.TH "serif::geometry::deformation" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::geometry::deformation
.SH SYNOPSIS
.br
.PP
.SS "Namespaces"

.in +1c
.ti -1c
.RI "namespace \fBbackend\fP"
.br
.ti -1c
.RI "namespace \fBdetail\fP"
.br
.ti -1c
.RI "namespace \fBkeys\fP"
.br
.ti -1c
.RI "namespace \fBspaces\fP"
.br
.in -1c
.SS "Classes"

.in +1c
.ti -1c
.RI "class \fBComposedDeformation\fP"
.br
.RI "Compose shape-to-surface and surface-to-volume maps with the complete derivative chain rule\&. "
.ti -1c
.RI "struct \fBDeformationFailure\fP"
.br
.RI "Describe a rejected geometry calculation; the dependency cache publishes results only after success\&. "
.ti -1c
.RI "struct \fBDeformationLinearization\fP"
.br
.RI "Freeze the shape coordinates associated with a derivative, independently of mutable caller inputs\&. "
.ti -1c
.RI "struct \fBDomainDeformation\fP"
.br
.RI "State how the stellar surface moves and how that motion extends into the two surrounding regions\&. "
.ti -1c
.RI "struct \fBEmptyDeformationWorkspace\fP"
.br
.RI "Stateless maps require no numerical scratch, while retaining the same explicit action interface\&. "
.ti -1c
.RI "struct \fBFixedInfinityRadialExtension\fP"
.br
.RI "Reduce surface motion linearly to zero at reference infinity in logical reference radius\&. "
.ti -1c
.RI "struct \fBGeometryStepLimit\fP"
.br
.RI "Geometry-only bound at the supplied sample points, with a location for the first obstruction\&. "
.ti -1c
.RI "struct \fBGeometryStepOptions\fP"
.br
.RI "Numerical controls for keeping a straight volume-displacement step above a Jacobian determinant floor\&. "
.ti -1c
.RI "struct \fBNodalRadialSurface\fP"
.br
.RI "Give each surface node an independent radial displacement, measured in physical length\&. "
.ti -1c
.RI "struct \fBPowerLawRadialExtension\fP"
.br
.RI "Extend surface motion toward a fixed stellar center using a power of logical reference radius\&. "
.ti -1c
.RI "class \fBRadialExtension\fP"
.br
.RI "Extend one interleaved surface vector into the MFEM component-block volume layout\&. Stellar ownership wins at shared nodes\&. Both actions use the same scalar interpolation, so their pairing is Euclidean virtual work without an additional surface-area weight\&. "
.ti -1c
.RI "class \fBRadialInterpolation\fP"
.br
.RI "A checked, immutable interpolation table; changing a radial law never revalidates its topology\&. "
.ti -1c
.RI "struct \fBRadialInterpolationData\fP"
.br
.RI "Own the surface interpolation shared by the stellar and vacuum extensions\&. "
.ti -1c
.RI "struct \fBReferenceSurface\fP"
.br
.RI "Own fixed surface positions and their canonical ascending scalar-node indices\&. "
.ti -1c
.RI "struct \fBSphericalHarmonicMode\fP"
.br
.RI "Identify a real harmonic, with negative orders using sine and positive orders using cosine\&. "
.ti -1c
.RI "struct \fBSphericalHarmonicSurface\fP"
.br
.RI "Represent radial displacement lengths with normalized real spherical harmonics on the reference surface\&. "
.ti -1c
.RI "class \fBSurfaceEmbedding\fP"
.br
.RI "Own a linear conversion from radial displacement lengths to Cartesian surface displacements\&. "
.in -1c
.SS "Concepts"

.in +1c
.ti -1c
.RI "concept \fBDeformationDimensions\fP"
.br
.RI "Matching lengths never replace the physical meanings of the input and output spaces\&. "
.ti -1c
.RI "concept \fBLinearDeformationMap\fP"
.br
.RI "Fixed maps provide just forward and transpose actions with caller-owned scratch\&. "
.ti -1c
.RI "concept \fBDifferentiableDeformationMap\fP"
.br
.RI "Nonlinear maps explicitly provide every term needed by a Newton force pullback\&. "
.ti -1c
.RI "concept \fBDeformationMap\fP"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "using \fBDeformationStatus\fP = std::expected<void, \fBDeformationFailure\fP>"
.br
.ti -1c
.RI "template<typename Map> using \fBDeformationWorkspace\fP = typename Map::Workspace"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum class \fBDeformationFailureReason\fP { \fBinvalid_configuration\fP, \fBincompatible_discretization\fP, \fBinvalid_size\fP, \fBnon_finite\fP, \fBunresolved_surface\fP, \fBinvalid_geometry\fP }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationWorkspace\fP< Map > \fBmake_deformation_workspace\fP (const Map &map)"
.br
.RI "Allocate action scratch explicitly, once per independent caller\&. "
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationStatus\fP \fBbuild_displacement\fP (const Map &map, std::span< const double > parameters, std::span< double > displacement, \fBDeformationWorkspace\fP< Map > &workspace)"
.br
.RI "Evaluate physical displacement with caller-owned output and scratch\&. All action outputs must be disjoint from their inputs\&. Workspace storage is reserved for the map and must not supply public input or output spans\&. "
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationStatus\fP \fBapply_jacobian\fP (const Map &map, std::span< const double > parameters, std::span< const double > direction, std::span< double > displacement_direction, \fBDeformationWorkspace\fP< Map > &workspace)"
.br
.RI "Linear maps reuse their primal action; nonlinear maps supply their exact tangent\&. "
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationStatus\fP \fBapply_jacobian_transpose\fP (const Map &map, std::span< const double > parameters, std::span< const double > displacement_dual, std::span< double > parameter_dual, \fBDeformationWorkspace\fP< Map > &workspace)"
.br
.RI "Transfer virtual work from the displacement field to its independent shape coefficients\&. "
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationStatus\fP \fBapply_pullback_derivative\fP (const Map &map, std::span< const double > parameters, std::span< const double > direction, std::span< const double > displacement_dual, std::span< double > parameter_dual, \fBDeformationWorkspace\fP< Map > &workspace)"
.br
.RI "Differentiate the transpose at fixed dual; zero is justified only for a declared linear map\&. "
.ti -1c
.RI "template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> 
.br
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>std::expected< \fBComposedDeformation\fP< SurfaceMap, ExtensionMap >, \fBDeformationFailure\fP > \fBcompose_deformation\fP (std::shared_ptr< const SurfaceMap > surface, std::shared_ptr< const ExtensionMap > extension)"
.br
.RI "Validate factor sizes before constructing an owning mathematical composition\&. "
.ti -1c
.RI "template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> 
.br
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>auto \fBmake_deformation_computations\fP ()"
.br
.RI "Declare the numerical composition as ordinary dependency computations\&. "
.ti -1c
.RI "template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> 
.br
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>auto \fBmake_deformation_graph\fP ()"
.br
.RI "Compose independently compiled mathematical factors without introducing a prepared-operator facade\&. "
.ti -1c
.RI "\fBDeformationStatus\fP \fBvalidate_deformation_values\fP (std::span< const double > values, std::size_t expected_size)"
.br
.RI "Reject incompatible lengths and non-finite values before evaluating a deformation action\&. "
.ti -1c
.RI "template<DeformationMap Map> std::expected< std::vector< double >, \fBDeformationFailure\fP > \fBevaluate_displacement\fP (const Map &map, std::span< const double > parameters)"
.br
.RI "Allocate a result for graph publication while leaving repeated low-level actions allocation-free\&. "
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationStatus\fP \fBapply_jacobian\fP (const \fBDeformationLinearization\fP< Map > &state, std::span< const double > direction, std::span< double > output, \fBDeformationWorkspace\fP< Map > &workspace)"
.br
.RI "Evaluate a tangent about the cache's accepted shape, not the caller's next trial state\&. "
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationStatus\fP \fBapply_jacobian_transpose\fP (const \fBDeformationLinearization\fP< Map > &state, std::span< const double > dual, std::span< double > output, \fBDeformationWorkspace\fP< Map > &workspace)"
.br
.RI "Pull displacement forces back to the accepted independent shape coordinates\&. "
.ti -1c
.RI "template<DeformationMap Map> \fBDeformationStatus\fP \fBapply_pullback_derivative\fP (const \fBDeformationLinearization\fP< Map > &state, std::span< const double > direction, std::span< const double > dual, std::span< double > output, \fBDeformationWorkspace\fP< Map > &workspace)"
.br
.RI "Keep the geometric contribution to the Newton force derivative available for nonlinear models\&. "
.ti -1c
.RI "std::expected< \fBRadialExtension\fP, \fBDeformationFailure\fP > \fBmake_radial_extension\fP (std::shared_ptr< const \fBRadialInterpolation\fP > interpolation, \fBPowerLawRadialExtension\fP interior={}, \fBFixedInfinityRadialExtension\fP vacuum={})"
.br
.RI "Compile regional weights while sharing the immutable surface interpolation\&. The interpolation factory has already established every reference-table invariant\&. "
.ti -1c
.RI "std::expected< \fBRadialInterpolation\fP, \fBDeformationFailure\fP > \fBmake_radial_interpolation\fP (\fBRadialInterpolationData\fP data)"
.br
.RI "Check imported or backend-generated reference rows once before sharing them with radial laws\&. "
.ti -1c
.RI "std::expected< \fBSurfaceEmbedding\fP, \fBDeformationFailure\fP > \fBbuild_surface_embedding\fP (const \fBNodalRadialSurface\fP &model, std::span< const std::array< double, 3 > > positions)"
.br
.RI "Compile fixed radial directions from ordered physical reference positions without retaining backend objects\&. "
.ti -1c
.RI "std::expected< \fBSurfaceEmbedding\fP, \fBDeformationFailure\fP > \fBbuild_surface_embedding\fP (const \fBSphericalHarmonicSurface\fP &model, std::span< const std::array< double, 3 > > positions)"
.br
.RI "Sample physically normalized real harmonics and reject unresolved modes without renormalizing or dropping coordinates\&. "
.ti -1c
.RI "template<typename Surface, typename Interior, typename Vacuum> auto \fBmake_deformation_inputs\fP (const \fBDomainDeformation\fP< Surface, Interior, Vacuum > &model, const ReferenceDiscretization &discretization, const std::vector< double > &coefficients)"
.br
.RI "Bind physical choices and a borrowed shape vector without evaluating deformation\&. "
.ti -1c
.RI "template<typename Surface> auto \fBmake_deformation_graph\fP ()"
.br
.RI "Provide a standalone graph while leaving the same computations available for equation composition\&. "
.ti -1c
.RI "template<typename Surface> 
.br
requires requires(const Surface& model, std::span<const std::array<double, 3>> positions) { { \fBbuild_surface_embedding\fP(model, positions) } \-> std::same_as<std::expected<\fBSurfaceEmbedding\fP, \fBDeformationFailure\fP>>; }auto \fBmake_deformation_computations\fP ()"
.br
.RI "Compile fixed reference factors and evaluate shape motion with one dependency engine\&. "
.ti -1c
.RI "template<discretization::domain::schema::IsSchema Schema = discretization::domain::schema::CoreEnvelopeVacuumDomainSchema> 
.br
requires (Schema::template contains_domain<\fBdiscretization::domain::StellarDomains\fP>() && Schema::template contains_domain<\fBdiscretization::domain::VacuumDomain\fP>() && Schema::template contains_boundary<\fBdiscretization::domain::StellarSurfaceBoundary\fP>() && Schema::template contains_boundary<\fBdiscretization::domain::InfinitySurfaceBoundary\fP>())ReferenceDiscretization \fBdeformation_discretization\fP (const ::mfem::FiniteElementSpace &scalar_space, const ::mfem::FiniteElementSpace &displacement_space, ::mfem::Mesh &logical_mesh)"
.br
.RI "Resolve physical domain names through the schema rather than hard-coded MFEM attributes\&. "
.in -1c
.SS "Variables"

.in +1c
.ti -1c
.RI "template<typename Map> constexpr bool \fBis_linear_deformation\fP"
.br
.RI "Linearity is an explicit property of the mathematics, independent of its action interface\&. "
.in -1c
.SH "Typedef Documentation"
.PP 
.SS "using \fBserif::geometry::deformation::DeformationStatus\fP = std::expected<void, \fBDeformationFailure\fP>"

.SS "template<typename Map> using \fBserif::geometry::deformation::DeformationWorkspace\fP = typename Map::Workspace"

.SH "Enumeration Type Documentation"
.PP 
.SS "enum class \fBserif::geometry::deformation::DeformationFailureReason\fP\fR [strong]\fP"

.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIinvalid_configuration \fP
.TP
\f(BIincompatible_discretization \fP
.TP
\f(BIinvalid_size \fP
.TP
\f(BInon_finite \fP
.TP
\f(BIunresolved_surface \fP
.TP
\f(BIinvalid_geometry \fP
.SH "Function Documentation"
.PP 
.SS "template<DeformationMap Map> \fBDeformationStatus\fP serif::geometry::deformation::apply_jacobian (const \fBDeformationLinearization\fP< Map > & state, std::span< const double > direction, std::span< double > output, \fBDeformationWorkspace\fP< Map > & workspace)\fR [nodiscard]\fP"

.PP
Evaluate a tangent about the cache's accepted shape, not the caller's next trial state\&. 
.SS "template<DeformationMap Map> \fBDeformationStatus\fP serif::geometry::deformation::apply_jacobian (const Map & map, std::span< const double > parameters, std::span< const double > direction, std::span< double > displacement_direction, \fBDeformationWorkspace\fP< Map > & workspace)\fR [nodiscard]\fP"

.PP
Linear maps reuse their primal action; nonlinear maps supply their exact tangent\&. 
.SS "template<DeformationMap Map> \fBDeformationStatus\fP serif::geometry::deformation::apply_jacobian_transpose (const \fBDeformationLinearization\fP< Map > & state, std::span< const double > dual, std::span< double > output, \fBDeformationWorkspace\fP< Map > & workspace)\fR [nodiscard]\fP"

.PP
Pull displacement forces back to the accepted independent shape coordinates\&. 
.SS "template<DeformationMap Map> \fBDeformationStatus\fP serif::geometry::deformation::apply_jacobian_transpose (const Map & map, std::span< const double > parameters, std::span< const double > displacement_dual, std::span< double > parameter_dual, \fBDeformationWorkspace\fP< Map > & workspace)\fR [nodiscard]\fP"

.PP
Transfer virtual work from the displacement field to its independent shape coefficients\&. 
.SS "template<DeformationMap Map> \fBDeformationStatus\fP serif::geometry::deformation::apply_pullback_derivative (const \fBDeformationLinearization\fP< Map > & state, std::span< const double > direction, std::span< const double > dual, std::span< double > output, \fBDeformationWorkspace\fP< Map > & workspace)\fR [nodiscard]\fP"

.PP
Keep the geometric contribution to the Newton force derivative available for nonlinear models\&. 
.SS "template<DeformationMap Map> \fBDeformationStatus\fP serif::geometry::deformation::apply_pullback_derivative (const Map & map, std::span< const double > parameters, std::span< const double > direction, std::span< const double > displacement_dual, std::span< double > parameter_dual, \fBDeformationWorkspace\fP< Map > & workspace)\fR [nodiscard]\fP"

.PP
Differentiate the transpose at fixed dual; zero is justified only for a declared linear map\&. 
.SS "template<DeformationMap Map> \fBDeformationStatus\fP serif::geometry::deformation::build_displacement (const Map & map, std::span< const double > parameters, std::span< double > displacement, \fBDeformationWorkspace\fP< Map > & workspace)\fR [nodiscard]\fP"

.PP
Evaluate physical displacement with caller-owned output and scratch\&. All action outputs must be disjoint from their inputs\&. Workspace storage is reserved for the map and must not supply public input or output spans\&. 
.SS "std::expected< \fBSurfaceEmbedding\fP, \fBDeformationFailure\fP > serif::geometry::deformation::build_surface_embedding (const \fBNodalRadialSurface\fP & model, std::span< const std::array< double, 3 > > positions)\fR [nodiscard]\fP"

.PP
Compile fixed radial directions from ordered physical reference positions without retaining backend objects\&. 
.SS "std::expected< \fBSurfaceEmbedding\fP, \fBDeformationFailure\fP > serif::geometry::deformation::build_surface_embedding (const \fBSphericalHarmonicSurface\fP & model, std::span< const std::array< double, 3 > > positions)\fR [nodiscard]\fP"

.PP
Sample physically normalized real harmonics and reject unresolved modes without renormalizing or dropping coordinates\&. 
.SS "template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> 
.br
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>std::expected< \fBComposedDeformation\fP< SurfaceMap, ExtensionMap >, \fBDeformationFailure\fP > serif::geometry::deformation::compose_deformation (std::shared_ptr< const SurfaceMap > surface, std::shared_ptr< const ExtensionMap > extension)\fR [nodiscard]\fP"

.PP
Validate factor sizes before constructing an owning mathematical composition\&. 
.SS "template<discretization::domain::schema::IsSchema Schema = discretization::domain::schema::CoreEnvelopeVacuumDomainSchema> 
.br
requires (Schema::template contains_domain<\fBdiscretization::domain::StellarDomains\fP>() && Schema::template contains_domain<\fBdiscretization::domain::VacuumDomain\fP>() && Schema::template contains_boundary<\fBdiscretization::domain::StellarSurfaceBoundary\fP>() && Schema::template contains_boundary<\fBdiscretization::domain::InfinitySurfaceBoundary\fP>())ReferenceDiscretization serif::geometry::deformation::backend::mfem::deformation_discretization (const ::mfem::FiniteElementSpace & scalar_space, const ::mfem::FiniteElementSpace & displacement_space, ::mfem::Mesh & logical_mesh)\fR [nodiscard]\fP"

.PP
Resolve physical domain names through the schema rather than hard-coded MFEM attributes\&. 
.SS "template<DeformationMap Map> std::expected< std::vector< double >, \fBDeformationFailure\fP > serif::geometry::deformation::evaluate_displacement (const Map & map, std::span< const double > parameters)\fR [nodiscard]\fP"

.PP
Allocate a result for graph publication while leaving repeated low-level actions allocation-free\&. 
.SS "template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> 
.br
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>auto serif::geometry::deformation::make_deformation_computations ()\fR [nodiscard]\fP"

.PP
Declare the numerical composition as ordinary dependency computations\&. 
.PP
\fBNote\fP
.RS 4
Shared immutable factors, coefficient snapshots, and results belong to the dependency cache\&. Analytical actions remain independent functions\&. 
.RE
.PP

.SS "template<typename Surface> 
.br
requires requires(const Surface& model, std::span<const std::array<double, 3>> positions) { { \fBbuild_surface_embedding\fP(model, positions) } \-> std::same_as<std::expected<\fBSurfaceEmbedding\fP, \fBDeformationFailure\fP>>; }auto serif::geometry::deformation::backend::mfem::make_deformation_computations ()\fR [nodiscard]\fP"

.PP
Compile fixed reference factors and evaluate shape motion with one dependency engine\&. 
.PP
\fBNote\fP
.RS 4
Configuration values are named context inputs\&. Factories declare work; try_prepare performs it explicitly\&. 
.RE
.PP

.SS "template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> 
.br
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>auto serif::geometry::deformation::make_deformation_graph ()\fR [nodiscard]\fP"

.PP
Compose independently compiled mathematical factors without introducing a prepared-operator facade\&. 
.SS "template<typename Surface> auto serif::geometry::deformation::backend::mfem::make_deformation_graph ()\fR [nodiscard]\fP"

.PP
Provide a standalone graph while leaving the same computations available for equation composition\&. 
.SS "template<typename Surface, typename Interior, typename Vacuum> auto serif::geometry::deformation::backend::mfem::make_deformation_inputs (const \fBDomainDeformation\fP< Surface, Interior, Vacuum > & model, const ReferenceDiscretization & discretization, const std::vector< double > & coefficients)\fR [nodiscard]\fP"

.PP
Bind physical choices and a borrowed shape vector without evaluating deformation\&. 
.PP
\fBNote\fP
.RS 4
Meshes, spaces, and the vector must outlive the context\&. Borrowing the container retains its current storage and size even if the caller subsequently resizes it\&. Coordinate edits must notify MFEM through its normal node-update API\&. 
.RE
.PP

.SS "template<DeformationMap Map> \fBDeformationWorkspace\fP< Map > serif::geometry::deformation::make_deformation_workspace (const Map & map)\fR [nodiscard]\fP"

.PP
Allocate action scratch explicitly, once per independent caller\&. 
.SS "std::expected< \fBRadialExtension\fP, \fBDeformationFailure\fP > serif::geometry::deformation::make_radial_extension (std::shared_ptr< const \fBRadialInterpolation\fP > interpolation, \fBPowerLawRadialExtension\fP interior = \fR{}\fP, \fBFixedInfinityRadialExtension\fP vacuum = \fR{}\fP)\fR [nodiscard]\fP"

.PP
Compile regional weights while sharing the immutable surface interpolation\&. The interpolation factory has already established every reference-table invariant\&. 
.SS "std::expected< \fBRadialInterpolation\fP, \fBDeformationFailure\fP > serif::geometry::deformation::make_radial_interpolation (\fBRadialInterpolationData\fP data)\fR [nodiscard]\fP"

.PP
Check imported or backend-generated reference rows once before sharing them with radial laws\&. 
.SS "\fBDeformationStatus\fP serif::geometry::deformation::validate_deformation_values (std::span< const double > values, std::size_t expected_size)\fR [inline]\fP, \fR [nodiscard]\fP"

.PP
Reject incompatible lengths and non-finite values before evaluating a deformation action\&. 
.SH "Variable Documentation"
.PP 
.SS "template<typename Map> bool serif::geometry::deformation::is_linear_deformation\fR [inline]\fP, \fR [constexpr]\fP"
\fBInitial value:\fP
.nf
= requires
    {
        requires Map::is_linear;
    }
.PP
.fi

.PP
Linearity is an explicit property of the mathematics, independent of its action interface\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for SERiF from the source code\&.