feat(newton): first newton solver implementation

libmeanfield/interface/operators/prepared_displacement_operator.cppm

@@ -2,6 +2,8 @@ module;
 
 #include <compare>
 #include <cstdint>
+#include <expected>
+#include <optional>
 
 #include <mfem.hpp>
 
@@ -18,6 +20,28 @@ export import :physics.rigid_rotation;
 export import :utils.blocks;
 
 export namespace mean_field::operators {
+    enum class DisplacementResidualPreparationRejectionSource : std::uint8_t {
+        pressure,
+        gravity,
+        rotation,
+        composition
+    };
+
+    enum class DisplacementResidualPreparationRejectionReason : std::uint8_t {
+        equation_of_state,
+        invalid_mapping,
+        non_finite_arithmetic
+    };
+
+    struct DisplacementResidualPreparationRejection final {
+        DisplacementResidualPreparationRejectionSource source{DisplacementResidualPreparationRejectionSource::pressure};
+        DisplacementResidualPreparationRejectionReason reason{
+            DisplacementResidualPreparationRejectionReason::equation_of_state
+        };
+        eos::EvaluationErrorCode equationOfStateCode{eos::EvaluationErrorCode::nonfinite_result};
+        mapping::MappingStatus mappingStatus{mapping::MappingStatus::valid};
+    };
+
     struct DisplacementResidualDependencyStamp final {
         std::uint64_t identity{0};
         std::uint64_t revision{0};
@@ -104,6 +128,15 @@ export namespace mean_field::operators {
             const physics::RigidRotation &rotation
         );
 
+        [[nodiscard]] std::expected<
+            PreparedDisplacementResidualReport,
+            DisplacementResidualPreparationRejection>
+        TryPrepare(
+            const DisplacementResidualStateView &state,
+            const DisplacementResidualDependencies &dependencies,
+            const physics::RigidRotation &rotation
+        );
+
         void BuildResidual(mfem::Vector &residual) const;
 
         void ApplyDensityJacobianAction(
@@ -154,7 +187,7 @@ export namespace mean_field::operators {
         GetGravityContext() const noexcept;
 
     private:
-        void AssembleResidual();
+        [[nodiscard]] std::optional<DisplacementResidualPreparationRejection> AssembleResidual();
         void VerifyPrepared() const;
 
         const fem::FEM &m_fem;