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

.in +1c
.ti -1c
.RI "namespace \fBadmissibility\fP"
.br
.ti -1c
.RI "namespace \fBbackend\fP"
.br
.ti -1c
.RI "namespace \fBcontinuation\fP"
.br
.ti -1c
.RI "namespace \fBdetail\fP"
.br
.ti -1c
.RI "namespace \fBlinear\fP"
.br
.ti -1c
.RI "namespace \fBnormalization\fP"
.br
.ti -1c
.RI "namespace \fBpreconditioner\fP"
.br
.ti -1c
.RI "namespace \fBseed\fP"
.br
.in -1c
.SS "Classes"

.in +1c
.ti -1c
.RI "struct \fBBacktracking\fP"
.br
.RI "Shorten a \fBNewton\fP step until the complete residual merit decreases sufficiently\&. "
.ti -1c
.RI "struct \fBDirectionAssessment\fP"
.br
.RI "A modified direction must report whether it is usable and any measured merit slope\&. "
.ti -1c
.RI "struct \fBMetricEvaluation\fP"
.br
.RI "Separate the convergence norm from the line-search merit for custom metrics\&. "
.ti -1c
.RI "struct \fBNewton\fP"
.br
.RI "Accuracy and work limits for finding one equilibrium star\&. "
.ti -1c
.RI "struct \fBNewtonCheckpoint\fP"
.br
.RI "Own the accepted physical star and the small amount of \fBNewton\fP history needed to continue it\&. "
.ti -1c
.RI "struct \fBNewtonProgress\fP"
.br
.RI "Numerical continuation data at one accepted \fBNewton\fP boundary\&. "
.ti -1c
.RI "struct \fBNoModel\fP"
.br
.RI "Marker for algebraic tests and custom problems without a stellar description\&. "
.ti -1c
.RI "struct \fBNoObserver\fP"
.br
.RI "Disable observation without introducing runtime callback allocation\&. "
.ti -1c
.RI "struct \fBNormalizedResidualMetric\fP"
.br
.RI "Use the Euclidean norm of SERiF's normalized residual and half its square\&. "
.ti -1c
.RI "struct \fBSolveDiagnostics\fP"
.br
.RI "Bounded work totals; accepted physical snapshots are stored separately from diagnostics\&. "
.ti -1c
.RI "struct \fBSolveEvent\fP"
.br
.RI "Small event record suitable for logging without retaining every iterate\&. "
.ti -1c
.RI "class \fBSolveResult\fP"
.br
.RI "Own the last accepted physical state, matching frozen system, and descriptive model\&. "
.ti -1c
.RI "struct \fBSolverOptions\fP"
.br
.RI "Select numerical policies while keeping equilibrium physics in the model\&. "
.ti -1c
.RI "struct \fBSolveTiming\fP"
.br
.RI "Optional elapsed wall time, kept separately from numerical restart history\&. "
.ti -1c
.RI "struct \fBStandardNewton\fP"
.br
.RI "Ordinary \fBNewton\fP supplies every strategy phase; custom policies may replace individual phases explicitly\&. "
.ti -1c
.RI "class \fBTimedObserver\fP"
.br
.RI "Measure solves explicitly while retaining an ordinary progress or stop callback\&. "
.ti -1c
.RI "struct \fBTrialAssessment\fP"
.br
.RI "A numerical policy explicitly accepts its work or explains why this candidate must be rejected\&. "
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "using \fBVolumeOptions\fP = \fBoperators::backend::mfem::VolumeOptions\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum class \fBSolveStatus\fP { \fBconverged\fP, \fBinitial_state_rejected\fP, \fBinvalid_metric\fP, \fBpreparation_failure\fP, \fBlinear_solve_failure\fP, \fBglobalization_failure\fP, \fBmaximum_iterations\fP, \fBstopped\fP }"
.br
.RI "Numerical termination; invalid configuration and user callback errors remain exceptions\&. "
.ti -1c
.RI "enum class \fBEventKind\fP { \fBinitial\fP, \fBbefore_iteration\fP, \fBtrial_rejected\fP, \fBbefore_accept\fP, \fBaccepted\fP, \fBfinished\fP, \fBresumed\fP }"
.br
.RI "Events expose immutable accepted/trial snapshots; callbacks never decide acceptance\&. "
.ti -1c
.RI "enum class \fBSolveControl\fP { \fBcontinue_solve\fP, \fBstop\fP }"
.br
.RI "A stop request is remembered until the next initial, resumed or accepted Newton boundary\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "template<typename Family, typename Factory, typename State, typename Options = SolverOptions<>> 
.br
requires std::copy_constructible<Options>auto \fBcontinue_equilibrium\fP (const Family &family, Factory configure, const State &initial_state, \fBcontinuation::Options\fP< Family > continuation_options, Options solver_options=\fBcontinuation::default_solver_options\fP())"
.br
.RI "Continue moving-star equilibria through an explicitly declared physical family\&. "
.ti -1c
.RI "template<typename Family, typename Factory, typename State> auto \fBcontinue_equilibrium\fP (const Family &family, Factory configure, const State &initial_state)"
.br
.RI "Start with the family's physics-owned default coordinates and bounded fallback route\&. "
.ti -1c
.RI "template<typename Family, typename Factory, typename State, typename Options = SolverOptions<>> 
.br
requires std::copy_constructible<Options>auto \fBcontinue_equilibrium\fP (const Family &family, Factory configure, const State &initial_state, const \fBVector\fP &displacement, \fBcontinuation::Options\fP< Family > continuation_options, Options solver_options=\fBcontinuation::default_solver_options\fP())"
.br
.RI "Continue a fixed-geometry model while preserving its prescribed displacement\&. "
.ti -1c
.RI "template<typename Family, typename Factory, typename State> auto \fBcontinue_equilibrium\fP (const Family &family, Factory configure, const State &initial_state, const \fBVector\fP &displacement)"
.br
.RI "Use the same default route and absolute qualification tolerance for fixed geometry\&. "
.ti -1c
.RI "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>auto \fBsolve_equilibrium\fP (Configuration configuration, \fBmodel::StellarState\fP< Layout > initial_state, Options options={}, Observer observer={}, \fBVolumeOptions\fP volume_options={}, Inputs prescribed=Inputs{}, ObserverFactory observer_factory={})"
.br
.RI "Solve a moving star from an owning physical initial state\&. "
.ti -1c
.RI "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires (!utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>)auto \fBsolve_equilibrium\fP (Configuration configuration, \fBmodel::StellarState\fP< Layout > initial_state, const \fBVector\fP &displacement, Options options={}, Observer observer={}, \fBVolumeOptions\fP volume_options={}, Inputs prescribed=Inputs{}, ObserverFactory observer_factory={})"
.br
.RI "Solve a fixed-geometry model with prescribed displacement outside its unknown vector\&. "
.ti -1c
.RI "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>auto \fBresume_equilibrium\fP (Configuration configuration, \fBNewtonCheckpoint\fP< \fBmodel::StellarState\fP< Layout > > checkpoint, Options options={}, Observer observer={}, \fBVolumeOptions\fP volume_options={}, Inputs prescribed=Inputs{}, ObserverFactory observer_factory={})"
.br
.RI "Continue a moving-star checkpoint using reconstructed physical and numerical configuration\&. "
.ti -1c
.RI "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires (!utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>)auto \fBresume_equilibrium\fP (Configuration configuration, \fBNewtonCheckpoint\fP< \fBmodel::StellarState\fP< Layout > > checkpoint, const \fBVector\fP &displacement, Options options={}, Observer observer={}, \fBVolumeOptions\fP volume_options={}, Inputs prescribed=Inputs{}, ObserverFactory observer_factory={})"
.br
.RI "Continue a fixed-geometry checkpoint with its separately restored prescribed displacement\&. "
.ti -1c
.RI "template<typename Problem, typename State, typename Options = SolverOptions<>, typename Observer = NoObserver> 
.br
requires detail::NewtonStrategyFor<Problem, State, Options>auto \fBsolve_newton\fP (Problem &problem, State initial_state, Options options={}, Observer observer={})"
.br
.RI "Solve a custom numerical problem using its native \fBVector\fP, evaluate, prepare and solve_linear operations\&. "
.ti -1c
.RI "template<typename Problem, typename State, typename Options = SolverOptions<>, typename Observer = NoObserver> 
.br
requires detail::NewtonStrategyFor<Problem, State, Options>auto \fBresume_newton\fP (Problem &problem, \fBNewtonCheckpoint\fP< State > checkpoint, Options options={}, Observer observer={})"
.br
.RI "Resume the original convergence reference, correction reuse, and cumulative work budget\&. "
.ti -1c
.RI "double \fBnext_backtracking_step\fP (double rejected_step, double accepted_determinant, double rejected_determinant, bool inverted, const \fBBacktracking\fP &options) noexcept"
.br
.RI "Skip only existing backtracking rungs when an inverted trial gives a finite boundary estimate\&. "
.ti -1c
.RI "std::optional< std::string > \fBvalidate_newton_progress\fP (const \fBNewtonProgress\fP &progress, const std::size_t state_size)"
.br
.RI "Reject incomplete or inconsistent imported history before preparing any runtime operators\&. "
.in -1c
.SH "Typedef Documentation"
.PP 
.SS "using \fBserif::solver::VolumeOptions\fP = \fBoperators::backend::mfem::VolumeOptions\fP"

.SH "Enumeration Type Documentation"
.PP 
.SS "enum class \fBserif::solver::EventKind\fP\fR [strong]\fP"

.PP
Events expose immutable accepted/trial snapshots; callbacks never decide acceptance\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIinitial \fP
.TP
\f(BIbefore_iteration \fP
.TP
\f(BItrial_rejected \fP
.TP
\f(BIbefore_accept \fP
.TP
\f(BIaccepted \fP
.TP
\f(BIfinished \fP
.TP
\f(BIresumed \fP
.SS "enum class \fBserif::solver::SolveControl\fP\fR [strong]\fP"

.PP
A stop request is remembered until the next initial, resumed or accepted \fBNewton\fP boundary\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIcontinue_solve \fP
.TP
\f(BIstop \fP
.SS "enum class \fBserif::solver::SolveStatus\fP\fR [strong]\fP"

.PP
Numerical termination; invalid configuration and user callback errors remain exceptions\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIconverged \fP
.TP
\f(BIinitial_state_rejected \fP
.TP
\f(BIinvalid_metric \fP
.TP
\f(BIpreparation_failure \fP
.TP
\f(BIlinear_solve_failure \fP
.TP
\f(BIglobalization_failure \fP
.TP
\f(BImaximum_iterations \fP
.TP
\f(BIstopped \fP
.SH "Function Documentation"
.PP 
.SS "template<typename Family, typename Factory, typename State> auto serif::solver::continue_equilibrium (const Family & family, Factory configure, const State & initial_state)\fR [nodiscard]\fP"

.PP
Start with the family's physics-owned default coordinates and bounded fallback route\&. 
.SS "template<typename Family, typename Factory, typename State> auto serif::solver::continue_equilibrium (const Family & family, Factory configure, const State & initial_state, const \fBVector\fP & displacement)\fR [nodiscard]\fP"

.PP
Use the same default route and absolute qualification tolerance for fixed geometry\&. 
.SS "template<typename Family, typename Factory, typename State, typename Options = SolverOptions<>> 
.br
requires std::copy_constructible<Options>auto serif::solver::continue_equilibrium (const Family & family, Factory configure, const State & initial_state, const \fBVector\fP & displacement, \fBcontinuation::Options\fP< Family > continuation_options, Options solver_options = \fR\fBcontinuation::default_solver_options\fP()\fP)\fR [nodiscard]\fP"

.PP
Continue a fixed-geometry model while preserving its prescribed displacement\&. 
.SS "template<typename Family, typename Factory, typename State, typename Options = SolverOptions<>> 
.br
requires std::copy_constructible<Options>auto serif::solver::continue_equilibrium (const Family & family, Factory configure, const State & initial_state, \fBcontinuation::Options\fP< Family > continuation_options, Options solver_options = \fR\fBcontinuation::default_solver_options\fP()\fP)\fR [nodiscard]\fP"

.PP
Continue moving-star equilibria through an explicitly declared physical family\&. 
.PP
\fBParameters\fP
.RS 4
\fIconfigure\fP Own or borrow a callable that returns a configured discretization for its supplied model\&. It must preserve the physical coordinate layout and finite-element reference of transferred states; fresh evaluators are implicit\&. 
.RE
.PP
\fBNote\fP
.RS 4
The explicit factory supports move-only resource policies without inventing a mutable clone/context hierarchy\&. 
.RE
.PP

.SS "double serif::solver::next_backtracking_step (double rejected_step, double accepted_determinant, double rejected_determinant, bool inverted, const \fBBacktracking\fP & options)\fR [nodiscard]\fP, \fR [noexcept]\fP"

.PP
Skip only existing backtracking rungs when an inverted trial gives a finite boundary estimate\&. 
.SS "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires (!utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>)auto serif::solver::resume_equilibrium (Configuration configuration, \fBNewtonCheckpoint\fP< \fBmodel::StellarState\fP< Layout > > checkpoint, const \fBVector\fP & displacement, Options options = \fR{}\fP, Observer observer = \fR{}\fP, \fBVolumeOptions\fP volume_options = \fR{}\fP, Inputs prescribed = \fRInputs{}\fP, ObserverFactory observer_factory = \fR{}\fP)\fR [nodiscard]\fP"

.PP
Continue a fixed-geometry checkpoint with its separately restored prescribed displacement\&. 
.PP
\fBNote\fP
.RS 4
The optional final observer factory measures graph work separately from physics and solver history\&. It is rebuilt for this solve and is not stored in the checkpoint\&. 
.RE
.PP

.SS "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>auto serif::solver::resume_equilibrium (Configuration configuration, \fBNewtonCheckpoint\fP< \fBmodel::StellarState\fP< Layout > > checkpoint, Options options = \fR{}\fP, Observer observer = \fR{}\fP, \fBVolumeOptions\fP volume_options = \fR{}\fP, Inputs prescribed = \fRInputs{}\fP, ObserverFactory observer_factory = \fR{}\fP)\fR [nodiscard]\fP"

.PP
Continue a moving-star checkpoint using reconstructed physical and numerical configuration\&. 
.PP
\fBNote\fP
.RS 4
The optional final observer factory measures graph work separately from physics and solver history\&. It is rebuilt for this solve and is not stored in the checkpoint\&. 
.RE
.PP

.SS "template<typename Problem, typename State, typename Options = SolverOptions<>, typename Observer = NoObserver> 
.br
requires detail::NewtonStrategyFor<Problem, State, Options>auto serif::solver::resume_newton (Problem & problem, \fBNewtonCheckpoint\fP< State > checkpoint, Options options = \fR{}\fP, Observer observer = \fR{}\fP)\fR [nodiscard]\fP"

.PP
Resume the original convergence reference, correction reuse, and cumulative work budget\&. 
.SS "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires (!utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>)auto serif::solver::solve_equilibrium (Configuration configuration, \fBmodel::StellarState\fP< Layout > initial_state, const \fBVector\fP & displacement, Options options = \fR{}\fP, Observer observer = \fR{}\fP, \fBVolumeOptions\fP volume_options = \fR{}\fP, Inputs prescribed = \fRInputs{}\fP, ObserverFactory observer_factory = \fR{}\fP)\fR [nodiscard]\fP"

.PP
Solve a fixed-geometry model with prescribed displacement outside its unknown vector\&. 
.PP
\fBNote\fP
.RS 4
The optional final observer factory measures graph work separately from physics and solver history\&. It is rebuilt for this solve and is not stored in the checkpoint\&. 
.RE
.PP

.SS "template<typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>, typename ObserverFactory = utils::dependencies::NoGraphObservers> 
.br
requires utils::dependencies::ContainsKey<\fBdiscretization::blocks::surface_deformation::coefficients\fP, typename Layout::Values>auto serif::solver::solve_equilibrium (Configuration configuration, \fBmodel::StellarState\fP< Layout > initial_state, Options options = \fR{}\fP, Observer observer = \fR{}\fP, \fBVolumeOptions\fP volume_options = \fR{}\fP, Inputs prescribed = \fRInputs{}\fP, ObserverFactory observer_factory = \fR{}\fP)\fR [nodiscard]\fP"

.PP
Solve a moving star from an owning physical initial state\&. 
.PP
\fBNote\fP
.RS 4
The model defines equilibrium; its evaluator and reusable cache are constructed internally\&. The returned result owns the last accepted physical star even when the solve does not converge\&. Initialize the backend's MPI runtime before using a recipe containing Hypre AMG\&. The optional final observer factory measures graph work separately from physics and solver history\&. 
.RE
.PP

.SS "template<typename Problem, typename State, typename Options = SolverOptions<>, typename Observer = NoObserver> 
.br
requires detail::NewtonStrategyFor<Problem, State, Options>auto serif::solver::solve_newton (Problem & problem, State initial_state, Options options = \fR{}\fP, Observer observer = \fR{}\fP)\fR [nodiscard]\fP"

.PP
Solve a custom numerical problem using its native \fBVector\fP, evaluate, prepare and solve_linear operations\&. 
.PP
\fBNote\fP
.RS 4
Strategies here are executable numerical methods; solve_equilibrium uses the same strategies\&. 
.RE
.PP

.SS "std::optional< std::string > serif::solver::validate_newton_progress (const \fBNewtonProgress\fP & progress, const std::size_t state_size)\fR [inline]\fP, \fR [nodiscard]\fP"

.PP
Reject incomplete or inconsistent imported history before preparing any runtime operators\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for SERiF from the source code\&.