feat(cpp-object-oriented-modular-refactoring): step 14 - runtime-element-factory

include/fesa/elements/element.h

@@ -0,0 +1,85 @@
+#ifndef FESA_ELEMENTS_ELEMENT_H_
+#define FESA_ELEMENTS_ELEMENT_H_
+
+#include <cstdint>
+#include <functional>
+#include <variant>
+#include <vector>
+
+#include "fesa/core/source_identity.h"
+#include "fesa/core/status.h"
+#include "fesa/math/matrix.h"
+#include "fesa/math/vector.h"
+#include "fesa/results/result_records.h"
+
+namespace fesa {
+
+/// @brief Identifies one component in the stable six-DOF node layout.
+enum class DofComponent : std::uint8_t {
+  kUx,
+  kUy,
+  kUz,
+  kUrx,
+  kUry,
+  kUrz,
+};
+
+/// @brief Describes one runtime element's stable node and component order.
+struct ElementDofLayout {
+  SourceEntityId source_id;
+  std::vector<EntityIndex> node_indices;
+  std::vector<DofComponent> components_per_node;
+};
+
+/// @brief Carries one element-local stiffness in its declared DOF order.
+struct ElementStiffnessContribution {
+  ElementDofLayout layout;
+  Matrix values;
+};
+
+/// @brief Keeps beam recovery locations in their distinct row collections.
+struct BeamElementResultRows {
+  std::vector<EndpointResultRow> endpoint_rows;
+  std::vector<GaussResultRow> gauss_rows;
+  std::vector<StressS11Row> stress_rows;
+};
+
+/// @brief Keeps physical shell rows separate from numerical drilling data.
+struct ShellElementResultRows {
+  std::vector<ShellResultRow> rows;
+  double physical_strain_energy{0.0};
+};
+
+/// @brief Selects the physical recovery shape of one runtime element.
+using ElementResultPayload =
+    std::variant<BeamElementResultRows, ShellElementResultRows>;
+
+/// @brief Carries stable source identity with one typed recovery payload.
+struct ElementResultBundle {
+  SourceEntityId source_id;
+  ElementResultPayload payload;
+};
+
+/// @brief Defines the numerical contract consumed by solver pipeline owners.
+class Element {
+ public:
+  virtual ~Element() = default;
+
+  /// @brief Returns the stable element-local DOF ordering.
+  virtual const ElementDofLayout& DofLayout() const noexcept = 0;
+
+  /// @brief Computes the finite stiffness in the declared local ordering.
+  virtual Result<ElementStiffnessContribution> ComputeStiffness() const = 0;
+
+  /// @brief Recovers typed physical rows from element-local global DOFs.
+  virtual Result<ElementResultBundle> Recover(
+      const Vector& element_displacement) const = 0;
+};
+
+/// @brief Provides non-owning runtime elements in stable owner order.
+/// @note Every referenced element must outlive this view.
+using ElementView = std::vector<std::reference_wrapper<const Element>>;
+
+}  // namespace fesa
+
+#endif  // FESA_ELEMENTS_ELEMENT_H_