SimLogger.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.
******************************************************************************/
/*
Logger header file
 
Author: Alex Reynolds
*/
#ifndef SIM_LOGGER_H
#define SIM_LOGGER_H
 
#include <vector>
#include <array>
#include <string>
 
#include "data_management/GraphTreeObject.h"
#include "core/clockwerkerrors.h"
#include "core/Matrix.hpp"
#include "architecture/EventLogger.h"
 
namespace clockwerk {
 
    enum vector_select_e {
        BOOL,
        INT,
        UINT,
        FLOAT,
        DOUBLE,
        STRING
    };
 
    class Executive;
 
    /// @brief   Class for logging data to a file
    /// 
    /// This function defines a base logger class with functions as outlined and
    /// described in the header. It fully defines the updstream logging interface
    /// (interface to logged objects and buffering), but does not define a downstream
    /// interface to the actual output file. That interface is reserved for inherited
    /// classes. With that in mind, this class is essentially useless until inherited,
    /// and should not be used directly.
 
    /// Current planned inherited file structures are CSV and HDF5.
 
    /// The logger class is a generic class targeted at collecting, buffering,
    /// and writing data to a file. It operates on the graph tree by interfacing with
    /// objects inherited from it (graph tree by default cannot be logged). Desired 
    /// log parameters can be passed either by a direct handle to the class or by string
    /// address, and may be passed as a single unit (just one data point) or a recursive
    /// inheritence (log an entire branch of the tree).
 
    /// Data may be buffered in the logger for speed and efficiency, but is not buffered
    /// by default for simplicity. Regardless, the buffer class is used as the primary method
    /// for collecting data off of graph tree objects for writing.
    class SimLogger : public GraphTreeObject {
    public:
        /// Constructor for the SimLogger object -- has a default rate of every ms
        /// @param   exec    Handle to the executive object
        SimLogger(Executive &executive, const std::string &filename="output.csv", unsigned int buffer_size=1);
        ~SimLogger() {close();}
 
        /// Functions to get and set buffer size
        unsigned int bufferSize() {return _buffer_size;}
        int bufferSize(unsigned int buffer_size);
 
        /// Functions to get and set filename
        std::string filename() {return _filename;}
        int filename(const std::string &name);
 
        /// Functions to get and set output directory
        std::string outDir() {return _output_directory;}
        int outDir(const std::string &directory);
 
        /// @brief   Function to set up the SimLogger
        /// @param   file_name   Name of the file to log to
        /// @return  Integer code indicating success/failure
        virtual int setup(const std::string &file_name) {return NO_ERROR;}
 
        /// @brief   Function to add a logging parameter to the SimLogger.
        ///          Overloaded to add graph node by string or by object
        /// @param   parameter   Graph tree node passed as object
        /// @param   param_name  The name to which the parameter will be logged
        /// @param   recursive   Flag indicating whether parameter should be added
        ///                      recursively (include all lower items on its tree)
        ///                      or not (the default)
        int addParameter(GraphTreeObject &parameter, const std::string &param_name,
                        bool recursive = false);
 
        /// @brief   Function to add a logging parameter to the SimLogger.
        ///          Overloaded to add graph node by string or by object
        /// @param   parameter   Graph tree node passed as address string
        /// @param   param_name  The name to which the parameter will be logged
        /// @param   recursive   Flag indicating whether parameter should be added
        ///                      recursively (include all lower items on its tree)
        ///                      or not (the default)
        int addParameter(const std::string &parameter, const std::string &param_name,
                        bool recursive = false);
 
        /// @brief   Function to lock the file for logging once all parameters have
        ///          been defined. Generates headers and creates buffers for logging
        ///          based on parameters that have already been added above.
        /// @note    Should be called once, before sim starts
        /// @note    If anything changes after this point, it could potentially cause
        ///          problems in the SimLoggers
        /// @note    Should NOT be overridden in standard logging implementation.
        virtual int lockForLogging();
 
        /// @brief   Function to log data to buffer. Flushes buffer to file when full
        /// @note    Should NOT be overridden in standard implementation. Virtual call
        ///          is for Python virtual implementation but should generally be disregarded
        virtual int log();
 
        /// @brief   Function to close down the file -- logs remaining buffered data
        ///          and closes
        virtual int close();
 
        int writeHeaders(const int &val) {_group_idx.push_back(-1); _headers.push_back(_current_name); return NO_ERROR;}
        int writeHeaders(const unsigned int &val) {_group_idx.push_back(-1); _headers.push_back(_current_name); return NO_ERROR;}
        int writeHeaders(const double &val) {_group_idx.push_back(-1); _headers.push_back(_current_name); return NO_ERROR;}
        int writeHeaders(const GraphTreeObject &val);
        int writeHeaders(void* val) {_group_idx.push_back(-1); _headers.push_back(_current_name); return NO_ERROR;}
        int writeHeaders(const std::string &val) {_group_idx.push_back(-1); _headers.push_back(_current_name); return NO_ERROR;}
 
        template <typename T> int writeHeaders(const std::vector<T> &val);
        template <typename T, long unsigned int N> int writeHeaders(const std::array<T, N> &val);
 
        template <typename T, unsigned int R, unsigned int C> int writeHeaders(const Matrix<T, R, C> &val);
 
        /// @brief   Overloaded function to write data to the buffer. Should not be
        ///          called directly by the user -- is reserved for call within graph
        ///          object providing the logging
        /// @note    If init is true, pushes back element into buffer. Otherwise, writes
        ///          to appropriate buffer
        int writeToBuffer(const bool &val);
        int writeToBuffer(const int &val);
        int writeToBuffer(const long unsigned int &val);
        int writeToBuffer(const float &val);
        int writeToBuffer(const double &val);
        int writeToBuffer(const std::string &val);
        int writeToBuffer(void* val);
        int writeToBuffer(GraphTreeObject &val);
 
        /// @brief   Function to handle iteratable values -- note here that we only need to define one
        ///          templated instance because this function will be fully templated out to all DataIO
        ///          objects that are instantiated, and calls the above ^ under the hood
        template <typename T> int writeToBuffer(const std::vector<T> &val);
        template <typename T, long unsigned int N> int writeToBuffer(const std::array<T, N> &val);
 
        template <typename T, unsigned int R, unsigned int C> int writeToBuffer(const Matrix<T, R, C> &val);
 
        /// @brief Function to set the local model log level
        /// @param new_level The new level to set logging to
        void logLevel(log_level_e new_level) {_local_log_level = new_level;}
 
        /// Handle to the executive object -- used for event logging, etc.
        Executive *exc;
    protected:
        /// @brief   Function to set all buffers to full size
        void _fillBuffers();
 
        /// @brief   Function to create a file, in whatever format is chosen, for logging
        virtual int _createSetupFile() {return NO_ERROR;}
 
        /// @brief   Function to write buffered data to file
        virtual int _writeToFile() {return NO_ERROR;}
 
        /// A vector to hold all graph tree object pointers
        std::vector<GraphTreeObject*> _logged_nodes;
        std::vector<std::string> _log_names;
        std::string _current_name;
 
        /// String for the filename
        std::string _filename;
        std::string _output_directory;
 
        /// Ok, so this is important. At the end of the day, every variable resolves
        /// somehow into a basic type, because it is mandated in our logging system.
        /// The catch is that we need to resolve variables into headers and then data
        /// streams, which can be difficult because C++ is a strongly typed language
        /// and we're not really detecting our type until runtime. The solution here
        /// is a little messy, but we're basically going to create a bunch of different
        /// vectors to hold our different variables, then tie each element to its vector
        /// via indices. Got it? God knows I sure don't. Here we go...
        /// Vectors to hold defined/accepted data types and read/write indices
        unsigned int _buffer_size = 10;
        unsigned int _buffer_write_idx = 0;
        unsigned int _buffer_read_idx = 0;
        std::vector<std::vector<bool>> _bool_vector;            /// 0
        std::vector<std::vector<int>> _int_vector;              /// 1
        std::vector<std::vector<long unsigned int>> _uint_vector;    /// 2
        std::vector<std::vector<float>> _float_vector;          /// 3
        std::vector<std::vector<double>> _double_vector;        /// 4
        std::vector<std::vector<std::string>> _string_vector;   /// 5
 
        /// Header and indexing variables
        bool _locked;
        unsigned int _seq_idx = 0;
        std::vector<std::string> _headers;
        std::vector<unsigned int> _sequence;
        std::vector<vector_select_e> _type;
 
        /// Grouping methods -- for some variables, such as arrays and vectors,
        /// we may want to lump all of the data elements together, even though
        /// they are tracked/"logged" as separate native datatypes. The following
        /// struct and associated tracking variables provide a mechanism for 
        /// doing that
        struct Group {
            long unsigned int size;     /// The size of the group
            std::string group_name;     /// The name of the group object
        };
        std::vector<int> _group_idx;    /// Set to -1 if variable is not part of group
        std::vector<Group> _groups;
 
        /// Our local log level -- allows a higher log level locally than the overall system
        log_level_e _local_log_level = NONE;
    };
 
 
    template <typename T>
    int SimLogger::writeToBuffer(const std::vector<T> &val) {
        int err;
        /// Loop through our vector and write each value individually to buffer
        for(unsigned int i = 0; i < val.size(); i++) {
            err = writeToBuffer(val[i]);
            if(err) {
                return err;
            }
        }
        return NO_ERROR;
    }
 
    template <typename T, long unsigned int N>
    int SimLogger::writeToBuffer(const std::array<T, N> &val) {
        int err;
        /// Loop through our vector and write each value individually to buffer
        for(unsigned int i = 0; i < N; i++) {
            err = writeToBuffer(val[i]);
            if(err) {
                return err;
            }
        }
        return NO_ERROR;
    }
 
    template <typename T, unsigned int R, unsigned int C>
    int SimLogger::writeToBuffer(const Matrix<T, R, C> &val) {
        int err;
        unsigned int i, j;
        for(i = 0; i < R; i++) {
            for(j = 0; j < C; j++) {
                err = writeToBuffer(val.values[i][j]);
                if(err) {
                    return err;
                }
            }
        }
        return NO_ERROR;
    }
 
    template <typename T>
    int SimLogger::writeHeaders(const std::vector<T> &val) {
        /// Vector is a group item -- create a group and record our index
        /// to it so it can be (optionally) accessed down the line
        _groups.push_back({val.size(), _current_name});
 
        for(unsigned int i = 0; i < val.size(); i++) {
            _headers.push_back(_current_name + "_" + std::to_string(i));
            _group_idx.push_back(_groups.size() - 1);
        }
        return NO_ERROR;
    }
 
    template <typename T, long unsigned int N>
    int SimLogger::writeHeaders(const std::array<T, N> &val) {
        /// Array is a group item -- create a group and record our index
        /// to it so it can be (optionally) accessed down the line
        _groups.push_back({val.size(), _current_name});
 
        for(unsigned int i = 0; i < N; i++) {
            _headers.push_back(_current_name + "_" + std::to_string(i));
            _group_idx.push_back(_groups.size() - 1);
        }
        return NO_ERROR;
    }
 
    template <typename T, unsigned int R, unsigned int C>
    int SimLogger::writeHeaders(const Matrix<T, R, C> &val) {
        /// Vector is a group item -- create a group and record our index
        /// to it so it can be (optionally) accessed down the line
        _groups.push_back({R*C, _current_name});
 
        unsigned int i, j;
        for(i = 0; i < R; i++) {
            for(j = 0; j < C; j++) {
                if(C == 1) {
                    /// This is a vector, so don't write out our column index
                    _headers.push_back(_current_name + "_" + std::to_string(i));
                    _group_idx.push_back(_groups.size() - 1);
                } else {
                    /// This is a matrix, so write out both dimensions
                    _headers.push_back(_current_name + "_" + std::to_string(i) + "_" + std::to_string(j));
                    _group_idx.push_back(_groups.size() - 1);
                }
            }
        }
        return NO_ERROR;
    }
 
}
 
#endif