Files
MeanField_SERiF/docs/man/man3/serif_solver_normalization.3

329 lines
16 KiB
Groff
Raw Permalink Normal View History

.TH "serif::solver::normalization" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::solver::normalization
.SH SYNOPSIS
.br
.PP
.SS "Namespaces"
.in +1c
.ti -1c
.RI "namespace \fBbackend\fP"
.br
.ti -1c
.RI "namespace \fBchecks\fP"
.br
.ti -1c
.RI "namespace \fBdetail\fP"
.br
.ti -1c
.RI "namespace \fBkeys\fP"
.br
.in -1c
.SS "Classes"
.in +1c
.ti -1c
.RI "struct \fBAutomaticPlan\fP"
.br
.RI "Derive the coordinate rules from the selected fields, equations and boundary formulation\&. "
.ti -1c
.RI "class \fBDiagonalNormalization\fP"
.br
.RI "Own the frozen, independent state and residual transformations used by one solve\&. "
.ti -1c
.RI "struct \fBDimensionless\fP"
.br
.RI "Remove physical and geometric units from the solver's coordinates and norms\&. "
.ti -1c
.RI "struct \fBDimensionlessMetricGeometry\fP"
.br
.RI "Require custom metrics to declare their geometric convention explicitly\&. "
.ti -1c
.RI "struct \fBDimensionlessMetricGeometry< geometry::deformation::keys::SurfaceMetric >\fP"
.br
.ti -1c
.RI "struct \fBDimensionlessMetricGeometry< ReferenceVolumeMetric< TermT > >\fP"
.br
.ti -1c
.RI "struct \fBDimensionlessMetricGeometry< UnitMetric >\fP"
.br
.ti -1c
.RI "struct \fBDimensionlessRieszCoordinate\fP"
.br
.RI "Measure coordinates using dimensionless physical fields and reference geometry\&. "
.ti -1c
.RI "struct \fBFromModel\fP"
.br
.RI "Obtain a reference value from the corresponding descriptive model prescription\&. "
.ti -1c
.RI "struct \fBIdentityCoordinate\fP"
.br
.RI "Leave the declared coordinates unchanged, including their physical units\&. "
.ti -1c
.RI "struct \fBLaneEmdenApproximation\fP"
.br
.RI "Estimate a reference radius from a Lane–Emden shape, mass and central density\&. "
.ti -1c
.RI "struct \fBMetricCoordinates\fP"
.br
.RI "Metric keys advertise the coordinate identities they measure; a same-sized unrelated metric is insufficient\&. "
.ti -1c
.RI "struct \fBMetricCoordinates< geometry::deformation::keys::SurfaceMetric >\fP"
.br
.RI "Consume deformation's existing metric directly in both native shape-coordinate roles\&. "
.ti -1c
.RI "struct \fBMetricCoordinates< MetricT, std::void_t< typename MetricT::Coordinates > >\fP"
.br
.ti -1c
.RI "struct \fBMetricCoordinates< UnitMetric >\fP"
.br
.RI "Permit a Euclidean norm of algebraic surface moments after their measure is made dimensionless\&. "
.ti -1c
.RI "struct \fBNormalizationOptions\fP"
.br
.RI "Declare normalization without evaluating a reference star or allocating coordinate factors\&. "
.ti -1c
.RI "struct \fBNormalizationPlan\fP"
.br
.RI "Independent term-to-method and row-to-method maps; their order does not define the packed layout\&. "
.ti -1c
.RI "struct \fBNormalizationPrescriptionTag\fP"
.br
.ti -1c
.RI "struct \fBPhysicalRieszCoordinate\fP"
.br
.RI "Measure a physical quantity with the named reference Gram diagonal\&. "
.ti -1c
.RI "struct \fBReferenceVolumeMetric\fP"
.br
.RI "Identify a reference volume metric by its physical term, including its support and FE representation\&. "
.ti -1c
.RI "struct \fBRuntimePreparedCoordinate\fP"
.br
.RI "Identify the exact prescription supplying positive factors; this never claims identity scaling\&. "
.ti -1c
.RI "struct \fBStellarReferenceScales\fP"
.br
.RI "Fixed reference scales used throughout a solve, independent of its candidate state\&. "
.ti -1c
.RI "struct \fBUnitMetric\fP"
.br
.RI "A unit Gram metric for algebraic coordinates, still subject to physical scaling\&. "
.ti -1c
.RI "struct \fBWithPointRows\fP"
.br
.RI "Replace selected volume residual rows by point residuals with their own physical quantity\&. "
.in -1c
.SS "Concepts"
.in +1c
.ti -1c
.RI "concept \fBNormalizationPreparable\fP"
.br
.ti -1c
.RI "concept \fBReferenceScheme\fP"
.br
.RI "A custom stellar reference strategy supplies the same typed scales and ordinary failure value\&. "
.ti -1c
.RI "concept \fBCoordinateLayoutType\fP"
.br
.RI "Normalization consumes the same coordinate representation as physical operators and solvers\&. "
.ti -1c
.RI "concept \fBMetricFor\fP"
.br
.ti -1c
.RI "concept \fBNormalizationPrescription\fP"
.br
.ti -1c
.RI "concept \fBNormalizationPlanType\fP"
.br
.ti -1c
.RI "concept \fBCompleteNormalizationFor\fP"
.br
.ti -1c
.RI "concept \fBStellarScaleQuantity\fP"
.br
.RI "Quantities whose characteristic scales follow from reference mass, radius, and G alone\&. "
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "template<utils::dependencies::IsKeyList Values, utils::dependencies::IsKeyList Residuals> using \fBCoordinateLayout\fP = \fBdiscretization::blocks::SystemLayout\fP<Values, Residuals>"
.br
.RI "Compatibility spelling for the shared discretization layout\&. "
.ti -1c
.RI "template<discretization::blocks::HasQuantity TermT> using \fBPhysicalValueRule\fP = \fButils::dependencies::Binding\fP<TermT, \fBPhysicalRieszCoordinate\fP<typename TermT::Quantity, typename decltype(\fBdetail::default_metric\fP<TermT>())::type>>"
.br
.RI "Describe an unknown from its existing quantity, support, and functional-space metadata\&. "
.ti -1c
.RI "template<typename EquationT> using \fBPhysicalResidualRule\fP = \fButils::dependencies::Binding\fP<EquationT, \fBPhysicalRieszCoordinate\fP<typename EquationT::ResidualQuantity, typename decltype(\fBdetail::default_metric\fP<EquationT>())::type>>"
.br
.RI "Describe a residual using the equation's declared quantity, which may differ from the unknown it closes\&. "
.in -1c
.SS "Enumerations"
.in +1c
.ti -1c
.RI "enum class \fBReferenceGeometry\fP { \fBvolume\fP, \fBsurface\fP, \fBalgebraic\fP }"
.br
.RI "Identify the geometric convention of a reference coordinate metric\&. "
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "template<typename PlanT, typename ScalesT = StellarReferenceScales, typename LayoutT>
.br
requires NormalizationPreparable<PlanT, LayoutT, ScalesT>auto \fBmake_normalization_computations\fP (const LayoutT &)"
.br
.RI "Declare normalization as ordinary dependency computations; no metrics or factors are prepared here\&. "
.ti -1c
.RI "template<typename Scheme, typename Coordinates, typename Plan, typename Sources, typename Computations> auto \fBmake_normalization\fP (\fBNormalizationOptions\fP< Scheme, Coordinates, Plan, Sources, Computations > options)"
.br
.RI "Preserve the deduced numerical choices for later preparation with a model and discretization\&. "
.ti -1c
.RI "auto \fBmake_normalization\fP ()"
.br
.RI "Select the usual dimensionless Lane–Emden reference; supply its central density before resolving it against a model\&. "
.ti -1c
.RI "std::expected< \fBStellarReferenceScales\fP, std::string > \fBprepare_reference_scales\fP (const \fBLaneEmdenApproximation\fP< \fBdimensions::MassValue\fP, \fBdimensions::DensityValue\fP > &scheme, \fBdimensions::QuantityValue\fP< \fBdimensions::GravitationalConstant\fP > gravitational_constant)"
.br
.RI "Derive the shared stellar scales after both dimensional reference inputs have been resolved\&. "
.ti -1c
.RI "std::expected< \fBStellarReferenceScales\fP, std::string > \fBprepare_reference_scales\fP (const \fBStellarReferenceScales\fP &reference, \fBdimensions::QuantityValue\fP< \fBdimensions::GravitationalConstant\fP > gravitational_constant)"
.br
.RI "Use explicitly prepared reference scales through the same graph as estimated references\&. "
.ti -1c
.RI "std::expected< double, std::string > \fBmake_riesz_factor\fP (\fBdiscretization::blocks::RepresentedValueKind\fP kind, double metric, double physical_scale)"
.br
.RI "Prepare one primal sqrt(metric)/scale or dual 1/(scale sqrt(metric)) factor\&. "
.ti -1c
.RI "std::expected< std::vector< double >, std::string > \fBmake_riesz_factors\fP (\fBdiscretization::blocks::RepresentedValueKind\fP kind, std::span< const double > metric, double physical_scale)"
.br
.RI "Prepare diagonal Riesz factors, reporting which coordinate has invalid data\&. "
.ti -1c
.RI "std::expected< \fBDiagonalNormalization\fP, std::string > \fBmake_diagonal_normalization\fP (std::vector< double > state, std::vector< double > residual)"
.br
.RI "Validate and freeze independent coordinate factors, including empty or rectangular systems\&. "
.ti -1c
.RI "std::expected< std::vector< double >, std::string > \fBmake_point_replaced_residual_factors\fP (std::span< const double > volume_metric, double volume_scale, std::span< const int > selected_rows, double point_scale)"
.br
.RI "Measure volume and replacement point residuals in their independently specified physical units\&. "
.ti -1c
.RI "std::expected< \fBStellarReferenceScales\fP, std::string > \fBprepare_stellar_reference_scales\fP (\fBdimensions::QuantityValue\fP< \fBdimensions::Mass\fP > mass, \fBdimensions::QuantityValue\fP< \fBdimensions::Length\fP > radius, \fBdimensions::QuantityValue\fP< \fBdimensions::GravitationalConstant\fP > gravitational_constant=\fBdimensions::QuantityValue\fP< \fBdimensions::GravitationalConstant\fP >{1\&.0})"
.br
.RI "Derive gravitational stellar scales from a finite, positive reference mass, radius, and G\&. "
.ti -1c
.RI "template<StellarScaleQuantity Quantity> \fBdimensions::QuantityValue\fP< Quantity > \fBcharacteristic_scale\fP (const \fBStellarReferenceScales\fP &scales, Quantity)"
.br
.RI "Select a typed scale; temperature and other unrelated quantities require an explicit prescription\&. "
.ti -1c
.RI "std::expected< double, std::string > \fBmake_riesz_factor\fP (Kind kind, double metric, double physical_scale)"
.br
.ti -1c
.RI "std::expected< std::vector< double >, std::string > \fBmake_riesz_factors\fP (Kind kind, std::span< const double > metric, double physical_scale)"
.br
.in -1c
.SH "Typedef Documentation"
.PP
.SS "template<utils::dependencies::IsKeyList Values, utils::dependencies::IsKeyList Residuals> using \fBserif::solver::normalization::CoordinateLayout\fP = \fBdiscretization::blocks::SystemLayout\fP<Values, Residuals>"
.PP
Compatibility spelling for the shared discretization layout\&.
.SS "template<typename EquationT> using \fBserif::solver::normalization::PhysicalResidualRule\fP = \fButils::dependencies::Binding\fP<EquationT, \fBPhysicalRieszCoordinate\fP<typename EquationT::ResidualQuantity, typename decltype(\fBdetail::default_metric\fP<EquationT>())::type>>"
.PP
Describe a residual using the equation's declared quantity, which may differ from the unknown it closes\&.
.SS "template<discretization::blocks::HasQuantity TermT> using \fBserif::solver::normalization::PhysicalValueRule\fP = \fButils::dependencies::Binding\fP<TermT, \fBPhysicalRieszCoordinate\fP<typename TermT::Quantity, typename decltype(\fBdetail::default_metric\fP<TermT>())::type>>"
.PP
Describe an unknown from its existing quantity, support, and functional-space metadata\&.
.SH "Enumeration Type Documentation"
.PP
.SS "enum class \fBserif::solver::normalization::ReferenceGeometry\fP\fR [strong]\fP"
.PP
Identify the geometric convention of a reference coordinate metric\&.
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIvolume \fP
.TP
\f(BIsurface \fP
.TP
\f(BIalgebraic \fP
.SH "Function Documentation"
.PP
.SS "template<StellarScaleQuantity Quantity> \fBdimensions::QuantityValue\fP< Quantity > serif::solver::normalization::characteristic_scale (const \fBStellarReferenceScales\fP & scales, Quantity )\fR [nodiscard]\fP"
.PP
Select a typed scale; temperature and other unrelated quantities require an explicit prescription\&.
.SS "std::expected< \fBDiagonalNormalization\fP, std::string > serif::solver::normalization::make_diagonal_normalization (std::vector< double > state, std::vector< double > residual)\fR [nodiscard]\fP"
.PP
Validate and freeze independent coordinate factors, including empty or rectangular systems\&.
.SS "auto serif::solver::normalization::make_normalization ()\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Select the usual dimensionless Lane–Emden reference; supply its central density before resolving it against a model\&.
.SS "template<typename Scheme, typename Coordinates, typename Plan, typename Sources, typename Computations> auto serif::solver::normalization::make_normalization (\fBNormalizationOptions\fP< Scheme, Coordinates, Plan, Sources, Computations > options)\fR [nodiscard]\fP"
.PP
Preserve the deduced numerical choices for later preparation with a model and discretization\&.
.SS "template<typename PlanT, typename ScalesT = StellarReferenceScales, typename LayoutT>
.br
requires NormalizationPreparable<PlanT, LayoutT, ScalesT>auto serif::solver::normalization::make_normalization_computations (const LayoutT & )\fR [nodiscard]\fP"
.PP
Declare normalization as ordinary dependency computations; no metrics or factors are prepared here\&.
.PP
\fBNote\fP
.RS 4
Supply \fBkeys::Layout\fP, \fBkeys::Scales\fP, and the plan's metric/selection/prescription sources\&. Copy the accepted \fBDiagonalNormalization\fP to freeze one solve before preparing later candidates\&.
.RE
.PP
.SS "std::expected< std::vector< double >, std::string > serif::solver::normalization::make_point_replaced_residual_factors (std::span< const double > volume_metric, double volume_scale, std::span< const int > selected_rows, double point_scale)\fR [nodiscard]\fP"
.PP
Measure volume and replacement point residuals in their independently specified physical units\&.
.PP
\fBNote\fP
.RS 4
Only replaced rows may have a zero or otherwise unusable volume metric\&. No bulk factor is evaluated for them\&.
.RE
.PP
.SS "std::expected< double, std::string > serif::solver::normalization::make_riesz_factor (\fBdiscretization::blocks::RepresentedValueKind\fP kind, double metric, double physical_scale)\fR [nodiscard]\fP"
.PP
Prepare one primal sqrt(metric)/scale or dual 1/(scale sqrt(metric)) factor\&.
.SS "std::expected< double, std::string > serif::solver::normalization::make_riesz_factor (Kind kind, double metric, double physical_scale)"
.SS "std::expected< std::vector< double >, std::string > serif::solver::normalization::make_riesz_factors (\fBdiscretization::blocks::RepresentedValueKind\fP kind, std::span< const double > metric, double physical_scale)\fR [nodiscard]\fP"
.PP
Prepare diagonal Riesz factors, reporting which coordinate has invalid data\&.
.SS "std::expected< std::vector< double >, std::string > serif::solver::normalization::make_riesz_factors (Kind kind, std::span< const double > metric, double physical_scale)"
.SS "std::expected< \fBStellarReferenceScales\fP, std::string > serif::solver::normalization::prepare_reference_scales (const \fBLaneEmdenApproximation\fP< \fBdimensions::MassValue\fP, \fBdimensions::DensityValue\fP > & scheme, \fBdimensions::QuantityValue\fP< \fBdimensions::GravitationalConstant\fP > gravitational_constant)\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Derive the shared stellar scales after both dimensional reference inputs have been resolved\&.
.SS "std::expected< \fBStellarReferenceScales\fP, std::string > serif::solver::normalization::prepare_reference_scales (const \fBStellarReferenceScales\fP & reference, \fBdimensions::QuantityValue\fP< \fBdimensions::GravitationalConstant\fP > gravitational_constant)\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Use explicitly prepared reference scales through the same graph as estimated references\&.
.SS "std::expected< \fBStellarReferenceScales\fP, std::string > serif::solver::normalization::prepare_stellar_reference_scales (\fBdimensions::QuantityValue\fP< \fBdimensions::Mass\fP > mass, \fBdimensions::QuantityValue\fP< \fBdimensions::Length\fP > radius, \fBdimensions::QuantityValue\fP< \fBdimensions::GravitationalConstant\fP > gravitational_constant = \fR\fBdimensions::QuantityValue\fP<\fBdimensions::GravitationalConstant\fP>{1\&.0}\fP)\fR [nodiscard]\fP"
.PP
Derive gravitational stellar scales from a finite, positive reference mass, radius, and G\&.
.SH "Author"
.PP
Generated automatically by Doxygen for SERiF from the source code\&.