spiceutils.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.
******************************************************************************/
#ifndef UTILS_SPICE_H
#define UTILS_SPICE_H
 
#include <vector>
#include <string>
 
#include "core/macros.h"
#include "core/CartesianVector.hpp"
#include "six_dof_dynamics/DCM.hpp"
#include "six_dof_dynamics/Frame.hpp"
 
namespace modelspace {
    /// @brief A function to load in a sinle spice kernel
    /// @param A single spice kernel to load
    void loadKernel(std::string kernel);
 
    /**
     * @brief The Spice Manager is a single class instance to manage spice frames and return SPICE states
     * 
     * The Spice Manager is a wrapper around SPICE utilities to simplify the process
     * of getting SPICE states. It needs to exist for the following reasons:
     * - Python/SWIG has some weirdness that couples with spice on kernel loading. Loading kernels
     *   here prevents having to load kernels multiple times
     * - Having a single class for all spice bodies ensures they're all using the same reference
     *   point (we woldn't want to reference relative to earth sometimes and the sun others)
     * 
     * By default, the Spice Manager will select the central body to be Earth, if the Earth is
     * present in the simulation. If Earth is not present, the Spice Manager will select its
     * central body as the largest body present in the simulation by mass. (i.e. Sun > Venus)
     * 
     * If the user desires a different central body than the one chosen by the SPICE manager, 
     * the central body may be set via setCentralBody. This will override the default behavior.
     */
    class SpiceManager {
    public:
        SpiceManager() {}
        ~SpiceManager() {}
 
        /// @brief A function to load in a list of SPICE kernels
        /// @param kernel_list A vector list of kernel files to load
        void loadKernels(std::vector<std::string> kernel_list);
 
        /// @brief Function to register a spice body with the spice manager
        /// @param body_name The SPICE body name to register
        void registerSpiceBody(const std::string &body_name);
 
        /// @brief Get the frame name associated with a body
        /// @param body_name The body name to query
        /// @return The string name associated with the body -- empty string if body is not found
        std::string getBodyFrameName(const std::string &body_name);
 
        /// @brief Function to set the central body in the SPICE manager
        /// @param central_body The central body to set
        void setCentralBody(const std::string &central_body);
 
        /// @brief Function to output the current central body
        /// @return The current central body
        std::string centralBody() {return _central_body;}
 
        /// @brief Function to return the gravitational parameter for a SPICE body
        /// @param body_name The body name to return gravitational parameter for
        /// @return The gravitational parameter in km^3/s^2
        double getGravitationalParameter(const std::string &body_name);
 
        /// @brief Function to return the position of a SPICE body relative to central body
        /// @param body_name The body name to query
        /// @param tdb_time The ephemeris time to query state position
        /// @return The J2000 position of the SPICE body relative to central body in km
        CartesianVector3D getSpicePosition(const std::string &body_name, double tdb_time);
 
        /// @brief Function to return the velocity of a SPICE body relative to central body
        /// @param body_name The body name to query
        /// @param tdb_time The ephemeris time to query state position
        /// @return The J2000 velocity of the SPICE body relative to central body in km/s
        CartesianVector3D getSpiceVelocity(const std::string &body_name, double tdb_time);
 
        /// @brief Function to return the attitude of a SPICE body relative to central body
        /// @param body_name The body name to query
        /// @param tdb_time The ephemeris time to query state position
        /// @return The J2000 attitude of the SPICE body relative to central body as a DCM
        DCMD getSpiceAttitude(const std::string &body_name, double tdb_time);
 
        /// @brief Function to return the angular velocity of a SPICE body relative to central body
        /// @param body_name The body name to query
        /// @param tdb_time The ephemeris time to query state position
        /// @return The J2000 angular velocity of the SPICE body relative to central body in rad/s
        CartesianVector3D getSpiceAngularVelocity(const std::string &body_name, double tdb_time);
    protected:
        // Record of all SPICE bodies tracked by the SPICE manager
        std::vector<std::string> _spice_bodies;
 
        // String indicating the central body for the SPICE manager
        std::string _central_body;
 
        // Boolean tracking whether central body was already set manually
        bool _manual_set = false;
 
        // Boolean to protect from duplicate spice kernel loading
        bool _kernels_loaded = false;
 
        // Temporary variables for calculation
        double _tmp_state[6];
        double _lt = 0.0;
        double _tmp_dbl[3][3];
        DCMD _tmp_dcm_p_pci;
        double _tmp_vec[3];
        CartesianVector3D _tmp_omega_p_pci__pci;
        double _ftmtrx[6][6];
    };
}
 
#endif