feat: implement consistent-mass HHT shell dynamics

include/fesa/elements/nonlinear_mitc4_inertia.h

@@ -0,0 +1,106 @@
+#ifndef FESA_ELEMENTS_NONLINEAR_MITC4_INERTIA_H_
+#define FESA_ELEMENTS_NONLINEAR_MITC4_INERTIA_H_
+
+#include <array>
+#include <string>
+
+#include "fesa/core/status.h"
+#include "fesa/elements/nonlinear_mitc4_shell.h"
+#include "fesa/math/matrix.h"
+#include "fesa/math/vector.h"
+#include "fesa/math/vector3.h"
+#include "fesa/model/model_types.h"
+
+namespace fesa {
+
+/// @brief Stores exact physical rotation-rate and drilling-null quantities.
+struct DynamicRotationKinematics {
+  Vector3 director;
+  Vector3 drill_null;
+  Matrix null_gradient{3U, 3U};
+  /// @brief Stores D2 drill_null[velocity, velocity], without Dn[a].
+  Vector3 null_directional_second;
+  Vector3 angular_velocity;
+  Vector3 angular_acceleration;
+  /// @brief Stores director derivatives in fixed-global chart directions.
+  std::array<Vector3, 3> director_first;
+  std::array<std::array<Vector3, 3>, 3> director_second;
+  std::array<std::array<std::array<Vector3, 3>, 3>, 3> director_third;
+};
+
+/// @brief Evaluates exact finite-rotation rates and the unit drilling null.
+/// @param phi Fixed-global principal-chart rotation coordinate.
+/// @param initial_director Unit director at zero rotation.
+/// @param velocity Fixed-chart rotation-coordinate rate.
+/// @param acceleration Fixed-chart rotation-coordinate acceleration.
+/// @return Finite director/rates/null derivatives or a structured failure.
+[[nodiscard]] Result<DynamicRotationKinematics> EvaluateDynamicRotation(
+    const Vector3& phi, const Vector3& initial_director,
+    const Vector3& velocity, const Vector3& acceleration);
+
+/// @brief Stores the consistent kinetic-inertia quantities at one trial.
+struct NonlinearMitc4InertiaEvaluation {
+  Matrix mass;
+  Matrix position_tangent;
+  Matrix velocity_tangent;
+  Vector force;
+  Vector convective_force;
+  double kinetic_energy;
+  Vector3 momentum;
+  Vector3 angular_momentum;
+  Vector3 momentum_rate;
+  Vector3 angular_momentum_rate;
+  /// @brief Stores uncancelled quadrature norm sums for balance checks.
+  double momentum_rate_scale = 0.0;
+  double angular_momentum_rate_scale = 0.0;
+};
+
+/// @brief Evaluates finite-rotation consistent inertia for one MITC4 shell.
+/// @note This object owns immutable reference geometry only, never analysis
+/// trial state.
+class NonlinearMitc4Inertia {
+ public:
+  /// @brief Creates a checked consistent kinetic-mass evaluator.
+  /// @param nodes Four non-owning nodes in source order.
+  /// @param initial_frames Fixed proper node frames in source order.
+  /// @param section Centered shell section with positive thickness.
+  /// @param material Shell material used to retain the nonlinear-shell input
+  /// contract.
+  /// @param density Reference mass density, strictly positive and finite.
+  /// @return A checked immutable evaluator or a structured model failure.
+  static Result<NonlinearMitc4Inertia> Create(
+      std::array<const Node*, 4> nodes,
+      std::array<ShellNodeInitialFrame, 4> initial_frames,
+      const ShellSection& section, const LinearElasticMaterial& material,
+      double density);
+
+  /// @brief Evaluates physical consistent inertia at a complete trial.
+  /// @param trial Fixed-global translation and rotation coordinates.
+  /// @param velocity24 Fixed-chart generalized physical velocity.
+  /// @param physical_acceleration24 Fixed-chart generalized physical
+  /// acceleration.
+  /// @return Current mass, inertia force and exact partial tangents, or a
+  /// fail-closed diagnostic.
+  [[nodiscard]] Result<NonlinearMitc4InertiaEvaluation> Evaluate(
+      const NonlinearMitc4TrialDofs& trial, const Vector& velocity24,
+      const Vector& physical_acceleration24) const;
+
+ private:
+  NonlinearMitc4Inertia(std::array<Vector3, 4> coordinates,
+                        std::array<Matrix, 4> initial_frames,
+                        std::array<Vector3, 4> initial_directors,
+                        double thickness, double density,
+                        SourceLocation source_location, std::string identity);
+
+  std::array<Vector3, 4> coordinates_;
+  std::array<Matrix, 4> initial_frames_;
+  std::array<Vector3, 4> initial_directors_;
+  double thickness_;
+  double density_;
+  SourceLocation source_location_;
+  std::string identity_;
+};
+
+}  // namespace fesa
+
+#endif  // FESA_ELEMENTS_NONLINEAR_MITC4_INERTIA_H_

include/fesa/elements/nonlinear_mitc4_shell.h

@@ -43,6 +43,16 @@ struct NonlinearMitc4InternalEquilibrium {
   Vector internal_force;
   NonlinearMitc4Recovery recovery;
   double physical_strain_energy;
+  Vector physical_force{0U};
+  Vector drilling_force{0U};
+  Matrix drilling_tangent{0U, 0U};
+  Matrix drilling_metric{0U, 0U};
+  double drilling_energy = 0.0;
+  Vector force_directional_second{0U};
+  Vector drilling_constraint{0U};
+  Matrix drilling_constraint_gradient{0U, 0U};
+  std::array<Matrix, 4> drilling_constraint_hessian{
+      Matrix{0U, 0U}, Matrix{0U, 0U}, Matrix{0U, 0U}, Matrix{0U, 0U}};
 };
 
 class NonlinearMitc4Shell;
@@ -50,11 +60,13 @@ class NonlinearMitc4Shell;
 /// @brief Evaluates the internal residual and tangent at one complete trial.
 /// @param element Immutable nonlinear MITC4 reference evaluator.
 /// @param trial Complete global translation and rotation trial coordinates.
+/// @param coordinate_direction Optional 24-vector for D2(f_int)[v,v].
 /// @return Internal force, consistent tangent and physical recovery, or
 /// failure.
 /// @note External load vectors and their tangents are intentionally excluded.
 Result<NonlinearMitc4InternalEquilibrium> EvaluateInternalResidualAndTangent(
-    const NonlinearMitc4Shell& element, const NonlinearMitc4TrialDofs& trial);
+    const NonlinearMitc4Shell& element, const NonlinearMitc4TrialDofs& trial,
+    const Vector* coordinate_direction = nullptr);
 
 /// @brief Evaluates fixed-reference Total Lagrangian MITC4 kinematics.
 /// @note This class owns no mutable trial or accepted analysis state.
@@ -94,7 +106,8 @@ class NonlinearMitc4Shell {
 
   friend Result<NonlinearMitc4InternalEquilibrium>
   EvaluateInternalResidualAndTangent(const NonlinearMitc4Shell& element,
-                                     const NonlinearMitc4TrialDofs& trial);
+                                     const NonlinearMitc4TrialDofs& trial,
+                                     const Vector* coordinate_direction);
 
   std::array<Vector3, 4> coordinates_;
   std::array<Matrix, 4> initial_frames_;