feat(newton): first newton solver implementation

libmeanfield/interface/operators/prepared_mass_normalization.cppm

@@ -2,7 +2,9 @@ module;
 
 #include <compare>
 #include <cstdint>
+#include <expected>
 #include <mfem.hpp>
+#include <optional>
 #include <vector>
 
 export module mean_field:operators.prepared_mass_normalization;
@@ -59,6 +61,28 @@ export namespace mean_field::operators {
         constexpr auto operator<=>(const PreparedMassNormalizationReport &) const = default;
     };
 
+    enum class MassNormalizationPreparationRejectionReason : std::uint8_t {
+        mapping_failure,
+        non_finite_density_interpolation,
+        non_finite_assembled_mass
+    };
+
+    /*
+     * Candidate rejection is deliberately represented without text or owned
+     * storage.  That makes the result cheap to propagate through a line search
+     * and gives the MPI implementation a deterministic, allocation-free value
+     * to select on every rank.
+     */
+    struct MassNormalizationPreparationRejection final {
+        MassNormalizationPreparationRejectionReason reason{
+            MassNormalizationPreparationRejectionReason::mapping_failure
+        };
+        mapping::MappingStatus mappingStatus{mapping::MappingStatus::non_finite_result};
+    };
+
+    using MassNormalizationPreparationResult =
+        std::expected<PreparedMassNormalizationReport, MassNormalizationPreparationRejection>;
+
     struct PreparedMassNormalizationActionStatistics final {
         std::uint64_t densityApplications{0};
         std::uint64_t displacementApplications{0};
@@ -109,6 +133,16 @@ export namespace mean_field::operators {
             const MassNormalizationDependencies &dependencies
         );
 
+        [[nodiscard]] MassNormalizationPreparationResult TryPrepare(
+            const MassNormalizationStateView &state,
+            const MassNormalizationDependencies &dependencies
+        );
+
+        [[nodiscard]] MassNormalizationPreparationResult TryPrepare(
+            const models::CompiledFixedMass &constraint,
+            const MassNormalizationDependencies &dependencies
+        );
+
         void BuildResidual(mfem::Vector &residual) const;
 
         void ApplyDensityJacobianAction(
@@ -179,9 +213,11 @@ export namespace mean_field::operators {
         };
 
         void BuildStaticPlan();
-        void RefreshGeometry(const mfem::Vector &displacement);
-        void RefreshDensity(const mfem::Vector &density);
-        void AssembleResidual();
+        [[nodiscard]] std::optional<MassNormalizationPreparationRejection>
+        RefreshGeometry(const mfem::Vector &displacement);
+        [[nodiscard]] std::optional<MassNormalizationPreparationRejection> RefreshDensity(const mfem::Vector &density);
+        [[nodiscard]] std::optional<MassNormalizationPreparationRejection> AssembleResidual();
+        [[nodiscard]] std::optional<MassNormalizationPreparationRejection> UpdateResidualForTargetMass();
         void VerifyPrepared() const;
 
         [[nodiscard]] double EvaluateDensityActionLocal(const mfem::Vector &densityVariation) const;