serif::geometry::deformation Namespace Reference

Namespaces
namespace	backend
namespace	detail
namespace	keys
namespace	spaces

Classes
class	ComposedDeformation
	Compose shape-to-surface and surface-to-volume maps with the complete derivative chain rule. More...
struct	DeformationFailure
	Describe a rejected geometry calculation; the dependency cache publishes results only after success. More...
struct	DeformationLinearization
	Freeze the shape coordinates associated with a derivative, independently of mutable caller inputs. More...
struct	DomainDeformation
	State how the stellar surface moves and how that motion extends into the two surrounding regions. More...
struct	EmptyDeformationWorkspace
	Stateless maps require no numerical scratch, while retaining the same explicit action interface. More...
struct	FixedInfinityRadialExtension
	Reduce surface motion linearly to zero at reference infinity in logical reference radius. More...
struct	GeometryStepLimit
	Geometry-only bound at the supplied sample points, with a location for the first obstruction. More...
struct	GeometryStepOptions
	Numerical controls for keeping a straight volume-displacement step above a Jacobian determinant floor. More...
struct	NodalRadialSurface
	Give each surface node an independent radial displacement, measured in physical length. More...
struct	PowerLawRadialExtension
	Extend surface motion toward a fixed stellar center using a power of logical reference radius. More...
class	RadialExtension
	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. More...
class	RadialInterpolation
	A checked, immutable interpolation table; changing a radial law never revalidates its topology. More...
struct	RadialInterpolationData
	Own the surface interpolation shared by the stellar and vacuum extensions. More...
struct	ReferenceSurface
	Own fixed surface positions and their canonical ascending scalar-node indices. More...
struct	SphericalHarmonicMode
	Identify a real harmonic, with negative orders using sine and positive orders using cosine. More...
struct	SphericalHarmonicSurface
	Represent radial displacement lengths with normalized real spherical harmonics on the reference surface. More...
class	SurfaceEmbedding
	Own a linear conversion from radial displacement lengths to Cartesian surface displacements. More...

Concepts
concept	DeformationDimensions
	Matching lengths never replace the physical meanings of the input and output spaces.
concept	LinearDeformationMap
	Fixed maps provide just forward and transpose actions with caller-owned scratch.
concept	DifferentiableDeformationMap
	Nonlinear maps explicitly provide every term needed by a Newton force pullback.
concept	DeformationMap

Typedefs
using	DeformationStatus = std::expected<void, DeformationFailure>
template<typename Map>
using	DeformationWorkspace = typename Map::Workspace

Enumerations
enum class	DeformationFailureReason {   invalid_configuration , incompatible_discretization , invalid_size , non_finite ,   unresolved_surface , invalid_geometry }

Functions
template<DeformationMap Map>
DeformationWorkspace< Map >	make_deformation_workspace (const Map &map)
	Allocate action scratch explicitly, once per independent caller.
template<DeformationMap Map>
DeformationStatus	build_displacement (const Map &map, std::span< const double > parameters, std::span< double > displacement, DeformationWorkspace< Map > &workspace)
	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.
template<DeformationMap Map>
DeformationStatus	apply_jacobian (const Map &map, std::span< const double > parameters, std::span< const double > direction, std::span< double > displacement_direction, DeformationWorkspace< Map > &workspace)
	Linear maps reuse their primal action; nonlinear maps supply their exact tangent.
template<DeformationMap Map>
DeformationStatus	apply_jacobian_transpose (const Map &map, std::span< const double > parameters, std::span< const double > displacement_dual, std::span< double > parameter_dual, DeformationWorkspace< Map > &workspace)
	Transfer virtual work from the displacement field to its independent shape coefficients.
template<DeformationMap Map>
DeformationStatus	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, DeformationWorkspace< Map > &workspace)
	Differentiate the transpose at fixed dual; zero is justified only for a declared linear map.
template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>
std::expected< ComposedDeformation< SurfaceMap, ExtensionMap >, DeformationFailure >	compose_deformation (std::shared_ptr< const SurfaceMap > surface, std::shared_ptr< const ExtensionMap > extension)
	Validate factor sizes before constructing an owning mathematical composition.
template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>
auto	make_deformation_computations ()
	Declare the numerical composition as ordinary dependency computations.
template<DeformationMap SurfaceMap, DeformationMap ExtensionMap> requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>
auto	make_deformation_graph ()
	Compose independently compiled mathematical factors without introducing a prepared-operator facade.
DeformationStatus	validate_deformation_values (std::span< const double > values, std::size_t expected_size)
	Reject incompatible lengths and non-finite values before evaluating a deformation action.
template<DeformationMap Map>
std::expected< std::vector< double >, DeformationFailure >	evaluate_displacement (const Map &map, std::span< const double > parameters)
	Allocate a result for graph publication while leaving repeated low-level actions allocation-free.
template<DeformationMap Map>
DeformationStatus	apply_jacobian (const DeformationLinearization< Map > &state, std::span< const double > direction, std::span< double > output, DeformationWorkspace< Map > &workspace)
	Evaluate a tangent about the cache's accepted shape, not the caller's next trial state.
template<DeformationMap Map>
DeformationStatus	apply_jacobian_transpose (const DeformationLinearization< Map > &state, std::span< const double > dual, std::span< double > output, DeformationWorkspace< Map > &workspace)
	Pull displacement forces back to the accepted independent shape coordinates.
template<DeformationMap Map>
DeformationStatus	apply_pullback_derivative (const DeformationLinearization< Map > &state, std::span< const double > direction, std::span< const double > dual, std::span< double > output, DeformationWorkspace< Map > &workspace)
	Keep the geometric contribution to the Newton force derivative available for nonlinear models.
std::expected< RadialExtension, DeformationFailure >	make_radial_extension (std::shared_ptr< const RadialInterpolation > interpolation, PowerLawRadialExtension interior={}, FixedInfinityRadialExtension vacuum={})
	Compile regional weights while sharing the immutable surface interpolation. The interpolation factory has already established every reference-table invariant.
std::expected< RadialInterpolation, DeformationFailure >	make_radial_interpolation (RadialInterpolationData data)
	Check imported or backend-generated reference rows once before sharing them with radial laws.
std::expected< SurfaceEmbedding, DeformationFailure >	build_surface_embedding (const NodalRadialSurface &model, std::span< const std::array< double, 3 > > positions)
	Compile fixed radial directions from ordered physical reference positions without retaining backend objects.
std::expected< SurfaceEmbedding, DeformationFailure >	build_surface_embedding (const SphericalHarmonicSurface &model, std::span< const std::array< double, 3 > > positions)
	Sample physically normalized real harmonics and reject unresolved modes without renormalizing or dropping coordinates.
template<typename Surface, typename Interior, typename Vacuum>
auto	make_deformation_inputs (const DomainDeformation< Surface, Interior, Vacuum > &model, const ReferenceDiscretization &discretization, const std::vector< double > &coefficients)
	Bind physical choices and a borrowed shape vector without evaluating deformation.
template<typename Surface>
auto	make_deformation_graph ()
	Provide a standalone graph while leaving the same computations available for equation composition.
template<typename Surface> requires requires(const Surface& model, std::span<const std::array<double, 3>> positions) { { build_surface_embedding(model, positions) } -> std::same_as<std::expected<SurfaceEmbedding, DeformationFailure>>; }
auto	make_deformation_computations ()
	Compile fixed reference factors and evaluate shape motion with one dependency engine.
template<discretization::domain::schema::IsSchema Schema = discretization::domain::schema::CoreEnvelopeVacuumDomainSchema> requires (Schema::template contains_domain<discretization::domain::StellarDomains>() && Schema::template contains_domain<discretization::domain::VacuumDomain>() && Schema::template contains_boundary<discretization::domain::StellarSurfaceBoundary>() && Schema::template contains_boundary<discretization::domain::InfinitySurfaceBoundary>())
ReferenceDiscretization	deformation_discretization (const ::mfem::FiniteElementSpace &scalar_space, const ::mfem::FiniteElementSpace &displacement_space, ::mfem::Mesh &logical_mesh)
	Resolve physical domain names through the schema rather than hard-coded MFEM attributes.

Variables
template<typename Map>
constexpr bool	is_linear_deformation
	Linearity is an explicit property of the mathematics, independent of its action interface.

Typedef Documentation

DeformationStatus

using serif::geometry::deformation::DeformationStatus = std::expected<void, DeformationFailure>

DeformationWorkspace

template<typename Map>

using serif::geometry::deformation::DeformationWorkspace = typename Map::Workspace

Enumeration Type Documentation

DeformationFailureReason

enum class serif::geometry::deformation::DeformationFailureReason

strong

Enumerator
invalid_configuration
incompatible_discretization
invalid_size
non_finite
unresolved_surface
invalid_geometry

Function Documentation

apply_jacobian() [1/2]

template<DeformationMap Map>

DeformationStatus serif::geometry::deformation::apply_jacobian ( const DeformationLinearization< Map > & state, std::span< const double > direction, std::span< double > output, DeformationWorkspace< Map > & workspace )

nodiscard

Evaluate a tangent about the cache's accepted shape, not the caller's next trial state.

apply_jacobian() [2/2]

template<DeformationMap Map>

DeformationStatus serif::geometry::deformation::apply_jacobian ( const Map & map, std::span< const double > parameters, std::span< const double > direction, std::span< double > displacement_direction, DeformationWorkspace< Map > & workspace )

nodiscard

Linear maps reuse their primal action; nonlinear maps supply their exact tangent.

apply_jacobian_transpose() [1/2]

template<DeformationMap Map>

DeformationStatus serif::geometry::deformation::apply_jacobian_transpose ( const DeformationLinearization< Map > & state, std::span< const double > dual, std::span< double > output, DeformationWorkspace< Map > & workspace )

nodiscard

Pull displacement forces back to the accepted independent shape coordinates.

apply_jacobian_transpose() [2/2]

template<DeformationMap Map>

DeformationStatus 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, DeformationWorkspace< Map > & workspace )

nodiscard

Transfer virtual work from the displacement field to its independent shape coefficients.

apply_pullback_derivative() [1/2]

template<DeformationMap Map>

DeformationStatus serif::geometry::deformation::apply_pullback_derivative ( const DeformationLinearization< Map > & state, std::span< const double > direction, std::span< const double > dual, std::span< double > output, DeformationWorkspace< Map > & workspace )

nodiscard

Keep the geometric contribution to the Newton force derivative available for nonlinear models.

apply_pullback_derivative() [2/2]

template<DeformationMap Map>

DeformationStatus 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, DeformationWorkspace< Map > & workspace )

nodiscard

Differentiate the transpose at fixed dual; zero is justified only for a declared linear map.

build_displacement()

template<DeformationMap Map>

DeformationStatus serif::geometry::deformation::build_displacement ( const Map & map, std::span< const double > parameters, std::span< double > displacement, DeformationWorkspace< Map > & workspace )

nodiscard

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.

build_surface_embedding() [1/2]

std::expected< SurfaceEmbedding, DeformationFailure > serif::geometry::deformation::build_surface_embedding ( const NodalRadialSurface & model, std::span< const std::array< double, 3 > > positions )

nodiscard

Compile fixed radial directions from ordered physical reference positions without retaining backend objects.

build_surface_embedding() [2/2]

std::expected< SurfaceEmbedding, DeformationFailure > serif::geometry::deformation::build_surface_embedding ( const SphericalHarmonicSurface & model, std::span< const std::array< double, 3 > > positions )

nodiscard

Sample physically normalized real harmonics and reject unresolved modes without renormalizing or dropping coordinates.

compose_deformation()

template<DeformationMap SurfaceMap, DeformationMap ExtensionMap>
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>

std::expected< ComposedDeformation< SurfaceMap, ExtensionMap >, DeformationFailure > serif::geometry::deformation::compose_deformation ( std::shared_ptr< const SurfaceMap > surface, std::shared_ptr< const ExtensionMap > extension )

nodiscard

Validate factor sizes before constructing an owning mathematical composition.

deformation_discretization()

template<discretization::domain::schema::IsSchema Schema = discretization::domain::schema::CoreEnvelopeVacuumDomainSchema>
requires (Schema::template contains_domain<discretization::domain::StellarDomains>() && Schema::template contains_domain<discretization::domain::VacuumDomain>() && Schema::template contains_boundary<discretization::domain::StellarSurfaceBoundary>() && Schema::template contains_boundary<discretization::domain::InfinitySurfaceBoundary>())

ReferenceDiscretization serif::geometry::deformation::backend::mfem::deformation_discretization ( const ::mfem::FiniteElementSpace & scalar_space, const ::mfem::FiniteElementSpace & displacement_space, ::mfem::Mesh & logical_mesh )

nodiscard

Resolve physical domain names through the schema rather than hard-coded MFEM attributes.

evaluate_displacement()

template<DeformationMap Map>

std::expected< std::vector< double >, DeformationFailure > serif::geometry::deformation::evaluate_displacement ( const Map & map, std::span< const double > parameters )

nodiscard

Allocate a result for graph publication while leaving repeated low-level actions allocation-free.

make_deformation_computations() [1/2]

template<DeformationMap SurfaceMap, DeformationMap ExtensionMap>
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>

auto serif::geometry::deformation::make_deformation_computations ( )

nodiscard

Declare the numerical composition as ordinary dependency computations.

Note

Shared immutable factors, coefficient snapshots, and results belong to the dependency cache. Analytical actions remain independent functions.

make_deformation_computations() [2/2]

template<typename Surface>
requires requires(const Surface& model, std::span<const std::array<double, 3>> positions) { { build_surface_embedding(model, positions) } -> std::same_as<std::expected<SurfaceEmbedding, DeformationFailure>>; }

auto serif::geometry::deformation::backend::mfem::make_deformation_computations ( )

nodiscard

Compile fixed reference factors and evaluate shape motion with one dependency engine.

Note

Configuration values are named context inputs. Factories declare work; try_prepare performs it explicitly.

make_deformation_graph() [1/2]

template<DeformationMap SurfaceMap, DeformationMap ExtensionMap>
requires std::same_as<typename SurfaceMap::OutputSpace, typename ExtensionMap::InputSpace>

auto serif::geometry::deformation::make_deformation_graph ( )

nodiscard

Compose independently compiled mathematical factors without introducing a prepared-operator facade.

make_deformation_graph() [2/2]

template<typename Surface>

auto serif::geometry::deformation::backend::mfem::make_deformation_graph ( )

nodiscard

Provide a standalone graph while leaving the same computations available for equation composition.

make_deformation_inputs()

template<typename Surface, typename Interior, typename Vacuum>

auto serif::geometry::deformation::backend::mfem::make_deformation_inputs ( const DomainDeformation< Surface, Interior, Vacuum > & model, const ReferenceDiscretization & discretization, const std::vector< double > & coefficients )

nodiscard

Bind physical choices and a borrowed shape vector without evaluating deformation.

Note

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.

make_deformation_workspace()

template<DeformationMap Map>

DeformationWorkspace< Map > serif::geometry::deformation::make_deformation_workspace ( const Map & map )

nodiscard

Allocate action scratch explicitly, once per independent caller.

make_radial_extension()

std::expected< RadialExtension, DeformationFailure > serif::geometry::deformation::make_radial_extension ( std::shared_ptr< const RadialInterpolation > interpolation, PowerLawRadialExtension interior = {}, FixedInfinityRadialExtension vacuum = {} )

nodiscard

Compile regional weights while sharing the immutable surface interpolation. The interpolation factory has already established every reference-table invariant.

make_radial_interpolation()

std::expected< RadialInterpolation, DeformationFailure > serif::geometry::deformation::make_radial_interpolation ( RadialInterpolationData data )

nodiscard

Check imported or backend-generated reference rows once before sharing them with radial laws.

validate_deformation_values()

DeformationStatus serif::geometry::deformation::validate_deformation_values ( std::span< const double > values, std::size_t expected_size )

inlinenodiscard

Reject incompatible lengths and non-finite values before evaluating a deformation action.

Variable Documentation

is_linear_deformation

template<typename Map>

bool serif::geometry::deformation::is_linear_deformation

inlineconstexpr

Initial value:

= requires
    {
        requires Map::is_linear;
    }

Linearity is an explicit property of the mathematics, independent of its action interface.