SimulatorConfig.hpp

Go to the documentation of this file.

#pragma once

 
#include <icarus/core/ComponentConfig.hpp>
#include <icarus/core/CoreTypes.hpp>
#include <icarus/io/log/LogService.hpp>
#include <icarus/signal/SignalRouter.hpp>
#include <icarus/sim/PhaseManager.hpp>
#include <icarus/sim/integrators/IntegratorTypes.hpp>
 
#include <cmath>
#include <cstdint>
#include <set>
#include <string>
#include <unordered_map>
#include <unordered_set>
#include <utility>
#include <vector>
 
namespace icarus {
 
// =============================================================================
// Forward Declarations
// =============================================================================
 
struct EpochConfig;
struct TrimConfig;
struct LinearizationConfig;
struct SymbolicsConfig;
struct StageConfig;
struct SchedulerConfig;
struct OutputConfig;
struct SimulatorConfig;
 
// =============================================================================
// EpochConfig
// =============================================================================

struct EpochConfig {
    std::string system = "MET";

    std::string reference;

    double jd = 0.0;

    int gps_week = 0;

    double gps_seconds = 0.0;

    bool gps_configured = false;

    [[nodiscard]] bool IsConfigured() const {
        return !reference.empty() || jd > 0.0 || gps_configured;
    }

    [[nodiscard]] static EpochConfig Default() { return EpochConfig{}; }
};
 
// =============================================================================
// TrimConfig
// =============================================================================

struct TrimConfig {
    bool enabled = false; 

    std::string mode = "equilibrium";
 
    // =========================================================================
    // Equilibrium mode settings
    // =========================================================================

    std::vector<std::string> zero_derivatives; // e.g., ["velocity_dot", "angular_rate_dot"]

    std::vector<std::string> control_signals; // e.g., ["throttle", "elevator"]

    double tolerance = 1e-6;
    int max_iterations = 100;
    std::string method = "newton"; 

    std::unordered_map<std::string, double> initial_guesses;

    std::unordered_map<std::string, std::pair<double, double>> control_bounds;
 
    // =========================================================================
    // Warmstart mode settings
    // =========================================================================

    std::string recording_path;

    double resume_time = 0.0;

    bool validate_schema = true;
 
    // =========================================================================
    // Methods
    // =========================================================================

    [[nodiscard]] static TrimConfig Default() { return TrimConfig{}; }

    [[nodiscard]] bool IsWarmstart() const { return mode == "warmstart"; }

    [[nodiscard]] bool IsEquilibrium() const { return mode == "equilibrium"; }

    [[nodiscard]] std::vector<std::string> Validate() const {
        std::vector<std::string> errors;
        if (enabled) {
            if (mode == "equilibrium") {
                if (zero_derivatives.empty()) {
                    errors.push_back("Trim enabled but no zero_derivatives specified");
                }
                if (control_signals.empty()) {
                    errors.push_back("Trim enabled but no control_signals specified");
                }
                if (method != "newton" && method != "ipopt") {
                    errors.push_back("Unknown trim method: " + method);
                }
            } else if (mode == "warmstart") {
                if (recording_path.empty()) {
                    errors.push_back("Warmstart enabled but no recording_path specified");
                }
            } else {
                errors.push_back("Unknown trim mode: " + mode +
                                 " (expected 'equilibrium' or 'warmstart')");
            }
        }
        return errors;
    }
};
 
// =============================================================================
// LinearizationConfig
// =============================================================================

struct LinearizationConfig {
    bool enabled = false;

    std::vector<std::string> states;

    std::vector<std::string> inputs;

    std::vector<std::string> outputs;
 
    // Export options
    bool export_matlab = false;
    bool export_numpy = false;
    bool export_json = false;
    std::string output_dir;

    [[nodiscard]] static LinearizationConfig Default() { return LinearizationConfig{}; }

    [[nodiscard]] std::vector<std::string> Validate() const {
        std::vector<std::string> errors;
        if (enabled && states.empty()) {
            errors.push_back("Linearization enabled but no states specified");
        }
        return errors;
    }
};
 
// =============================================================================
// SymbolicsConfig
// =============================================================================

struct SymbolicsConfig {
    bool enabled = false;
    bool generate_dynamics = true;  
    bool generate_jacobian = false; 
    std::string output_dir;         

    [[nodiscard]] static SymbolicsConfig Default() { return SymbolicsConfig{}; }
};
 
// =============================================================================
// StageConfig
// =============================================================================

struct StageConfig {
    TrimConfig trim;
    LinearizationConfig linearization;
    SymbolicsConfig symbolics;
 
    // Validation settings
    bool validate_wiring = false; 
    bool warn_on_unwired = true;  

    [[nodiscard]] static StageConfig Default() { return StageConfig{}; }

    [[nodiscard]] std::vector<std::string> Validate() const {
        std::vector<std::string> errors;
        auto trim_errors = trim.Validate();
        errors.insert(errors.end(), trim_errors.begin(), trim_errors.end());
        auto lin_errors = linearization.Validate();
        errors.insert(errors.end(), lin_errors.begin(), lin_errors.end());
        return errors;
    }
};
 
// =============================================================================
// SchedulerConfig
// =============================================================================

enum class SchedulingMode {
    Automatic, 
    Explicit   
};

struct GroupMember {
    std::string component; 
    int priority = 0;      
 
    GroupMember() = default;
    GroupMember(std::string comp, int prio = 0) : component(std::move(comp)), priority(prio) {}
};

struct SchedulerGroupConfig {
    std::string name;
    double rate_hz = 400.0; 
    int priority = 0;       
    std::vector<GroupMember> members;

    std::set<int32_t> active_phases;
 
    SchedulerGroupConfig() = default;
    SchedulerGroupConfig(std::string n, double rate, int prio = 0)
        : name(std::move(n)), rate_hz(rate), priority(prio) {}

    [[nodiscard]] bool IsActiveInPhase(int32_t current_phase) const {
        return active_phases.empty() || active_phases.contains(current_phase);
    }
};

struct TopologyConfig {
    SchedulingMode mode = SchedulingMode::Explicit;
 
    enum class CycleHandling { Error, Warn, BreakAtDelay };
    CycleHandling cycle_detection = CycleHandling::Error;
    bool log_order = true; 
};

struct SchedulerConfig {
    std::vector<SchedulerGroupConfig> groups;
    TopologyConfig topology;

    std::unordered_map<std::string, int> group_frame_divisors;

    [[nodiscard]] static SchedulerConfig Default() {
        SchedulerConfig cfg;
        cfg.groups.emplace_back("default", 400.0, 0);
        return cfg;
    }

    [[nodiscard]] static SchedulerConfig FromFile(const std::string & /*yaml_path*/) {
        throw NotImplementedError("SchedulerConfig::FromFile - use SimulationLoader::Load()");
    }

    [[nodiscard]] double MaxRate() const {
        double max_rate = 0.0;
        for (const auto &group : groups) {
            if (group.rate_hz > max_rate) {
                max_rate = group.rate_hz;
            }
        }
        return max_rate > 0.0 ? max_rate : 400.0; // Default fallback
    }

    [[nodiscard]] std::vector<std::string> Validate() const {
        std::vector<std::string> errors;
 
        if (groups.empty()) {
            errors.push_back("No scheduler groups defined");
        }
 
        std::unordered_set<std::string> seen_components;
        std::unordered_set<std::string> seen_group_names;
 
        for (const auto &group : groups) {
            // Check for duplicate group names
            if (seen_group_names.count(group.name)) {
                errors.push_back("Duplicate group name: " + group.name);
            }
            seen_group_names.insert(group.name);
 
            // Check rate is positive
            if (group.rate_hz <= 0.0) {
                errors.push_back("Group '" + group.name +
                                 "' has invalid rate: " + std::to_string(group.rate_hz));
            }
 
            // Check for duplicate component assignments
            for (const auto &member : group.members) {
                if (seen_components.count(member.component)) {
                    errors.push_back("Component '" + member.component +
                                     "' assigned to multiple groups");
                }
                seen_components.insert(member.component);
            }
        }
 
        return errors;
    }

    [[nodiscard]] std::vector<std::string> ValidateGlobalTiming(double sim_rate_hz) const {
        std::vector<std::string> errors;
 
        for (const auto &group : groups) {
            // Group rate cannot exceed simulation rate
            if (group.rate_hz > sim_rate_hz) {
                errors.push_back("Group '" + group.name + "' rate " +
                                 std::to_string(group.rate_hz) + " Hz exceeds simulation rate " +
                                 std::to_string(sim_rate_hz) + " Hz");
            }
 
            // Group rate must be integer divisor of simulation rate
            double ratio = sim_rate_hz / group.rate_hz;
            if (std::abs(ratio - std::round(ratio)) > 1e-9) {
                errors.push_back("Group '" + group.name + "' rate " +
                                 std::to_string(group.rate_hz) +
                                 " Hz is not an integer divisor of simulation rate " +
                                 std::to_string(sim_rate_hz) + " Hz");
            }
        }
 
        return errors;
    }

    void ComputeFrameDivisors(double sim_rate_hz) {
        group_frame_divisors.clear();
        for (const auto &group : groups) {
            int divisor = static_cast<int>(std::round(sim_rate_hz / group.rate_hz));
            group_frame_divisors[group.name] = divisor;
        }
    }
};
 
// =============================================================================
// OutputConfig
// =============================================================================

struct OutputConfig {
    std::string directory = "./output";
 
    // Data dictionary
    bool data_dictionary = true;
    std::string data_dictionary_format = "yaml"; 
 
    // Telemetry
    bool telemetry = true;
    std::string telemetry_format = "hdf5"; 
 
    // Timing reports
    bool timing_report = false;

    [[nodiscard]] static OutputConfig Default() { return OutputConfig{}; }
};
 
// =============================================================================
// RecordingConfig
// =============================================================================

struct RecordingConfig {
    bool enabled = false;

    std::string path = "output/recording.h5";

    std::string mode = "outputs";

    std::vector<std::string> include;

    std::vector<std::string> exclude;

    bool include_derivatives = false;

    bool include_inputs = false;

    int flush_interval = 0;

    int decimation = 1;

    bool export_csv = false;

    [[nodiscard]] static RecordingConfig Default() { return RecordingConfig{}; }

    [[nodiscard]] bool IsActive() const { return enabled && mode != "off"; }

    [[nodiscard]] std::vector<std::string> Validate() const {
        std::vector<std::string> errors;
        if (enabled) {
            if (decimation < 1) {
                errors.push_back("Recording decimation must be >= 1");
            }
            if (mode != "off" && mode != "all" && mode != "outputs" && mode != "signals") {
                errors.push_back("Unknown recording mode: " + mode);
            }
            if (mode == "signals" && include.empty()) {
                errors.push_back("Recording mode 'signals' requires include patterns");
            }
        }
        return errors;
    }
};
 
// =============================================================================
// EntityTemplate
// =============================================================================

struct EntityTemplate {
    std::string name;        
    std::string description; 

    std::vector<ComponentConfig> components;

    std::vector<signal::SignalRoute> routes;

    SchedulerConfig scheduler;

    StageConfig staging;

    static EntityTemplate FromFile(const std::string &yaml_path);
};
 
// =============================================================================
// EntityInstance
// =============================================================================

struct EntityInstance {
    EntityTemplate entity_template;

    std::string name;

    std::unordered_map<std::string, ComponentConfig> overrides;
};
 
// =============================================================================
// SwarmConfig
// =============================================================================

struct SwarmConfig {
    EntityTemplate entity_template;

    std::string name_prefix;

    int count = 1;
 
    // Future: per-instance overrides with Jinja-style templating
    // Future: swarm-internal routes (neighbor connections)
};
 
// =============================================================================
// EntitySystemConfig
// =============================================================================

struct EntitySystemConfig {
    std::vector<EntityInstance> entities;
    std::vector<SwarmConfig> swarms;
    std::vector<signal::SignalRoute> cross_entity_routes;

    std::vector<std::string> entity_order;
    bool auto_order = true;

    std::tuple<std::vector<ComponentConfig>, std::vector<signal::SignalRoute>, SchedulerConfig>
    ExpandAll() const;
};
 
// =============================================================================
// SimulatorConfig
// =============================================================================

struct SimulatorConfig {
    // =========================================================================
    // Identity
    // =========================================================================
    std::string name = "Simulation";
    std::string version = icarus::Version();
    std::string description;
    std::string source_file; 
 
    // =========================================================================
    // Time
    // =========================================================================
    double t_start = 0.0;
    double t_end = 100.0;
    double dt = 0.01; 

    EpochConfig epoch;
 
    // =========================================================================
    // Components (flattened from entity expansion)
    // =========================================================================
    std::vector<ComponentConfig> components;
 
    // =========================================================================
    // Signal Routing (flattened from entity expansion)
    // =========================================================================
    std::vector<signal::SignalRoute> routes;
 
    // =========================================================================
    // Scheduler
    // =========================================================================
    SchedulerConfig scheduler = SchedulerConfig::Default();
 
    // =========================================================================
    // Staging (Trim + Linearization + Symbolics)
    // =========================================================================
    StageConfig staging;
 
    // =========================================================================
    // Phase Management
    // =========================================================================
    PhaseConfig phases;
 
    // =========================================================================
    // Integrator
    // =========================================================================
    IntegratorConfig<double> integrator = IntegratorConfig<double>::RK4Default();
 
    // =========================================================================
    // Logging
    // =========================================================================
    LogConfig logging;
 
    // =========================================================================
    // Recording (HDF5 telemetry)
    // =========================================================================
    RecordingConfig recording;
 
    // =========================================================================
    // Output
    // =========================================================================
    OutputConfig output;
 
    // =========================================================================
    // Factory Methods
    // =========================================================================

    [[nodiscard]] static SimulatorConfig Default() { return SimulatorConfig{}; }

    [[nodiscard]] static SimulatorConfig FromFile(const std::string &path);

    [[nodiscard]] static SimulatorConfig FromFiles(const std::string & /*master_path*/,
                                                   const std::string & /*routes_path*/) {
        throw NotImplementedError("SimulatorConfig::FromFiles - use SimulationLoader::Load()");
    }

    [[nodiscard]] std::vector<std::string> Validate() const {
        std::vector<std::string> errors;
 
        // Time validation
        if (t_end <= t_start) {
            errors.push_back("t_end must be greater than t_start");
        }
        if (dt <= 0.0) {
            errors.push_back("dt must be positive");
        }
 
        // Sub-config validation
        auto sched_errors = scheduler.Validate();
        errors.insert(errors.end(), sched_errors.begin(), sched_errors.end());
 
        auto stage_errors = staging.Validate();
        errors.insert(errors.end(), stage_errors.begin(), stage_errors.end());
 
        return errors;
    }
};
 
} // namespace icarus