From 4ebdb7d0589e19eacf37d82a6c163b88c69eb47d Mon Sep 17 00:00:00 2001
From: Emily Boudreaux <thomas@boudreauxmail.com>
Date: Mon, 9 Nov 2026 13:36:11 -0500
Subject: [PATCH] feat(solver): high level solver interface

High level solver interface allowing for robust compile-time claims to be made
---
 src/include/serif/solver/equilibrium.hpp | 84 ++++++++++++++++++++++++
 src/include/serif/solver/solver.hpp      | 12 ++++
 2 files changed, 96 insertions(+)
 create mode 100644 src/include/serif/solver/equilibrium.hpp

diff --git a/src/include/serif/solver/equilibrium.hpp b/src/include/serif/solver/equilibrium.hpp
new file mode 100644
index 00000000..0f568479
--- /dev/null
+++ b/src/include/serif/solver/equilibrium.hpp
@@ -0,0 +1,84 @@
+#pragma once
+
+#include "serif/backend/mfem/solver/equilibrium.hpp"
+#include "serif/solver/nonlinear/newton.hpp"
+#include "serif/model/finite_elements.hpp"
+
+namespace serif::solver {
+    using VolumeOptions = operators::backend::mfem::VolumeOptions;
+
+    /**
+     * @brief Solve a moving star from an owning physical initial state.
+     * @note 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.
+     */
+    template <typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver, utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>,
+              typename ObserverFactory = utils::dependencies::NoGraphObservers>
+        requires utils::dependencies::ContainsKey<discretization::blocks::surface_deformation::coefficients, typename Layout::Values>
+    [[nodiscard]] auto solve_equilibrium(
+        Configuration configuration,
+        model::StellarState<Layout> initial_state,
+        Options options = {},
+        Observer observer = {},
+        VolumeOptions volume_options = {},
+        Inputs prescribed = Inputs{},
+        ObserverFactory observer_factory = {}
+    ) {
+        auto problem = backend::mfem::make_observed_stellar_problem(std::move(configuration), initial_state, options.strategies,
+            volume_options, std::move(prescribed), std::move(observer_factory));
+        return solve_newton(problem, std::move(initial_state), std::move(options), std::move(observer));
+    }
+
+    /**
+     * @brief Solve a fixed-geometry model with prescribed displacement outside its unknown vector.
+     * @note 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.
+     */
+    template <typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver,
+              utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>,
+              typename ObserverFactory = utils::dependencies::NoGraphObservers>
+        requires (!utils::dependencies::ContainsKey<discretization::blocks::surface_deformation::coefficients, typename Layout::Values>)
+    [[nodiscard]] auto solve_equilibrium(Configuration configuration, model::StellarState<Layout> initial_state,
+        const Vector& displacement, Options options = {}, Observer observer = {},
+        VolumeOptions volume_options = {}, Inputs prescribed = Inputs{}, ObserverFactory observer_factory = {}) {
+        auto problem = backend::mfem::make_observed_stellar_problem(std::move(configuration), initial_state, options.strategies,
+            volume_options, std::move(prescribed), std::move(observer_factory), displacement);
+        return solve_newton(problem, std::move(initial_state), std::move(options), std::move(observer));
+    }
+
+
+    /**
+     * @brief Continue a moving-star checkpoint using reconstructed physical and numerical configuration.
+     * @note 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.
+     */
+    template <typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver,
+              utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>,
+              typename ObserverFactory = utils::dependencies::NoGraphObservers>
+        requires utils::dependencies::ContainsKey<discretization::blocks::surface_deformation::coefficients, typename Layout::Values>
+    [[nodiscard]] auto resume_equilibrium(Configuration configuration, NewtonCheckpoint<model::StellarState<Layout>> checkpoint,
+        Options options = {}, Observer observer = {}, VolumeOptions volume_options = {}, Inputs prescribed = Inputs{}, ObserverFactory observer_factory = {}) {
+        auto problem = backend::mfem::make_observed_stellar_problem(std::move(configuration), checkpoint.state, options.strategies,
+            volume_options, std::move(prescribed), std::move(observer_factory));
+        return resume_newton(problem, std::move(checkpoint), std::move(options), std::move(observer));
+    }
+
+    /**
+     * @brief Continue a fixed-geometry checkpoint with its separately restored prescribed displacement.
+     * @note 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.
+     */
+    template <typename Configuration, typename Layout, typename Options = SolverOptions<>, typename Observer = NoObserver,
+              utils::dependencies::IsDependencyContext Inputs = utils::dependencies::DependencyContext<>,
+              typename ObserverFactory = utils::dependencies::NoGraphObservers>
+        requires (!utils::dependencies::ContainsKey<discretization::blocks::surface_deformation::coefficients, typename Layout::Values>)
+    [[nodiscard]] auto resume_equilibrium(Configuration configuration, NewtonCheckpoint<model::StellarState<Layout>> checkpoint,
+        const Vector& displacement, Options options = {}, Observer observer = {},
+        VolumeOptions volume_options = {}, Inputs prescribed = Inputs{}, ObserverFactory observer_factory = {}) {
+        auto problem = backend::mfem::make_observed_stellar_problem(std::move(configuration), checkpoint.state, options.strategies,
+            volume_options, std::move(prescribed), std::move(observer_factory), displacement);
+        return resume_newton(problem, std::move(checkpoint), std::move(options), std::move(observer));
+    }
+}
diff --git a/src/include/serif/solver/solver.hpp b/src/include/serif/solver/solver.hpp
index e69de29b..b641f4df 100644
--- a/src/include/serif/solver/solver.hpp
+++ b/src/include/serif/solver/solver.hpp
@@ -0,0 +1,12 @@
+#pragma once
+
+#include "serif/solver/normalization/normalization.hpp"
+#include "serif/solver/preconditioner/preconditioner.hpp"
+
+#include "serif/solver/equilibrium.hpp"
+#include "serif/solver/continuation/continuation.hpp"
+#include "serif/solver/continuation/equilibrium.hpp"
+#include "serif/solver/seed/polytrope.hpp"
+#include "serif/solver/seed/fitted.hpp"
+
+#include "serif/solver/seed/state.hpp"