feat(nonlinear-static-newton-raphson): step 2 - finite-rotation-state

include/fesa/elements/finite_rotation.h

@@ -0,0 +1,63 @@
+#ifndef FESA_ELEMENTS_FINITE_ROTATION_H_
+#define FESA_ELEMENTS_FINITE_ROTATION_H_
+
+#include "fesa/core/status.h"
+#include "fesa/math/matrix.h"
+#include "fesa/math/vector3.h"
+
+namespace fesa {
+
+/// @brief Stores one finite-rotation coordinate and its derived triad state.
+struct FiniteRotationState {
+  /// @brief Fixed-global principal-chart rotation coordinate in radians.
+  Vector3 phi;
+
+  /// @brief Proper orthogonal triad computed as exp(phi^) times the initial
+  /// frame.
+  Matrix q;
+
+  /// @brief Current director computed from the third column of q.
+  Vector3 director;
+};
+
+/// @brief Computes Rodrigues' exponential of the three-dimensional skew map.
+/// @param phi Fixed-global rotation coordinate in radians.
+/// @return The 3-by-3 rotation tensor exp(phi^).
+/// @pre phi is finite and lies inside the approved principal chart.
+Matrix ExpSkew(const Vector3& phi);
+
+/// @brief Computes the SO(3) left Jacobian for a fixed-global coordinate.
+/// @param phi Fixed-global rotation coordinate in radians.
+/// @return The 3-by-3 left Jacobian that maps coordinate variations to spatial
+/// rotations.
+/// @pre phi is finite and lies inside the approved principal chart.
+Matrix LeftJacobianSO3(const Vector3& phi);
+
+/// @brief Computes the inverse transpose of the SO(3) left Jacobian.
+/// @param phi Fixed-global rotation coordinate in radians.
+/// @return The 3-by-3 inverse-transpose left Jacobian.
+/// @pre phi is finite and lies inside the approved principal chart.
+Matrix InverseTransposeLeftJacobianSO3(const Vector3& phi);
+
+/// @brief Builds a checked finite-rotation state from its reference frame.
+/// @param phi Fixed-global principal-chart rotation coordinate in radians.
+/// @param initial_frame Valid initial right-handed 3-by-3 triad.
+/// @return A complete finite state or an `invalid-accepted-state` failure.
+/// @note The input frame is validated but never normalized or repaired.
+Result<FiniteRotationState> MakeFiniteRotationState(
+    const Vector3& phi, const Matrix& initial_frame);
+
+/// @brief Applies a fixed-global Newton rotation increment to one state.
+/// @param committed Fully validated state that remains unchanged by this call.
+/// @param delta_phi Fixed-global additive rotation correction in radians.
+/// @param initial_frame Valid initial right-handed 3-by-3 triad.
+/// @return A rebuilt trial state or an `invalid-accepted-state` failure.
+/// @note The result is recomputed from phi plus delta_phi and initial_frame;
+/// incremental tensors are not successively composed.
+Result<FiniteRotationState> ApplyGlobalRotationIncrement(
+    const FiniteRotationState& committed, const Vector3& delta_phi,
+    const Matrix& initial_frame);
+
+}  // namespace fesa
+
+#endif  // FESA_ELEMENTS_FINITE_ROTATION_H_