feat(newton): first newton solver implementation

libmeanfield/interface/operators/prepared_hydrostatic_equilibrium_operator.cppm

@@ -3,7 +3,9 @@ module;
 #include <compare>
 #include <cstddef>
 #include <cstdint>
+#include <expected>
 #include <optional>
+#include <stdexcept>
 #include <vector>
 
 #include <mfem.hpp>
@@ -30,6 +32,35 @@ export namespace mean_field::operators {
         }
     };
 
+    enum class HydrostaticEquilibriumPreparationRejectionReason : std::uint8_t {
+        inverted_geometry,
+        non_finite_geometry,
+        non_finite_residual
+    };
+
+    struct HydrostaticEquilibriumPreparationRejection final {
+        HydrostaticEquilibriumPreparationRejectionReason reason{
+            HydrostaticEquilibriumPreparationRejectionReason::inverted_geometry
+        };
+        mapping::MappingStatus mappingStatus{mapping::MappingStatus::valid};
+    };
+
+    using HydrostaticEquilibriumPreparationResult =
+        std::expected<PreparedHydrostaticEquilibriumReport, HydrostaticEquilibriumPreparationRejection>;
+
+    [[noreturn]] inline void
+    throwHydrostaticEquilibriumPreparationRejection(const HydrostaticEquilibriumPreparationRejection &rejection) {
+        switch (rejection.reason) {
+        case HydrostaticEquilibriumPreparationRejectionReason::non_finite_geometry:
+            throw std::domain_error("Prepared hydrostatic equilibrium encountered non-finite mapped geometry.");
+        case HydrostaticEquilibriumPreparationRejectionReason::non_finite_residual:
+            throw std::domain_error("Prepared hydrostatic equilibrium produced a non-finite residual.");
+        case HydrostaticEquilibriumPreparationRejectionReason::inverted_geometry:
+        default:
+            throw std::domain_error("Prepared hydrostatic equilibrium encountered inverted mapped geometry.");
+        }
+    }
+
     struct PreparedHydrostaticAlgebraicJacobianStatistics {
         std::uint64_t preparations{0};
         std::uint64_t enthalpyApplications{0};
@@ -102,6 +133,12 @@ export namespace mean_field::operators {
             const physics::RigidRotation &rotation
         );
 
+        [[nodiscard]] HydrostaticEquilibriumPreparationResult TryPrepare(
+            const context::hydrostatic::HydrostaticEquilibriumStateView &state,
+            const context::hydrostatic::HydrostaticEquilibriumDependencies &dependencies,
+            const physics::RigidRotation &rotation
+        );
+
         void BuildResidual(mfem::Vector &residual) const;
 
         void ApplyEnthalpyJacobianAction(
@@ -221,12 +258,12 @@ export namespace mean_field::operators {
         };
 
         void PrepareStaticPlan();
-        void PrepareGeometry();
-        void PrepareAlgebraicJacobianBlocks();
-        void PrepareRotation();
-        void PrepareBaseState();
+        [[nodiscard]] std::optional<mapping::MappingStatus> PrepareGeometry();
+        [[nodiscard]] bool PrepareAlgebraicJacobianBlocks();
+        [[nodiscard]] bool PrepareRotation();
+        [[nodiscard]] bool PrepareBaseState();
         void FinalizeDisplacementJacobianPreparation();
-        void AssembleCachedResidual();
+        [[nodiscard]] bool AssembleCachedResidual();
         void VerifyPrepared() const;
 
         const fem::FEM &m_fem;