DirectionalAdaptiveGuidance.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.
******************************************************************************/
/*
Directional Adaptive Guidance task header file

Author: Alex Reynolds
*/
/*
Metadata for MS GUI:
imdata = {"exclude" : True}
*/

#ifndef DIRECTIONAL_ADAPTIVE_GUIDANCE_H
#define DIRECTIONAL_ADAPTIVE_GUIDANCE_H

#include "simulation/Model.h"
#include "constants/planetdefaults.h"
#include "core/CartesianVector.hpp"

namespace warptwin {

    /**
     * @brief   Weighted Directional Adaptive Guidance for Low Thrust Maneuvering
     * 
     * This task calculates the pointing vector for a low thrust orbit control
     * of orbital elements in the two body problem. It is based on an excellent
     * NASA paper on low thrust control laws, found here:
     * https://ntrs.nasa.gov/api/citations/20140011269/downloads/20140011269.pdf
     * 
     * Original source here:
     * https://electricrocket.org/IEPC/IEPC-2011-102.pdf
     * 
     * It uses the weighting parameters Wx to weight the algorithm, and calculates
     * control on the basis of difference in orbital parameters.
     * 
     * The output is a unit vector pointed in the direction of the desired
     * acceleration. 
     * 
     * Algorithm is capable of controlling semimajor axis, eccentricity, inclination,
     * and RAAN. Can be extended to control argument of periapsis (which is in
     * the original source) as needed.
    */
    MODEL(DirectionalAdaptiveGuidance)
    public:
        // Model params
        //         NAME                     TYPE                    DEFAULT VALUE 
        START_PARAMS
            /** This is the gravitational parameter of our parent planet. Defaults to
             * Earth's gravitational parameter for ease of use */
            SIGNAL(mu,                      double,                 warpos::earth_wgs84.mu)
            /** The weight applied to semimajor axis control */
            SIGNAL(a_weight,                double,                 0.0)
            /** The weight applied to eccentricity control */
            SIGNAL(e_weight,                double,                 0.0)
            /** The weight applied to inclination control */
            SIGNAL(i_weight,                double,                 0.0)
            /** The weight applied to RAAN control */
            SIGNAL(RAAN_weight,             double,                 0.0)
        END_PARAMS

        // Model inputs
        //         NAME                     TYPE                    DEFAULT VALUE
        START_INPUTS
            /** Total thrust force produced by the system. Default is in N */
            SIGNAL(thrust_force,            double,                 1.0)
            /** The desired semimajor axis for the spacecraft orbit. Default is in m. */
            SIGNAL(a_target,                double,                 0.0)
            /** The desired eccentricity for the spacecraft orbit */
            SIGNAL(e_target,                double,                 0.0)
            /** The desired orbit inclination, in radians */
            SIGNAL(i_target,                double,                 0.0)
            /** The desired orbit RAAN, in radians */
            SIGNAL(RAAN_target,             double,                 0.0)
            /** The body axis vector which will be pointed to desired_primary */
            SIGNAL(pos_pci,                 CartesianVector3,       CartesianVector3({0.0, 0.0, 0.0}))
            /** The desired primary vector expressed in an arbitrary frame */
            SIGNAL(vel_pci,                 CartesianVector3,       CartesianVector3({0.0, 0.0, 0.0}))
        END_INPUTS 

        // Model outputs
        //         NAME                     TYPE                    DEFAULT VALUE
        START_OUTPUTS
            /** The desired acceleration thrusting direction in the planet centered inertial frame */
            SIGNAL(accel_pnt_pci,           CartesianVector3,       CartesianVector3({0.0, 0.0, 0.0}))
        END_OUTPUTS

    protected:
        int16 execute();

        /// @brief Calculate force vector from alpha and beta parameters
        /// @param alpha The in-plane (pitch) angle
        /// @param beta The out of plane (yaw) angle
        /// @return Force vector calculated from alpha and beta
        CartesianVector3 _calcForceRswFromAlphaBeta(double alpha, double beta);
    };

}

#endif