DI-engine Config规范¶

开发者提交的 config 需要遵守以下规范，以保证 config 的易用性，可读性，与可扩展性。

DI-engine 的 config 包括 main_config 和 create_config 两部分。

示例链接¶

普通算法 (DQN) 的示例：

https://github.com/opendilab/DI-engine/blob/main/dizoo/atari/config/serial/pong/pong_dqn_config.py

包含模型或数据的算法 (SQIL) 的示例:

https://github.com/opendilab/DI-engine/blob/main/dizoo/atari/config/serial/pong/pong_sqil_config.py

规范内容¶

语法规范¶

config 需要满足 flake8 python 语法检查, 以及进行 yapf 格式化。

命名规范¶

config.py 文件名，main_config 和 create_config 相关变量名
- 统一以<环境名>_<算法名>_config.py 命名。文件的名称以及文件中相关变量名不用添加 default 字段。例如应该将文件名 hopper_onppo_default_config.py 改为 hopper_onppo_config.py。
- 类似 ICM 算法这种，总的算法是论文提出的模块再结合某个基线算法，其对应的 config 名称，按照<环境名>_<模块名>_<基线算法名>_config.py 命名，例如 cartpole_icm_offppo_config.py
- 算法如果有 on-policy 和 off-policy 的不同版本，统一在 config.py 文件名和文件中相关变量名，使用 onppo/offppo 区分 on-policy 和 off-policy 版的算法。例如对于 PPO 算法的 config, 应该将 hopper_ppo_config.py 改成 hopper_onppo_config.py。
exp_name 字段
- main_config 中必须添加 exp_name 字段
- 命名规范为环境+算法+seed，例如qbert_sqil_seed0
文件路径名
- 参见 sqil 示例，并加上相应的注释。如果需要加载多个模型 model，则模型路径 (model_path) 变量按照以下方式命名：prefix1_model_path，prefix2_model_path，…, 数据路径 (data_path) 变量命名类似。

config = dict(
    ...,
    # Users should add their own model path here. Model path should lead to a model.
    # Absolute path is recommended.
    # In DI-engine, it is ``exp_name/ckpt/ckpt_best.pth.tar``.
    model_path='model_path_placeholder',
    # Users should add their own data path here. Data path should lead to a file to store data or load the stored data.
    # Absolute path is recommended.
    # In DI-engine, it is usually located in ``exp_name`` directory
    data_path='data_path_placeholder',
)

主要规范¶

对于 create_config 中的 env_manager 字段，除了简单环境 cartpole, pendulum, bitflip 环境使用 base, 其他环境一般使用 subprocess：
```
env_manager=dict(type='subprocess'),
```
保证 evaluator_env_num：n_evaluator_episode = 1:1 （ smac 环境例外）
在 main_config 的 env 字段中一般不应该包含 manager 字段 (当不包含 manager 字段时，shared_memory 默认为 True)：
- smac 环境例外，由于状态维度问题，smac 需要设置 shared_memory=Fasle。
- smac 环境外的其他环境，如果由于状态维度问题运行报错，可以包含 manager 字段并设置 shared memory=False。

如果想开启/关闭 shared memory, 请在env.manager字段中进行控制

config = dict(
    ...,
    env=dict(
        manager=dict(
            shared_memory=True,
        ),
    ),
)

create config
- env字段中，只需要包含 type 和 import_names两个字段, 例如：
```
env=dict(
    type='atari',
    import_names=['dizoo.atari.envs.atari_env'],
),
```
- 一般不需要replay_buffer字段。如果想使用存储为deque的buffer，请在create_config中指定replay_buffer的type为deque：
```
replay_buffer=dict(type='deque'),
```
serial_pipeline
- 使用二级引用避免 circular import：即使用from ding.entry import serial_pipeline而不是from ding.entry.serial_entry import serial_pipeline
- 使用[main_config, create_config] 以统一风格，如果算法需要调用其他 config，可以不遵循此约定。例如 imitation learning 算法需要引入专家 config，具体参见 sqil 的示例。
- 每一个 config 必须有一个启动命令，且写成类似下面这种格式
```
if ___name___ == "___main___":
    # or you can enter `ding -m serial -c cartpole_dqn_config.py -s 0`
    from ding.entry import serial_pipeline
    serial_pipeline([main_config, create_config], seed=0)
```
  - 注意from ding.entry import serial_pipeline这行不要写在文件开头，要写在if ___name___ == "___main___":下面。
- 如果算法使用了不同的 serial_pipeline_X，需要在https://github.com/opendilab/DI-engine/blob/5d2beed4a8a07fb70599d910c6d53cf5157b133b/ding/entry/cli.py#L189中添加相应的启动命令对应 serial_X。
seed 在入口函数中设置，config 中不要包含 seed。
如果算法中超参数有确定的一个合理范围，请在算法 config 的对应超参数上写上注释，例如 sqil 中的 alpha 值：
```
alpha=0.1,  # alpha: 0.08-0.12
```
确保 config 中所有参数都是有效的，需要删除没有用到的 key。
一般在 config 中不包含 TODO 项，如果确实有必要写进 config，需要写清楚内容，例如：TODO(name): xxx.