feat(newton): first newton solver implementation

libmeanfield/interface/operators/prepared_barotropic_closure_operator.cppm

@@ -1,6 +1,7 @@
 module;
 
 #include <cstdint>
+#include <expected>
 #include <mfem.hpp>
 #include <vector>
 
@@ -22,6 +23,29 @@ export namespace mean_field::operators {
         }
     };
 
+    enum class BarotropicClosurePreparationRejectionReason : std::uint8_t {
+        mapping_failure,
+        invalid_quadrature_data,
+        equation_of_state
+    };
+
+    /*
+     * A rejected candidate is part of the nonlinear-solver control flow, not
+     * an exceptional API failure.  Keep the payload fixed-size so it can be
+     * selected deterministically across ranks without allocating.  Only the
+     * detail associated with `reason` is meaningful.
+     */
+    struct BarotropicClosurePreparationRejection final {
+        BarotropicClosurePreparationRejectionReason reason{
+            BarotropicClosurePreparationRejectionReason::mapping_failure
+        };
+        mapping::MappingStatus mappingStatus{mapping::MappingStatus::non_finite_result};
+        eos::EvaluationErrorCode equationOfStateError{eos::EvaluationErrorCode::nonfinite_result};
+    };
+
+    using BarotropicClosurePreparationResult =
+        std::expected<PreparedBarotropicClosureReport, BarotropicClosurePreparationRejection>;
+
     class PreparedBarotropicClosureOperator final : public mfem::Operator {
     public:
         PreparedBarotropicClosureOperator(
@@ -40,6 +64,11 @@ export namespace mean_field::operators {
             const context::barotropic::BarotropicClosureDependencies &dependencies
         );
 
+        [[nodiscard]] BarotropicClosurePreparationResult TryPrepare(
+            const context::barotropic::BarotropicClosureStateView &state,
+            const context::barotropic::BarotropicClosureDependencies &dependencies
+        );
+
         void Mult(
             const mfem::Vector &densityVariation,
             const mfem::Vector &enthalpyVariation,