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)
329 lines
16 KiB
Groff
329 lines
16 KiB
Groff
.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\&.
|