Randomization Handler

class DomainRandomizationHandler(xml_handles, domain_rand_conf_path, parallel=True, N_worker_per_xml=4)[source]

Bases: object

Description

Class for handling domain randomization.

Right now, LocoMujoco support domain randomization for the Properties of the joints, geometries, and the inertials of the bodies. The domain randomization is done by modifying the Mujoco XML file of the respective environment. The domain randomization is done based on a config file that specifies what parameters to randomize and what kind of domain randomization distribution to choose. An example of such a file is given below.

Randomization Distributions

The following tags are support to specify randomization distributions:

sigma: Specifies a zero-mean Gaussian distribution with a specified standard deviation.: Either a float or a list of floats can be provided. If a list is provided, the randomization will be done with

a multivariate Gaussian distribution.
uniform_range: Specifies a uniform distribution with a specified range.: Only a list can be provided. The first element of the list specifies the lower bound and the second element

specifies the upper bound. This type does not support multivariate distributions.
uniform_range_delta: Specifies a uniform distribution centered around a specified the default parameter with a specified delta range.: Either a float or a list of floats can be provided. If a list is provided, the randomization will be done with

a multivariate uniform distribution.

Supported Components to Randomize

Here are the supported components in the XML and their parameters that can be randomized.

Note

Click on the respective links to jump to the Mujoco XML reference for the components!

Joint 

damping: The damping coefficient of the joint.: Supported Randomization Distributions: Gaussian, Uniform, UniformDelta

Allowed Tags: sigma, uniform_range, uniform_range_delta

Only univariate distributions are supported.
frictionloss: The frictionloss coefficient of the joint.: Supported Randomization Distributions: Gaussian, Uniform, UniformDelta

Allowed Tags: sigma, uniform_range, uniform_range_delta

Only univariate distributions are supported.
armature: The armature coefficient of the joint.: Supported Randomization Distributions: Gaussian, Uniform, UniformDelta

Allowed Tags: sigma, uniform_range, uniform_range_delta

Only univariate distributions are supported.
stiffness: The stiffness coefficient of the joint.: Supported Randomization Distributions: Gaussian, Uniform, UniformDelta

Allowed Tags: sigma, uniform_range, uniform_range_delta

Only univariate distributions are supported.

Geom 

mass: The mass of the geometry.: Supported Randomization Distributions: Gaussian, Uniform, UniformDelta

Allowed Tags: sigma, uniform_range, uniform_range_delta

Only univariate distributions are supported.
friction: The friction coefficient of the geometry.: Supported Randomization Distributions: Gaussian, UniformDelta

Allowed Tags: sigma`, uniform_range_delta

Specialty: Need to be provided as a 3D list as the friction parameters are 3D.

The first number is the sliding friction, acting along both axes of the tangent plane. The second number is

the torsional friction, acting around the contact normal. The third number is the rolling friction, acting

around both axes of the tangent plane.

Only multivariate distributions are supported.
density: The density of the geometry.: Supported Randomization Distributions: Gaussian, Uniform, UniformDelta

Allowed Tags: sigma, uniform_range, uniform_range_delta

Only univariate distributions are supported.

Inertial 

mass: The mass of the geometry.: Supported Randomization Distributions: Gaussian, Uniform, UniformDelta

Allowed Tags: sigma, uniform_range, uniform_range_delta

Only univariate distributions are supported.
diaginertia: Diagonal inertia matrix, expressing the body inertia relative to the inertial frame.: Supported Randomization UniformDelta

Allowed Tags: uniform_range_delta

Specialty: All diagonal elements of the inertia matrix are randomized uniformly with the same

delta range. Hence, only a single number is required to specify the delta range.

Only univariate distributions are supported.
fullinertia: Full inertia matrix M, expressing the body inertia relative to the inertial frame.: Supported Randomization UniformDelta

Allowed Tags: uniform_range_delta

Specialty: A SVD is conducted and all singular values are randomized uniformly with the same

delta range. Afterwards, the full inertial matrix is calculated again. Hence, only a single number

is required to specify the delta range.

Only univariate distributions are supported.

Parallelization

Compilation of a model given its XML file can be time-consuming. To speed up the domain randomization process, the domain randomization can be done in parallel. Then, models with randomized parameters will be compiled while the training of another model is running. To enable parallel compilation, set the parameter parallel to True. Instead of compiling just one model in parallel, we allow to compile multiple models in parallel for to speed up even further. To do so, set the N_worker_per_xml parameter to the number of workers you want to use for each XML file.

Note

Parallelization is done using multiprocessing. If this is interfering with your code, we suggest to disable parallelization.

Example

Here is an example of how to use the domain randomization configuration file. Note that it is also possible to set a default randomization for all components and then override the default for specific components (e.g., the joint). If you would like to exclude certain components from randomization, you can do so by setting the exclude parameter.

# here a default randomization can be set for all joints.
Default:
  # these joints will not be included during domain randomization.
  exclude: ["pelvis_tx", "pelvis_ty", "pelvis_tz", "pelvis_tilt", "pelvis_list", "pelvis_rotation"]
  Joints:
    damping:
      sigma: 0.0
    stiffness:
      sigma: 0.0
    frictionloss:
      sigma: 0.0

# here joint specific configurations can be made
Joints:
  # set either a sigma for sampling from a normal distribution, or set a range or delta-range for uniform sampling.
  back_bkz:
    damping:
      uniform_range: [4.0, 6.0]
    stiffness:
      sigma: 0.0
    armature:
      sigma: 0.0
    frictionloss:
      sigma: 0.0
  back_bkx:
    damping:
      uniform_range: [4.0, 6.0]
    stiffness:
      sigma: 0.0
    armature:
      sigma: 0.0
    frictionloss:
      sigma: 0.0

Inertial:
  leg_right_6_link:
    mass:
      uniform_range_delta: 0.5
    diaginertia:
      uniform_range_delta: 0.001
  leg_right_5_link:
    fullinertia:
        uniform_range_delta: 0.001

Tutorial

If you would like to see a complete example, please refer to check out the Tutorial on Domain Randomization.

Methods

get_randomized_model(model_id)[source]: Returns a randomized model based on the model-id.

apply_domain_randomization(xml_handle, domain_randomization_config)[source]

Applies domain/dynamics randomization to the xml_handle based on the provided configuration file.

Args:: xml_handle: Handle to Mujoco XML. domain_randomization_config (str): Path to the configuration file for domain randomization.
Returns:: Modified Mujoco XML Handle.

build_MjModel_from_xml_handle(xml_handle, path_domain_rand_conf)[source]

Function that takes in an xml_handle and a path to the domain randomization file and returns a randomizaed model.

Args:: xml_handle: Mujoco xml handle. path_domain_rand_conf (str): Path to the domain randomization file.
Returns:: Randomized model.

build_MjModel_from_xml_handle_job(xml_handle, path_domain_rand_conf, sq, rq)[source]

Worker function for parallel domain randomization. It takes in an xml_handle and a path to the domain randomization file and puts a randomized model in the respective queue.

Args:: xml_handle: Mujoco xml handle. path_domain_rand_conf (str): Path to the domain randomization file. sq (Queue): Send queue used to send the model to the main tread. rq (Queue): Receive queue used to receive the trigger to sample another randomized model.

check_lows_singular_values(lows, delta, ih, sing_val)[source]

check_uniform_range_conf(h, params, check_low_greater_zero=True)[source]

check_uniform_range_delta_conf(h, params)[source]

set_geom_conf(conf, gh)[source]

Set the properties of the geom handle (gh) to the randomization properties defined in conf.

Args:: conf (dict): Dictionary defining the randomization properties of the geom. gh: Mujoco geom handle to be modified.
Returns:: Mujoco geom handle.

set_inertial_conf(conf, ih)[source]

Set the properties of the inertial handle (ih) to the randomization properties defined in conf.

Args:: conf (dict): Dictionary defining the randomization properties of the inertial. ih: Mujoco inertial handle to be modified.
Returns:: Mujoco inertial handle.

set_joint_conf(conf, jh)[source]

Set the properties of the joint handle (jh) to the randomization properties defined in conf.

Args:: conf (dict): Dictionary defining the randomization properties of the joint. jh: Mujoco joint handle to be modified.
Returns:: Mujoco joint handle.