Hyperparameter optimization

[vwxyzjn]

Description

This PR adds a first pass of hyperparameter optimization.

The API design roughly looks like

import optuna
from cleanrl_utils.tuner import Tuner
    
tuner = Tuner(
    script="cleanrl/ppo.py",
    metric="charts/episodic_return",
    metric_last_n_average_window=50,
    direction="maximize",
    target_scores={
        "CartPole-v1": [0, 500],
        "Acrobot-v1": [-500, 0],
    },
    params_fn=lambda trial: {
        "learning-rate": trial.suggest_loguniform("learning-rate", 0.0003, 0.003),
        "num-minibatches": trial.suggest_categorical("num-minibatches", [1, 2, 4]),
        "update-epochs": trial.suggest_categorical("update-epochs", [1, 2, 4]),
        "num-steps": trial.suggest_categorical("num-steps", [5, 16, 32, 64, 128]),
        "vf-coef": trial.suggest_uniform("vf-coef", 0, 5),
        "max-grad-norm": trial.suggest_uniform("max-grad-norm", 0, 5),
        "total-timesteps": 10000,
        "num-envs": 16,
    },
    pruner=optuna.pruners.MedianPruner(n_startup_trials=5),
    wandb_kwargs={"project": "cleanrl"},
)
tuner.tune(
    num_trials=10,
    num_seeds=3,
)

Preliminary docs are available at https://cleanrl-jlu83xh5n-vwxyzjn.vercel.app/advanced/hyperparameter-tuning/

Types of changes

• Bug fix
• New feature
• New algorithm
• Documentation

Checklist:

• I've read the CONTRIBUTION guide (required).
• I have ensured pre-commit run --all-files passes (required).
• I have updated the documentation and previewed the changes via mkdocs serve.
• I have updated the tests accordingly (if applicable).

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
cleanrl	✅ Ready (Inspect)	Visit Preview	Aug 26, 2022 at 1:54AM (UTC)

[vwxyzjn]

@dosssma, @yooceii, @Dipamc77 would you mind giving this a try? See https://cleanrl-jlu83xh5n-vwxyzjn.vercel.app/advanced/hyperparameter-tuning/ for the current tutorial. Would love to hear your feedback.

[dosssman]

@vwxyzjn Thanks for the great addition.

Tried to follow up the instructions to get it to work, but there were a few snags along the way:

1. The poetry rule to install optuna do not seem present. Also, in the docs, shouldn't it be something like poetry install -E optuna instead of the current poetry install optuna ? For now, I just installed it using pip install optuna to test the scripts at least.

2. Running pip install optuna did not seem to be enough. I also had to run pip install rich to tuner_example.py to at least start.

3. A bit tangential to this hyparam search feature, but in the Cleanrl starting documentation, it is started that the library requires either python 3.8 or 3.9. (See corresponding single comment)

I have yet to test other tuner scripts than tyner_example.py, but it looks good so far.

[vwxyzjn]

Thanks will definitely add the dependencies in poetry - I just try to do this in the last step due to the potential poetry conflicts with other branches. Glad to hear tuner_example.py is working fine.

[dipamc]

Haven't been able to run the code yet, but I read the code, here are some thoughts.

• The minimum and maximum reward being required beforehand is a bit of a limitation. Though it's not clear to me that normalization is needed when running on a single environment. If it isn’t maybe it can be left optional or at least stated in the docs so that anyone trying a new env doesn’t need to provide them.

• Should link to the documentation of what other samplers are available under trial that is passed to sampler_fn

[yooceii]

Faced the same situation that dossman@ have when installing optuna. but other than that. Example works.
Wonder if it's better to do the hyperparameter sweep that works for multiple env or individual env as different env might have different optimal parameter settings.

[vwxyzjn]

Thanks, @Dipamc77 @dosssman @yooceii @kinalmehta for the review

The minimum and maximum reward being required beforehand is a bit of a limitation.

Addressed. Users can put target_scores = {"CartPole-v1": None}

Should link to the documentation of what other samplers are available under trial that is passed to sampler_fn

Done and added another API to pass user specified sampler.

Wonder if it's better to do the hyperparameter sweep that works for multiple env or individual env as different env might have different optimal parameter settings.

If the users want to do that, they could probably create multiple instances of the tuner like

from cleanrl_utils.tuner import Tuner
tuner = Tuner(
    script="cleanrl/ppo.py",
    metric="charts/episodic_return",
    metric_last_n_average_window=50,
    direction="maximize",
    target_scores={
        "CartPole-v1": None,
    },
    params_fn=lambda trial: {
        "learning-rate": trial.suggest_loguniform("learning-rate", 0.0003, 0.003),
        "num-minibatches": trial.suggest_categorical("num-minibatches", [1, 2, 4]),
        "update-epochs": trial.suggest_categorical("update-epochs", [1, 2, 4]),
        "num-steps": trial.suggest_categorical("num-steps", [5, 16, 32, 64, 128]),
        "vf-coef": trial.suggest_uniform("vf-coef", 0, 5),
        "max-grad-norm": trial.suggest_uniform("max-grad-norm", 0, 5),
        "total-timesteps": 10000,
        "num-envs": 4,
    },
)
tuner.tune(
    num_trials=100,
    num_seeds=3,
)
tuner = Tuner(
    script="cleanrl/ppo.py",
    metric="charts/episodic_return",
    metric_last_n_average_window=50,
    direction="maximize",
    target_scores={
        "Acrobat-v1": None,
    },
    params_fn=lambda trial: {
        "learning-rate": trial.suggest_loguniform("learning-rate", 0.0003, 0.003),
        "num-minibatches": trial.suggest_categorical("num-minibatches", [1, 2, 4]),
        "update-epochs": trial.suggest_categorical("update-epochs", [1, 2, 4]),
        "num-steps": trial.suggest_categorical("num-steps", [5, 16, 32, 64, 128]),
        "vf-coef": trial.suggest_uniform("vf-coef", 0, 5),
        "max-grad-norm": trial.suggest_uniform("max-grad-norm", 0, 5),
        "total-timesteps": 10000,
        "num-envs": 4,
    },
)
tuner.tune(
    num_trials=100,
    num_seeds=3,
)

[dosssman]

Looking good to me.
Tested the tuner_example and it is working out of the box.
I had to abort it quite early though.
Great work.

Comments addressed

[vwxyzjn]

Refactored the documentation a bit to help users better get started. Merging now.

[braham-snyder]

Any chance anyone wants to explain the biggest advantage of Optuna over wandb's hyperparameter optimization? The latter's practically already built-in.

(Btw thanks for a great library!)

[vwxyzjn]

Hi @braham-snyder, Wanda’s hyperparameter optimization is great. I have used it before and it’s easy to use.

Feature-wise optuna does support more functionalities. E.g., pruning less promising experiments or multi objective optimization.

[braham-snyder]

Thanks!