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\&.
|