diff --git a/README.md b/README.md index 3b44a27a..9cc9e3bf 100644 --- a/README.md +++ b/README.md @@ -220,12 +220,20 @@ We want to provide a framework for RL algorithms that is at the same time simple Moreover, in many RL repositories, the RL algorithm is tightly coupled with the environment, making it harder to extend them beyond the gym interface. We want to provide a framework that allows to easily decouple the RL algorithm from the environment, so that it can be used with any environment. -## How to use +## How to use it -Two options exist for using SheepRL. One can either clone the repo and install the local version, or one can pip install the framework using the GitHub clone URL. Instructions for both methods are shown below. +### Installation + +Three options exist for installing SheepRL + +1. Install the latest version directly from the [PyPi index](https://pypi.org/project/sheeprl/) +2. Clone the repo and install the local version +3. pip-install the framework using the GitHub clone URL + +Instructions for the three methods are shown below. + +#### Install SheepRL from PyPi -
- Cloning and installing the lastest version from PyPi You can install the latest version of SheepRL with @@ -233,14 +241,13 @@ You can install the latest version of SheepRL with pip install sheeprl ``` +> [!NOTE] +> > To install optional dependencies one can run for example `pip install sheeprl[atari,box2d,dev,mujoco,test]` For a detailed information about all the optional dependencies you can install please have a look at the [What](#what) section -
- -
- Cloning and installing a local version +#### Cloning and installing a local version First, clone the repo with: @@ -255,12 +262,11 @@ From inside the newly created folder run pip install . ``` -> To install all the optional dependencies one can run `pip install .[atari,mujoco,dev,test]` - -
+> [!NOTE] +> +> To install optional dependencies one can run for example `pip install .[atari,box2d,dev,mujoco,test]` -
- Installing the framework from the GitHub repo +#### Installing the framework from the GitHub repo If you haven't already done so, create an environment with your choice of venv or conda. @@ -269,33 +275,41 @@ If you haven't already done so, create an environment with your choice of venv o ```sh # create a virtual environment python3 -m venv .venv + # activate the environment source .venv/bin/activate + # if you do not wish to install extras such as mujuco, atari do pip install "sheeprl @ git+https://github.com/Eclectic-Sheep/sheeprl.git" + # or, to install with atari and mujuco environment support, do pip install "sheeprl[atari,mujoco,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" + # or, to install with box2d environment support, do pip install swig pip install "sheeprl[box2d] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" + # or, to install with minedojo environment support, do pip install "sheeprl[minedojo,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" + # or, to install with minerl environment support, do pip install "sheeprl[minerl,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" + # or, to install with diambra environment support, do pip install "sheeprl[diambra,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" + # or, to install with super mario bros environment support, do pip install "sheeprl[supermario,dev] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" + # or, to install all extras, do pip install swig pip install "sheeprl[box2d,atari,mujoco,minerl,supermario,dev,test] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" ``` -
- -
- Installing on an M-series Mac +#### Additional: installing on an M-series Mac +> [!CAUTION] +> > If you are on an M-series Mac and encounter an error attributed box2dpy during installation, you need to install SWIG using the instructions shown below. @@ -304,37 +318,54 @@ It is recommended to use [homebrew](https://brew.sh/) to install [SWIG](https:// ```sh # if needed install homebrew /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + # then, do brew install swig + # then attempt to pip install with the preferred method, such as pip install "sheeprl[atari,box2d,mujoco,dev,test] @ git+https://github.com/Eclectic-Sheep/sheeprl.git" ``` -
- -
- MineRL and MineDojo +#### Additional: MineRL and MineDojo +> [!NOTE] +> > If you want to install the *minedojo* or *minerl* environment support, Java JDK 8 is required: you can install it by following the instructions at this [link](https://docs.minedojo.org/sections/getting_started/install.html#on-ubuntu-20-04). + +> [!CAUTION] > -> **MineRL** and **MineDojo** environments have **conflicting requirements**, so **DO NOT install them together** with the `pip install -e .[minerl,minedojo]` command, but instead **install them individually** with either the command `pip install -e .[minerl]` or `pip install -e .[minedojo]` before running an experiment with the MineRL or MineDojo environment, respectively. +> **MineRL** and **MineDojo** environments have **conflicting requirements**, so **DO NOT install them together** with the `pip install sheeprl[minerl,minedojo]` command, but instead **install them individually** with either the command `pip install sheeprl[minerl]` or `pip install sheeprl[minedojo]` before running an experiment with the MineRL or MineDojo environment, respectively. -
+### Run an experiment with SheepRL Now you can use one of the already available algorithms, or create your own. - For example, to train a PPO agent on the CartPole environment with only vector-like observations, just run ```bash python sheeprl.py exp=ppo env=gym env.id=CartPole-v1 ``` -You check all the available algorithms with +if you have installed from a cloned repo, or + +```bash +sheeprl exp=ppo env=gym env.id=CartPole-v1 +``` + +if you have installed SheepRL from PyPi. + +Similarly, you check all the available algorithms with ```bash python sheeprl/available_agents.py ``` +if you have installed from a cloned repo, or + +```bash +sheeprl-agents +``` +if you have installed SheepRL from PyPi. + That's all it takes to train an agent with SheepRL! 🎉 > Before you start using the SheepRL framework, it is **highly recommended** that you read the following instructional documents: @@ -363,7 +394,7 @@ What you run is the PPO algorithm with the default configuration. But you can al For example, in the default configuration, the number of parallel environments is 4. Let's try to change it to 8 by passing the `--num_envs` argument: ```bash -python sheeprl.py exp=ppo env=gym env.id=CartPole-v1 env.num_envs=8 +sheeprl exp=ppo env=gym env.id=CartPole-v1 env.num_envs=8 ``` All the available arguments, with their descriptions, are listed in the `sheeprl/config` directory. You can find more information about the hierarchy of configs [here](./howto/run_experiments.md). @@ -373,7 +404,7 @@ All the available arguments, with their descriptions, are listed in the `sheeprl To run the algorithm with Lightning Fabric, you need to specify the Fabric parameters through the CLI. For example, to run the PPO algorithm with 4 parallel environments on 2 nodes, you can run: ```bash -python sheeprl.py fabric.accelerator=cpu fabric.strategy=ddp fabric.devices=2 exp=ppo env=gym env.id=CartPole-v1 +sheeprl fabric.accelerator=cpu fabric.strategy=ddp fabric.devices=2 exp=ppo env=gym env.id=CartPole-v1 ``` You can check the available parameters for Lightning Fabric [here](https://lightning.ai/docs/fabric/stable/api/fabric_args.html). @@ -383,7 +414,7 @@ You can check the available parameters for Lightning Fabric [here](https://light You can easily evaluate your trained agents from checkpoints: training configurations are retrieved automatically. ```bash -python sheeprl_eval.py checkpoint_path=/path/to/checkpoint.ckpt fabric.accelerator=gpu env.capture_video=True +sheeprl-eval checkpoint_path=/path/to/checkpoint.ckpt fabric.accelerator=gpu env.capture_video=True ``` For more information, check the corresponding [howto](./howto/eval_your_agent.md). diff --git a/howto/model_manager.md b/howto/model_manager.md index 07f102ed..f82cb510 100644 --- a/howto/model_manager.md +++ b/howto/model_manager.md @@ -56,8 +56,9 @@ If you do not want to log some models, then, you just need to remove it from the > Make sure that the models specified in the configuration file are a subset of the models defined by the `MODELS_TO_REGISTER` variable. ## Register models from checkpoints -Another possibility is to register the models after the training, by manually selecting the checkpoint where to retrieve the agent. To do this, it is possible to run the `sheeprl_model_manager.py` script by properly specifying the `checkpoint_path`, the `model_manager`, and the MLFlow-related configurations. +Another possibility is to register the models after the training, by manually selecting the checkpoint where to retrieve the agent. To do this, it is possible to run the `sheeprl_model_manager.py` script (or directly `sheeprl-registration`) by properly specifying the `checkpoint_path`, the `model_manager`, and the MLFlow-related configurations. The default configurations are defined in the `./sheeprl/configs/model_manager_config.yaml` file, that is reported below: + ```yaml # ./sheeprl/configs/model_manager_config.yaml @@ -98,6 +99,14 @@ For instance, you can register the DreamerV3 models from a checkpoint with the f python sheeprl_model_manager.py model_manager=dreamer_v3 checkpoint_path=/path/to/checkpoint.ckpt ``` +if you have installed SheepRL from a cloned repo, or + +```bash +sheeprl-registration model_manager=dreamer_v3 checkpoint_path=/path/to/checkpoint.ckpt +``` + +if you have installed SheepRL from PyPi. + ## Delete, Transition and Download Models The MLFlow model manager enables the deletion of the registered models, moving them from one stage to another or downloading them. [This notebook](../examples/model_manager.ipynb) contains a tutorial on how to use the MLFlow model manager. We recommend taking a look to see what APIs the model manager makes available. \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 551e1b33..4219079d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,6 +55,9 @@ readme = {file = ["docs/README.md"], content-type = "text/markdown"} [project.scripts] sheeprl = "sheeprl.cli:run" +sheeprl-eval = "sheeprl.cli:evaluation" +sheeprl-agents = "sheeprl.available_agents:available_agents" +sheeprl-registration = "sheeprl.cli:registration" [project.urls] homepage = "https://eclecticsheep.ai" diff --git a/sheeprl/available_agents.py b/sheeprl/available_agents.py index 25daa243..7031f2c8 100644 --- a/sheeprl/available_agents.py +++ b/sheeprl/available_agents.py @@ -1,9 +1,10 @@ -if __name__ == "__main__": - from rich.console import Console - from rich.table import Table +from rich.console import Console +from rich.table import Table + +from sheeprl.utils.registry import algorithm_registry, evaluation_registry - from sheeprl.utils.registry import algorithm_registry, evaluation_registry +def available_agents(): table = Table(title="SheepRL Agents") table.add_column("Module") table.add_column("Algorithm") @@ -11,8 +12,6 @@ table.add_column("Decoupled") table.add_column("Evaluated by") - # print(evaluation_registry) - for module, implementations in algorithm_registry.items(): for algo in implementations: evaluated_by = "Undefined" @@ -33,3 +32,7 @@ console = Console() console.print(table) + + +if __name__ == "__main__": + available_agents() diff --git a/sheeprl/cli.py b/sheeprl/cli.py index 8eeef18d..6f80a768 100644 --- a/sheeprl/cli.py +++ b/sheeprl/cli.py @@ -325,7 +325,7 @@ def run(cfg: DictConfig): @hydra.main(version_base="1.3", config_path="configs", config_name="eval_config") def evaluation(cfg: DictConfig): # Load the checkpoint configuration - checkpoint_path = Path(cfg.checkpoint_path) + checkpoint_path = Path(os.path.abspath(cfg.checkpoint_path)) ckpt_cfg = OmegaConf.load(checkpoint_path.parent.parent / "config.yaml") ckpt_cfg.pop("seed", None) @@ -341,6 +341,7 @@ def evaluation(cfg: DictConfig): "strategy": "auto", "accelerator": getattr(cfg.fabric, "accelerator", "auto"), } + cfg.root_dir = str(checkpoint_path.parent.parent.parent.parent) # Merge configs ckpt_cfg.merge_with(cfg)