Files
MeanField_SERiF/docs/latex/namespaceserif_1_1solver_1_1detail.tex
Emily Boudreaux 6b57738330 docs(docs): built docs
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)
2026-11-09 14:09:44 -05:00

169 lines
19 KiB
TeX

\doxysection{serif\+::solver\+::detail Namespace Reference}
\hypertarget{namespaceserif_1_1solver_1_1detail}{}\label{namespaceserif_1_1solver_1_1detail}\index{serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection*{Classes}
\begin{DoxyCompactItemize}
\item
struct \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_initial_evaluation}{Initial\+Evaluation}}
\begin{DoxyCompactList}\small\item\em Keep a freshly qualified metric beside the exact system from which it was measured. \end{DoxyCompactList}\item
struct \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_newton_failure}{Newton\+Failure}}
\begin{DoxyCompactList}\small\item\em Explain why a candidate cannot provide a usable nonlinear metric. \end{DoxyCompactList}\item
struct \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_qualified_step}{Qualified\+Step}}
\begin{DoxyCompactList}\small\item\em Own a qualified trial; a terminal root deliberately has no prepared inverse. \end{DoxyCompactList}\item
class \mbox{\hyperlink{classserif_1_1solver_1_1detail_1_1_solve_observation}{Solve\+Observation}}
\begin{DoxyCompactList}\small\item\em Adapt callbacks and latch requests; only the \doxylink{structserif_1_1solver_1_1_newton}{Newton} driver decides when stopping is safe. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsubsection*{Concepts}
\begin{DoxyCompactItemize}
\item
concept \mbox{\hyperlink{conceptserif_1_1solver_1_1detail_1_1_newton_strategy_for}{Newton\+Strategy\+For}}
\begin{DoxyCompactList}\small\item\em A custom method must supply the exact correction contract; malformed overrides never select a fallback. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsubsection*{Functions}
\begin{DoxyCompactItemize}
\item
{\footnotesize template$<$typename Problem, typename State, typename Options, typename Observer$>$ }\\auto \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_ad84838af2c61fd8a7ff1143ed6e30e07}{run\+\_\+newton}} (Problem \&problem, State initial\+\_\+state, Options options, Observer observer, std\+::optional$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_newton_progress}{Newton\+Progress}} $>$ restart)
\begin{DoxyCompactList}\small\item\em Find equilibrium while retaining the last fully qualified physical state. \end{DoxyCompactList}\item
std\+::optional$<$ std\+::string $>$ \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_abcb4ab5dca0460589f2989c776a641d7}{preparation\+\_\+rejection}} (const auto \&problem, const auto \&evaluation)
\begin{DoxyCompactList}\small\item\em Preserve numerical preparation failures while propagating invalid physical configurations. \end{DoxyCompactList}\item
std\+::expected$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_metric_evaluation}{Metric\+Evaluation}}, \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_newton_failure}{Newton\+Failure}} $>$ \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_a20193e65f854a97472b6a4f1602798e8}{qualify\+\_\+candidate}} (auto \&problem, const auto \&state, const auto \&evaluation, auto \&metric\+\_\+function, auto \&strategy, \mbox{\hyperlink{structserif_1_1solver_1_1_trial_assessment}{Trial\+Assessment}} assessment=\{\})
\begin{DoxyCompactList}\small\item\em Qualify one already evaluated candidate through the same physical and metric gates everywhere. \end{DoxyCompactList}\item
bool \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_af66d3dcd2f2fc1b4e4858dcd4e23be8f}{finite\+\_\+correction}} (std\+::span$<$ const double $>$ correction, const int expected\+\_\+size)
\begin{DoxyCompactList}\small\item\em Every custom backend must preserve the correction dimensions and finite coefficients. \end{DoxyCompactList}\item
void \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_a07717377a241ffd25e63aa977ff4f554}{validate\+\_\+start}} (const auto \&options, const std\+::optional$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_newton_progress}{Newton\+Progress}} $>$ \&restart, std\+::size\+\_\+t size)
\begin{DoxyCompactList}\small\item\em Validate controls and restored history before any physical preparation. \end{DoxyCompactList}\item
{\footnotesize template$<$typename Problem$>$ }\\std\+::expected$<$ \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_initial_evaluation}{Initial\+Evaluation}}$<$ typename Problem\+::\+System $>$, \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_newton_failure}{Newton\+Failure}} $>$ \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_a6791c39e3a55c271764d9926c97956e0}{evaluate\+\_\+start}} (Problem \&problem, auto \&state, auto \&options, const std\+::optional$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_newton_progress}{Newton\+Progress}} $>$ \&restart, \mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&diagnostics)
\begin{DoxyCompactList}\small\item\em Qualify the initial state and verify a restart against its original convergence reference. \end{DoxyCompactList}\item
std\+::expected$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_direction_assessment}{Direction\+Assessment}}, \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_newton_failure}{Newton\+Failure}} $>$ \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_a5961bb80a48f170cb4e90a77dcb039ec}{compute\+\_\+direction}} (auto \&problem, const auto \&\mbox{\hyperlink{namespaceserif_1_1solver_a6fa8bbc306fbf990b16ade9fb7771464a3e4d891a5df3d6d0d7dd9432a1bc6470}{accepted}}, const auto \&prepared, auto \&options, \mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&diagnostics, auto \&rhs, auto \&correction, std\+::span$<$ double $>$ physical\+\_\+direction)
\begin{DoxyCompactList}\small\item\em Solve and qualify a normalized correction before exposing its physical direction to backtracking. \end{DoxyCompactList}\item
{\footnotesize template$<$typename Problem, typename State, typename System, typename Model$>$ }\\auto \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_ad9c44d75fd77ec596f5d512dc3508bd1}{find\+\_\+acceptable\+\_\+step}} (Problem \&problem, const \mbox{\hyperlink{classserif_1_1solver_1_1_solve_result}{Solve\+Result}}$<$ State, System, Model $>$ \&\mbox{\hyperlink{namespaceserif_1_1solver_a6fa8bbc306fbf990b16ade9fb7771464a3e4d891a5df3d6d0d7dd9432a1bc6470}{accepted}}, \mbox{\hyperlink{structserif_1_1solver_1_1_metric_evaluation}{Metric\+Evaluation}} accepted\+\_\+metric, const auto \&correction, std\+::span$<$ const double $>$ physical\+\_\+direction, const \mbox{\hyperlink{structserif_1_1solver_1_1_direction_assessment}{Direction\+Assessment}} \&direction, double step, auto \&options, \mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&diagnostics, auto \&observation)
\begin{DoxyCompactList}\small\item\em Find a safe, sufficiently decreasing candidate without changing the accepted state. \end{DoxyCompactList}\item
void \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_a94057867583afc7737886a2cc9cb27d3}{save\+\_\+progress}} (auto \&result, auto \&options, \mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&diagnostics, \mbox{\hyperlink{structserif_1_1solver_1_1_metric_evaluation}{Metric\+Evaluation}} metric, std\+::span$<$ const double $>$ correction, double next\+\_\+step)
\begin{DoxyCompactList}\small\item\em Snapshot only fully committed numerical history; reporting has no influence on restart. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsubsection*{Variables}
\begin{DoxyCompactItemize}
\item
{\footnotesize template$<$typename Options$>$ }\\constexpr bool \mbox{\hyperlink{namespaceserif_1_1solver_1_1detail_aca34a8e5074029c302fd5d3fc9d35244}{checkpointable\+\_\+options}}
\begin{DoxyCompactList}\small\item\em Only built-\/in stateless numerical policies currently have a complete restart contract. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection{Function Documentation}
\Hypertarget{namespaceserif_1_1solver_1_1detail_a5961bb80a48f170cb4e90a77dcb039ec}\index{serif::solver::detail@{serif::solver::detail}!compute\_direction@{compute\_direction}}
\index{compute\_direction@{compute\_direction}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{compute\_direction()}{compute\_direction()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_a5961bb80a48f170cb4e90a77dcb039ec}
std\+::expected$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_direction_assessment}{Direction\+Assessment}}, \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_newton_failure}{Newton\+Failure}} $>$ serif\+::solver\+::detail\+::compute\+\_\+direction (\begin{DoxyParamCaption}\item[{auto \&}]{problem}{, }\item[{const auto \&}]{accepted}{, }\item[{const auto \&}]{prepared}{, }\item[{auto \&}]{options}{, }\item[{\mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&}]{diagnostics}{, }\item[{auto \&}]{rhs}{, }\item[{auto \&}]{correction}{, }\item[{std\+::span$<$ double $>$}]{physical\+\_\+direction}{}\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [nodiscard]}}
Solve and qualify a normalized correction before exposing its physical direction to backtracking.
\Hypertarget{namespaceserif_1_1solver_1_1detail_a6791c39e3a55c271764d9926c97956e0}\index{serif::solver::detail@{serif::solver::detail}!evaluate\_start@{evaluate\_start}}
\index{evaluate\_start@{evaluate\_start}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{evaluate\_start()}{evaluate\_start()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_a6791c39e3a55c271764d9926c97956e0}
template$<$typename Problem$>$ \\
std\+::expected$<$ \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_initial_evaluation}{Initial\+Evaluation}}$<$ typename Problem\+::\+System $>$, \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_newton_failure}{Newton\+Failure}} $>$ serif\+::solver\+::detail\+::evaluate\+\_\+start (\begin{DoxyParamCaption}\item[{Problem \&}]{problem}{, }\item[{auto \&}]{state}{, }\item[{auto \&}]{options}{, }\item[{const std\+::optional$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_newton_progress}{Newton\+Progress}} $>$ \&}]{restart}{, }\item[{\mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&}]{diagnostics}{}\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [nodiscard]}}
Qualify the initial state and verify a restart against its original convergence reference.
\Hypertarget{namespaceserif_1_1solver_1_1detail_ad9c44d75fd77ec596f5d512dc3508bd1}\index{serif::solver::detail@{serif::solver::detail}!find\_acceptable\_step@{find\_acceptable\_step}}
\index{find\_acceptable\_step@{find\_acceptable\_step}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{find\_acceptable\_step()}{find\_acceptable\_step()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_ad9c44d75fd77ec596f5d512dc3508bd1}
template$<$typename Problem, typename State, typename System, typename Model$>$ \\
auto serif\+::solver\+::detail\+::find\+\_\+acceptable\+\_\+step (\begin{DoxyParamCaption}\item[{Problem \&}]{problem}{, }\item[{const \mbox{\hyperlink{classserif_1_1solver_1_1_solve_result}{Solve\+Result}}$<$ State, System, Model $>$ \&}]{accepted}{, }\item[{\mbox{\hyperlink{structserif_1_1solver_1_1_metric_evaluation}{Metric\+Evaluation}}}]{accepted\+\_\+metric}{, }\item[{const auto \&}]{correction}{, }\item[{std\+::span$<$ const double $>$}]{physical\+\_\+direction}{, }\item[{const \mbox{\hyperlink{structserif_1_1solver_1_1_direction_assessment}{Direction\+Assessment}} \&}]{direction}{, }\item[{double}]{step}{, }\item[{auto \&}]{options}{, }\item[{\mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&}]{diagnostics}{, }\item[{auto \&}]{observation}{}\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [nodiscard]}}
Find a safe, sufficiently decreasing candidate without changing the accepted state.
\begin{DoxyNote}{Note}
A nonterminal candidate must prepare its inverse before publication. Preparation failure terminates this attempt; the caller still owns the previously accepted physical star.
\end{DoxyNote}
\Hypertarget{namespaceserif_1_1solver_1_1detail_af66d3dcd2f2fc1b4e4858dcd4e23be8f}\index{serif::solver::detail@{serif::solver::detail}!finite\_correction@{finite\_correction}}
\index{finite\_correction@{finite\_correction}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{finite\_correction()}{finite\_correction()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_af66d3dcd2f2fc1b4e4858dcd4e23be8f}
bool serif\+::solver\+::detail\+::finite\+\_\+correction (\begin{DoxyParamCaption}\item[{std\+::span$<$ const double $>$}]{correction}{, }\item[{const int}]{expected\+\_\+size}{}\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [nodiscard]}}
Every custom backend must preserve the correction dimensions and finite coefficients.
\Hypertarget{namespaceserif_1_1solver_1_1detail_abcb4ab5dca0460589f2989c776a641d7}\index{serif::solver::detail@{serif::solver::detail}!preparation\_rejection@{preparation\_rejection}}
\index{preparation\_rejection@{preparation\_rejection}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{preparation\_rejection()}{preparation\_rejection()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_abcb4ab5dca0460589f2989c776a641d7}
std\+::optional$<$ std\+::string $>$ serif\+::solver\+::detail\+::preparation\+\_\+rejection (\begin{DoxyParamCaption}\item[{const auto \&}]{problem}{, }\item[{const auto \&}]{evaluation}{}\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [nodiscard]}}
Preserve numerical preparation failures while propagating invalid physical configurations.
\Hypertarget{namespaceserif_1_1solver_1_1detail_a20193e65f854a97472b6a4f1602798e8}\index{serif::solver::detail@{serif::solver::detail}!qualify\_candidate@{qualify\_candidate}}
\index{qualify\_candidate@{qualify\_candidate}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{qualify\_candidate()}{qualify\_candidate()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_a20193e65f854a97472b6a4f1602798e8}
std\+::expected$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_metric_evaluation}{Metric\+Evaluation}}, \mbox{\hyperlink{structserif_1_1solver_1_1detail_1_1_newton_failure}{Newton\+Failure}} $>$ serif\+::solver\+::detail\+::qualify\+\_\+candidate (\begin{DoxyParamCaption}\item[{auto \&}]{problem}{, }\item[{const auto \&}]{state}{, }\item[{const auto \&}]{evaluation}{, }\item[{auto \&}]{metric\+\_\+function}{, }\item[{auto \&}]{strategy}{, }\item[{\mbox{\hyperlink{structserif_1_1solver_1_1_trial_assessment}{Trial\+Assessment}}}]{assessment}{ = {\ttfamily \{\}}}\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [nodiscard]}}
Qualify one already evaluated candidate through the same physical and metric gates everywhere.
\Hypertarget{namespaceserif_1_1solver_1_1detail_ad84838af2c61fd8a7ff1143ed6e30e07}\index{serif::solver::detail@{serif::solver::detail}!run\_newton@{run\_newton}}
\index{run\_newton@{run\_newton}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{run\_newton()}{run\_newton()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_ad84838af2c61fd8a7ff1143ed6e30e07}
template$<$typename Problem, typename State, typename Options, typename Observer$>$ \\
auto serif\+::solver\+::detail\+::run\+\_\+newton (\begin{DoxyParamCaption}\item[{Problem \&}]{problem}{, }\item[{State}]{initial\+\_\+state}{, }\item[{Options}]{options}{, }\item[{Observer}]{observer}{, }\item[{std\+::optional$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_newton_progress}{Newton\+Progress}} $>$}]{restart}{}\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [nodiscard]}}
Find equilibrium while retaining the last fully qualified physical state.
\begin{DoxyNote}{Note}
Preparation belongs to the problem; this driver alone publishes accepted steps. Scratch vectors use the problem\textquotesingle{}s native storage. Timing belongs entirely to observers.
\end{DoxyNote}
\Hypertarget{namespaceserif_1_1solver_1_1detail_a94057867583afc7737886a2cc9cb27d3}\index{serif::solver::detail@{serif::solver::detail}!save\_progress@{save\_progress}}
\index{save\_progress@{save\_progress}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{save\_progress()}{save\_progress()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_a94057867583afc7737886a2cc9cb27d3}
void serif\+::solver\+::detail\+::save\+\_\+progress (\begin{DoxyParamCaption}\item[{auto \&}]{result}{, }\item[{auto \&}]{options}{, }\item[{\mbox{\hyperlink{structserif_1_1solver_1_1_solve_diagnostics}{Solve\+Diagnostics}} \&}]{diagnostics}{, }\item[{\mbox{\hyperlink{structserif_1_1solver_1_1_metric_evaluation}{Metric\+Evaluation}}}]{metric}{, }\item[{std\+::span$<$ const double $>$}]{correction}{, }\item[{double}]{next\+\_\+step}{}\end{DoxyParamCaption})}
Snapshot only fully committed numerical history; reporting has no influence on restart.
\Hypertarget{namespaceserif_1_1solver_1_1detail_a07717377a241ffd25e63aa977ff4f554}\index{serif::solver::detail@{serif::solver::detail}!validate\_start@{validate\_start}}
\index{validate\_start@{validate\_start}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{validate\_start()}{validate\_start()}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_a07717377a241ffd25e63aa977ff4f554}
void serif\+::solver\+::detail\+::validate\+\_\+start (\begin{DoxyParamCaption}\item[{const auto \&}]{options}{, }\item[{const std\+::optional$<$ \mbox{\hyperlink{structserif_1_1solver_1_1_newton_progress}{Newton\+Progress}} $>$ \&}]{restart}{, }\item[{std\+::size\+\_\+t}]{size}{}\end{DoxyParamCaption})}
Validate controls and restored history before any physical preparation.
\doxysubsection{Variable Documentation}
\Hypertarget{namespaceserif_1_1solver_1_1detail_aca34a8e5074029c302fd5d3fc9d35244}\index{serif::solver::detail@{serif::solver::detail}!checkpointable\_options@{checkpointable\_options}}
\index{checkpointable\_options@{checkpointable\_options}!serif::solver::detail@{serif::solver::detail}}
\doxysubsubsection{\texorpdfstring{checkpointable\_options}{checkpointable\_options}}
{\footnotesize\ttfamily \label{namespaceserif_1_1solver_1_1detail_aca34a8e5074029c302fd5d3fc9d35244}
template$<$typename Options$>$ \\
bool serif\+::solver\+::detail\+::checkpointable\+\_\+options\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [constexpr]}}
{\bfseries Initial value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{=}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ std::same\_as<std::remove\_cvref\_t<decltype(std::declval<Options>().strategies)>,\ \mbox{\hyperlink{structserif_1_1solver_1_1_standard_newton}{StandardNewton}}>\ \&\&}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ std::same\_as<std::remove\_cvref\_t<\textcolor{keyword}{decltype}(std::declval<Options>().metric)>,\ \mbox{\hyperlink{structserif_1_1solver_1_1_normalized_residual_metric}{NormalizedResidualMetric}}>\ \&\&}
\DoxyCodeLine{\ \ \ \ \ \ \ \ \ \ \ \ std::same\_as<std::remove\_cvref\_t<\textcolor{keyword}{decltype}(std::declval<Options>().linear\_solver)>,\ \mbox{\hyperlink{structserif_1_1solver_1_1linear_1_1_f_g_m_r_e_s}{linear::FGMRES}}>}
\end{DoxyCode}
Only built-\/in stateless numerical policies currently have a complete restart contract.