Class ModelManager

Class ModelManager#

Nested Relationships#

Nested Types#

Inheritance Relationships#

Base Type#

Derived Type#

Class Documentation#

class ModelManager : public Karana::Core::LockingBase#

Class to manage the multibody dynamics and KModels.

See System level models section for more information on the ModelManager class.

Subclassed by Karana::Dynamics::StatePropagator

Public Types

enum class MMSolverType#

Enum with values to classify the reason for the termination of a step.

Values:

enumerator TREE_DYNAMICS#

ATBI forward dynamics for a tree system.

enumerator TREE_AUGMENTED_DYNAMICS#

tree-augmented ATBI constrained forward dynamics

enumerator BAUMGARTE_DYNAMICS#

Baumgarte constrained forward dynamics.

enumerator KINEMATICS#

kinematics simulation mode

enumerator INVERSE_DYNAMICS#

inverse dynamics for a tree system

enumerator UNDEFINED#

undefined solver type

Public Functions

ModelManager(const kc::ks_ptr<SubTree> &st, kc::ks_ptr<MMOptions> mm_opts = nullptr, MMSolverType solver_type = MMSolverType::UNDEFINED)#

ModelManager constructor. The constructor is not meant to be called directly. Please use the create(…) method instead to create an instance.

If the solver type is not specified, the constructor will use TREE_DYNAMICS if the specified st argument is a pure subtree (and not SubGraph), or if is the multibody instance itself with no bilateral constraints. For all other st, an error will be raised - and a legal solver type must be explicitly specified since there is no good way to infer one.

Parameters:

  • st – the SubTree instance

  • mm_opts – options for the model manager

  • solver_type – the solver type

~ModelManager()#

Destructor.

inline MMSolverType solverType() const#

Return the solver type for the propagator.

Returns:

the solver type

void setSolverType(MMSolverType solver_type)#

Set the solver type for the propagator.

Parameters:

solver_type – the new solver type

virtual void setState(const km::Vec &x)#

Reset the integrator to the new state values.

This is also referred to as a soft reset. This method assumes that only the state values have changed, and there have been no configuration changes causing changes to the size or structure of the state vector. The input state vector elements for subhinges should contain global coordinate values. This method resets the chart offsets for all regular and constraint subhinges for the sub graph.

The state itself is often created using the assembleState method.

See also

assembleState

Parameters:

x – the new state value

km::Vec assembleState() const#

Combine the current associated SubTree state and continuous KModel states into one vector.

This state vector reflects the current state of the Multibody and KModels’ continuous states, which may be different than the state vector in the integrator.

The packing order is the same as the integrator. This can be used to create an initial state for the integrator as follows: state_propagator->setState(state_propagator->assembleState()).

Returns:

A state vector representing the Multibody and KModels’ continuous states of this ModelManager.

km::Vec assembleStateDeriv() const#

Combine the current associated SubTree state derivative and continuous KModel state derivatives into one vector.

This state derivative vector reflects the current state of the Multibody and KModels’ continuous states’ derivatives, which may be different than the state vector in the integrator.

The packing order is the same as the integrator. *

Returns:

A state vector derivative representing the Multibody and KModels’ continuous states’ derivatives of this ModelManager.

inline size_t nstates() const#

Return the state vector size.

Returns:

the state vector size

virtual void derivFunction(const km::Ktime &t, const km::Vec &x, Eigen::Ref<km::Vec> dx)#

The derivative function for use by the integrator.

This method is used to compute the state derivative by the numerical integrator for propagating system state.

Parameters:

  • t – the current time

  • x – the current state

  • dx – the computed state derivative

virtual void setTime(const km::Ktime &t)#

Reset the integrator to the new time value.

This is also referred to as a soft reset. If the time set is different than the current time, this will attempt to rescheduled all TimedEvents appropriately; however, since TimedEvents can have arbitrary reschedule_fns, it is impossible to meet all corner cases. Use this with caution when you have non-uniform TimedEvents. See

System state section for more on this topic.

Parameters:

t – the new time

inline const km::Ktime &getTime() const#

Return the current state propagation time value.

Returns:

the Ktime time value

km::Mat computeJacobian()#

Use numerical differentiation and the derivative function to compute the Jacobian (experimental)

Returns:

the Jacobian matrix

void registerModel(const kc::ks_ptr<kmo::BaseKModel> &model)#

Register the provided BaseKModel model instance with the model manager.

See KModel component models section for more discussion on component models and the Registering and unregistering models section on registering models.

Registering a model is a way to activate a model so that it is used in the physics computations. See KModel component models section for more discussion on component models.

Parameters:

model – - The model to register.

void unregisterModel(const kc::ks_ptr<kmo::BaseKModel> &model)#

Unregister the provided BaseKModel model from the model manager.

Unregistering a model is a way to deactivate a model so that it is no longer used in the physics computations. See the

KModel component models section for more discussion on component models and the Registering and unregistering models section on registering models.

Parameters:

model – - The model to unregister.

const std::vector<kc::ks_ptr<kmo::BaseKModel>> &getRegisteredModels() const#

Return a vector or registered models.

Returns:

A vector of registered models.

kc::ks_ptr<kmo::BaseKModel> getRegisteredModel(std::string_view name) const#

Return the registered model with the specified name.

Parameters:

name – the name of the model being sought

Returns:

The registered model or null if there is no model with matching name

const kc::ks_ptr<SubTree> &getSubTree() const#

Return the SubTree used by this ModelManager.

Returns:

The SubTree used by this ModelManager.

virtual void hardReset()#

Reset the size of the internal state vector to match the size of the SubTree state.

  • the size of all the continuous model states.

This method also makeNotReadys the state, so setState must be called afterwards.

const kc::ks_ptr<TimeKeeper> &getTimeKeeper() const#

Return the TimeKeeper used by this ModelManager.

Returns:

The TimeKeeper used by this ModelManager.

std::string dumpString(std::string_view prefix = "", const Base::DumpOptions *options = nullptr) const override#

Public Members

bool trace_state_propagator = false#

Enable/disable model manager debug message.

MMFunctions fns#

User defined functions to tailor the behavior of the state propagator

Public Static Functions

static kc::ks_ptr<ModelManager> create(const kc::ks_ptr<SubTree> &st, kc::ks_ptr<MMOptions> mm_opts = nullptr, MMSolverType solver_type = MMSolverType::UNDEFINED)#

Create an instance of the ModelManager.

If the solver type is not specified, the constructor will use TREE_DYNAMICS if the specified st argument is a pure subtree (and not SubGraph), or if is the multibody instance itself with no bilateral constraints. For all other st, an error will be raised - and a legal solver type must be explicitly specified since there is no good way to infer one.

Parameters:

  • st – the SubTree instance

  • mm_opts – options for the model manager

  • solver_type – the solver type

Returns:

An instance of the ModelManager.

Protected Functions

void _setStateWithModels(const km::Vec &x, bool global = false)#

Pushes the combined state vector values into the SubTree state and continuous KModel states.

The packing order is the same as the integrator. This method is the converse of the assembleState() method.

Parameters:

  • x – the state vector

  • global – if true, the state coord values are for the global charts

void _discard(kc::ks_ptr<kc::Base> &base) override#

Discard the ModelManager.

Parameters:

base – A base pointer to the ModelManager to discard.

virtual void _hardSetState(const km::Ktime &t, const km::Vec &x)#

Resize and reset the new time and state values.

This is also referred to as a hard reset. This is like a soft reset, except it also allows the state vector size to change. The input state vector elements for subhinges should contain local chart coordinate values (in contrast with setState() which works with global coordinate values). The packing order should reflect the packing order of the ModelManager. See System state section for more on this topic.

Parameters:

  • t – the new time

  • x – the new state value

void _stdTraceMsg(std::string_view msg)#

Log a standard trace message.

Parameters:

msg – The message to log.

Eigen::Index _requiredStateSize() const#

Return the size that the ModelManager _curr_X should be.

This is the size of the SubTree’s states plus the size of the continuous model states.

Returns:

the size value

void _checkConstraintErrors(double threshold) const#

For SubGraphs, this method will verify that the Q and U coordinates currently in the SubGraph satisfy the constraints, i.e. the error norm is smaller than the specified threshold.

Parameters:

threshold – the threshold to use

virtual void registerTimedEvent(const kc::ks_ptr<TimedEvent> &timed_event)#

Register a TimedEvent. This is a no-op. Only used so we can call registerTimedEvent for KModels.

Parameters:

timed_event – The TimedEvent to register.

virtual void unregisterTimedEvent(std::string_view name, bool pre_hop, bool okay_not_exists = false)#

Unregister a TimedEvent.

This is a no-op. Only used so we can call registerTimedEvent for KModels.

Parameters:

  • name – - The name of the timed event to remove.

  • pre_hop – - Whether the event to remove is a pre_hop or post_hop timed event.

  • okay_not_exists – - If true, then do not error out if a timed event by this name does not exist with the given pre_hop setting, otherwise, error our if the given event is not found.

virtual bool hasRegisteredTimedEvent(std::string_view name, bool pre_hop) const#

Determine whether a TimedEvent with the given name exists.

This is a no-op. Only used so we can call registerTimedEvent for KModels.

Parameters:

  • name – - The name of the TimedEvent.

  • pre_hop – - Whether this is a pre_hop timed event or not.

Returns:

true if a TimedEvent with the given name and pre_hop setting exists, false otherwise.

Protected Attributes

kc::ks_ptr<SubTree> _st = nullptr#

the sub-tree

kc::ks_ptr<SubGraph> _sg = nullptr#

dynamic cast the subtree to a SubGraph. Non-null only if the subtree is in fact a SubGraph

Eigen::Index _nstates#

the size of the state vector

km::Vec _curr_X#

the current state value. Normally identical to the value in the integrator, but we have it here as well for cases where we do not have an integrator. This value is updated at the end of each integration sub-step and hop.

kc::ks_ptr<TimeKeeper> _time_keeper = nullptr#

The TimeKeeper keeps track of the time.

kc::RegistryList<kmo::BaseKModel> _registered_models#

List of registered models.

std::vector<kc::ks_ptr<kmo::BaseKModel>> _continuous_models#

List of models with continuous states.

Eigen::Array<Eigen::Index, Eigen::Dynamic, 1> _continuous_models_sizes#

Map with size of the continuous states for the models with continuous states.

kc::ks_ptr<MMOptions> _options = nullptr#

the model manager options

Eigen::Index _num_st_states#

The number of states in the SubTree.

Friends

friend class kmo::KModel
struct MMFunctions#

Struct with optional user-defined functions to be used by the model manager.

Public Members

kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&> pre_deriv_fns = kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&>()#

Optional function called before evaluating system derivative. Useful for setting gravity accel and other forces on the system.

kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&> post_deriv_fns = kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&>()#

Optional function called after evaluating system derivative. Useful for passing state derivative values to models that needs them, and to perform data logging.

kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&> pre_hop_fns = kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&>()#

Optional function called at the start of a hop step. Useful for propagating discrete states, sanitizing the input state (e.g., for changing coordinate chart origin), calling FSM step functions, processing external models to apply force inputs from closed-loop controllers etc.

kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&> post_hop_fns = kc::CallbackRegistry<void, const km::Ktime&, const km::Vec&>()#

Optional function called at the end of a hop step. Useful for processing external models that use the new state to set sensor inputs for closed-loop controllers, data logging, updating visualization, cleaning up the state to null out constraint errors etc.

std::function<bool(const km::Ktime&, const km::Vec&)> step_validate_fn = nullptr#

Optional function called at the end of a integration step to decide whether to accept the new state, or to roll back to the state at the start of the hop. Useful for repeating a the time step when the new state has invalid values.

kc::CallbackRegistry<bool, const km::Vec&, bool> zero_crossing_fns = kc::CallbackRegistry<bool, const km::Vec&, bool>()#

Optional function used for terminating a hop when a zero-crossing condition has been met. Useful for getting a simulation hop to terminate precisely when the implicitly defined zero-crossing condition occurs instead of continuing till the specified hop end time. See the

Zero-crossings section for more discussion on zero crossing detection.

The zero crossing functions return a bool. This should be true if the zero has been crossed. The second argument to the function is a boolean. This will be true when we have reached the zero, and false otherwise.

kc::CallbackRegistry<bool, const km::Ktime&, const km::Vec&> terminate_advance_to_fns = kc::CallbackRegistry<bool, const km::Ktime&, const km::Vec&>()#

Optional function called to check whether to terminate the state propagation prematurely before the state advancement end time has been reached. Handy when the simulation has already reached an end state (possibly for an FSM) and there is no value in continuing on with the state propagation. This check is only done at the end of a hop, so there may be some timing slop in the check for an end state. This is in contrast with the zero-crossing check which is done within a hop to end the hop precisely when the zero-crossing condition is met.

Friends

friend class ModelManager
class MMOptions : public std::enable_shared_from_this<MMOptions>#

Options for the model manager.

Subclassed by Karana::Dynamics::StatePropagator::SpOptions

Public Functions

MMOptions()#

MMOptions constructor. The constructor is not meant to be called directly. Please use the create(…) method instead to create an instance.

virtual ~MMOptions()#

Destructor.

Public Members

double baumgarte_stiffness = -1#

the Baumgarte stiffness parameter

Parameters for the Baumgarte method for loop constraint stabilization

double baumgarte_damping = -1#

the Baumgarte damping parameter

Public Static Functions

static kc::ks_ptr<MMOptions> create()#

Create an instance of MMOptions.

Returns:

A pointer to the newly created MMOptions.

Contents