Program Listing for File GravityInterface.h#
↰ Return to documentation for file (include/Karana/GeneralKModels/GravityInterface.h)
/*
* Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
*
* NOTICE TO USER:
*
* This source code and/or documentation (the "Licensed Materials") is
* the confidential and proprietary information of Karana Dynamics Inc.
* Use of these Licensed Materials is governed by the terms and conditions
* of a separate software license agreement between Karana Dynamics and the
* Licensee ("License Agreement"). Unless expressly permitted under that
* agreement, any reproduction, modification, distribution, or disclosure
* of the Licensed Materials, in whole or in part, to any third party
* without the prior written consent of Karana Dynamics is strictly prohibited.
*
* THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
* KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
* BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
* FITNESS FOR A PARTICULAR PURPOSE.
*
* IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
* INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
* OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
*
* U.S. Government End Users: The Licensed Materials are a "commercial item"
* as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
* only as a commercial end item under the terms of this license.
*
* Any use of the Licensed Materials in individual or commercial software must
* include, in the user documentation and internal source code comments,
* this Notice, Disclaimer, and U.S. Government Use Provision.
*/
/**
* @file
* @brief Contains the gravity inteface definition.
*/
#pragma once
#include "Karana/KCore/Base.h"
#include "Karana/Math/Defs.h"
#include "Karana/SOADyn/KModel.h"
#include "Karana/SOADyn/SubTree.h"
namespace Karana::Models {
namespace km = Karana::Math;
namespace kc = Karana::Core;
namespace kf = Karana::Frame;
namespace kd = Karana::Dynamics;
namespace kmo = Karana::Models;
/**
* @struct GravityOutput
* @brief The output of a GravityInterface.
*/
struct GravityOutput {
/// The acceleration due to gravity.
km::Vec3 g;
/// The time the gravity acceleration was set at.
km::Ktime t;
/// The update type associated with setting the gravity.
kmo::OutputUpdateType update_type;
};
/**
* @class GravityInterface
* @brief Common GravityInterface used for computing gravity with various methods.
*/
class GravityInterface : public kc::Base {
public:
/**
* @brief GravityInterface constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
*
* @param name The name of the GravityInterface.
*/
GravityInterface(std::string_view name);
/**
* @brief Used to ensure the params are ready.
*
* @return `true` if the params are ready, `false` otherwise.
*/
bool isReady() const override;
/**
* @brief Compute the acceleration due to gravity and set its value in the GravityOutput.
*
* @param t The time this acceleration was calculated at.
* @param output_update_type The type of update that updated the gravity.
*/
virtual void computeGravity(const km::Ktime t,
const OutputUpdateType &output_update_type) = 0;
/**
* @brief Get the GravityOutput data.
*
* @return The GravityOutput data.
*/
const GravityOutput &getGravity() const;
/**
* @brief Set the GravityOutput data.
*
* @param g The acceleration due to gravity.
* @param t The time this acceleration was calculated at.
* @param output_update_type The type of update that updated the gravity.
*/
void setGravity(const km::Vec3 &g,
const km::Ktime t,
const OutputUpdateType &output_update_type);
protected:
/// The output of the most recent gravity calculation.
GravityOutput _g;
};
/**
* @class UniformGravity
* @brief A GravityInterface implementation for uniform gravity.
*/
class UniformGravity : public GravityInterface {
public:
/**
* @brief UniformGravity constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
*
* @param name The name of the GravityInterface.
*/
UniformGravity(std::string_view name);
/**
* @brief This is a no-op. It does not modify the value of g.
*
* @param t The time this acceleration was calculated at.
* @param output_update_type The type of update that updated the gravity.
*/
void computeGravity(const km::Ktime t, const OutputUpdateType &output_update_type) override;
/**
* @brief Constructor.
*
* @param name The name of the UniformGravity interface.
* @returns A pointer to the newly created instance of UniformGravity.
*/
static kc::ks_ptr<UniformGravity> create(std::string_view name);
/**
* @brief Return a formatted string containing information about this object.
* @param prefix String prefix to use for formatting.
* @param options Dump options (if null, defaults will be used).
* @return A string representation of the object.
*/
std::string dumpString(std::string_view prefix = "",
const Base::DumpOptions *options = nullptr) const override;
};
/**
* @class PointMassGravity
* @brief A GravityInterface implementation for point-mass gravity.
*/
class PointMassGravity : public GravityInterface {
public:
/**
* @brief UniformGravity constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
*
* @param name The name of the GravityInterface.
* @param st The SubTree to get the center of mass from.
* @param central_body The point mass central body applying the gravitational force
*/
PointMassGravity(std::string_view name,
const kc::ks_ptr<kd::SubTree> &st,
const kc::ks_ptr<kf::Frame> ¢ral_body);
/**
* @brief This is a no-op. It does not modify the value of g.
*
* @param t The time this acceleration was calculated at.
* @param output_update_type The type of update that updated the gravity.
*/
void computeGravity(const km::Ktime t, const OutputUpdateType &output_update_type) override;
/**
* @brief Constructor.
*
* @param name The name of the PointMassGravity interface.
* @param st The SubTree to get the center of mass from.
* @param central_body The point mass central body applying the gravitational force
* @returns A pointer to the newly created instance of PointMassGravity.
*/
static kc::ks_ptr<PointMassGravity> create(std::string_view name,
const kc::ks_ptr<kd::SubTree> &st,
const kc::ks_ptr<kf::Frame> ¢ral_body);
/// Gravitational constant (units: m^3/(kg s^2) )
double mu = km::notReadyNaN;
/**
* @brief Used to ensure the params are ready.
*
* @return `true` if the params are ready, `false` otherwise.
*/
bool isReady() const override;
/**
* @brief Get the IDs of the SubTree and central body used
* by this PointMassGravity.
*
* @returns The IDs of the SubTree and central body used by this
* PointMassGravity.
*/
std::array<kc::id_t, 2> getObjIds() const;
/**
* @brief Return a formatted string containing information about this object.
* @param prefix String prefix to use for formatting.
* @param options Dump options (if null, defaults will be used).
* @return A string representation of the object.
*/
std::string dumpString(std::string_view prefix = "",
const Base::DumpOptions *options = nullptr) const override;
private:
/// The SubTree to use to get the cm frame.
kc::ks_ptr<kd::SubTree> _st;
/// the central body frame
const kc::ks_ptr<kf::Frame> _cb;
};
} // namespace Karana::Models