Component.hpp

Go to the documentation of this file.

#pragma once

 
#include <icarus/core/ComponentConfig.hpp>
#include <icarus/core/CoreTypes.hpp>
#include <icarus/core/Error.hpp>
#include <janus/math/Quaternion.hpp>
#include <string>
#include <vector>
#include <vulcan/time/Epoch.hpp>
 
namespace icarus {
 
// Forward declarations
template <typename Scalar> class Backplane;

struct SignalDecl {
    std::string name;        
    std::string unit;        
    std::string description; 
    bool is_input = false;   
};

template <typename Scalar> class Component {
  public:
    virtual ~Component() = default;
 
    // =========================================================================
    // Core Lifecycle (Required)
    // =========================================================================

    virtual void Provision(Backplane<Scalar> &bp) = 0;

    virtual void Stage(Backplane<Scalar> &bp) = 0;

    virtual void Step(Scalar t, Scalar dt) = 0;
 
    // =========================================================================
    // Extended Lifecycle Hooks (Optional)
    // =========================================================================

    virtual void PreStep(Scalar /*t*/, Scalar /*dt*/) {}

    virtual void PostStep(Scalar /*t*/, Scalar /*dt*/) {}

    virtual void OnError(const SimulationError & /*error*/) {}

    virtual void Shutdown() {}
 
    // =========================================================================
    // Identity & Introspection
    // =========================================================================

    [[nodiscard]] virtual std::string Name() const = 0;

    [[nodiscard]] virtual std::string Entity() const { return ""; }

    [[nodiscard]] virtual std::string TypeName() const { return Name(); }

    [[nodiscard]] std::string FullName() const { return MakeFullPath(Entity(), Name()); }

    [[nodiscard]] virtual std::vector<SignalDecl> DeclareInputs() const { return {}; }

    [[nodiscard]] virtual std::vector<SignalDecl> DeclareOutputs() const { return {}; }

    [[nodiscard]] std::vector<std::string> GetOutputNames() const {
        std::vector<std::string> names;
        for (const auto &decl : DeclareOutputs()) {
            names.push_back(decl.name);
        }
        return names;
    }

    [[nodiscard]] std::vector<std::string> GetInputNames() const {
        std::vector<std::string> names;
        for (const auto &decl : DeclareInputs()) {
            names.push_back(decl.name);
        }
        return names;
    }
 
    // =========================================================================
    // Body Attachment API
    // =========================================================================

    [[nodiscard]] virtual bool HasBodyAttachment() const { return false; }

    [[nodiscard]] virtual Vec3<Scalar> GetBodyPosition() const { return Vec3<Scalar>::Zero(); }

    [[nodiscard]] virtual janus::Quaternion<Scalar> GetBodyOrientation() const {
        return janus::Quaternion<Scalar>();
    }
 
    // =========================================================================
    // Lifecycle State
    // =========================================================================

    [[nodiscard]] bool IsProvisioned() const { return provisioned_; }

    [[nodiscard]] bool IsStaged() const { return staged_; }
 
    // =========================================================================
    // Configuration Access
    // =========================================================================

    void SetConfig(ComponentConfig config) { config_ = std::move(config); }

    [[nodiscard]] const ComponentConfig &GetConfig() const { return config_; }

    [[nodiscard]] const vulcan::time::Epoch<Scalar> *GetEpoch() const { return epoch_; }
 
  protected:
    // =========================================================================
    // Configuration Helpers
    // =========================================================================
    // These simplify reading config values in Stage() by:
    // - Eliminating redundant Has/Get patterns
    // - Automatically handling double→Scalar conversion for vectors
    // - Providing a clean one-liner API

    template <typename T> T read_param(const std::string &key, const T &default_val) const {
        return config_.template Get<T>(key, default_val);
    }

    template <typename T> T require_param(const std::string &key) const {
        return config_.template Require<T>(key);
    }

    Vec3<Scalar> read_param_vec3(const std::string &key, const Vec3<Scalar> &default_val) const {
        if (!config_.template Has<Vec3<double>>(key)) {
            return default_val;
        }
        auto v = config_.template Get<Vec3<double>>(key, Vec3<double>::Zero());
        return Vec3<Scalar>{static_cast<Scalar>(v(0)), static_cast<Scalar>(v(1)),
                            static_cast<Scalar>(v(2))};
    }

    Vec3<Scalar> require_param_vec3(const std::string &key) const {
        auto v = config_.template Require<Vec3<double>>(key);
        return Vec3<Scalar>{static_cast<Scalar>(v(0)), static_cast<Scalar>(v(1)),
                            static_cast<Scalar>(v(2))};
    }

    Vec4<Scalar> read_param_vec4(const std::string &key, const Vec4<Scalar> &default_val) const {
        if (!config_.template Has<Vec4<double>>(key)) {
            return default_val;
        }
        auto v = config_.template Get<Vec4<double>>(key, Vec4<double>::Zero());
        return Vec4<Scalar>{static_cast<Scalar>(v(0)), static_cast<Scalar>(v(1)),
                            static_cast<Scalar>(v(2)), static_cast<Scalar>(v(3))};
    }

    Vec4<Scalar> require_param_vec4(const std::string &key) const {
        auto v = config_.template Require<Vec4<double>>(key);
        return Vec4<Scalar>{static_cast<Scalar>(v(0)), static_cast<Scalar>(v(1)),
                            static_cast<Scalar>(v(2)), static_cast<Scalar>(v(3))};
    }
 
    // =========================================================================
    // Lifecycle State Management
    // =========================================================================
 
    // Called by Simulator to track lifecycle state
    void MarkProvisioned() { provisioned_ = true; }
    void MarkStaged() { staged_ = true; }
    void ResetStaged() { staged_ = false; }
 
    // Called by Backplane during Stage() to bind epoch reference
    void BindEpoch(const vulcan::time::Epoch<Scalar> *epoch) { epoch_ = epoch; }
 
    // Allow Simulator to call Mark* methods
    template <typename S> friend class Simulator;
    friend class Simulator; // Non-templated Simulator (Phase 4.0.7)
    template <typename S> friend class Backplane;
 
  private:
    ComponentConfig config_;
    const vulcan::time::Epoch<Scalar> *epoch_ = nullptr;
    bool provisioned_ = false;
    bool staged_ = false;
};
 
} // namespace icarus