feat(nonlinear-static-newton-raphson): step 5 - load-boundary-path-and-convergence-gates

include/fesa/analysis/nonlinear_static_control.h

@@ -0,0 +1,131 @@
+#ifndef FESA_ANALYSIS_NONLINEAR_STATIC_CONTROL_H_
+#define FESA_ANALYSIS_NONLINEAR_STATIC_CONTROL_H_
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "fesa/core/diagnostic.h"
+#include "fesa/core/status.h"
+#include "fesa/fem/dof_manager.h"
+#include "fesa/math/sparse_matrix.h"
+#include "fesa/math/vector.h"
+#include "fesa/math/vector3.h"
+#include "fesa/model/domain.h"
+
+namespace fesa {
+
+/// @brief Identifies one deterministic nonlinear load-factor increment.
+struct LoadFactorIncrement {
+  std::uint32_t increment_index;
+  double load_factor;
+  bool is_factor_one;
+};
+
+/// @brief Identifies the physical dimension of a convergence threshold.
+enum class NewtonChannelUnit {
+  kForce,
+  kForceLength,
+  kLength,
+  kDimensionless,
+};
+
+inline constexpr double kNewtonRelativeThreshold = 1.0e-2;
+inline constexpr double kNewtonZeroScaleThreshold = 1.0e-3;
+
+/// @brief Carries one same-trial free residual convergence channel.
+struct NewtonResidualChannelInput {
+  std::string identity;
+  Vector free_residual;
+  Vector free_internal;
+  Vector free_external;
+};
+
+/// @brief Carries one same-iteration free correction convergence channel.
+struct NewtonCorrectionChannelInput {
+  std::string identity;
+  Vector fresh_correction;
+  Vector current_increment;
+};
+
+/// @brief Groups the four approved Newton convergence channels.
+struct NewtonConvergenceInput {
+  NewtonResidualChannelInput force_residual;
+  NewtonResidualChannelInput moment_residual;
+  NewtonCorrectionChannelInput translation_correction;
+  NewtonCorrectionChannelInput rotation_correction;
+};
+
+/// @brief Identifies the only approved Newton convergence comparison branch.
+enum class NewtonConvergenceBranch { kRelative, kZeroScale };
+
+/// @brief Records the deterministic decision for one Newton channel.
+struct NewtonChannelDecision {
+  std::string identity;
+  double numerator_norm;
+  double denominator_scale;
+  NewtonConvergenceBranch branch;
+  double threshold;
+  NewtonChannelUnit threshold_unit;
+  bool passed;
+};
+
+/// @brief Groups all four channel decisions and their logical conjunction.
+struct NewtonConvergenceResult {
+  NewtonChannelDecision force_residual;
+  NewtonChannelDecision moment_residual;
+  NewtonChannelDecision translation_correction;
+  NewtonChannelDecision rotation_correction;
+  bool combined_passed;
+};
+
+/// @brief Stores the full-space fixed-load vector and its exact tangent.
+struct GlobalFixedLoadContribution {
+  Vector generalized_external_force;
+  SparseMatrix generalized_external_tangent;
+  std::vector<Diagnostic> diagnostics;
+};
+
+/// @brief Derives the fixed nonlinear factor path from raw static controls.
+/// @param step Immutable nonlinear static step that owns raw source controls.
+/// @return Ordered factors ending in an exactly assigned factor one, or an
+/// input failure.
+Result<std::vector<LoadFactorIncrement>> BuildFixedLoadFactorSequence(
+    const StepDefinition& step);
+
+/// @brief Scales factor-one prescribed targets from the zero step-start state.
+/// @param step Immutable nonlinear step whose boundary order fixes output
+/// order.
+/// @param load_factor Current finite factor in the closed interval [0, 1].
+/// @return One absolute prescribed value per step boundary component, or an
+/// input failure.
+Result<Vector> ApplyAbsolutePrescribedDisplacementTarget(
+    const StepDefinition& step, double load_factor);
+
+/// @brief Assembles fixed-global CLOAD work once in full generalized space.
+/// @param domain Immutable nonlinear semantic model with one active step.
+/// @param dofs Stable full-DOF mapping for domain nodes.
+/// @param trial_generalized_coordinates Current full global [u, phi] trial.
+/// @param load_factor Current finite factor in the closed interval [0, 1].
+/// @return External vector and tangent for r=f_int-f_ext and K=K_int-K_ext,
+/// or a structured model/solver failure.
+Result<GlobalFixedLoadContribution> AssembleGlobalFixedLoadContribution(
+    const Domain& domain, const DofManager& dofs,
+    const Vector& trial_generalized_coordinates, double load_factor);
+
+/// @brief Rejects a nonzero source moment with director-parallel work.
+/// @param director Current finite unit director in global coordinates.
+/// @param source_moment Immutable fixed-global source moment.
+/// @return Success when rho_M is at most 1e-12 or the source moment is zero.
+Status CheckMomentAdmissibility(const Vector3& director,
+                                const Vector3& source_moment);
+
+/// @brief Evaluates the four immutable, typed Newton convergence gates.
+/// @param input Same-trial free residuals and same-iteration corrections.
+/// @return Per-channel decision records and their logical conjunction.
+NewtonConvergenceResult EvaluateNewtonConvergence(
+    const NewtonConvergenceInput& input);
+
+}  // namespace fesa
+
+#endif  // FESA_ANALYSIS_NONLINEAR_STATIC_CONTROL_H_