Configuring

As highlighted in the Running section, the project can be configured either in the script itself or via hydra. We suggest to read the hydra documentation to get familiar with all its functionalities.

Each component in the project has a corresponding YAML configuration in the BenchMARL conf tree. Components’ configurations are loaded from these files into python dataclasses that act as schemas for validation of parameter names and types. That way we keep the best of both words: separation of all configuration from code and strong typing for validation! You can also directly load and validate configuration yaml files without using hydra from a script by calling ComponentConfig.get_from_yaml().

Experiment

Experiment configurations are in benchmarl/conf/config.yaml. Running custom experiments is extremely simplified by the Hydra configurations. The default configuration for the library is contained in the benchmarl/conf folder.

When running an experiment you can override its hyperparameters like so

python benchmarl/run.py task=vmas/balance algorithm=mappo experiment.lr=0.03 experiment.evaluation=true experiment.train_device="cpu"

Experiment hyperparameters are loaded from benchmarl/conf/experiment into a dataclass ExperimentConfig defining their domain. This makes it so that all and only the parameters expected are loaded with the right types. You can also directly load them from a script by calling benchmarl.experiment.ExperimentConfig.get_from_yaml().

Here is an example of overriding experiment hyperparameters from hydra

Example

or from a script

Example

Algorithm

You can override an algorithm configuration when launching BenchMARL.

python benchmarl/run.py task=vmas/balance algorithm=masac algorithm.num_qvalue_nets=3 algorithm.target_entropy=auto algorithm.share_param_critic=true

Available algorithms and their default configs can be found at benchmarl/conf/algorithm. They are loaded into a dataclass AlgorithmConfig, present for each algorithm, defining their domain. This makes it so that all and only the parameters expected are loaded with the right types. You can also directly load them from a script by calling YourAlgorithmConfig.get_from_yaml().

Here is an example of overriding algorithm hyperparameters from hydra

Example

or from a script

Example

Task

You can override a task configuration when launching BenchMARL. However this is not recommended for benchmarking as tasks should have fixed version and parameters for reproducibility.

python benchmarl/run.py task=vmas/balance algorithm=mappo task.n_agents=4

Available tasks and their default configs can be found at benchmarl/conf/task. They are loaded into a dataclass TaskConfig, defining their domain. Tasks are enumerations under the environment name. For example, benchmarl.environments.VmasTask.NAVIGATION represents the navigation task in the VMAS simulator. This allows autocompletion and seeing all available tasks at once. You can also directly load them from a script by calling YourEnvTask.TASK_NAME.get_from_yaml().

Here is an example of overriding task hyperparameters from hydra

Example

or from a script

Example

Model

You can override the model configuration when launching BenchMARL. By default an Mlp model will be loaded with the default config. You can change it like so:

python benchmarl/run.py task=vmas/balance algorithm=mappo model=layers/mlp model.layer_class="torch.nn.Linear" "model.num_cells=[32,32]" model.activation_class="torch.nn.ReLU"

Available models and their configs can be found at benchmarl/conf/model/layers. They are loaded into a dataclass ModelConfig, defining their domain. You can also directly load them from a script by calling YourModelConfig.get_from_yaml().

Here is an example of overriding model hyperparameters from hydra

Example

or from a script

Example

Sequence model

You can compose layers into a sequence model. Available layer names are in the benchmarl/conf/model/layers folder.

python benchmarl/run.py task=vmas/balance algorithm=mappo model=sequence "model.intermediate_sizes=[256]" "model/layers@model.layers.l1=mlp" "model/layers@model.layers.l2=mlp" "+model/layers@model.layers.l3=mlp" "model.layers.l3.num_cells=[3]"

Add a layer with "+model/layers@model.layers.l3=mlp".

Remove a layer with "~model.layers.l2".

Configure a layer with "model.layers.l1.num_cells=[3]".

Here is an example of creating a sequence model from hydra

Example

or from a script

Example