blueprints.actuators module#

Actuators are the interface by which an Agent moves in the World. The following description is summarized from Mujoco. The nomenclature is summarized in the following table.

Keyword	Nomenclature
Actuator index	\({}_i\)
Actuator control input	\(u_i\)
Actuator force output	\(p_i\)
Actuator Length	\(l_i(q)\)
Joint position	\(q\)
Joint momentum arms for each Actuator	\(\nabla l_i(q)\)
Gain term	\(\bf a\)
Bias term	\(\bf b\)
Gain parameters	\(\vec a\)
Bias parameters	\(\vec b\)
Dynamics parameters	\(\vec d\)

Force Transmission#

Actuators enables Agents to move in the World. Each Actuator has a single control input \(u_i\) and a single force output \(p_i\). Additionally each Actuator has a scalar value called its length \(l_i(q)\) which is a function of the Joints position \(q\) and is defined by the Actuators properties. The force of an Actuator acting on a Joint is the Actuator force \(p\) distributed over the Joints degrees of freedoms by scaling them with the momentum arms \(\nabla l\). The net force acting on a Joint than is:

\(\vec F = \sum_i \nabla l_i(q) \cdot p_i\)

Force Generation#

The force generated by an Actuator affacting a Joint is dependent on three variables, ‘Actuator control input \(u_i\), a dynamic activation state \(w_i\) (for some Actuators) and the Actuator length for the Joint \(l_i(q)\) as well as its velocity \(\dot{l}_i(q)\). The force is generated from an affine mapping with a linear gain term \(\bf a\) and a bias term \(\bf b\).

\(p_i(u_i, w_i, l_i, \dot l_i) = \textbf {a} (l_i, \dot l_i) \cdot (u_i \text{ or } w_i) + \textbf {b} (l_i, \dot l_i)\)

Gain#

The gain term \(\bf a\) is linear w.r.t. either the control output \(u_i\) or the activation variable \(w_i\) which dynamically depends on \(u_i\) and will be explained in a later section. The activation dynamics are defined in dyntype. The gain term is computed by one of the following options, which can be specified in gaintype and the respective gain parameters \(\vec a\) are defined in gainprm.

`gaintype`	\(\textbf{a}(l_i, \dot l_i)\)
`'fixed'`	\(\textbf{a} = a_0\)
`'affine'`	\(\textbf{a} = a_0 + a_1 \cdot l_i + a_2 \cdot \dot l_i\)
`'muscle'`	\(\textbf{a} = \text{muscle_gain}(…)\)
`'user'`	\(\textbf{a} = \text{user_gain}(…)\)

A description for muscle dynamics can be found here.

Bias#

The bias term is a constant added to the Actuator force and does not depend on the Actuator outputs. The bias term is computed by one of the following options, which can be specified in biastype and the respective bias parameters \(\vec b\) are defined in biasprm.

`biastype`	\(\textbf{b}(l_i, \dot l_i)\)
`'none'`	\(\textbf{b} = 0\)
`'affine'`	\(\textbf{b} = b_0 + b_1 \cdot l_i + b_2 \cdot \dot l_i\)
`'muscle'`	\(\textbf{b} = \text{muscle_bias}(…)\)
`'user'`	\(\textbf{b} = \text{user_bias}(…)\)

A description for muscle dynamics can be found here.

Activation#

Some Actuators use an activation variable \(\textbf{w}\) instead of the control variable \(\textbf{u}\) to compute \(\textbf{a}\). The activation dynamics are specified in dyntype and the respective dynamics parameters \(\vec d\) are defined in dynprm.

`dyntype`	Force Generation \(p_i(u_i, w_i, l_i, \dot l_i)\)	Activation dynamics \(w_i\)
`'none'`	\(p_i = \textbf{a} \cdot u_i + \textbf{b}\)	No internal state
`'integrator'`	\(p_i = \textbf{a} \cdot w_i + \textbf{b}\)	\(\dot w = u\)
`'filter'`	\(p_i = \textbf{a} \cdot w_i + \textbf{b}\)	\(\dot w = (u - w)/d_0\)
`'filterexact'`	\(p_i = \textbf{a} \cdot w_i + \textbf{b}\)	like filter but with exact integration
`'muscle'`	\(p_i = \textbf{a} \cdot w_i + \textbf{b}\)	\(\dot w = \text{muscle_dyn}(…)\)
`'user'`	\(p_i = \textbf{a} \cdot w_i + \textbf{b}\)	\(\dot w = \text{user_dyn}(…)\)

A description for muscle dynamics can be found here.

Usage#

Actuators can either be defined using the General Actuator, or by using one of the shortcut Actuators — Motor, Position, Velocity, IntVelocity, Damper, Cylinder, Muscle and Adhesion.

Attachment#

Actuators will apply a force to their parent. They can be attached to Bodies, Joints and Sites.

Attachment to Parents#

>>> actuator = blue.actuators.General()
>>> body  = blue.Body(actuators=actuator)
>>> joint = blue.joints.Joint(actuators=actuator)
>>> site  = blue.sites.Site(actuators=actuator)

For the force computation an Actuator that is attached to a Joint can also use the joints parent frame of reference by setting the inparent argument.

Joint in parent#

>>> actuator = blue.actuators.General(inparent=True)
>>> joint = blue.joints.Joint(actuators=actuator)

Sites can also use a different frame of reference using either the refsite or the ref_actuators attribute. This can only be done for Sites that are part of the same kinematic tree.

Reference Sites#

Reference Sites Error#

>>> source = blue.sites.Site(name='source')
>>> target = blue.sites.Site(name='target')
>>> source.attach(actuator)
>>> target.ref_actuators = source.actuators
ValueError: Setting refsite is only allowed for references that share the same root.

Setting reference Sites can either be done, by setting the ref_actuators or the refsite attribute.

Reference Sites Variations#

>>> root = blue.Body(sites=[source, target])

VARIATION 1

>>> root.sites['target'].ref_actuators = root.sites['source'].actuators

VARIATION 2

>>> root.sites['source'].actuators.refsite = root.sites['target']

The resulting XML looks like this:

XML Structure Attachment#

<mujoco>
    <actuator>
        <general name="unnamed_general" refsite="target" site="source" />
    </actuator>
    <worldbody>
        <body name="root">
            <site type="site" name="source" />
            <site type="site" name="target" />
        </body>
    </worldbody>
</mujoco>

Detachment#

When the parent Site or the reference Site are no longer part of the same kinematic tree, the reference Site gets detached. This is necessary to avoid redundant copies of Actuators of orphaned parents and references.

Reference Sites Detachment#

>>> root.sites['source'].actuators.refsite
View[1|root.sites.actuators.refsite]
>>> root.detach(root.sites['target'])
>>> root.sites['source'].actuators.refsite
[]

The resulting XML looks like this:

XML Structure Detachment#

<mujoco>
    <actuator>
        <general name="unnamed_general" site="source" />
    </actuator>
    <worldbody>
        <body name="root">
            <site type="site" name="source" />
        </body>
    </worldbody>
</mujoco>

Parent Sites Detachment#

>>> root.sites['source'].actuators.refsite
View[1|root.sites.actuators.refsite]
>>> root.detach(root.sites['source'])
>>> root.sites['target'].ref_actuators
View[0|root.sites.ref_actuators]

The resulting XML looks like this:

XML Structure Detachment#

<mujoco>
    <worldbody>
        <body name="root">
            <site type="site" name="target" />
        </body>
    </worldbody>
</mujoco>

Note

Actuators will not appear as children of their parents in xml, but instead in a separate <actuators> element.

class blueprints.actuators.BaseActuator[source]#

Bases: ActuatorType, CyclicalThing, NodeThing

Most attribute descriptions are partially taken from Mujoco.

__init__(name=None, inparent=False, ctrllimited=None, forcelimited=None, actlimited=None, ctrlrange=[0.0, 0.0], forcerange=[0.0, 0.0], actrange=[0.0, 0.0], lengthrange=[0.0, 0.0], gear=[1.0, 0.0, 0.0, 0.0, 0.0, 0.0], cranklength=0.0, dyntype='none', gaintype='fixed', biastype='none', dynprm=1.0, gainprm=1.0, biasprm=1.0, sensors=None, copy=True, **kwargs)[source]#

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
inparent (bool, optional) – If`:attr:inparent is True and the parent of the Actuator is blueprints.joints.BaseJoint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. It is different from the gain in the force generation mechanism, because the gain only scales the force output and does not affect the length, moment arms and velocity. For actuators with scalar transmission, only the first element of this vector is used. The remaining elements are needed for joint (with or without inparent) and site transmissions where this attribute is used to specify 3D force and torque axes.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.

dyntype (str, optional) –

Activation dynamics type for the actuator.

Keyword	Description
`'none'`	No internal state
`'integrator'`	\(\dot w = u\)
`'filter'`	\(\dot w = (u - w)/\text{dynprm}[0]\)
`'filterexact'`	Like filter but with exact integration
`'muscle'`	\(\dot w = \text{mju_muscleDynamics}(…)\)
`'user'`	\(\dot w = \text{mjcb_act_dyn}(…)\)

gaintype (str, optional) –

The gain and bias together determine the output of the force generation mechanism, which is currently assumed to be affine. As already explained above, the general formula is: \(p = \textbf{a} \cdot (u \text{ or } w) + \textbf{b}\) The formula uses the activation state when present, and the control otherwise. The keywords have the following meaning:

Keyword	Description
`'fixed'`	\(\textbf{a} = a_0\)
`'affine'`	\(\textbf{a} = a_0 + a_1 \cdot length + a_2 \cdot velocity\)
`'muscle'`	\(\textbf{a} = \text{mju_muscleGain}(…)\)
`'user'`	\(\textbf{a} = \text{mjcb_act_gain}(…)\)

biastype (str, optional) –

The keywords have the following meaning:

Keyword	Description
`'none'`	\(\textbf{b} = 0\)
`'affine'`	\(\textbf{b} = b_0 + b_1 \cdot length + b_2 \cdot velocity\)
`'muscle'`	\(\textbf{b} = \text{mju_muscleBias}(…)\)
`'user'`	\(\textbf{b} = \text{mjcb_act_bias}(…)\)

dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. The built-in activation types (except for muscle) use only the first parameter, but we provide additional parameters in case user callbacks implement a more elaborate model. The length of this array is not enforced by the parser, so the user can enter as many parameters as needed. These defaults are not compatible with muscle actuators.
gainprm (int | float | list[int | float] | np.ndarray, optional) – Gain parameters. The built-in gain types (except for muscle) use only the first parameter, but we provide additional parameters in case user callbacks implement a more elaborate model. The length of this array is not enforced by the parser, so the user can enter as many parameters as needed. These defaults are not compatible with muscle actuators.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. The affine bias type uses three parameters. The length of this array is not enforced by the parser, so the user can enter as many parameters as needed. These defaults are not compatible with muscle actuators.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property force: float#

The force applied to the Actuator

Return type:: float

property activation: float | None#

The activation state of the Actuator

Return type:: float

property parent_tag#

The name of the parent that is used for the reference attribute in the xml tag.

Returns:: A string describing the parent tag
Return type:: str
Raises:: ValueError – If the parent is not of a valid ThingType an error is raised.

property inparent: bool#

If inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.

Return type:: bool

property refsite: SiteType | None#

If refsite is set to a side, the Actuator will assume the frame of reference of the refsite instead of its parent. This only possible if the parent is also a Site.

Return type:: blue.SiteType | None

property tag: str#

The tag will later become the tag name of the xml element.

Return type:: str

property ctrllimited: bool | None#

If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.

Return type:: bool | None

property forcelimited: bool | None#

If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.

Return type:: bool | None

property actlimited: bool | None#

If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.

Return type:: bool | None

property ctrlrange: ndarray#

Range for clamping the control input. The compiler expects the first value to be smaller than the second value.

Return type:: np.ndarray

property forcerange: ndarray#

Range for clamping the force output. The compiler expects the first value to be no greater than the second value.

Return type:: np.ndarray

property actrange: ndarray#

Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.

Return type:: np.ndarray

property lengthrange: ndarray#

Range of feasible lengths of the actuator’s transmission.

Return type:: np.ndarray

property gear: ndarray#

This attribute scales the length (and consequently moment arms, velocity and force) of the Actuator, for all transmission types. It is different from the gain in the force generation mechanism, because the gain only scales the force output and does not affect the length, moment arms and velocity. For actuators with scalar transmission, only the first element of this vector is used. The remaining elements are needed for joint (with or without inparent) and site transmissions where this attribute is used to specify 3D force and torque axes.

Return type:: np.ndarray

property cranklength: float#

Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.

Return type:: float

property dyntype: str#

Activation dynamics type for the actuator. See dyntype for a detailed description.

Return type:: str

property gaintype: str#

The gain and bias together determine the output of the force generation mechanism, which is currently assumed to be affine. See gaintype for a detailed description.

Return type:: str

property biastype: str#

See biastype for a detailed description.

Return type:: str

property dynprm: ndarray#

Activation dynamics parameters. The built-in activation types (except for muscle) use only the first parameter, but we provide additional parameters in case user callbacks implement a more elaborate model. The length of this array is not enforced by the parser, so the user can enter as many parameters as needed. These defaults are not compatible with muscle actuators.

Return type:: np.ndarray

property gainprm: ndarray#

Gain parameters. The built-in gain types (except for muscle) use only the first parameter, but we provide additional parameters in case user callbacks implement a more elaborate model. The length of this array is not enforced by the parser, so the user can enter as many parameters as needed. These defaults are not compatible with muscle actuators.

Return type:: np.ndarray

property biasprm: ndarray#

Bias parameters. The affine bias type uses three parameters. The length of this array is not enforced by the parser, so the user can enter as many parameters as needed. These defaults are not compatible with muscle actuators.

Return type:: np.ndarray

class blueprints.actuators.General[source]#

Bases: BaseActuator

This is the General form of an Actuator. Useful shortcuts are defined in the following classes.

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

class blueprints.actuators.Motor[source]#

Bases: BaseActuator

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

class blueprints.actuators.Position[source]#

Bases: BaseActuator

__init__(name=None, gear=[1.0, 0.0, 0.0, 0.0, 0.0, 0.0], kp=1.0, ctrllimited=True, forcelimited=None, actlimited=None, ctrlrange=[0.0, 0.0], forcerange=[0.0, 0.0], actrange=[0.0, 0.0], lengthrange=[0.0, 0.0], cranklength=0.0, dyntype='none', gaintype='fixed', biastype='none', dynprm=1.0, gainprm=1.0, biasprm=1.0, sensors=None, copy=True, **kwargs)[source]#

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
kp (int|float) – Position feedback gain.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property kp: float#

Position feedback gain.

Return type:: float

class blueprints.actuators.Velocity[source]#

Bases: BaseActuator

__init__(name=None, gear=[1.0, 0.0, 0.0, 0.0, 0.0, 0.0], kv=1.0, ctrllimited=True, forcelimited=None, actlimited=None, ctrlrange=[0.0, 0.0], forcerange=[0.0, 0.0], actrange=[0.0, 0.0], lengthrange=[0.0, 0.0], cranklength=0.0, dyntype='none', gaintype='fixed', biastype='none', dynprm=1.0, gainprm=1.0, biasprm=1.0, sensors=None, copy=True, **kwargs)[source]#

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
kv (int|float) – Velocity feedback gain.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property kv: float#

Velocity feedback gain.

Return type:: float

class blueprints.actuators.IntVelocity[source]#

Bases: BaseActuator

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
kp (int | float) – Position feedback gain.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property kp: float#

Position feedback gain.

Return type:: float

class blueprints.actuators.Damper[source]#

Bases: BaseActuator

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
kv (int | float) – Velocity feedback gain.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property kv: float#

Velocity feedback gain.

Return type:: float

class blueprints.actuators.Cylinder[source]#

Bases: BaseActuator

__init__(name=None, gear=[1.0, 0.0, 0.0, 0.0, 0.0, 0.0], timeconst=1.0, area=1.0, diameter=None, bias=[0.0, 0.0, 0.0], ctrllimited=True, forcelimited=None, actlimited=None, ctrlrange=[0.0, 0.0], forcerange=[0.0, 0.0], actrange=[0.0, 0.0], lengthrange=[0.0, 0.0], cranklength=0.0, dyntype='none', gaintype='fixed', biastype='none', dynprm=1.0, gainprm=1.0, biasprm=1.0, sensors=None, copy=True, **kwargs)[source]#

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
timeconst (int | float) – Time constant of the activation dynamics.
area (int | float) – Area of the cylinder. This is used internally as actuator gain.
diameter (int | float | None) – Instead of area the user can specify diameter. If both are specified, diameter has precedence.
bias (np.ndarray | list[int | float]) – Bias parameters, copied internally into biasprm.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property timeconst: float#

Time constant of the activation dynamics.

Return type:: float

property area: float#

Area of the cylinder. This is used internally as actuator gain.

Return type:: float

property diameter: float | None#

Instead of area the user can specify diameter. If both are specified, diameter has precedence.

Return type:: float | None

property bias: ndarray#

Bias parameters, copied internally into biasprm.

Return type:: np.ndarray

class blueprints.actuators.Muscle[source]#

Bases: BaseActuator

__init__(name=None, gear=[1.0, 0.0, 0.0, 0.0, 0.0, 0.0], timeconst=[0.01, 0.04], tausmooth=0.0, range=[0.75, 1.05], force=-1.0, scale=200, lmin=0.5, lmax=1.6, vmax=1.5, fpmax=1.3, fvmax=1.2, ctrllimited=True, forcelimited=None, actlimited=None, ctrlrange=[0.0, 0.0], forcerange=[0.0, 0.0], actrange=[0.0, 0.0], lengthrange=[0.0, 0.0], cranklength=0.0, dyntype='none', gaintype='fixed', biastype='none', dynprm=1.0, gainprm=1.0, biasprm=1.0, sensors=None, copy=True, **kwargs)[source]#

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
timeconst (np.ndarray | list[int | float]) – Time constants for activation and de-activation dynamics.
tausmooth (int | float) – Width of smooth transition between activation and deactivation time constants. Units of ctrl, must be nonegative.
range (np.ndarray | list[int | float]) – Operating length range of the muscle, in units of L0.
force (int | float) – Peak active force at rest. If this value is negative, the peak force is determined automatically using the scale attribute below.
scale (int | float) – If the force attribute is negative, the peak active force for the muscle is set to this value divided by mjModel.actuator_acc0. The latter is the norm of the joint-space acceleration vector caused by unit force on the actuator’s transmission in qpos0. In other words, scaling produces higher peak forces for muscles that pull more weight.
lmin (int | float) – Lower position range of the normalized FLV curve, in units of L0.
lmax (int | float) – Upper position range of the normalized FLV curve, in units of L0.
vmax (int | float) – Shortening velocity at which muscle force drops to zero, in units of L0 per second.
fpmax (int | float) – Passive force generated at lmax, relative to the peak rest force.
fvmax (int | float) – Active force generated at saturating lengthening velocity, relative to the peak rest force.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property timeconst: ndarray#

Time constants for activation and de-activation dynamics.

Return type:: np.ndarray

property tausmooth: float#

Width of smooth transition between activation and deactivation time constants. Units of ctrl, must be nonegative.

Return type:: float

property range: ndarray#

Operating length range of the muscle, in units of L0.

Return type:: np.ndarray

property force: float#

Peak active force at rest. If this value is negative, the peak force is determined automatically using the scale attribute below.

Return type:: float

property scale: float#

If the force attribute is negative, the peak active force for the muscle is set to this value divided by mjModel.actuator_acc0. The latter is the norm of the joint-space acceleration vector caused by unit force on the actuator’s transmission in qpos0. In other words, scaling produces higher peak forces for muscles that pull more weight.

Return type:: float

property lmin: float#

Lower position range of the normalized FLV curve, in units of L0.

Return type:: float

property lmax: float#

Upper position range of the normalized FLV curve, in units of L0.

Return type:: float

property vmax: float#

Shortening velocity at which muscle force drops to zero, in units of L0 per second.

Return type:: float

property fpmax: float#

Passive force generated at lmax, relative to the peak rest force.

Return type:: float

property fvmax: float#

Active force generated at saturating lengthening velocity, relative to the peak rest force.

Return type:: float

class blueprints.actuators.Adhesion[source]#

Bases: BaseActuator

__init__(name=None, gear=[1.0, 0.0, 0.0, 0.0, 0.0, 0.0], gain=1.0, ctrllimited=None, forcelimited=None, actlimited=None, ctrlrange=[0.0, 1.0], forcerange=[0.0, 0.0], actrange=[0.0, 0.0], lengthrange=[0.0, 0.0], cranklength=0.0, dyntype='none', gaintype='fixed', biastype='none', dynprm=1.0, gainprm=1.0, biasprm=1.0, sensors=None, copy=True, **kwargs)[source]#

Parameters:

name (str | None, optional) – The user specified name for the Actuator. In the case of a naming conflict the name will be altered by an enumeration scheme.
gain (int | float) – Gain of the adhesion actuator, in units of force. The total adhesion force applied by the Actuator is the control value multiplied by the gain. This force is distributed equally between all the contacts involving geoms belonging to the target Body.
inparent (bool, optional) – If :attr:`inparent is True and the parent of the Actuator is Joint the actuator assumes the frame of reference from the parent.
ctrllimited (bool | None, optional) – If true, the control input to this actuator is automatically clamped to ctrlrange at runtime. If false, control input clamping is disabled.
forcelimited (bool | None, optional) – If true, the force output of this actuator is automatically clamped to forcerange at runtime. If false, force clamping is disabled.
actlimited (bool | None, optional) – If true, the internal state (activation) associated with this actuator is automatically clamped to actrange at runtime.
ctrlrange (np.ndarray | list[int | float], optional) – Range for clamping the control input. The compiler expects the first value to be smaller than the second value.
forcerange (np.ndarray | list[int | float], optional) – Range for clamping the force output. The compiler expects the first value to be no greater than the second value.
actrange (np.ndarray | list[int | float], optional) – Range for clamping the activation state. The compiler expects the first value to be no greater than the second value.
lengthrange (np.ndarray | list[int | float], optional) – Range of feasible lengths of the actuator’s transmission.
gear (np.ndarray | list[int | float], optional) – This attribute scales the length (and consequently moment arms, velocity and force) of the actuator, for all transmission types. See gear for a detailed description.
cranklength (int | float, optional) – Used only for the slider-crank transmission type. Specifies the length of the connecting rod. The compiler expects this value to be positive when a slider-crank transmission is present.
dyntype (str, optional) – See dyntype for a detailed description.
gaintype (str, optional) – See gaintype for a detailed description.
biastype (str, optional) – See biastype for a detailed description.
dynprm (int | float | list[int | float] | np.ndarray, optional) – Activation dynamics parameters. See dynprm for a detailed description.
gainprm (int | float | list[int | float] | np.ndarray, optional) – The gain and bias together determine the output of the force generation mechanism. See gainprm for a detailed description.
biasprm (int | float | list[int | float] | np.ndarray, optional) – Bias parameters. See biasprm for a detailed description.
sensors (list | blue.SensorType | None, optional) – The Sensors are attached to the actuator on initialization.
copy (bool, optional) – If True, the Sensors passed during init will be copied before attachment, otherwise the original Sensor is attached.
**kwargs – Keyword arguments are passed to super().__init__.

property parent: BodyType | None#

The parent to which the Thing is attach, if it unattached parent is None.

Return type:: blueBodyType

property gain: float#

Gain of the adhesion actuator, in units of force. The total adhesion force applied by the Actuator is the control value multiplied by the gain. This force is distributed equally between all the contacts involving geoms belonging to the target Body.

Return type:: float

blueprints.actuators module#

Force Transmission#

Force Generation#

Gain#

Bias#

Activation#

Usage#

Attachment#

Reference Sites#

Detachment#

This Page