Helpers

Miscellaneous utilities that have no place anywhere else but are very useful nonetheless.

class gym_jiminy.common.utils.misc.RandomDistribution(*args, **kwargs)[source]

Bases: Protocol

Protocol that must be satisfied for passing a generic callable as custom statistical distribution to sample method.

gym_jiminy.common.utils.misc.is_nan(value)[source]

Check if any value of a numpy array is nan.

Warning

This method does not implement any short-circuit mechanism as it is optimized for arrays that are unlikely to contain nan values.

Parameters:

value (ndarray) – N-dimensional array.

Return type:

bool

gym_jiminy.common.utils.misc.get_fieldnames(structure, namespace='')[source]

Generate generic fieldnames for a given nested data structure, so that it can be used in conjunction with register_variables, to register any value from gym space to the telemetry conveniently.

Parameters:

  • structure (Space[Mapping[str, StructNested[ValueT]] | Iterable[StructNested[ValueT]] | ndarray] | Mapping[str, StructNested[ValueT]] | Iterable[StructNested[ValueT]] | ndarray) – Nested data structure on which to operate.

  • namespace (str) – Namespace used to prepend fields, using ‘.’ delimiter. Empty string to disable. Optional: Disabled by default.

Return type:

List[Sequence[FieldNestedSequence | str] | str]

gym_jiminy.common.utils.misc.register_variables(controller, fieldnames, data)[source]

Register data from Gym.Space to the telemetry of a controller.

Warning

Variables are registered by reference. This is necessary because, under the hood, Jiminy telemetry stores pointers to the underlying memory for efficiency. Consequently, the user is responsible to manage the lifetime of the data to avoid it being garbage collected, and to make sure the variables are updated by reassigning its value instead of re-allocating memory, using either np.copyto, [:] operator, or jiminy.array_copyto (from slowest to fastest).

Warning

The telemetry only supports np.float64 or np.int64 dtypes.

Parameters:

  • controller (AbstractController) – Robot’s controller of the simulator used to register variables to the telemetry.

  • fieldnames (ValuesView[Mapping[str, StructNested[ValueT]] | Iterable[StructNested[ValueT]] | str] | Mapping[str, StructNested[ValueT]] | Iterable[StructNested[ValueT]] | str) – Nested variable names, as returned by get_fieldnames method. It can be a nested list or/and dict. The leaves are str corresponding to the name of each scalar data.

  • data (Mapping[str, StructNested[ValueT]] | Iterable[StructNested[ValueT]] | ndarray) – Data from gym.spaces.Space to register.

Return type:

None

gym_jiminy.common.utils.misc.sample(low=-1.0, high=1.0, dist='uniform', scale=1.0, enable_log_scale=False, shape=None, rg=None)[source]

Randomly sample values from a given distribution.

Parameters:

  • low (float | ndarray) – Lower value for bounded distribution, negative-side standard deviation otherwise. Optional: -1.0 by default.

  • high (float | ndarray) – Upper value for bounded distribution, positive-side standard deviation otherwise. Optional: 1.0 by default.

  • dist (str | RandomDistribution) – The statistical from which to draw samples, either provided as a pre-defined string or a callable. For strings, then it must be a member function of np.random.Generator (only ‘uniform’ and ‘normal’ are supported for now). For callables, it must corresponds to a standardized distribution and satisfying gym_jiminy.common.utils.RandomDistribution protocol. This is especially useful for specifying custom parameters of complex distributions such as Beta. Using functools.partial is recommended, eg partial(np.random.Generator.Beta, a=1, b=8). Optional: ‘uniform’ by default.

  • scale (float | ndarray) – Shrink the standard deviation of the distribution around the mean by this factor. Optional: No scaling by default?

  • enable_log_scale (bool) – The sampled values are power of 10.

  • shape (Sequence[int] | None) – Enforce of the sampling shape. Only available if ‘low’, ‘high’ and ‘scale’ are floats. None to disable. Optional: Disabled by default.

  • rg (Generator | None) – Custom random number generator from which to draw samples. Optional: Default to np.random.

Return type:

ndarray