FESADev/include/fesa/elements/euler_beam_3d.h

#ifndef FESA_ELEMENTS_EULER_BEAM_3D_H_
#define FESA_ELEMENTS_EULER_BEAM_3D_H_

#include <array>
#include <cstddef>
#include <string>
#include <string_view>
#include <vector>

#include "fesa/core/status.h"
#include "fesa/elements/element.h"
#include "fesa/elements/element_definition.h"
#include "fesa/materials/isotropic_linear_elastic_material.h"
#include "fesa/math/matrix.h"
#include "fesa/math/vector.h"
#include "fesa/properties/general_beam_section.h"

namespace fesa {

class Domain;
struct Node;

/// @brief Defines one two-node B33 semantic element.
class EulerBeam3DDefinition final : public ElementDefinition {
 public:
  /// @brief Constructs a parser-validated semantic definition.
  EulerBeam3DDefinition(SourceEntityId source_id,
                        std::array<EntityIndex, 2> node_indices,
                        EntityIndex material_index, EntityIndex section_index,
                        SourceLocation location);

  ElementDefinitionKind Kind() const noexcept override;
  const SourceEntityId& SourceId() const noexcept override;
  std::string_view SourceElementType() const noexcept override;
  const std::vector<EntityIndex>& NodeIndices() const noexcept override;
  EntityIndex MaterialIndex() const noexcept override;
  EntityIndex PropertyIndex() const noexcept override;

  SourceEntityId source_id;
  std::array<EntityIndex, 2> node_indices;
  EntityIndex material_index;
  EntityIndex section_index;
  SourceLocation location;

 private:
  friend class Domain;

  /// @brief Synchronizes the base view after parser-candidate construction.
  void SynchronizeNodeIndices();

  std::vector<EntityIndex> node_indices_view_;
};

/// @brief Stores constant line-load components in the beam local frame.
struct ConstantLocalLineLoad {
  double px;
  double py;
  double pz;
  double mx;
};

/// @brief Stores one axial stress at a Gauss and section-point identity.
struct BeamStressPoint {
  int gauss_point;
  std::size_t section_point;
  double x1;
  double x2;
  double s11;
  std::string source;
};

/// @brief Stores distinct beam end-action, section, Gauss, and stress results.
struct BeamRecovery {
  std::array<std::array<double, 6>, 2> equilibrium_end_actions;
  std::array<std::array<double, 4>, 2> endpoint_section_resultants;
  std::array<std::array<double, 4>, 2> gauss_generalized_strains;
  std::array<std::array<double, 4>, 2> gauss_generalized_resultants;
  std::vector<BeamStressPoint> stress_points;
};

/// @brief Implements the approved two-node prismatic B33 Euler beam kernel.
/// @note Equation numbering and semantic element identity remain external.
class EulerBeam3D final : public Element {
 public:
  /// @brief Creates a validated beam kernel and right-handed local frame.
  /// @param first_node First source node in the element connectivity.
  /// @param second_node Second source node in the element connectivity.
  /// @param section Supported general beam section and local first axis.
  /// @param material Supported isotropic elastic material.
  /// @return A validated beam or a structured model failure.
  static Result<EulerBeam3D> Create(const Node& first_node,
                                    const Node& second_node,
                                    const GeneralBeamSection& section,
                                    const LinearElasticMaterial& material);

  /// @brief Returns the factory-bound B33 DOF order.
  const ElementDofLayout& DofLayout() const noexcept override;

  /// @brief Computes global B33 stiffness through the runtime contract.
  Result<ElementStiffnessContribution> ComputeStiffness() const override;

  /// @brief Recovers typed B33 rows through the runtime contract.
  Result<ElementResultBundle> Recover(
      const Vector& element_displacement) const override;

  /// @brief Computes the 12-by-12 stiffness in local DOF order.
  /// @note Uses the approved two-point Gauss operation order.
  Matrix LocalStiffness() const;

  /// @brief Computes the stiffness in stable global element DOF order.
  Matrix GlobalStiffness() const;

  /// @brief Computes the formulation-only constant local line-load vector.
  /// @warning This kernel does not expose distributed loads through parser
  /// input.
  Vector LocalEquivalentLoad(const ConstantLocalLineLoad& load) const;

  /// @brief Recovers signed physical quantities at their distinct locations.
  /// @param global_element_displacement Twelve global element DOF values.
  /// @return Beam recovery rows in deterministic location order.
  BeamRecovery RecoverBeam(const Vector& global_element_displacement) const;

 private:
  friend class ElementFactory;

  /// @brief Binds Domain identity after the numerical candidate is valid.
  void BindRuntime(ElementDofLayout layout, EntityIndex element_index,
                   std::vector<SourceEntityId> node_source_ids,
                   SourceLocation location);

  /// @brief Stores already validated geometry, material, and section state.
  EulerBeam3D(double length, double youngs_modulus, double shear_modulus,
              double area, double iy, double iz, double torsional_constant,
              std::array<double, 9> rotation,
              std::vector<std::array<double, 2>> section_points);

  double length_;
  double youngs_modulus_;
  double shear_modulus_;
  double area_;
  double iy_;
  double iz_;
  double torsional_constant_;
  std::array<double, 9> rotation_;
  std::vector<std::array<double, 2>> section_points_;
  ElementDofLayout dof_layout_;
  EntityIndex element_index_{0U};
  std::vector<SourceEntityId> node_source_ids_;
  SourceLocation runtime_location_;
};

}  // namespace fesa

#endif  // FESA_ELEMENTS_EULER_BEAM_3D_H_