feat(cpp-object-oriented-modular-refactoring): step 18 - load-hierarchy

include/fesa/analysis/analysis_model.h

@@ -21,7 +21,7 @@ class AnalysisModel {
   const Domain& GetDomain() const noexcept;
 
   /// @brief Returns the sole active static step.
-  const StaticStepDefinition& Step() const noexcept;
+  const StepDefinition& Step() const noexcept;
 
   /// @brief Returns active element-definition indices in stable Domain order.
   const std::vector<EntityIndex>& ActiveElements() const noexcept;

include/fesa/assembly/load_assembler.h

@@ -3,6 +3,7 @@
 
 #include "fesa/analysis/analysis_model.h"
 #include "fesa/fem/dof_manager.h"
+#include "fesa/loads/load.h"
 #include "fesa/math/sparse_matrix.h"
 #include "fesa/math/vector.h"
 
@@ -16,6 +17,14 @@ class LoadAssembler {
   static Result<Vector> AssembleFullNodalLoad(const AnalysisModel& model,
                                               const DofManager& dofs);
 
+  /// @brief Accumulates explicitly supplied loads in their view order.
+  /// @param loads Non-owning loads whose contribution source orders must match
+  /// their view positions.
+  /// @return A candidate committed only after all contributions validate.
+  static Result<Vector> AssembleFullNodalLoad(const AnalysisModel& model,
+                                              const DofManager& dofs,
+                                              const LoadView& loads);
+
   /// @brief Forms Ff-Kfc*dc in stable free/constrained order.
   /// @note This operation neither factorizes nor invokes a solver.
   static Result<Vector> EffectiveFreeRhs(const Vector& full_load,

include/fesa/loads/concentrated_nodal_load.h

@@ -0,0 +1,52 @@
+#ifndef FESA_LOADS_CONCENTRATED_NODAL_LOAD_H_
+#define FESA_LOADS_CONCENTRATED_NODAL_LOAD_H_
+
+#include <array>
+#include <cstddef>
+
+#include "fesa/core/diagnostic.h"
+#include "fesa/loads/load.h"
+#include "fesa/model/source_target_resolver.h"
+
+namespace fesa {
+
+/// @brief Emits global concentrated nodal components for one source target.
+class ConcentratedNodalLoad final : public Load {
+ public:
+  /// @brief Creates a six-component global concentrated nodal load.
+  ConcentratedNodalLoad(SourceTargetQuery target,
+                        std::array<double, 6> global_components,
+                        std::size_t source_order);
+
+  /// @brief Creates one parsed CLOAD component while preserving diagnostics.
+  ConcentratedNodalLoad(SourceTargetQuery target, int source_dof,
+                        double magnitude, std::size_t source_order,
+                        SourceLocation location);
+
+  /// @brief Computes target-major, component-minor full-DOF contributions.
+  Result<std::vector<LoadContribution>> ComputeContributions(
+      const LoadContext& context) const override;
+
+  /// @brief Returns the immutable source target query.
+  const SourceTargetQuery& Target() const noexcept;
+
+  /// @brief Returns six global force/moment components without reordering.
+  const std::array<double, 6>& GlobalComponents() const noexcept;
+
+  /// @brief Returns the stable CLOAD declaration order.
+  std::size_t SourceOrder() const noexcept;
+
+  /// @brief Returns the source location used by structured diagnostics.
+  const SourceLocation& Location() const noexcept;
+
+ private:
+  SourceTargetQuery target_;
+  std::array<double, 6> global_components_{};
+  std::size_t source_order_;
+  SourceLocation location_{};
+  int source_dof_{0};
+};
+
+}  // namespace fesa
+
+#endif  // FESA_LOADS_CONCENTRATED_NODAL_LOAD_H_

include/fesa/loads/load.h

@@ -0,0 +1,48 @@
+#ifndef FESA_LOADS_LOAD_H_
+#define FESA_LOADS_LOAD_H_
+
+#include <cstddef>
+#include <functional>
+#include <vector>
+
+#include "fesa/core/status.h"
+
+namespace fesa {
+
+class DofManager;
+class Domain;
+class SourceTargetResolver;
+
+/// @brief Describes one ordered contribution to the full load vector.
+struct LoadContribution {
+  std::size_t source_order;
+  std::size_t full_dof_index;
+  double value;
+};
+
+/// @brief Provides immutable semantic and equation context to a Load.
+/// @note Every referenced object must outlive a contribution request.
+struct LoadContext {
+  const Domain& domain;
+  const DofManager& dof_manager;
+  const SourceTargetResolver& target_resolver;
+};
+
+/// @brief Produces local ordered load contributions without global mutation.
+class Load {
+ public:
+  virtual ~Load() = default;
+
+  /// @brief Computes finite full-DOF contributions in stable target order.
+  /// @param context Non-owning semantic and equation context for this call.
+  /// @return Ordered contributions or a structured model failure.
+  virtual Result<std::vector<LoadContribution>> ComputeContributions(
+      const LoadContext& context) const = 0;
+};
+
+/// @brief Holds non-owning loads in an explicitly supplied source order.
+using LoadView = std::vector<std::reference_wrapper<const Load>>;
+
+}  // namespace fesa
+
+#endif  // FESA_LOADS_LOAD_H_

include/fesa/model/domain.h

@@ -8,10 +8,14 @@
 #include <vector>
 
 #include "fesa/core/status.h"
+#include "fesa/loads/concentrated_nodal_load.h"
+#include "fesa/loads/load.h"
 #include "fesa/model/model_types.h"
 
 namespace fesa {
 
+class StepDefinition;
+
 /// @brief Exposes immutable references without transferring Domain ownership.
 /// @tparam T Base or concrete semantic type stored by the Domain.
 template <class T>
@@ -33,6 +37,7 @@ class DomainCollectionView {
 
  private:
   friend class Domain;
+  friend class StepDefinition;
 
   /// @brief Adds one reference while the owning Domain candidate is built.
   void Add(const T& entry) { entries_.push_back(&entry); }
@@ -40,6 +45,62 @@ class DomainCollectionView {
   std::vector<const T*> entries_;
 };
 
+/// @brief Owns one immutable static-step semantic definition.
+/// @note Loads retain source order and are owned polymorphically by unique
+/// pointers.
+class StepDefinition {
+ public:
+  StepDefinition(const StepDefinition&) = delete;
+  StepDefinition& operator=(const StepDefinition&) = delete;
+  StepDefinition(StepDefinition&&) noexcept = default;
+  StepDefinition& operator=(StepDefinition&&) noexcept = default;
+
+  /// @brief Returns the source step name.
+  const std::string& Name() const noexcept;
+
+  /// @brief Returns current boundary records in declaration order.
+  const std::vector<BoundaryCondition>& Boundaries() const noexcept;
+
+  /// @brief Returns polymorphic loads in stable source order.
+  const LoadView& Loads() const noexcept;
+
+  /// @brief Returns current concentrated loads in stable source order.
+  const DomainCollectionView<ConcentratedNodalLoad>& ConcentratedLoads()
+      const noexcept;
+
+  /// @brief Returns the static initial increment provenance value.
+  double InitialIncrement() const noexcept;
+
+  /// @brief Returns the static time-period provenance value.
+  double TimePeriod() const noexcept;
+
+  /// @brief Returns the static minimum-increment provenance value.
+  double MinimumIncrement() const noexcept;
+
+  /// @brief Returns the static maximum-increment provenance value.
+  double MaximumIncrement() const noexcept;
+
+  /// @brief Returns the source location of the step declaration.
+  const SourceLocation& Location() const noexcept;
+
+ private:
+  friend class Domain;
+
+  /// @brief Converts one parsed static-step record to owned semantic objects.
+  explicit StepDefinition(StaticStepDefinition definition);
+
+  std::string name_;
+  std::vector<BoundaryCondition> boundaries_;
+  std::vector<std::unique_ptr<Load>> loads_;
+  LoadView loads_view_;
+  DomainCollectionView<ConcentratedNodalLoad> concentrated_loads_view_;
+  double initial_increment_;
+  double time_period_;
+  double minimum_increment_;
+  double maximum_increment_;
+  SourceLocation location_;
+};
+
 /// @brief Owns the complete immutable semantic model definition.
 /// @note Collection positions remain stable internal indices after
 /// construction.
@@ -96,7 +157,7 @@ class Domain {
   const std::vector<ElementSet>& ElementSets() const noexcept;
 
   /// @brief Returns static steps in stable declaration order.
-  const std::vector<StaticStepDefinition>& Steps() const noexcept;
+  const DomainCollectionView<StepDefinition>& Steps() const noexcept;
 
   /// @brief Returns sorted nonfatal mapping diagnostics.
   const std::vector<Diagnostic>& Warnings() const noexcept;
@@ -115,6 +176,7 @@ class Domain {
   std::vector<std::unique_ptr<ElementDefinition>> element_definitions_;
   std::vector<std::unique_ptr<ElementProperty>> element_properties_;
   std::vector<std::unique_ptr<Material>> materials_;
+  std::vector<std::unique_ptr<StepDefinition>> step_definitions_;
   DomainCollectionView<ElementDefinition> elements_view_;
   DomainCollectionView<EulerBeam3DDefinition> beam_elements_view_;
   DomainCollectionView<Mitc4ShellDefinition> shell_elements_view_;
@@ -123,6 +185,7 @@ class Domain {
   DomainCollectionView<ShellSection> shell_sections_view_;
   DomainCollectionView<Material> materials_view_;
   DomainCollectionView<LinearElasticMaterial> linear_materials_view_;
+  DomainCollectionView<StepDefinition> steps_view_;
 };
 
 }  // namespace fesa