SimulationExecutive.h

/******************************************************************************
* Copyright (c) ATTX LLC 2024. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, LLC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, LLC.
******************************************************************************/
/*
Simulation Executive header file
 
Author: Alex Reynolds
*/
#ifndef SIMULATION_EXECUTIVE_H
#define SIMULATION_EXECUTIVE_H
 
#include "architecture/Executive.h"
#include "six_dof_dynamics/Frame.hpp"
#include "six_dof_dynamics/Body.hpp"
#include "six_dof_dynamics/Node.hpp"
#include "core/clockwerkerrors.h"
#include "simulation/SimScheduler.h"
#include "monitors/TimeTriggerMonitor.h"
#include "events/SimTerminationEvent.h"
#include "simulation/ArgParser.h"
#include "simulation/DispersionEngine.h"
#include "simulation/SimTimeManager.h"
#include "logging/LogManager.h"
#include "simulation/VisualsModel.h"
#include "utils/spiceutils.h"
 
namespace modelspace {
 
    class Monitor;
 
    /// @brief   Implementation of the executive class for simulation
    /// 
    /// The SimulationExecutive is a specific implementation of the 
    /// Executive base class for simulation. It contains specified
    /// implementations of the scheduler, a frame tree and associated
    /// search functions, and functions for logging and integration
    /// setup.
    ///
    /// The simulation executive also controls visuals, if the user
    /// chooses to enable them. They are inactive by default.
    ///
    /// Command line arguments that can be set on simulation executive
    /// "end" - The simulation end time, as a double
    /// "run" - The run number for Monte Carlo simulation. Run 0 is the "default"
    /// "out-dir" - The output directory to which results should be dumped
    /// "use-spice" - A flag indicating whether SPICE should be used. Default is true
    ///
    /// With regards to SPICE, the simulation executive loads by default the
    /// kernels provided in utils/spiceutils.h. Users may command the simulation
    /// executive to load more kernels using the function loadSpiceKernels
    class SimulationExecutive : public clockwerk::Executive {
    public:
        /// @brief   Constructor for the simulation executive
        SimulationExecutive();
        ~SimulationExecutive();
 
        /// @brief Wrapper around arg parse
        /// @param argc C++ argc input
        /// @param argv C++ argv input
        /// @return Error code corresponding to success/failure
        int parseArgs(int argc, char *argv[]);
 
        /// @brief Wrapper around arg parse
        /// @param args A std::vector of arguments
        /// @return Error code corresponding to success/failure
        int parseArgs(std::vector<std::string> arguments);
 
        /// Functions to set and get our integrator
        void integrator(int val) {_sim_scheduler.params.integrator_type(val);}
        int integrator() {return _sim_scheduler.params.integrator_type();}
 
        /// @brief   Function to set the simulation run rate, in Hz
        /// @param   rate_hz     The simulation run rate, in Hz
        void setRateHz(unsigned int rate_hz);
 
        /// @brief   Function to set the simulation run rate, in seconds as Time
        /// @param   rate_sec    The simulation run rate as a timespec with seconds, nanoseconds
        void setRateSec(clockwerk::Time rate_sec);
        void setRateSec(struct timespec rate_sec);
        void setRateSec(double rate_sec);
 
        /// @brief   Overloaded function to set the simulation end time
        /// @param   end_time    The end time in its respective format
        void end(clockwerk::Time end_time);
        void end(struct timespec end_time);
        void end(double end_time);
 
        /// @brief   Function to return simulation end time
        /// @return  End time, as a Time class
        clockwerk::Time end() {return _term_monitor.params.trigger_time();}
 
        /// @brief   Function to initialize our simulation executive and everything
        ///          it contains
        /// @return  Error code corresponding to success/failure
        int startup();
 
        /// @brief   Function to step the scheduler by a single step
        /// @return  Error code corresponding to success/failure
        int step();
 
        /// @brief   Function to step the scheduler by a single step
        /// @param   step_size The step size (as a time object) to step the sim by
        /// @return  Error code corresponding to success/failure
        int step(const clockwerk::Time &step_size);
 
        /// /  @brief   Function to execute run for the executive and its kids
        /// /  @return  Error code corresponding to success/failure
        int run();
 
        /// @brief   Function to acces the run rate of the simulation
        /// @return  The rate of the simulation
        clockwerk::Time rate() {return _sim_scheduler.inputs.rate();}
 
        /// @brief   Getter for the simulation root frame
        clockwerk::Frame<double>* rootFrame() {return &_root_frame;}
 
        /// @brief   Function to search the simulation and frame trees for 
        ///          a match
        /// @param   s_val   The value to search for
        /// @return  A vector of string addresses matching the query
        /// @note    Returns string addresses -- user must get address and
        ///          cast appropriately if they wish to use appropriate type
        std::vector<std::string> search(const std::string &s_val);
 
        /// @brief   Function to search the frame tree for a match
        /// @param   s_val   The value to search for
        /// @return  A vector of string addresses matching the query
        /// @note    Returns string addresses -- user must get address and
        ///          cast appropriately if they wish to use appropriate type
        std::vector<std::string> searchFrameTree(const std::string &s_val);
 
        /// @brief   Function to search the simulation architecture tree for a match
        /// @param   s_val   The value to search for
        /// @return  A vector of string addresses matching the query
        /// @note    Returns string addresses -- user must get address and
        ///          cast appropriately if they wish to use appropriate type
        std::vector<std::string> searchSimTree(const std::string &s_val);
 
        /// Getter for the log manager
        modelspace::LogManager* logManager() {return &_log_manager;}
 
        /// @brief   Overloaded function to register and set up a logger
        /// @param   log     The logger to add to the sim
        /// @param   rate    The rate, in Hz, at which the logger should log
        void addLog(clockwerk::SimLogger &log, unsigned int rate) {_log_manager.addLog(log, rate);}
 
        /// @brief   Overloaded function to register and set up a logger
        /// @param   log     The logger to add to the sim
        /// @param   monitor The monitor which triggers the logger
        void addLog(clockwerk::SimLogger &log, clockwerk::Monitor &monitor) {_log_manager.addLog(log, monitor);}
 
        /// Getter for the schedule
        modelspace::SimScheduler* schedule() {return &_sim_scheduler;}
 
        /// Getter for the visuals model
        modelspace::VisualsModel* visualsModel() {return _visuals_model;}
 
        /// @brief Function to enable visuals for the simulation
        void enableVisuals();
 
        /// @brief Function to disable visuals for the simulation
        /// @note  Shouldn't need to call this unless visuals were already enabled
        void disableVisuals();
 
        /// @brief Function to set the local model log level
        /// @param new_level The new level to set logging to
        void logLevel(clockwerk::log_level_e new_level) {_local_log_level = new_level;}
 
        /// @brief Returns termination flag
        /// @return Termination flag
        bool isTerminated() {return _sim_scheduler.isTerminated();}
 
        /// @brief Getter for run number
        /// @return The run number 
        unsigned int runNumber() {return _run_num;}
 
        /// @brief Setter for run number
        /// @return The run number 
        void runNumber(unsigned int run_num) {_run_num = run_num;}
 
        /// @brief Function to access args
        /// @return Pointer to arguments
        modelspace::ArgParser* args() {return &_args;}
 
        /// @brief Function to access dispersions
        /// @return Pointer to dispersions
        modelspace::DispersionEngine* dispersions() {return &_dispersion_engine;}
 
        /// @brief Override of time() from executive to return SimTimeManager
        /// @return A pointer to the sim time manager.
        modelspace::SimTimeManager* time() {return &_sim_scheduler.time;}
 
        /// @brief Function to access sim time
        /// @return Current sim time
        double simTime() {return time()->base_time().asDouble();}
 
        /// @brief Function to return pointer to the spice manager
        /// @return Pointer to the spice manager
        modelspace::SpiceManager* spiceManager() {return &_spice_manager;}
 
        /// @brief Function to set time by string input
        /// @param time_input The string input by which time will be set. 
        ///                   valid inputs are any input which is accepted
        ///                   by the SPICE function STR2ET. More info here:
        ///                   https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/spicelib/str2et.html
        ///                   This value defaults to 2023 September 26, 12:00:00 MDT
        void setTime(const std::string &time_in) {time()->setTime(time_in);}
 
        /// @brief Function to return whether the simulation executive is started
        /// @return True if started, false if not
        bool started() {return _started;}
 
    protected:
        /// @brief Function to configure simulation executive from command line input
        void _configureFromCmdLine();
 
        /// @brief Function to print information associated with the simulation
        void _printSimInfo();
 
        /// @brief Pointer to the executive object, which for sim executive is self
        /// This feature included for easy logging and consistent access accross modules
        clockwerk::Executive* exc;
 
        /// @brief To parse our command line arguments
        ArgParser _args;
 
        /// @brief To generate dispersions for the simulation
        DispersionEngine _dispersion_engine;
        int _rng_seed = 0;
 
        /// The run number
        unsigned int _run_num = 0;
 
        /// @brief This is our sim's root frame, from which all other frames derive their relationships
        ///
        /// The root frame within the simulation executive is an arbitrary frame
        /// relative to which all frames are defined. When SPICE is active in the
        /// simulation executive the root frame is treated as the root of the 
        /// J2000 frame, and all planets will be set relative to that point.
        clockwerk::Frame<double> _root_frame;
 
        /// Specific declarations of scheduler, etc. specific to the simulation
        /// executive
        LogManager _log_manager;
        SimScheduler _sim_scheduler;
 
        /// The spice manager to control all spice interactions
        SpiceManager _spice_manager;
 
        /// Monitor and event to terminate sim run
        TimeTriggerMonitor _term_monitor;
        SimTerminationEvent _term_event;
 
        /// Pointer to our visuals manager
        VisualsModel* _visuals_model = nullptr;
 
        /// Our local log level -- allows a higher log level locally than the overall system
        clockwerk::log_level_e _local_log_level = clockwerk::NONE;
 
        /// Flag to indicate whether the executive has been properly started.
        /// Executive will not run unless startup has been called.
        bool _started = false;
 
        /// Variable to track the number of steps the simulation has taken
        unsigned long long _step_count = 0;
    };
 
}
 
#endif