Transform¶
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.transform.StackedQuantity(env: InterfaceJiminyEnv, parent: InterfaceQuantity | None, quantity: Tuple[Type[InterfaceQuantity[ValueT]], Dict[str, Any]], *, max_stack: int, is_wrapping: bool, as_array: Literal[False])[source]¶
- class gym_jiminy.common.quantities.transform.StackedQuantity(env: InterfaceJiminyEnv, parent: InterfaceQuantity | None, quantity: Tuple[Type[InterfaceQuantity[ndarray | float]], Dict[str, Any]], *, max_stack: int, is_wrapping: bool, as_array: Literal[True])
Bases:
InterfaceQuantity[OtherValueT],Generic[ValueT,OtherValueT]Keep track of a given quantity over time by automatically stacking its value once per environment step since last reset.
Note
A new entry is added to the stack right before evaluating the reward and termination conditions. Internal simulation steps, observer and controller updates are ignored.
- 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.
quantity (InterfaceQuantity[ValueT]) – Tuple gathering the class of the quantity whose values must be stacked, plus all its constructor keyword- arguments except environment ‘env’ and ‘parent’.
max_stack (int) – Maximum number of values that keep in memory before starting to discard the oldest one (FIFO). Optional: The maxium sequence length by default, ie sys.maxsize (2^63 - 1).
is_wrapping (bool) – Whether to wrap the stack around (i.e. starting filling data back from the start when full) when full instead of shifting data to the left. Note that wrapping around is much faster for large stack but does not preserve temporal ordering. Optional: False by default.
as_array (bool) – Whether to return data as a list or a contiguous N-dimensional array whose last dimension gathers the value of individual timesteps.
- quantity: InterfaceQuantity[ValueT]¶
Base quantity whose value must be stacked over time since last reset.
- max_stack: int¶
Maximum number of values that keep in memory before starting to discard the oldest one (FIFO). sys.maxsize if unlimited.
- is_wrapping: bool¶
Whether to wrap the stack around (i.e. starting filling data back from the start when full) when full instead of shifting data to the left.
- as_array: bool¶
Whether to return data as a tuple or a contiguous N-dimensional array whose last dimension gathers the value of individual timesteps.
- 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
- class gym_jiminy.common.quantities.transform.MaskedQuantity(env, parent, quantity, keys, *, axis=0)[source]¶
Bases:
InterfaceQuantity[ndarray]Extract a pre-defined set of elements from a given quantity whose value is a N-dimensional array along an axis.
Elements will be extract by copy unless the indices of the elements to extract to be written equivalently by a slice (ie they are evenly spaced), and the array can be flattened while preserving memory contiguity if ‘axis’ is None, which means that the result will be different between C- and F- contiguous arrays.
- 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.
quantity (InterfaceQuantity[ndarray]) – Tuple gathering the class of the quantity whose values must be extracted, plus any keyword-arguments of its constructor except ‘env’ and ‘parent’.
keys (Sequence[int | ellipsis] | Sequence[bool]) – Sequence of indices or boolean mask that will be used to extract elements from the quantity along one axis. Ellipsis can be specified to automatically extract any indices in between surrounding indices or at both ends. Ellipsis on the right end is only supported for indices with constant stride.
axis (int | None) – Axis over which to extract elements. None to consider flattened array. Optional: First axis by default.
- quantity: InterfaceQuantity[ndarray]¶
Base quantity whose elements must be extracted.
- class gym_jiminy.common.quantities.transform.ConcatenatedQuantity(env, parent, quantities, *, axis=0)[source]¶
Bases:
InterfaceQuantity[ndarray]Concatenate a set of quantities whose value are N-dimensional arrays along a given axis.
All the quantities must have the same shape, except for the dimension corresponding to concatenation axis.
Note
For efficiency and convenience, built-in scalars and 0-D arrays are treated as 1D arrays. For instance, multiple floats can be concatenated as a vector.
- 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.
quantities (Tuple[InterfaceQuantity[ndarray], ...]) – Sequence of tuples, each of which gathering the class of the quantity whose values must be extracted, plus any keyword-arguments of its constructor except ‘env’ and ‘parent’.
axis (int) – Axis over which to concatenate values. Optional: First axis by default.
- quantities: Tuple[InterfaceQuantity[ndarray], ...]¶
Base quantities whose values must be concatenated.
- 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
- class gym_jiminy.common.quantities.transform.UnaryOpQuantity(env, parent, quantity, op)[source]¶
Bases:
InterfaceQuantity[ValueT],Generic[ValueT,OtherValueT]Apply a given unary operator to a quantity.
This quantity is useful to translate quantities from world frame to local odometry frame. It may also be used to convert multi-variate quantities as scalar, typically by computing the L^p-norm.
- 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.
quantity (InterfaceQuantity[OtherValueT]) – Tuple gathering the class of the quantity whose value must be passed as argument of the unary operator, plus any keyword-arguments of its constructor except ‘env’ and ‘parent’.
op (Callable[[OtherValueT], ValueT]) – Any callable taking any value of the quantity as input argument. For example partial(np.linalg.norm, ord=2) to compute the difference.
- quantity: InterfaceQuantity[OtherValueT]¶
Quantity that will be forwarded to the unary operator.
- class gym_jiminy.common.quantities.transform.BinaryOpQuantity(env, parent, quantity_left, quantity_right, op)[source]¶
Bases:
InterfaceQuantity[ValueT],Generic[ValueT,OtherValueT,YetAnotherValueT]Apply a given binary operator between two quantities.
This quantity is mainly useful for computing the error between the value of a given quantity evaluated at the current simulation state and the state of at the current simulation time for the reference trajectory being selected.
- 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.
quantity_left (InterfaceQuantity[OtherValueT]) – Tuple gathering the class of the quantity that must be passed to left-hand side of the binary operator, plus all its constructor keyword- arguments except environment ‘env’ and parent ‘parent.
quantity_right (InterfaceQuantity[YetAnotherValueT]) – Quantity that must be passed to right-hand side of the binary operator as a tuple (class, keyword-arguments). See quantity_left argument for details.
op (Callable[[OtherValueT, YetAnotherValueT], ValueT]) – Any callable taking the right- and left-hand side quantities as input argument. For example operator.sub to compute the difference.
- quantity_left: InterfaceQuantity[OtherValueT]¶
Left-hand side quantity that will be forwarded to the binary operator.
- quantity_right: InterfaceQuantity[YetAnotherValueT]¶
Right-hand side quantity that will be forwarded to the binary operator.
- class gym_jiminy.common.quantities.transform.MultiAryOpQuantity(env, parent, quantities, op)[source]¶
Bases:
InterfaceQuantity[ValueT]Apply a given n-ary operator to the values of a given set of quantities.
- 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.
quantities (Tuple[InterfaceQuantity[Any], ...]) – Ordered sequence of n pairs, each gathering the class of a quantity whose value must be passed as argument of the n-ary operator, plus any keyword-arguments of its constructor except ‘env’ and ‘parent’.
op (Callable[[Sequence[Any]], ValueT]) – Any callable taking the packed sequence of values for all the quantities as input argument, in the exact order they were originally specified.
- op: Callable[[Sequence[Any]], ValueT]¶
Callable taking the packed sequence of values for all the specified quantities as input argument.
- quantities: Tuple[InterfaceQuantity[Any], ...]¶
Sequence of quantities that will be forwarded to the n-ary operator in this exact order.
- class gym_jiminy.common.quantities.transform.DeltaQuantity(env, parent, quantity, horizon, *, op=<built-in function sub>, bounds_only=True)[source]¶
Bases:
InterfaceQuantity[ndarray|number|float|int|bool|complex]Variation of a given quantity over the whole span of a horizon.
If bounds_only=False, then the differences of the value of the quantity between successive timesteps is accumulated over a variable-length history bounded by ‘max_stack’, which is basically a sliding window. The total variation over this horizon is defined as the sum of all the successive differences stored in the history.
If bounds_only=True, then the value of the quantity is accumulated over a variable-length history bounded by ‘max_stack’. The total variation is simply computed as the difference between most recent and oldest values stored in the history.
- 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.
quantity (InterfaceQuantity[ndarray | Sequence[ndarray | number | float | int | bool | complex]]) – Tuple gathering the class of the quantity from which to compute the variation, plus any keyword-arguments of its constructor except ‘env’ and ‘parent’.
horizon (float | None) – Horizon over which values of the quantity will be stacked before computing the drift. None to consider only two successive timesteps.
op (Callable[[ndarray | number | float | int | bool | complex, ndarray | number | float | int | bool | complex], ndarray | number | float | int | bool | complex]) – Any callable taking as input argument the current and some previous value of the quantity in that exact order, and returning the signed difference between them. Typically, the substraction operation is appropriate for position in Euclidean space, but not for orientation as it is important to count turns. Optional: sub by default.
bounds_only (bool) – Whether to compute the total variation as the difference between the most recent and oldest value stored in the history, or the sum of differences between successive timesteps. Optional: True by default.
- op: Callable[[ndarray | number | float | int | bool | complex, ndarray | number | float | int | bool | complex], ndarray | number | float | int | bool | complex]¶
Any callable taking as input argument the current and some previous value of the quantity in that exact order, and returning the signed difference between them.
- bounds_only: bool¶
Whether to compute the total variation as the difference between the most recent and oldest value stored in the history, or the sum of differences between successive timesteps.