Update how to use baselines (#2582)

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

baselines/doc/source/how-to-use-baselines.rst

@@ -25,23 +25,77 @@ All baselines are available in the directory `baselines <https://github.com/adap
 Please note that some baselines might include additional files (e.g. a :code:`requirements.txt`) or a hierarchy of :code:`.yaml` files for `Hydra <https://hydra.cc/>`_.
 
 
-Using a Baseline
-----------------
+Setting up your machine
+-----------------------
 
-Common to all baselines is `Poetry <https://python-poetry.org/docs/>`_, 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 <https://python-poetry.org/docs/>`_, a tool to manage Python dependencies. Baselines also make use of `Pyenv <https://github.com/pyenv/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 <https://github.com/pyenv/pyenv#installation>`_ 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 <https://python-poetry.org/docs/#installation>`_.
+  # 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 <https://python-poetry.org/docs/#installation>`_.
+
+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.