MJSpec

Variables

template<class> bool dependent_false = false

class MJSpec

#include <MJSpec.h>

A wrapper for a MuJoCo mjSpec, which represents a high-level model specification.

The MJSpec class manages a pair of MuJoCo models and data objects, for which it supports recompilation.

This class owns the compiled model/data pair and tracks Basilisk wrappers for the bodies, actuators, and equalities of an MJScene. Recompilation prepares a candidate model, validates established state and runtime layouts, copies runtime values, and updates wrapper bindings after replacing the model. Configuration errors propagate without restoring the previous wrapper bindings.

NoRecompileGuard keeps borrowed model/data pointers stable during scene callbacks. Model initialization uses the compiled result and updates state values directly.

Public Functions

MJSpec(MJScene &scene, std::string xmlString, const std::vector<std::string> &files = {})

Constructs an MJSpec object.

Parameters:

scene – Reference to the MJScene managing this spec.
xmlString – The XML string defining the MuJoCo model.
files – Optional list of additional files to load.

MJSpec(const MJSpec&) = delete

MJSpec(MJSpec&&) = delete

MJSpec &operator=(const MJSpec&) = delete

MJSpec &operator=(MJSpec&&) = delete

inline MJScene &getScene()

Retrieves the scene that this model specification represents.

Returns:: Reference to the MJScene.

void markAsNeedingToRecompileModel(): Declares that the mjModel should recompiled because we performed an action that rendered the current mjModel stale.

mjModel *getMujocoModel()

Retrieves the MuJoCo model (mjModel object).

Returns:: Pointer to the MuJoCo model.

mjData *getMujocoData()

Retrieves the MuJoCo data (mjData object).

Returns:: Pointer to the MuJoCo data.

mjSpec *getMujocoSpec()

Retrieves the raw MuJoCo model specification (mjSpec object).

Returns:: Pointer to the MuJoCo specification.

bool recompileIfNeeded()

Recompiles the model if needed.

Returns:: True if recompilation occurred, false otherwise.

void recompileUntilStable(): Recompile until configuration no longer requests another pass.

inline bool hasPendingModelChanges() const noexcept: Return whether the specification has uncompiled model changes.

void configureForStateRegistration()

Compile all pending specification changes and configure wrappers.

This completes before MJScene registers states, so all registered dimensions and qpos policy topology come from the final model.

void configure(): Configures all bodies, actuators, and equalities with the current model.

inline std::list<MJBody> &getBodies()

Retrieves the list of all bodies in the simulation.

Returns:: Reference to the list of MJBody objects.

inline std::vector<std::unique_ptr<MJActuator>> &getActuators()

Retrieves the list of all actuators in the simulation.

Returns:: Reference to the vector of unique pointers to MJActuator objects.

inline std::list<MJEquality> &getEqualities()

Retrieves the list of equalities in the simulation.

Note that this not include constraint equalities automatically created for all scalar joints in the simulation.

Returns:: Reference to the list of MJEquality objects.

std::vector<std::string> getBodyNames() const

Retrieves the names of all bodies in the specification.

This method does not trigger model recompilation, so it can be called before initialization.

Returns:: A vector of body names.

std::string getBodyParentName(const std::string &bodyName) const

Retrieves the parent body name of a given body.

Uses the existing compiled model (without triggering recompilation) to look up the parent relationship. Returns the string "world" if the body’s direct parent is the worldbody. Throws std::invalid_argument if no body with the given name exists.

Parameters:: bodyName – The name of the body.
Throws:: std::invalid_argument – If the body does not exist.
Returns:: The parent body’s name, or "world" if the parent is the worldbody.

std::vector<MJGeomInfo> getGeomInfos() const

Retrieves geometry information for all geoms in the model.

Uses the existing compiled model (without triggering recompilation). Each entry describes a geom’s shape, size, position, orientation, and color, along with which body it belongs to.

Returns:: A vector of MJGeomInfo structs.

bool hasActuator(const std::string &name)

Checks if an actuator exists with the given name.

Parameters:: name – The name of the actuator.
Returns:: True if the actuator exists, false otherwise.

template<typename T> T &getActuator(const std::string &name)

Retrieves an actuator by name and casts it to the specified type.

Template Parameters:: T – The expected type of the actuator.
Parameters:: name – The name of the actuator.
Throws:: std::invalid_argument – If the actuator does not exist or has a different type.
Returns:: Reference to the actuator of type T.

MJSingleActuator &addJointSingleActuator(const std::string &name, const std::string &joint)

Adds a single-input actuator acting on a joint (MJSingleActuator).

This actuator will impart a force and/or torque at the given joint.

Parameters:

name – The name of the actuator.
joint – The joint to attach the actuator.

Returns:

Reference to the created MJSingleActuator.

MJSingleActuator &addSingleActuator(const std::string &name, const std::string &site, const Eigen::Vector6d &gear)

Adds a single-input actuator (MJSingleActuator).

This actuator will impart a force and/or torque at the given site.

The gear argument defines how the single input of the actuator (the control value of this actuator is a single value) maps into a force and/or torque. For example:

For gear={1,0,0,0,0,0} and ctrl=10, the actuator will impart 10 N of force along the X-axis of the site reference frame.
For gear={1,0,0,0,1,0} and ctrl=10, the actuator will impart 10 N of force along the X-axis of the site reference frame and 10 Nm of torque along the Y-axis of the same reference frame.

Parameters:

name – The name of the actuator.
site – The site to attach the actuator.
gear – The gear parameters for the actuator.

Returns:

Reference to the created MJSingleActuator.

template<typename T> inline T &addCompositeActuator(const std::string &name, const std::string &site)

Adds a composite actuator to the specification.

Composite actuators are those composed by more than one single actuator.

Template Parameters:

T – The type of composite actuator to add. Supported types are MJForceActuator, MJTorqueActuator, MJForceTorqueActuator.

Parameters:

name – The name of the actuator.
site – The site to attach the actuator.

Returns:

Reference to the created actuator of type T.

Protected Functions

void loadBodies(): Load bodies in spec into MJBody.

void loadActuators(): Load actuators in spec into MJActuator.

void loadEqualities(): Load equalities in spec into MJEquality.

template<typename T> std::unique_ptr<T> createActuator(const std::string &name, const std::string &siteHint, std::unordered_map<std::string, MJActuatorObject> &existingActuators)

Creates an actuator of type T, where T must be one of: MJForceActuator, MJTorqueActuator, or MJForceTorqueActuator.

The actuator will be composed of a collection of the MJActuatorObject given in existingActuators, if they are available. Otherwise, new MJActuatorObject will be created at the given site.

Template Parameters:

T – The type of actuator to add. Supported types are MJForceActuator, MJTorqueActuator, MJForceTorqueActuator.

Parameters:

name – The name of the actuator.
siteHint – The site to attach the actuator.
existingActuators – Colleciton of existing MJActuatorObject to use.

Returns:

Reference to the created actuator of type T.

Protected Attributes

std::unique_ptr<mjSpec, MJBasilisk::detail::mjSpecDeleter> spec: MuJoCo spec.

std::unique_ptr<mjModel, MJBasilisk::detail::mjModelDeleter> model: MuJoCo model.

std::unique_ptr<mjData, MJBasilisk::detail::mjDataDeleter> data: MuJoCo data.

std::unique_ptr<mjVFS, MJBasilisk::detail::mjVFSDeleter> virtualFileSystem: MuJoCo virtual file system.

MJScene &scene: Reference to the associated scene.

std::vector<std::unique_ptr<MJActuator>> actuators: List of actuators.

std::list<MJBody> bodies: List of bodies.

std::list<MJEquality> equalities: List of equalities.

bool shouldRecompile = false: A number of operations on the mjSpec (like adding elements) will require that we recompile the mjModel. If this flag is true when getMujocoModel()/getMujocoData() is called, then they will be recompiled before returning. However, also read the docstring for shouldRecompileWhenAsked.

bool shouldRecompileWhenAsked = true: If we are going to make a series of operations that should trigger a recompile, but we want to avoid having to recompile until they are all done, then we can switch this flag, which will prevent any recompilation when calling getMujocoModel()/getMujocoData().

struct NoRecompileGuard

#include <MJSpec.h>

Guard to temporarily disable model recompilation.

Disables automatic recompilation of the MuJoCo model during its lifetime. Can be used when one wants to take one or several actions that would normally trigger a model recompilation, but for efficiency recompilation is suppressed until a later moment.

Public Functions

inline NoRecompileGuard(MJSpec &spec)

Constructs the guard and disables recompilation.

Parameters:: spec – Reference to the MJSpec object.

NoRecompileGuard(const NoRecompileGuard&) = delete

NoRecompileGuard &operator=(const NoRecompileGuard&) = delete

NoRecompileGuard(NoRecompileGuard&&) = delete

NoRecompileGuard &operator=(NoRecompileGuard&&) = delete

inline ~NoRecompileGuard() noexcept: Restores the previous recompilation flag state.

Public Members

MJSpec &spec: Reference to the MJSpec object.

bool prevShouldRecompileWhenAsked: Previous state of recompilation flag.

namespace Eigen

Typedefs

using Vector6d = Eigen::Matrix<double, 6, 1>