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

154 lines
8.3 KiB
Groff
Raw Normal View History

.TH "serif::solver::detail" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::solver::detail
.SH SYNOPSIS
.br
.PP
.SS "Classes"
.in +1c
.ti -1c
.RI "struct \fBInitialEvaluation\fP"
.br
.RI "Keep a freshly qualified metric beside the exact system from which it was measured\&. "
.ti -1c
.RI "struct \fBNewtonFailure\fP"
.br
.RI "Explain why a candidate cannot provide a usable nonlinear metric\&. "
.ti -1c
.RI "struct \fBQualifiedStep\fP"
.br
.RI "Own a qualified trial; a terminal root deliberately has no prepared inverse\&. "
.ti -1c
.RI "class \fBSolveObservation\fP"
.br
.RI "Adapt callbacks and latch requests; only the \fBNewton\fP driver decides when stopping is safe\&. "
.in -1c
.SS "Concepts"
.in +1c
.ti -1c
.RI "concept \fBNewtonStrategyFor\fP"
.br
.RI "A custom method must supply the exact correction contract; malformed overrides never select a fallback\&. "
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "template<typename Problem, typename State, typename Options, typename Observer> auto \fBrun_newton\fP (Problem &problem, State initial_state, Options options, Observer observer, std::optional< \fBNewtonProgress\fP > restart)"
.br
.RI "Find equilibrium while retaining the last fully qualified physical state\&. "
.ti -1c
.RI "std::optional< std::string > \fBpreparation_rejection\fP (const auto &problem, const auto &evaluation)"
.br
.RI "Preserve numerical preparation failures while propagating invalid physical configurations\&. "
.ti -1c
.RI "std::expected< \fBMetricEvaluation\fP, \fBNewtonFailure\fP > \fBqualify_candidate\fP (auto &problem, const auto &state, const auto &evaluation, auto &metric_function, auto &strategy, \fBTrialAssessment\fP assessment={})"
.br
.RI "Qualify one already evaluated candidate through the same physical and metric gates everywhere\&. "
.ti -1c
.RI "bool \fBfinite_correction\fP (std::span< const double > correction, const int expected_size)"
.br
.RI "Every custom backend must preserve the correction dimensions and finite coefficients\&. "
.ti -1c
.RI "void \fBvalidate_start\fP (const auto &options, const std::optional< \fBNewtonProgress\fP > &restart, std::size_t size)"
.br
.RI "Validate controls and restored history before any physical preparation\&. "
.ti -1c
.RI "template<typename Problem> std::expected< \fBInitialEvaluation\fP< typename Problem::System >, \fBNewtonFailure\fP > \fBevaluate_start\fP (Problem &problem, auto &state, auto &options, const std::optional< \fBNewtonProgress\fP > &restart, \fBSolveDiagnostics\fP &diagnostics)"
.br
.RI "Qualify the initial state and verify a restart against its original convergence reference\&. "
.ti -1c
.RI "std::expected< \fBDirectionAssessment\fP, \fBNewtonFailure\fP > \fBcompute_direction\fP (auto &problem, const auto &\fBaccepted\fP, const auto &prepared, auto &options, \fBSolveDiagnostics\fP &diagnostics, auto &rhs, auto &correction, std::span< double > physical_direction)"
.br
.RI "Solve and qualify a normalized correction before exposing its physical direction to backtracking\&. "
.ti -1c
.RI "template<typename Problem, typename State, typename System, typename Model> auto \fBfind_acceptable_step\fP (Problem &problem, const \fBSolveResult\fP< State, System, Model > &\fBaccepted\fP, \fBMetricEvaluation\fP accepted_metric, const auto &correction, std::span< const double > physical_direction, const \fBDirectionAssessment\fP &direction, double step, auto &options, \fBSolveDiagnostics\fP &diagnostics, auto &observation)"
.br
.RI "Find a safe, sufficiently decreasing candidate without changing the accepted state\&. "
.ti -1c
.RI "void \fBsave_progress\fP (auto &result, auto &options, \fBSolveDiagnostics\fP &diagnostics, \fBMetricEvaluation\fP metric, std::span< const double > correction, double next_step)"
.br
.RI "Snapshot only fully committed numerical history; reporting has no influence on restart\&. "
.in -1c
.SS "Variables"
.in +1c
.ti -1c
.RI "template<typename Options> constexpr bool \fBcheckpointable_options\fP"
.br
.RI "Only built-in stateless numerical policies currently have a complete restart contract\&. "
.in -1c
.SH "Function Documentation"
.PP
.SS "std::expected< \fBDirectionAssessment\fP, \fBNewtonFailure\fP > serif::solver::detail::compute_direction (auto & problem, const auto & accepted, const auto & prepared, auto & options, \fBSolveDiagnostics\fP & diagnostics, auto & rhs, auto & correction, std::span< double > physical_direction)\fR [nodiscard]\fP"
.PP
Solve and qualify a normalized correction before exposing its physical direction to backtracking\&.
.SS "template<typename Problem> std::expected< \fBInitialEvaluation\fP< typename Problem::System >, \fBNewtonFailure\fP > serif::solver::detail::evaluate_start (Problem & problem, auto & state, auto & options, const std::optional< \fBNewtonProgress\fP > & restart, \fBSolveDiagnostics\fP & diagnostics)\fR [nodiscard]\fP"
.PP
Qualify the initial state and verify a restart against its original convergence reference\&.
.SS "template<typename Problem, typename State, typename System, typename Model> auto serif::solver::detail::find_acceptable_step (Problem & problem, const \fBSolveResult\fP< State, System, Model > & accepted, \fBMetricEvaluation\fP accepted_metric, const auto & correction, std::span< const double > physical_direction, const \fBDirectionAssessment\fP & direction, double step, auto & options, \fBSolveDiagnostics\fP & diagnostics, auto & observation)\fR [nodiscard]\fP"
.PP
Find a safe, sufficiently decreasing candidate without changing the accepted state\&.
.PP
\fBNote\fP
.RS 4
A nonterminal candidate must prepare its inverse before publication\&. Preparation failure terminates this attempt; the caller still owns the previously accepted physical star\&.
.RE
.PP
.SS "bool serif::solver::detail::finite_correction (std::span< const double > correction, const int expected_size)\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Every custom backend must preserve the correction dimensions and finite coefficients\&.
.SS "std::optional< std::string > serif::solver::detail::preparation_rejection (const auto & problem, const auto & evaluation)\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Preserve numerical preparation failures while propagating invalid physical configurations\&.
.SS "std::expected< \fBMetricEvaluation\fP, \fBNewtonFailure\fP > serif::solver::detail::qualify_candidate (auto & problem, const auto & state, const auto & evaluation, auto & metric_function, auto & strategy, \fBTrialAssessment\fP assessment = \fR{}\fP)\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Qualify one already evaluated candidate through the same physical and metric gates everywhere\&.
.SS "template<typename Problem, typename State, typename Options, typename Observer> auto serif::solver::detail::run_newton (Problem & problem, State initial_state, Options options, Observer observer, std::optional< \fBNewtonProgress\fP > restart)\fR [nodiscard]\fP"
.PP
Find equilibrium while retaining the last fully qualified physical state\&.
.PP
\fBNote\fP
.RS 4
Preparation belongs to the problem; this driver alone publishes accepted steps\&. Scratch vectors use the problem's native storage\&. Timing belongs entirely to observers\&.
.RE
.PP
.SS "void serif::solver::detail::save_progress (auto & result, auto & options, \fBSolveDiagnostics\fP & diagnostics, \fBMetricEvaluation\fP metric, std::span< const double > correction, double next_step)"
.PP
Snapshot only fully committed numerical history; reporting has no influence on restart\&.
.SS "void serif::solver::detail::validate_start (const auto & options, const std::optional< \fBNewtonProgress\fP > & restart, std::size_t size)"
.PP
Validate controls and restored history before any physical preparation\&.
.SH "Variable Documentation"
.PP
.SS "template<typename Options> bool serif::solver::detail::checkpointable_options\fR [inline]\fP, \fR [constexpr]\fP"
\fBInitial value:\fP
.nf
=
std::same_as<std::remove_cvref_t<decltype(std::declval<Options>()\&.strategies)>, StandardNewton> &&
std::same_as<std::remove_cvref_t<decltype(std::declval<Options>()\&.metric)>, NormalizedResidualMetric> &&
std::same_as<std::remove_cvref_t<decltype(std::declval<Options>()\&.linear_solver)>, linear::FGMRES>
.PP
.fi
.PP
Only built-in stateless numerical policies currently have a complete restart contract\&.
.SH "Author"
.PP
Generated automatically by Doxygen for SERiF from the source code\&.