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)
154 lines
8.3 KiB
Groff
154 lines
8.3 KiB
Groff
.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\&.
|