SimpleMeanWindModel.h

/******************************************************************************
* Copyright (c) ATTX INC 2025. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, INC. 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, INC.
******************************************************************************/
/*
Simple mean wind model header file

Author: James Tabony
*/
/*
Metadata for MS GUI:
imdata = {"exclude" : True}
*/

#ifndef MODELS_ENVIRONMENT_SIMPLE_MEAN_WIND_MODEL_H 
#define MODELS_ENVIRONMENT_SIMPLE_MEAN_WIND_MODEL_H

#include "simulation/Model.h"
#include "constants/unitutils.h"
#include "simulation/UniformRandom.hpp"
#include "utils/Interpolate2D.h"

namespace warptwin {

    /**
     * @brief   Simple mean wind model
     * 
     * This model generates an objects experienced mean wind through a pseudo-deterministic process.
     * The mean wind magnitude is based an a power function sclaled by a reference wind spead at
     * a given altitude. 
     * 
     * $$ V(h) = V_{ref} * \left(  \frac{h}{h_{ref}}  \right)^\alpha $$
     * 
     * The wind direction perturbed around a provided value (wind direction at reference altitude)
     * in a continuous (not smooth) manner. By a function f(h) with uniformly distributed outputs
     * for select altitudes between the values of [-1, 1]. This relationship is:
     * 
     * $$ \theta(h) = \theta_0 + \Delta \theta \cdot f(h) \qquad f:h \in \mathbb{R} \mapsto [-1, 1] \, \, \text{and} \, f(0) := 0 $$
     * 
     * Author: James Tabony <james.tabony@attx.tech>
    */
    MODEL(SimpleMeanWindModel)
    public:
        // Model params
        //         NAME                     TYPE                    DEFAULT VALUE
        START_PARAMS
            /** The average wind speed measured at the reference altitude. (meters/second) */
            SIGNAL(wind_speed_ref,          double,                 25.0*warpos::FEET_TO_METERS)
            /** The average wind azimuth angle (angle of the wind vector measured off of local north towards east) 
             *  at the reference altitude. Make sure to set before exc.startup. (radians) */
            SIGNAL(wind_azimuth_ref,        double,                 0.0)
            /** Reference altitude, typically close to the surface. This altitude is measured from surface NOT WGS84 ellipsoid. (meters) */
            SIGNAL(altitude_ref,            double,                 20.0*warpos::FEET_TO_METERS)
            /** Altitude of the surface relative to the WGS84 model. (meters) */
            SIGNAL(altitude_surface,        double,                 0.0)
            /** Wind shear factor. Used to describe the change in mean wind magnitude with respect
             *  to altitude. This parameter is dependent on the terrain underneath the flight operation.
             *  Open sea ~ 0.1, Suburban ~ 0.25, Forest/Mountains ~ 0.4. */
            SIGNAL(wind_shear_exponent,     double,                 0.2)
            /** Maximum direction shift of mean wind. You can effectively turn off the wind vector shear
             *  by setting this value to zero. (radians) */
            SIGNAL(wind_direction_shift_max, double,                0.0)
            /** Value to seed the internal RNG for this model. */
            SIGNAL(seed_value,              int,                    0)
        END_PARAMS

        // Model inputs
        //         NAME                     TYPE                    DEFAULT VALUE
        START_INPUTS
            /** Altitude of the object as relative to the WGS84 model. (meters) */
            SIGNAL(altitude,                double,                 0.0)
        END_INPUTS

        // Model outputs
        //         NAME                     TYPE                    DEFAULT VALUE
        START_OUTPUTS
            /** The mean wind vector of the object expressed in the local NED frame of the reference position.
             *  The velocity is expressed relative to the planet rotating frame. (meters/second) */
            SIGNAL(wind_mean__NED,          CartesianVector3,      CartesianVector3({0.0, 0.0, 0.0}))
        END_OUTPUTS

    protected:
        int16 start() override;
        int16 execute() override;

        /// @brief Function to configure sensor -- runs in all constructors
        void _configureInternal();

        // Internal variable for the ordered image set of the vector shear function (see confluence)
        std::vector<double> _image_set;

        // Internal variable for true altitude, altitude relative to surface not WGS84 Ellipsoid
        double _altitude_true;

        // Internal vairbale for wind azimuth and wind magnitude
        double _azimuth;
        double _magnitude;

        // Internal model for generating a random number under a uniform distribution
        UniformRandom<double> _uniform_random;

        // Internal model for linear interlopolation
        Interpolate2D _interpolate2D_model;
    };

}

#endif