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)
386 lines
15 KiB
Groff
386 lines
15 KiB
Groff
.TH "serif::solver::continuation" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
serif::solver::continuation
|
|
.SH SYNOPSIS
|
|
.br
|
|
.PP
|
|
.SS "Namespaces"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "namespace \fBdetail\fP"
|
|
.br
|
|
.in -1c
|
|
.SS "Classes"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "struct \fBAngularMomentum\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "class \fBBoundFamily\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "class \fBBoundFamily< Model, ParameterList< Selected\&.\&.\&. >, std::tuple< Laws\&.\&.\&. >, EquationFactory >\fP"
|
|
.br
|
|
.RI "Own target physics and construct fresh family members without a mesh, evaluator, or mutable solve context\&. "
|
|
.ti -1c
|
|
.RI "class \fBCoordinateController\fP"
|
|
.br
|
|
.RI "Own only the continuation path; a caller promotes physical states after successful correction\&. "
|
|
.ti -1c
|
|
.RI "struct \fBCoordinateCounters\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBCoordinateOptions\fP"
|
|
.br
|
|
.RI "Numerical increments are fractions of each coordinate's complete physical span\&. "
|
|
.ti -1c
|
|
.RI "struct \fBCoordinateProposal\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBCorrectionControls\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBFailure\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "class \fBFamily\fP"
|
|
.br
|
|
.RI "Own a reusable physical family definition before selecting a target model\&. "
|
|
.ti -1c
|
|
.RI "struct \fBIdentifiedEquations\fP"
|
|
.br
|
|
.RI "Give a deferred equation definition an explicit physical identity without runtime polymorphism\&. "
|
|
.ti -1c
|
|
.RI "struct \fBNumericalControls\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBOptions\fP"
|
|
.br
|
|
.RI "Bound continuation work and storage independently of \fBNewton\fP's per-correction controls\&. "
|
|
.ti -1c
|
|
.RI "struct \fBOrdering\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBParameterDescriptor\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBParameterLaw\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBPolytropicConstant\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBPolytropicIndex\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "class \fBPreservePressureAtReferenceDensity\fP"
|
|
.br
|
|
.RI "Vary K with n to preserve pressure at one explicitly selected physical reference density\&. "
|
|
.ti -1c
|
|
.RI "struct \fBResult\fP"
|
|
.br
|
|
.RI "Retain the last converged physical state separately from the requested endpoint and failed candidates\&. "
|
|
.ti -1c
|
|
.RI "struct \fBSpecificationTraits\fP"
|
|
.br
|
|
.RI "Add continuation access without imposing numerical dependencies on a physical prescription\&. "
|
|
.ti -1c
|
|
.RI "struct \fBSpecificationTraits< eos::models::Polytrope >\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBSpecificationTraits< model::FixedAngularMomentum >\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBSpecificationTraits< Specification >\fP"
|
|
.br
|
|
.RI "Preserve unselected scalar prescriptions in the complete physical identity\&. "
|
|
.ti -1c
|
|
.RI "struct \fBStageRecord\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBStartingAt\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBStartingStar\fP"
|
|
.br
|
|
.RI "A supplied physical anchor still requires fresh qualification at the continuation tolerance\&. "
|
|
.in -1c
|
|
.SS "Concepts"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "concept \fBCoordinateValue\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "concept \fBPhysicalParameter\fP"
|
|
.br
|
|
.RI "A typed physical parameter owns its domain predicate, units, owner, and stable identity\&. "
|
|
.ti -1c
|
|
.RI "concept \fBIdentifiedSpecification\fP"
|
|
.br
|
|
.RI "Require explicit identity data, never an object address or incidental memory representation\&. "
|
|
.in -1c
|
|
.SS "Typedefs"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "template<typename\&.\&.\&. Parameters> using \fBParameterList\fP = \fButils::dependencies::KeyList\fP<Parameters\&.\&.\&.>"
|
|
.br
|
|
.in -1c
|
|
.SS "Enumerations"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "enum class \fBCoordinateOrder\fP { \fBautomatic\fP, \fBpreferred\fP, \fBstrict\fP }"
|
|
.br
|
|
.ti -1c
|
|
.RI "enum class \fBAttemptOutcome\fP { \fBsuccess\fP, \fBrecoverable_rejection\fP, \fBfatal_failure\fP }"
|
|
.br
|
|
.ti -1c
|
|
.RI "enum class \fBControllerStatus\fP { \fBready\fP, \fBpending\fP, \fBcomplete\fP, \fBattempt_limit\fP, \fBno_progress\fP, \fBfatal_failure\fP }"
|
|
.br
|
|
.ti -1c
|
|
.RI "enum class \fBStatus\fP { \fBtarget_reached\fP, \fBstarting_star_failed\fP, \fBattempt_limit\fP, \fBwork_limit\fP, \fBno_progress\fP, \fBinvalid_model\fP }"
|
|
.br
|
|
.ti -1c
|
|
.RI "enum class \fBStageDisposition\fP { \fBconverged\fP, \fBnot_converged\fP, \fBinvalid_model\fP }"
|
|
.br
|
|
.in -1c
|
|
.SS "Functions"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "template<typename \fBFamily\fP, typename State, typename Corrector> auto \fBrun\fP (const \fBFamily\fP &family, const State &initial_state, Corrector &&correct, \fBOptions\fP< \fBFamily\fP > options, double absolute_tolerance)"
|
|
.br
|
|
.RI "Follow a physical family using owning correction results and physical state transfer\&. "
|
|
.ti -1c
|
|
.RI "template<typename \fBFamily\fP, typename Model, typename State, typename Corrector> auto \fBrun\fP (const \fBFamily\fP &family, const \fBStartingStar\fP< Model, State > &\fBinitial\fP, Corrector &&correct, \fBOptions\fP< \fBFamily\fP > options, double absolute_tolerance)"
|
|
.br
|
|
.RI "Qualify a supplied star afresh after checking every physical family input\&. "
|
|
.ti -1c
|
|
.RI "\fBSolverOptions\fP \fBdefault_solver_options\fP ()"
|
|
.br
|
|
.RI "Continuation uses one absolute qualification threshold across all family members\&. "
|
|
.ti -1c
|
|
.RI "template<PhysicalParameter\&.\&.\&. Parameters> constexpr auto \fBdepends_on\fP (Parameters\&.\&.\&.) noexcept"
|
|
.br
|
|
.RI "Name only independent physical inputs to a dependent law\&. "
|
|
.ti -1c
|
|
.RI "template<PhysicalParameter Output, PhysicalParameter\&.\&.\&. Inputs, typename Function>
|
|
.br
|
|
requires utils::dependencies::IsKeyList<\fBParameterList\fP<Inputs\&.\&.\&.>> && std::invocable<const std::remove_cvref_t<Function>&, typename Inputs::Value\&.\&.\&.> && std::same_as<std::remove_cvref_t<std::invoke_result_t<const std::remove_cvref_t<Function>&, typename Inputs::Value\&.\&.\&.>>, typename Output::Value>auto \fBlaw\fP (Output, \fBParameterList\fP< Inputs\&.\&.\&. >, Function &&function)"
|
|
.br
|
|
.RI "Own a typed law, including move-only captures; its inputs are selected coordinates rather than other laws\&. "
|
|
.ti -1c
|
|
.RI "template<PhysicalParameter\&.\&.\&. Parameters>
|
|
.br
|
|
requires (sizeof\&.\&.\&.(Parameters) > 0) && utils::dependencies::IsKeyList<\fBParameterList\fP<Parameters\&.\&.\&.>>auto \fBin\fP (Parameters\&.\&.\&.)"
|
|
.br
|
|
.RI "Select independent physical coordinates with duplicate detection at compile time\&. "
|
|
.ti -1c
|
|
.RI "template<typename Definition, CoordinateValue\&.\&.\&. Values> auto \fBidentified_equations\fP (Definition definition, Values\&.\&.\&. values)"
|
|
.br
|
|
.RI "Declare every fixed physical constant captured by a deferred equation definition\&. "
|
|
.ti -1c
|
|
.RI "template<PhysicalParameter Parameter> auto \fBstarting_at\fP (Parameter, typename Parameter::Value value)"
|
|
.br
|
|
.RI "Select a physical starting value with the parameter's required units\&. "
|
|
.ti -1c
|
|
.RI "template<PhysicalParameter\&.\&.\&. Parameters>
|
|
.br
|
|
requires (sizeof\&.\&.\&.(Parameters) > 0) && utils::dependencies::IsKeyList<\fBParameterList\fP<Parameters\&.\&.\&.>>auto \fBprefer\fP (Parameters\&.\&.\&.)"
|
|
.br
|
|
.RI "Try these physical coordinates first, allowing blocked coordinates to yield\&. "
|
|
.ti -1c
|
|
.RI "template<PhysicalParameter\&.\&.\&. Parameters>
|
|
.br
|
|
requires (sizeof\&.\&.\&.(Parameters) > 0) && utils::dependencies::IsKeyList<\fBParameterList\fP<Parameters\&.\&.\&.>>auto \fBstages\fP (Parameters\&.\&.\&.)"
|
|
.br
|
|
.RI "Complete each physical stage before attempting the next\&. "
|
|
.ti -1c
|
|
.RI "template<std::size_t Count> auto \fBnumerics\fP (\fBCoordinateOptions\fP< Count > options)"
|
|
.br
|
|
.RI "Expose advanced numerical coordinate stepping without mixing it into physical prescriptions\&. "
|
|
.ti -1c
|
|
.RI "template<typename \fBFamily\fP, typename\&.\&.\&. Settings>
|
|
.br
|
|
requires (requires(const Settings& setting, \fBOptions\fP<\fBFamily\fP>& options) { setting\&.apply(options); } && \&.\&.\&.)auto \fBmake_options\fP (const \fBFamily\fP &family, const Settings &\&.\&.\&. settings)"
|
|
.br
|
|
.RI "Resolve physical settings from family defaults before any corrector runs\&. "
|
|
.ti -1c
|
|
.RI "template<CoordinateValue Value> constexpr double \fBcoordinate_value\fP (Value value) noexcept"
|
|
.br
|
|
.RI "Convert physical units only at the coordinate-controller boundary\&. "
|
|
.ti -1c
|
|
.RI "auto \fBpreserve_pressure_at_reference_density\fP (\fBdimensions::DensityValue\fP density)"
|
|
.br
|
|
.RI "Choose a pressure-preserving physical EOS family, independently of numerical normalization\&. "
|
|
.in -1c
|
|
.SH "Typedef Documentation"
|
|
.PP
|
|
.SS "template<typename\&.\&.\&. Parameters> using \fBserif::solver::continuation::ParameterList\fP = \fButils::dependencies::KeyList\fP<Parameters\&.\&.\&.>"
|
|
|
|
.SH "Enumeration Type Documentation"
|
|
.PP
|
|
.SS "enum class \fBserif::solver::continuation::AttemptOutcome\fP\fR [strong]\fP"
|
|
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\f(BIsuccess \fP
|
|
.TP
|
|
\f(BIrecoverable_rejection \fP
|
|
.TP
|
|
\f(BIfatal_failure \fP
|
|
.SS "enum class \fBserif::solver::continuation::ControllerStatus\fP\fR [strong]\fP"
|
|
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\f(BIready \fP
|
|
.TP
|
|
\f(BIpending \fP
|
|
.TP
|
|
\f(BIcomplete \fP
|
|
.TP
|
|
\f(BIattempt_limit \fP
|
|
.TP
|
|
\f(BIno_progress \fP
|
|
.TP
|
|
\f(BIfatal_failure \fP
|
|
.SS "enum class \fBserif::solver::continuation::CoordinateOrder\fP\fR [strong]\fP"
|
|
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\f(BIautomatic \fP
|
|
.TP
|
|
\f(BIpreferred \fP
|
|
.TP
|
|
\f(BIstrict \fP
|
|
.SS "enum class \fBserif::solver::continuation::StageDisposition\fP\fR [strong]\fP"
|
|
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\f(BIconverged \fP
|
|
.TP
|
|
\f(BInot_converged \fP
|
|
.TP
|
|
\f(BIinvalid_model \fP
|
|
.SS "enum class \fBserif::solver::continuation::Status\fP\fR [strong]\fP"
|
|
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\f(BItarget_reached \fP
|
|
.TP
|
|
\f(BIstarting_star_failed \fP
|
|
.TP
|
|
\f(BIattempt_limit \fP
|
|
.TP
|
|
\f(BIwork_limit \fP
|
|
.TP
|
|
\f(BIno_progress \fP
|
|
.TP
|
|
\f(BIinvalid_model \fP
|
|
.SH "Function Documentation"
|
|
.PP
|
|
.SS "template<CoordinateValue Value> double serif::solver::continuation::coordinate_value (Value value)\fR [nodiscard]\fP, \fR [constexpr]\fP, \fR [noexcept]\fP"
|
|
|
|
.PP
|
|
Convert physical units only at the coordinate-controller boundary\&.
|
|
.SS "\fBSolverOptions\fP serif::solver::continuation::default_solver_options ()\fR [inline]\fP, \fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Continuation uses one absolute qualification threshold across all family members\&.
|
|
.SS "template<PhysicalParameter\&.\&.\&. Parameters> auto serif::solver::continuation::depends_on (Parameters\&.\&.\&. )\fR [nodiscard]\fP, \fR [constexpr]\fP, \fR [noexcept]\fP"
|
|
|
|
.PP
|
|
Name only independent physical inputs to a dependent law\&.
|
|
.SS "template<typename Definition, CoordinateValue\&.\&.\&. Values> auto serif::solver::continuation::identified_equations (Definition definition, Values\&.\&.\&. values)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Declare every fixed physical constant captured by a deferred equation definition\&.
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
Include all captured physical inputs, such as G and surface pressure\&. Values read from the supplied model belong to its specification identity already\&. The declaration is a user contract: C++ cannot inspect arbitrary captures or prove that a callback uses only these inputs\&. Move-only definitions remain supported with an explicit equation factory when binding a family\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "template<PhysicalParameter\&.\&.\&. Parameters>
|
|
.br
|
|
requires (sizeof\&.\&.\&.(Parameters) > 0) && utils::dependencies::IsKeyList<\fBParameterList\fP<Parameters\&.\&.\&.>>auto serif::solver::continuation::in (Parameters\&.\&.\&. )\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Select independent physical coordinates with duplicate detection at compile time\&.
|
|
.SS "template<PhysicalParameter Output, PhysicalParameter\&.\&.\&. Inputs, typename Function>
|
|
.br
|
|
requires utils::dependencies::IsKeyList<\fBParameterList\fP<Inputs\&.\&.\&.>> && std::invocable<const std::remove_cvref_t<Function>&, typename Inputs::Value\&.\&.\&.> && std::same_as<std::remove_cvref_t<std::invoke_result_t<const std::remove_cvref_t<Function>&, typename Inputs::Value\&.\&.\&.>>, typename Output::Value>auto serif::solver::continuation::law (Output , \fBParameterList\fP< Inputs\&.\&.\&. > , Function && function)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Own a typed law, including move-only captures; its inputs are selected coordinates rather than other laws\&.
|
|
.SS "template<typename \fBFamily\fP, typename\&.\&.\&. Settings>
|
|
.br
|
|
requires (requires(const Settings& setting, \fBOptions\fP<\fBFamily\fP>& options) { setting\&.apply(options); } && \&.\&.\&.)auto serif::solver::continuation::make_options (const \fBFamily\fP & family, const Settings &\&.\&.\&. settings)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Resolve physical settings from family defaults before any corrector runs\&.
|
|
.SS "template<std::size_t Count> auto serif::solver::continuation::numerics (\fBCoordinateOptions\fP< Count > options)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Expose advanced numerical coordinate stepping without mixing it into physical prescriptions\&.
|
|
.SS "template<PhysicalParameter\&.\&.\&. Parameters>
|
|
.br
|
|
requires (sizeof\&.\&.\&.(Parameters) > 0) && utils::dependencies::IsKeyList<\fBParameterList\fP<Parameters\&.\&.\&.>>auto serif::solver::continuation::prefer (Parameters\&.\&.\&. )\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Try these physical coordinates first, allowing blocked coordinates to yield\&.
|
|
.SS "auto serif::solver::continuation::preserve_pressure_at_reference_density (\fBdimensions::DensityValue\fP density)\fR [inline]\fP, \fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Choose a pressure-preserving physical EOS family, independently of numerical normalization\&.
|
|
.SS "template<typename \fBFamily\fP, typename Model, typename State, typename Corrector> auto serif::solver::continuation::run (const \fBFamily\fP & family, const \fBStartingStar\fP< Model, State > & initial, Corrector && correct, \fBOptions\fP< \fBFamily\fP > options, double absolute_tolerance)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Qualify a supplied star afresh after checking every physical family input\&.
|
|
.SS "template<typename \fBFamily\fP, typename State, typename Corrector> auto serif::solver::continuation::run (const \fBFamily\fP & family, const State & initial_state, Corrector && correct, \fBOptions\fP< \fBFamily\fP > options, double absolute_tolerance)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Follow a physical family using owning correction results and physical state transfer\&.
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIcorrect\fP A callable accepting a fresh model, a physical state value, and \fBCorrectionControls\fP\&. Its result must expose \fBconverged()\fP, has_state(), state(), diagnostics()\&.attempted_iterations/final_residual_norm, and message()\&.
|
|
.RE
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
The corrector must honor the supplied work cap and one fixed positive absolute tolerance\&. Failed states are never transferred into retries\&. Numerical nonconvergence is recoverable; malformed family models stop the path\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "template<PhysicalParameter\&.\&.\&. Parameters>
|
|
.br
|
|
requires (sizeof\&.\&.\&.(Parameters) > 0) && utils::dependencies::IsKeyList<\fBParameterList\fP<Parameters\&.\&.\&.>>auto serif::solver::continuation::stages (Parameters\&.\&.\&. )\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Complete each physical stage before attempting the next\&.
|
|
.SS "template<PhysicalParameter Parameter> auto serif::solver::continuation::starting_at (Parameter , typename Parameter::Value value)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Select a physical starting value with the parameter's required units\&.
|
|
.SH "Author"
|
|
.PP
|
|
Generated automatically by Doxygen for SERiF from the source code\&.
|