SimpleSpacecraft.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.
******************************************************************************/
/*
Spacecraft model header file
 
Author: Alex Reynolds
*/
 
#ifndef MODELS_ASSEMBLIES_SPACECRAFT_H
#define MODELS_ASSEMBLIES_SPACECRAFT_H
 
#include "core/macros.h"
#include "core/CartesianVector.hpp"
#include "six_dof_dynamics/Body.hpp"
#include "six_dof_dynamics/Node.hpp"
#include "models/states/FrameStateSensorModel.h"
#include "models/environment/AsphericalGravityModel.h"
#include "models/assemblies/SimplePlanet.h"
#include "models/assemblies/SpicePlanet.h"
#include "models/states/PlanetRelativeStatesModel.h"
#include "models/environment/GravityGradientModel.h"
#include "models/support/LvlhFrameManagerModel.h"
#include "models/actuators/TimedImpulsiveBurnModel.h"
 
namespace modelspace {
 
    /**
     * @brief   Simple Spacecraft Model
     * 
     * The simple spacecraft model is a convenient wrapper around a simple model of a
     * spacecraft acting under the force of gravity. It includes a gravity model
     * with J2 and J3 effects as well as gravity gradient moments and sensors to 
     * determine spacecraft state relative to its central planet.
     * 
     * To configure spacecraft, users have two options:
     * - They may call configFromPlanet to simply and quickly configure spacecraft
     *   from the planet model
     * - They may manually configure each model in spacecraft by accessing them
     *   individually, e.g. spacecraft.gravityModel().params.mu(<value>)
    */
    class SimpleSpacecraft : public Model {
    public:
        // Model params
        //         NAME                     TYPE                    DEFAULT VALUE
        START_PARAMS
            /** The position of the spacecraft in the initialization frame, expressed in init frame */
            SIGNAL(initial_position,        CartesianVector3D,      CartesianVector3D({0.0,0.0,0.0}))
            /** The velocity of the spacecraft in the initialization frame, expressed in init frame */
            SIGNAL(initial_velocity,        CartesianVector3D,      CartesianVector3D({0.0,0.0,0.0}))
            /** The frame in which position and velocity are initialized. */
            SIGNAL(pos_vel_init_frame,      FrameD*,                nullptr)
            /** The attitude of the spacecraft relative to the initialization frame. */
            SIGNAL(initial_attitude,        QuaternionD,            QuaternionD({1.0,0.0,0.0,0.0}))
            /** The angular velocity of the spacecraft relative to the initialization frame, expressed
             *  in spacecraft body frame.*/
            SIGNAL(initial_ang_vel,         CartesianVector3D,      CartesianVector3D({0.0,0.0,0.0}))
            /** The frame in which attitude and angular velocity are initialized. */
            SIGNAL(att_init_frame,          FrameD*,                nullptr)
            /** The angular velocity of the planet rotating frame relative to the inertial frame.
             *  Defaults to Earth's rotation rate */
            SIGNAL(planet_configuration,    void*,                  nullptr)
            /** Inertial frame of planet spacecraft is orbiting */
            SIGNAL(planet_inertial_frame,   FrameD*,                nullptr)
            /** Rotating frame of planet spacecraft is orbiting */
            SIGNAL(planet_rotating_frame,   FrameD*,                nullptr)
        END_PARAMS
 
        // Model inputs
        //         NAME                     TYPE                    DEFAULT VALUE
        START_INPUTS
 
        END_INPUTS
 
        // Model outputs
        //         NAME                     TYPE                    DEFAULT VALUE
        START_OUTPUTS
            /** Accessor to the inertial frame of the planet. Set to point to _planet_inertial in constructor. */
            SIGNAL(body,                    FrameD*,                nullptr)
            /** Accessor to the rotating frame of the planet. Set to point to _planet_inertial in constructor. */
            SIGNAL(lvlh,                    FrameD*,                nullptr)
            /** Position wrt planet centered inertial frame */
            SIGNAL(pos_sc_pci,              CartesianVector3D,      CartesianVector3D({0.0, 0.0, 0.0}))
            /** Velocity wrt planet centered inertial fraame */
            SIGNAL(vel_sc_pci,              CartesianVector3D,      CartesianVector3D({0.0, 0.0, 0.0}))
            /** Attitude quaternion wrt planet inertial frame */
            SIGNAL(quat_sc_pci,             QuaternionD,            QuaternionD({1.0, 0.0, 0.0, 0.0}))
            /** Angular velocity of the spacecraft wrt planet, output in body frame */
            SIGNAL(ang_vel_sc_pci__body,    CartesianVector3D,      CartesianVector3D({0.0, 0.0, 0.0}))
            /** The latitude of the spacecraft wrt planet rotating frame, in radians */
            SIGNAL(latitude_detic,          double,                 0.0)
            /** The longitude of the spacecraft wrt the planet rotating frame, in radians */
            SIGNAL(longitude,               double,                 0.0)
            /** The altitude of the spacecraft wrt planet ellipsoid */
            SIGNAL(altitude_detic,          double,                 0.0)
        END_OUTPUTS
 
        SimpleSpacecraft(Model &pnt, const std::string &m_name="spacecraft");
        SimpleSpacecraft(SimulationExecutive &e, const std::string &m_name="spacecraft");
        ~SimpleSpacecraft();
 
        /// @brief Function to get a handle to the frame state sensor relative to the planet inertial frame 
        /// @return Pointer to the planet inertial frame state sensor
        modelspace::FrameStateSensorModel* planetInertialStateSensor() {return &_planet_inertial_state_sensor;}
        /// @brief Function to get a handle to the frame state sensor relative to the planet rotating frame 
        /// @return Pointer to the planet rotating frame state sensor
        modelspace::FrameStateSensorModel* planetRotatingStateSensor() {return &_planet_rotating_state_sensor;}
        /// @brief Function to get a handle to the aspherical gravity model contained within this model
        /// @return Pointer to the aspherical gravity model
        modelspace::AsphericalGravityModel* gravityModel() {return &_gravity;}
        /// @brief Function to get a handle to the planet relative state model contained within this model
        /// @return Pointer to the planet relative state sensor model
        modelspace::PlanetRelativeStatesModel* planetRelativeModel() {return &_planet_relative;}
        /// @brief Function to get a handle to the gravity gradient model contained within this model
        /// @return Pointer to the gravity gradient model
        modelspace::GravityGradientModel* gravityGradientModel() {return &_gravity_gradient;}
    protected:
        int start();
 
        /// @brief Function to internally map relationships between sensors
        void _mapInternal();
 
        /// @brief Initialize position and velocity of the spacecraft body frame
        /// @param position_sc_frame__frame The desired position of the spacecraft body wrt frame_ptr
        /// @param velocity_sc_frame__frame The desired velocity of the spacecraft body represented in frame frame_ptr
        /// @param frame_ptr The frame relative to which state is initialized. Default (nullptr) will init wrt sim root frame
        /// @return Error code corresponding to success/failure
        /// @note Overloaded to init via string or frame
        int _initializePositionVelocity(CartesianVector3D position_sc_frame__frame,
                                       CartesianVector3D velocity_sc_frame__frame,
                                       FrameD* frame_ptr=nullptr);
 
        /// @brief Initialize attitude and angular velocity of the spacecraft body frame
        /// @param quat_sc_frame__frame The desired attitude of the spacecraft body wrt frame_ptr
        /// @param ang_vel_sc_frame__sc The desired angular velocity of the spacecraft body wrt frame_ptr in the sc body frame
        /// @param frame_ptr The frame relative to which state is initialized. Default (nullptr) will init wrt sim root frame
        /// @return Error code corresponding to success/failure
        /// @note Overloaded to init via string or frame
        int _initializeAttitude(QuaternionD quat_sc_frame__frame,
                               CartesianVector3D ang_vel_sc_frame__sc,
                               FrameD* frame_ptr=nullptr);
 
        // Spacecraft body and node for gravity application
        BodyD _body;
        NodeD _gravity_node;
 
        // Models included within the Spacecraft class
        FrameStateSensorModel _planet_inertial_state_sensor;
        FrameStateSensorModel _planet_rotating_state_sensor;
        LvlhFrameManagerModel _lvlh_frame_manager;
        AsphericalGravityModel _gravity;
        GravityGradientModel _gravity_gradient;
        PlanetRelativeStatesModel _planet_relative;
    };
 
}
 
#endif