Program Listing for File SpringDamper.h#
↰ Return to documentation for file (include/Karana/GeneralKModels/SpringDamper.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 declarations for the SpringDamper KModel.
*/
#pragma once
#include "Karana/Frame/ChainedFrameToFrame.h"
#include "Karana/SOADyn/KModel.h"
#include "Karana/SOADyn/Node.h"
namespace Karana::Models {
namespace km = Karana::Math;
namespace kd = Karana::Dynamics;
namespace kf = Karana::Frame;
// Forward declarations
class SpringDamperParams;
class SpringDamperScratch;
/**
* @class SpringDamperParamsVars
* @brief The Vars for the SpringDamperParams class.
*/
class SpringDamperParamsVars : public Karana::Core::BaseVars {
public:
/**
* @brief SpringDamperParamsVars constructor. The constructor is not meant to be
* called directly. Please use the create(...) method instead to create
* an instance.
*
* @param params The params class associated with this SpringDamperParamsVars.
*/
SpringDamperParamsVars(const kc::ks_ptr<const SpringDamperParams> ¶ms);
/**
* @brief Destructor.
*/
~SpringDamperParamsVars();
/**
* @brief Create an instance of the SpringDamperParamsVars.
*
* @param params The params class associated with this SpringDamperParamsVars.
* @returns A pointer to the newly created instance of SpringDamperParamsVars.
*/
static kc::ks_ptr<SpringDamperParamsVars>
create(const kc::ks_ptr<const SpringDamperParams> ¶ms);
/**
* @brief Get all the Vars that this SpringDamperParamsVars has.
*
* @returns A map of Vars, where the Var name is the key and the Var is the value.
*/
kc::NestedVars getAllVars() const override;
/// Unsprung length
kc::ks_ptr<Karana::Core::Var_T<double>> unsprung_length;
/// Spring constant
kc::ks_ptr<Karana::Core::Var_T<double>> k;
/// Damper constant
kc::ks_ptr<Karana::Core::Var_T<double>> d;
};
/**
* @class SpringDamperScratchVars
* @brief The Vars for the SpringDamperScratch class.
*/
class SpringDamperScratchVars : public Karana::Core::BaseVars {
public:
/**
* @brief SpringDamperScratchVars constructor. The constructor is not meant to be
* called directly. Please use the create(...) method instead to create
* an instance.
*
* @param scratch The scratch class associated with this SpringDamperScratchVars.
*/
SpringDamperScratchVars(const kc::ks_ptr<const SpringDamperScratch> &scratch);
/**
* @brief Destructor.
*/
~SpringDamperScratchVars();
/**
* @brief Create an instance of the SpringDamperScratchVars.
*
* @param scratch The scratch class associated with this SpringDamperScratchVars.
* @returns A pointer to the newly created instance of SpringDamperScratchVars.
*/
static kc::ks_ptr<SpringDamperScratchVars>
create(const kc::ks_ptr<const SpringDamperScratch> &scratch);
/**
* @brief Get all the Vars that this SpringDamperScratchVars has.
*
* @returns A map of Vars, where the Var name is the key and the Var is the value.
*/
kc::NestedVars getAllVars() const override;
/// Translation from node1 to node2
kc::ks_ptr<Karana::Core::Var_T<km::Vec3>> offset;
/// Signed length offset from the unsprung length
kc::ks_ptr<Karana::Core::Var_T<double>> position_error;
/// Relative linear velocity across the spring
kc::ks_ptr<Karana::Core::Var_T<km::Vec3>> velocity_error;
/// Signed scalar force due to spring stiffness
kc::ks_ptr<Karana::Core::Var_T<double>> stiffness_force;
/// Linear force due to spring damping
kc::ks_ptr<Karana::Core::Var_T<km::Vec3>> damping_force;
/// Total linear spring force
kc::ks_ptr<Karana::Core::Var_T<km::Vec3>> total_force;
};
/**
* @class SpringDamperParams
* @brief Parameters for the SpringDamper model.
*/
class SpringDamperParams : public KModelParams {
public:
/**
* @brief Constructor
* @param name - Name of the params.
*/
SpringDamperParams(std::string_view name);
/**
* @brief Used to ensure the params are ready.
*
* @return `true` if the params are ready, `false` otherwise.
*/
bool isReady() const final;
std::string
dumpString(std::string_view prefix,
const Karana::Core::Base::DumpOptions *options = nullptr) const override;
/// Unsprung length
double unsprung_length;
/// Spring constant
double k;
/// Damper constant
double d;
protected:
Karana::Core::ks_ptr<Karana::Core::BaseVars> _getVars() const override;
};
/**
* @class SpringDamperScratch
* @brief Scratch variables for the SpringDamper model.
*/
class SpringDamperScratch : public KModelScratch {
public:
/**
* @brief Constructor
* @param name - Name of the scratch.
*/
SpringDamperScratch(std::string_view name);
/// Translation from node1 to node2
km::Vec3 offset;
/// Signed length offset from the unsprung length
double position_error = km::notReadyNaN;
/// Relative linear velocity across the spring
km::Vec3 velocity_error;
/// Signed scalar force due to spring stiffness
double stiffness_force = km::notReadyNaN;
/// Linear force due to spring damping
km::Vec3 damping_force;
/// Total linear spring force
km::Vec3 total_force;
std::string
dumpString(std::string_view prefix,
const Karana::Core::Base::DumpOptions *options = nullptr) const override;
protected:
Karana::Core::ks_ptr<Karana::Core::BaseVars> _getVars() const override;
};
/**
* @class SpringDamper
* @brief Adds a spring-damper between two nodes.
*/
class SpringDamper : public KModel<SpringDamper, SpringDamperParams, SpringDamperScratch> {
public:
/**
* @brief SpringDamper constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
* The SpringDamper model applies an equal and opposing force to two
* nodes based on their current distance apart.
*
* @param name The name of the model.
* @param mm The ModelManager to register this model with.
* @param nd1 The first node in the spring damper model.
* @param nd2 The second node in the spring damper model.
*/
SpringDamper(std::string_view name,
const kc::ks_ptr<kd::ModelManager> &mm,
const kc::ks_ptr<kd::Node> nd1,
const kc::ks_ptr<kd::Node> nd2);
/**
* @brief Destructor for SpringDamper.
*/
~SpringDamper();
/**
* @brief Constructor. The SpringDamper model applies an equal and opposing force to two
* nodes based on their current distance apart.
*
* @param name The name of the model.
* @param mm The ModelManager to register this model with.
* @param nd1 The first node in the spring damper model.
* @param nd2 The second node in the spring damper model.
* @return A ks_ptr to the newly created instance of the SpringDamper model.
*/
static kc::ks_ptr<SpringDamper> create(std::string_view name,
const kc::ks_ptr<kd::ModelManager> &mm,
const kc::ks_ptr<kd::Node> nd1,
const kc::ks_ptr<kd::Node> nd2);
/**
* @brief Calculate and apply the spring/damper force.
* @param t Current time. Not used.
* @param x Current state. Not used.
*/
void preDeriv(const km::Ktime &t, const km::Vec &x);
/**
* @brief Get the first node of the spring-damper
*
* @return The node
*/
const kc::ks_ptr<kd::Node> &sourceNode() const;
/**
* @brief Get the second node of the spring-damper
*
* @return The node
*/
const kc::ks_ptr<kd::Node> &targetNode() const;
private:
/// The first node of the spring-damper.
kc::ks_ptr<kd::Node> _nd1;
/// The second node of the spring-damper.
kc::ks_ptr<kd::Node> _nd2;
/// FrameToFrame between the newtonian frame and node1
kc::ks_ptr<kf::ChainedFrameToFrame> _f2f1;
/// FrameToFrame between the newtonian frame and node2
kc::ks_ptr<kf::ChainedFrameToFrame> _f2f2;
/// The newtonian frame of the multibody
kc::ks_ptr<kf::Frame> _newton;
};
} // namespace Karana::Models