feat: implement consistent-mass HHT shell dynamics

src/fesa/analysis/hht_dynamic_internal.h

@@ -0,0 +1,102 @@
+#ifndef FESA_ANALYSIS_HHT_DYNAMIC_INTERNAL_H_
+#define FESA_ANALYSIS_HHT_DYNAMIC_INTERNAL_H_
+
+#include <array>
+#include <vector>
+
+#include "fesa/analysis/dynamic_analysis_state.h"
+#include "fesa/analysis/hht_time_integration.h"
+#include "fesa/elements/nonlinear_mitc4_inertia.h"
+#include "fesa/elements/nonlinear_mitc4_shell.h"
+#include "fesa/math/sparse_matrix.h"
+
+namespace fesa {
+class LinearSolver;
+class ParallelFor;
+class TangentSolver;
+namespace hht_internal {
+
+/// @brief Keeps immutable local evaluators with the DOF-owner scatter.
+struct RuntimeShell {
+  EntityIndex element_index;
+  std::array<std::size_t, 24> scatter;
+  NonlinearMitc4Shell internal;
+  NonlinearMitc4Inertia inertia;
+};
+
+/// @brief Stores a complete trial with independently assembled operators.
+struct DynamicAssembly {
+  DynamicAcceptedFrameState frame;
+  SparseMatrix mass;
+  SparseMatrix internal_tangent;
+  SparseMatrix effective_tangent;
+  SparseMatrix drilling_metric;
+  Vector force_directional_second;
+  Vector force_directional_second_scale;
+  std::vector<DynamicRotationKinematics> rotations;
+  double momentum_rate_scale;
+  double angular_momentum_rate_scale;
+  Vector hidden_second{0U};
+  Vector hidden_second_scale{0U};
+};
+
+/// @brief Builds checked shell evaluators in stable source order.
+Result<std::vector<RuntimeShell>> BuildRuntimeShells(const Domain& domain,
+                                                     const DofManager& dofs);
+
+/// @brief Returns the maximum initial active-element edge length.
+Result<double> ReferenceLength(const Domain& domain);
+
+/// @brief Assembles dead loads and their uncancelled absolute row scales.
+Result<std::array<Vector, 2>> AssembleLoads(const Domain& domain,
+                                            const DofManager& dofs);
+
+/// @brief Evaluates current kinetic and internal quantities without commit.
+Result<DynamicAssembly> EvaluateAssembly(
+    const Domain& domain, const DofManager& dofs,
+    const std::vector<RuntimeShell>& shells, DynamicAcceptedFrameState frame,
+    const Vector& load_scale, double time_increment,
+    const HhtParameters& parameters, const ParallelFor& parallel_for,
+    bool directional_third);
+
+/// @brief Builds deterministic CSR structure from an ordered local list.
+Result<SparseMatrix> MakeSparse(std::size_t rows, std::size_t columns,
+                                std::vector<CooContribution> contributions);
+
+/// @brief Builds the scaled free-space operator D^T K D.
+Result<SparseMatrix> ScaledFree(const SparseMatrix& matrix,
+                                const DofManager& dofs, double length);
+
+/// @brief Checks normwise backward error in the supplied equation space.
+Status CheckLinearSolve(const SparseMatrix& matrix, const Vector& rhs,
+                        const Vector& solution);
+
+/// @brief Finds analytic admissible node null directions without rank cuts.
+std::vector<std::size_t> NullNodes(
+    const DofManager& dofs,
+    const std::vector<DynamicRotationKinematics>& rotations);
+
+/// @brief Solves the positive-mass and differentiated-null initial equations.
+Result<Vector> InitializeAcceleration(const Domain& domain,
+                                      const DofManager& dofs,
+                                      const DynamicAssembly& initial,
+                                      double length,
+                                      LinearSolver& positive_solver,
+                                      TangentSolver& tangent_solver);
+
+/// @brief Checks mass/regularity and recovers all exact hidden defects.
+Status CompleteConstraintEvidence(
+    const Domain& domain, const DofManager& dofs,
+    const DynamicAssembly& assembly, double length,
+    const std::vector<std::size_t>& initial_null_nodes,
+    LinearSolver& positive_solver, TangentSolver& tangent_solver,
+    DynamicAcceptedFrameState* frame);
+
+/// @brief Recovers physical support balance using volume momentum rates.
+Status CompleteEquilibrium(const Domain& domain, const DofManager& dofs,
+                           const DynamicAssembly& assembly,
+                           DynamicAcceptedFrameState* frame);
+
+}  // namespace hht_internal
+}  // namespace fesa
+#endif  // FESA_ANALYSIS_HHT_DYNAMIC_INTERNAL_H_