diff --git a/baselines/README.md b/baselines/README.md index 17f4d405cba3..3b30ff1a9eaf 100644 --- a/baselines/README.md +++ b/baselines/README.md @@ -23,23 +23,23 @@ Please note that some baselines might include additional files (e.g. a `requirem ## Running the baselines -Each baseline is self-contained in its own directory. Furthermore, each baseline defines its own Python environment using [Poetry](https://python-poetry.org/docs/) via a `pyproject.toml` file. In order to run a baseline: +Each baseline is self-contained in its own directory. Furthermore, each baseline defines its own Python environment using [Poetry](https://python-poetry.org/docs/) via a `pyproject.toml` file and [`pyenv`](https://github.com/pyenv/pyenv). If you haven't setup `Poetry` and `pyenv` already on your machine, please take a look at the [Documentation](https://flower.dev/docs/baselines/how-to-use-baselines.html#setting-up-your-machine) for a guide on how to do so. -1. First, ensure you have Poetry installed in your system. For Linux and macOS, installing Poetry can be done from a single command: +Assuming `pyenv` and `Poetry` are already installed on your system. Running a baseline can be done by: + +1. Cloning the flower repository ```bash - curl -sSL https://install.python-poetry.org | python3 - + git clone https://github.com/adap/flower.git && cd flower ``` - To install Poetry on a different OS, to customise your installation, or to further integrate Poetry with your shell after installation, please check [the Poetry documentation](https://python-poetry.org/docs/#installing-with-the-official-installer). - 2. Navigate inside the directory of the baseline you'd like to run. 3. Follow the `[Environment Setup]` instructions in the `README.md`. In most cases this will require you to just do: ```bash poetry install ``` -4. Run the baseline as indicated in the `[Running the Experiments]` section in the `README.md` +4. Run the baseline as indicated in the `[Running the Experiments]` section in the `README.md` or in the `[Expected Results]` section to reproduce the experiments in the paper. ## Contributing a new baseline diff --git a/baselines/doc/source/how-to-use-baselines.rst b/baselines/doc/source/how-to-use-baselines.rst index 23e21b74dedc..b89c17b17a98 100644 --- a/baselines/doc/source/how-to-use-baselines.rst +++ b/baselines/doc/source/how-to-use-baselines.rst @@ -25,23 +25,77 @@ All baselines are available in the directory `baselines `_. -Using a Baseline ----------------- +Setting up your machine +----------------------- -Common to all baselines is `Poetry `_, a tool to manage Python dependencies. You'll need to install it on your system before running a baseline. For Linux and macOS, installing Poetry can be done from a single command: +.. note:: + Flower baselines are designed to run on Ubuntu 22.04. While a GPU is not required to run the baselines, some of the more computationally demanding ones do benefit from GPU acceleration. + +Common to all baselines is `Poetry `_, a tool to manage Python dependencies. Baselines also make use of `Pyenv `_. You'll need to install both on your system before running a baseline. What follows is a step-by-step guide on getting :code:`pyenv` and :code:`Poetry` installed on your system. + +Let's begin by installing :code:`pyenv`. We'll be following the standard procedure. Please refere to the `pyenv docs `_ for alternative ways of installing it. + +.. code-block:: bash + + # first install a few packages needed later for pyenv + sudo apt install build-essential zlib1g-dev libssl-dev libsqlite3-dev \ + libreadline-dev libbz2-dev libffi-dev liblzma-dev + + # now clone pyenv into your home directory (this is the default way of installing pyenv) + git clone https://github.com/pyenv/pyenv.git ~/.pyenv + + # Then add pyenv to your path by adding the below to your .bashrc/.zshrc + export PYENV_ROOT="$HOME/.pyenv" + command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH" + eval "$(pyenv init -)" + +Verify your installtion by opening a new terminal and + +.. code-block:: bash + + # check python versions available + pyenv versions + # * system (...) # <-- it should just show one + +Then you can proceed and install any version of Python. Most baselines currently use Python 3.10.6, so we'll be installing that one. + +.. code-block:: bash + + pyenv install 3.10.6 + # this will take a little while + # once done, you should see that that version is avaialble + pyenv versions + # system + # * 3.10.6 # <-- you just installed this + +Now that we have :code:`pyenv` installed, we are ready to install :code:`poetry`. Installing Poetry can be done from a single command: .. code-block:: bash curl -sSL https://install.python-poetry.org | python3 - -To install Poetry on a different OS, to customise your installation, or to further integrate Poetry with your shell after installation, please check `the Poetry documentation `_. + # add to path by putting this line at the end of your .zshrc/.bashrc + export PATH="$HOME/.local/bin:$PATH" + + +To install Poetry from source, to customise your installation, or to further integrate Poetry with your shell after installation, please check `the Poetry documentation `_. + +Using a Flower Baseline +----------------------- + +To use Flower Baselines you need first to install :code:`pyenv` and :code:`Poetry`, then: + +1. Clone the flower repository + +.. code-block:: bash + git clone https://github.com/adap/flower.git && cd flower -1. Navigate inside the directory of the baseline you'd like to run -2. Follow the :code:`[Environment Setup]` instructions in the :code:`README.md`. In most cases this will require you to just do: +2. Navigate inside the directory of the baseline you'd like to run +3. Follow the :code:`[Environment Setup]` instructions in the :code:`README.md`. In most cases this will require you to just do: .. code-block:: bash poetry install -3. Run the baseline as indicated in the :code:`[Running the Experiments]` section in the :code:`README.md` +4. Run the baseline as indicated in the :code:`[Running the Experiments]` section in the :code:`README.md` or in the `[Expected Results]` section to reproduce the experiments in the paper.