Generic¶

Generic quantities that may be relevant for any kind of robot, regardless its topology (multiple or single branch, fixed or floating base…) and the application (locomotion, grasping…).

class gym_jiminy.common.quantities.generic.FrameQuantity(*args, **kwargs)[source]¶

Bases: Protocol

Protocol that must be satisfied by all quantities associated with one particular frame.

This protocol is used when aggregating individual frame-level quantities in a larger batch for computation vectorization on all frames at once. Intermediate quantities managing these batches will make sure that all their parents derive from one of the supported protocols, which includes this one.

frame_name: str¶

class gym_jiminy.common.quantities.generic.MultiFrameQuantity(*args, **kwargs)[source]¶

Bases: Protocol

Protocol that must be satisfied by all quantities associated with a particular set of frames for which the same batched intermediary quantities must be computed.

This protocol is involved in automatic computation vectorization. See FrameQuantity documentation for details.

frame_names: Tuple[str, ...]¶

gym_jiminy.common.quantities.generic.aggregate_frame_names(quantity)[source]¶

Generate a sequence of frame names that contains all the sub-sequences specified by the parents of all the cache owners of a given quantity.

Ideally, the generated sequence should be the shortest possible. Since finding the optimal sequence is a complex problem, a heuristic is used instead. It consists in aggregating first all multi-frame quantities sequentially after ordering them by decreasing length, followed by all single-frame quantities.

Note

Only active quantities are considered for best performance, which may change dynamically. Delegating this responsibility to cache owners may be possible but difficult to implement because frame_names must be cleared first before re-registering themselves, just in case of optimal computation graph has changed, not only once to avoid getting rid of quantities that just registered themselves. Nevertheless, whenever re-initializing this quantity to take into account changes of the active set must be decided by cache owners.

Parameters:: quantity (InterfaceQuantity) – Quantity whose parent implements either FrameQuantity or MultiFrameQuantity protocol. All the parents of all its cache owners must also implement one of these protocol.
Return type:: Tuple[Tuple[str, …], Dict[str | Tuple[str, …], int | Tuple[()] | slice]]

class gym_jiminy.common.quantities.generic.OrientationType(value)[source]¶

Bases: IntEnum

Specify the desired vector representation of the frame orientations.

MATRIX = 0¶: 3D rotation matrix.

EULER = 1¶: Euler angles (Roll, Pitch, Yaw).

QUATERNION = 2¶: Quaternion coordinates (QuatX, QuatY, QuatZ, QuatW).

ANGLE_AXIS = 3¶: Angle-Axis representation (theta * AxisX, theta * AxisY, theta * AxisZ).

conjugate()¶: Returns self, the complex conjugate of any int.

bit_length()¶

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

bit_count()¶

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

to_bytes(length, byteorder, *, signed=False)¶

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

from_bytes(byteorder, *, signed=False)¶

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Indicates whether two’s complement is used to represent the integer.

as_integer_ratio()¶

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

real¶: the real part of a complex number

imag¶: the imaginary part of a complex number

numerator¶: the numerator of a rational number in lowest terms

denominator¶: the denominator of a rational number in lowest terms

class gym_jiminy.common.quantities.generic.FrameOrientation(env, parent, frame_name, *, type=OrientationType.MATRIX, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Vector representation of the orientation of a given frame in world reference frame at the end of the agent step.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name (str) – Name of the frame on which to operate.
type (OrientationType) – Desired vector representation of the orientation. Optional: ‘OrientationType.MATRIX’ by default.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.

frame_name: str¶: Name of the frame on which to operate.

type: OrientationType¶: Desired vector representation of the orientation.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

initialize()[source]¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.MultiFrameOrientation(env, parent, frame_names, *, type=OrientationType.MATRIX, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Vector representation of the orientation of a given set of frames in world reference frame at the end of the agent step.

The vector representation of the orientation of all the frames are stacked in a single contiguous N-dimensional array whose last dimension corresponds to the individual frames. See _BatchedFramesOrientation documentation for details.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_names (Tuple[str, ...]) – Name of the frames on which to operate.
type (OrientationType) – Desired vector representation of the orientation for all frames. Optional: ‘OrientationType.MATRIX’ by default.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.

frame_names: Tuple[str, ...]¶: Name of the frames on which to operate.

type: OrientationType¶: Selected vector representation of the orientation for all frames.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

initialize()[source]¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.FramePosition(env, parent, frame_name, *, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Position vector (X, Y, Z) of a given frame in world reference frame at the end of the agent step.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name (str) – Name of the frame on which to operate.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.

frame_name: str¶: Name of the frame on which to operate.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

initialize()[source]¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.MultiFramePosition(env, parent, frame_names, *, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Position vector (X, Y, Z) of a given set of frames in world reference frame at the end of the agent step.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name – Name of the frames on which to operate.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.
frame_names (Tuple[str, ...])

frame_names: Tuple[str, ...]¶: Name of the frames on which to operate.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

initialize()[source]¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.FrameXYZQuat(env, parent, frame_name, *, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Spatial vector representation (X, Y, Z, QuatX, QuatY, QuatZ, QuatW) of the transform of a given frame in world reference frame at the end of the agent step.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name (str) – Name of the frame on which to operate.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.

frame_name: str¶: Name of the frame on which to operate.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

initialize()¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.MultiFrameXYZQuat(env, parent, frame_names, *, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Spatial vector representation (X, Y, Z, QuatX, QuatY, QuatZ, QuatW) of the transform of a given set of frames in world reference frame at the end of the agent step.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name – Name of the frames on which to operate.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.
frame_names (Tuple[str, ...])

frame_names: Tuple[str, ...]¶: Name of the frames on which to operate.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

initialize()¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.MultiFrameMeanXYZQuat(env, parent, frame_names, *, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Spatial vector representation (X, Y, Z, QuatX, QuatY, QuatZ, QuatW) of the average transform of a given set of frames in world reference frame at the end of the agent step.

Broadly speaking, the average is defined as the value minimizing the mean error wrt every individual elements, considering some distance metric. In this case, the average position (X, Y, Z) and orientation as a quaternion vector (QuatX, QuatY, QuatZ, QuatW) are computed separately (double geodesic). It has the advantage to be much easier to compute, and to decouple the translation from the rotation, which is desirable when defining reward components weighting differently position or orientation errors. See quaternion_average for details about the distance metric being used to compute the average orientation.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name – Name of the frames on which to operate.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.
frame_names (Tuple[str, ...])

frame_names: Tuple[str, ...]¶: Name of the frames on which to operate.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

initialize()¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.MultiFrameCollisionDetection(env, parent, frame_names, *, security_margin=0.0)[source]¶

Bases: InterfaceQuantity[bool]

Check if some geometry objects are colliding with each other.

It takes into account some safety margins by which their volume will be inflated / deflated.

Note

Jiminy enforces all collision geometries to be either primitive shapes or convex polyhedra for efficiency. In practice, tf meshes where specified in the original URDF file, then they will be converted into their respective convex hull.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_names (Tuple[str, ...]) – Name of the bodies of the robot to consider for collision detection. All the geometry objects sharing with them the same parent joint will be taking into account.
security_margin (float) – Signed distance below which a pair of geometry objects is stated in collision. Optional: 0.0 by default.

frame_names: Tuple[str, ...]¶

Name of the bodies of the robot to consider for collision detection.

All the geometry objects sharing with them the same parent joint will be taking into account.

security_margin: float¶

Signed distance below which a pair of geometry objects is stated in collision.

This can be interpreted as inflating or deflating the geometry objects by the safety margin depending on whether it is positive or negative respectively. Therefore, the actual geometry objects do no have to be in contact to be stated in collision if the satefy margin is positive. On the contrary, the penetration depth must be large enough if the security margin is positive.

initialize()[source]¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: bool

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

class gym_jiminy.common.quantities.generic.AverageFrameXYZQuat(env, parent, frame_name, *, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Spatial vector representation (X, Y, Z, QuatX, QuatY, QuatZ, QuatW) of the average pose of a given frame over the whole agent step.

The average frame pose is obtained by integration of the average velocity over the whole agent step, backward in time from the state at the end of the step to the midpoint. See _DifferenceFrameXYZQuat documentation for details.

Note

There is a coupling between the rate of change of the orientation over the agent step and the position of the midpoint. Depending on the application, it may be desirable to decouple the translation from the rotation completely by performing computation on the Cartesian Product of the 3D Euclidean space R3 times the Special Orthogonal Group SO3. The resulting distance metric is referred to as double geodesic and does not correspond to the actual shortest path anymore.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name (str) – Name of the frame on which to operate.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

initialize()¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

frame_name: str¶: Name of the frame on which to operate.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

class gym_jiminy.common.quantities.generic.AverageFrameRollPitch(env, parent, frame_name, *, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Quaternion representation of the average Yaw-free orientation from the Roll-Pitch_yaw decomposition of a given frame over the whole agent step.

See also

See remove_yaw_from_quat and AverageFrameXYZQuat for details about the Roll-Pitch-Yaw decomposition and how the average frame pose is defined respectively.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name (str) – Name of the frame on which to operate.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

initialize()¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

frame_name: str¶: Name of the frame on which to operate.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

class gym_jiminy.common.quantities.generic.FrameSpatialAverageVelocity(env, parent, frame_name, *, reference_frame=pinocchio.pinocchio_pywrap.ReferenceFrame.LOCAL, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[ndarray]

Average spatial velocity of a given frame at the end of the agent step.

The average spatial velocity is obtained by finite difference. More precisely, it is defined here as the ratio of the geodesic distance in SE3 Lie Group between the pose of the frame at the end of previous and current step over the time difference between them. Notably, under this definition, the linear average velocity jointly depends on rate of change of the translation and rotation of the frame, which may be undesirable in some cases. Alternatively, the double geodesic distance could be used instead to completely decouple the translation from the rotation.

Note

The local frame for which the velocity is expressed is defined as the midpoint interpolation between the previous and current frame pose. This definition is arbitrary, in a sense that any other point for an interpolation ratio going from 0.0 (previous pose) to 1.0 (current pose) would be equally valid.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
frame_name (str) – Name of the frame on which to operate.
reference_frame (ReferenceFrame) – Whether the spatial velocity must be computed in local reference frame (aka ‘pin.LOCAL’) or re-aligned with world axes (aka ‘pin.LOCAL_WORLD_ALIGNED’). Optional: ‘pinocchio.ReferenceFrame.LOCAL’ by default.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity. Optional: ‘QuantityEvalMode.TRUE’ by default.

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

initialize()¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

frame_name: str¶: Name of the frame on which to operate.

reference_frame: ReferenceFrame¶: Whether the spatial velocity must be computed in local reference frame or re-aligned with world axes.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

class gym_jiminy.common.quantities.generic.MultiActuatedJointKinematic(env, parent, *, kinematic_level=pinocchio.pinocchio_pywrap.KinematicLevel.POSITION, is_motor_side=False, mode=QuantityEvalMode.TRUE)[source]¶

Bases: AbstractQuantity[ndarray]

Current position, velocity or acceleration of all the actuated joints of the robot before or after the mechanical transmissions.

In practice, all actuated joints must be 1DoF for now. In the case of revolute unbounded revolute joints, the principal angle ‘theta’ is used to encode the position, not the polar coordinates (cos(theta), sin(theta)).

Warning

Data is extracted from the true configuration vector instead of using sensor data. As a result, this quantity is appropriate for computing reward components and termination conditions but must be avoided in observers and controllers.

Warning

Revolute unbounded joints are not supported for now.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
kinematic_level (KinematicLevel) – Desired kinematic level, ie position, velocity or acceleration.
is_motor_side (bool) – Whether the compute kinematic data on motor- or joint-side, ie before or after the mechanical transmisions. Optional: False by default.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity.

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

kinematic_level: KinematicLevel¶: Kinematic level to consider, ie position, velocity or acceleration.

is_motor_side: bool¶: Whether the compute kinematic data on motor- or joint-side, ie before or after their respective mechanical transmision.

initialize()[source]¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: ndarray

class gym_jiminy.common.quantities.generic.EnergyGenerationMode(value)[source]¶

Bases: IntEnum

Specify what happens to the energy generated by motors when breaking.

conjugate()¶: Returns self, the complex conjugate of any int.

bit_length()¶

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

bit_count()¶

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

to_bytes(length, byteorder, *, signed=False)¶

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

from_bytes(byteorder, *, signed=False)¶

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Indicates whether two’s complement is used to represent the integer.

as_integer_ratio()¶

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

real¶: the real part of a complex number

imag¶: the imaginary part of a complex number

numerator¶: the numerator of a rational number in lowest terms

denominator¶: the denominator of a rational number in lowest terms

CHARGE = 0¶: The energy flows back to the battery to charge them without any kind of losses in the process if negative overall.

LOST_EACH = 1¶: The generated energy by each motor individually is lost by thermal dissipation, without flowing back to the battery nor powering other motors consuming energy if any.

LOST_GLOBAL = 2¶: The energy is lost by thermal dissipation without flowing back to the battery if negative overall.

PENALIZE = 3¶: The generated energy by each motor individually is treated as consumed.

class gym_jiminy.common.quantities.generic.AverageMechanicalPowerConsumption(env, parent, *, horizon, generator_mode=EnergyGenerationMode.CHARGE, mode=QuantityEvalMode.TRUE)[source]¶

Bases: InterfaceQuantity[float]

Average mechanical power consumption by all the motors over a sliding time window.

Parameters:

env (InterfaceJiminyEnv) – Base or wrapped jiminy environment.
parent (InterfaceQuantity | None) – Higher-level quantity from which this quantity is a requirement if any, None otherwise.
horizon (float) – Horizon over which values of the quantity will be stacked before computing the average.
generator_mode (EnergyGenerationMode) – Specify what happens to the energy generated by motors when breaking. Optional: EnergyGenerationMode.CHARGE by default.
mode (QuantityEvalMode) – Desired mode of evaluation for this quantity.

allow_update_graph: ClassVar[bool] = True¶: Whether dynamic computation graph update is allowed. This implies that the quantity can be reset at any point in time to re-compute the optimal computation path, typically after deletion or addition of some other node to its dependent sub-graph. When this happens, the quantity gets reset on the spot, even if a simulation is already running. This is not always acceptable, hence the capability to disable this feature at class-level.

property cache: SharedCache[ValueT]¶: Get shared cache if available, otherwise raises an exception.

Warning

This method is not meant to be overloaded.

get()¶

Get cached value of requested quantity if available, otherwise evaluate it and store it in cache.

This quantity is considered active as soon as this method has been called at least once since previous tracking reset. The method is_active will be return true even before calling initialize.

Warning

This method is not meant to be overloaded.

Return type:: ValueT

initialize()¶

Initialize internal buffers.

This is typically useful to refresh shared memory proxies or to re-initialize pre-allocated buffers.

Warning

Intermediary quantities ‘requirements’ are NOT initialized automatically because they can be initialized lazily in most cases, or are optional depending on the most efficient computation path at run-time. It is up to the developer implementing quantities to take care of it.

Note

This method must be called before starting a new episode.

Note

Lazy-initialization is used for efficiency, ie initialize will be called before the first time refresh has to be called, which may never be the case if cache is shared between multiple identical instances of the same quantity.

Return type:: None

is_active(any_cache_owner=False)¶

Whether this quantity is considered active, namely initialize has been called at least once since previous tracking reset.

Parameters:

any_owner – False to check only if this exact instance is active, True if any of the identical quantities (sharing the same cache) is considered sufficient. Optional: False by default.
any_cache_owner (bool)

Return type:

bool

reset(reset_tracking=False, *, ignore_other_instances=False)¶

Consider that the quantity must be re-initialized before being evaluated once again.

If shared cache is available, then it will be cleared and all identity quantities will jointly be reset.

Note

This method must be called right before performing any agent step, otherwise this quantity will not be refreshed if it was evaluated previously.

Warning

This method is not meant to be overloaded.

Parameters:

reset_tracking (bool) – Do not consider this quantity as active anymore until the get method gets called once again. Optional: False by default.
ignore_other_instances (bool) – Whether to skip reset of intermediary quantities as well as any shared cache co-owner quantity instances. Optional: False by default.

Return type:

None

requirements: Dict[str, InterfaceQuantity]¶: Intermediary quantities on which this quantity may rely on for its evaluation at some point, depending on the optimal computation path at runtime. They will be exposed to the user as usual attributes.

max_stack: int¶: Time horizon over which values of the instantaneous power consumption will be stacked for computing the average.

generator_mode: EnergyGenerationMode¶: Specify what happens to the energy generated by motors when breaking. See EnergyGenerationMode documentation for details.

mode: QuantityEvalMode¶: Specify on which state to evaluate this quantity. See QuantityEvalMode documentation for details about each mode.

Warning

Mode REFERENCE requires a reference trajectory to be selected manually prior to evaluating this quantity for the first time.

refresh()[source]¶

Evaluate this quantity based on the agent state at the end of the current agent step.

Return type:: float