DispersionEngine.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.
******************************************************************************/
/*
Normal Random Distribution Header File
 
Author: Alex Reynolds
*/
#ifndef DISPERSION_ENGINE_H
#define DISPERSION_ENGINE_H
 
#include <vector>
 
#include "data_management/GraphTreeObject.h"
#include "data_management/DataIO.hpp"
#include "UniformRandom.hpp"
#include "NormalRandom.hpp"
#include "architecture/Executive.h"
 
namespace modelspace {
 
    /**
     * @brief   Struct to store all data associated with dispersion
    */
    struct Dispersion {
        Dispersion(std::string nme, double d_v, clockwerk::GraphTreeObject* parent)
            : default_val(d_v), value(parent, nme, 0.0) {}
        double default_val;
        clockwerk::DataIO<double> value;
        clockwerk::DataIO<double>& operator () () {return value;}
    };
 
    /**
     * @brief   Struct to store all data associated with uniform dispersion
    */
    struct UniformDispersion : public Dispersion {
        UniformDispersion(std::string nme, double d_v, double mn, double mx, clockwerk::GraphTreeObject* parent)
        : Dispersion(nme, d_v, parent), min(mn), max(mx) {}
        double min;
        double max;
    };
 
    /**
     * @brief   Struct to store all data associated with normal dispersion
    */
    struct NormalDispersion : public Dispersion {
        NormalDispersion(std::string nme, double d_v, double mn, double sd, clockwerk::GraphTreeObject* parent)
            : Dispersion(nme, d_v, parent), mean(mn), stdev(sd) {}
        double mean;
        double stdev;
    };
 
    const int HASH_MULTIPLIER = 37;
    const int HASH_ADDER = 3;
 
    /**
     * @brief   Class to generate input dispersions for the simulation
     * 
     * The dispersion engine class is used to generate input dispersions
     * for use in Monte Carlo and similar simulations. It generates 
     * dispersion values which parameters and inputs on models can map
     * to, allowing for full dispersion-->model traceability.
     * 
     * The dispersion engine registers dispersions 
    */
    class DispersionEngine : public clockwerk::GraphTreeObject {
    public:
        // Standard constructor. Takes executive
        DispersionEngine(clockwerk::Executive &e) : exc(&e) {}
        ~DispersionEngine();
 
        /// @brief Function to initialize the dispersion engine
        /// @param seed The seed to be used in hashing the rng
        /// @param run The run number
        /// @param nruns The number of runs to generate dispersions for
        void initialize(int seed, int run, int nruns=1000);
 
        /// @brief Function to set the value of a dispersion
        /// @param dispersion The dispersion to set the value for
        void setUniformValue(UniformDispersion* dispersion_ptr);
 
        /// @brief Function to set the value of a dispersion
        /// @param dispersion The dispersion to set the value for
        void setNormalValue(NormalDispersion* dispersion_ptr);
 
        /// @brief Function to generate a uniform input dispersion
        /// @param name The name of the dispersion
        /// @param default_value The "run zero" value for the undispersed case
        /// @param min The minimum for the uniform distribution
        /// @param max The maximum for the uniform distribution
        /// @return The uniform dispersion struct created in the generation process
        UniformDispersion& createUniformInputDispersion(const std::string &name,
                                                        double default_val, double min, double max);
 
        /// @brief Function to generate a normal input dispersion
        /// @param name The name of the dispersion
        /// @param default_value The "run zero" value for the undispersed case
        /// @param mean The mean for the normal distribution
        /// @param stdev The standard deviation of the normal distribution
        /// @return The normal dispersion struct created in the generation process
        NormalDispersion& createNormalInputDispersion(const std::string &name,
                                                    double default_val, double mean, double stdev);
 
        /// @brief Call operator to get pointer to dispersion matching string
        /// @param The name of the knob to search for
        /// @return Pointer to the base dispersion object. nullptr if match not found
        Dispersion* operator () (const std::string &query);
 
        /// @brief Function to dump all knob information
        void dump();
 
        // Pointer to the executive object
        clockwerk::Executive* exc;
 
        // The has seed generated by the dispersion engine
        int hash_seed = 0;
    protected:
        /// @brief Function to generate a hashed seed from run number and seed
        /// @param run_number The monte carlo run number
        /// @param seed The seed to affect hash generation 
        /// @return Seed generated by hash function
        int _hash(int run_number, int seed);
 
        // Variable to store our hash value
        int _hash_value;
 
        // Variable to store the current run number
        int _run_number;
 
        // Variable to set the number of runs
        int _nruns;
 
        // Our lists to store each type of dispersion info
        std::vector<UniformDispersion*> _uniform_dispersions;
        std::vector<NormalDispersion*> _normal_dispersions;
 
        // Our distribution engines for generating varied inputs
        UniformRandom<double>* _uniform_dist = nullptr;
        NormalRandom<double>* _normal_dist = nullptr;
    };
 
}
 
#endif