Feature/improve documentation (#1028)

* Experimental instruction for installing SMAC in windows via WSL

* More detailed documentation regarding continuing runs

* Fixes

* Fixes

* Fixes

* Update docs/10_experimental.rst

Co-authored-by: Difan Deng <33290713+dengdifan@users.noreply.github.com>

* Fixes from PR

* Fixes from PR

* Fixes from PR

* Fixes from PR

* Fixes from PR

---------

Co-authored-by: Difan Deng <33290713+dengdifan@users.noreply.github.com>

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Improvements
 - Add an error when we get an empty dict data_to_scatter so that we can avoid an internal error caused in Dask precautiously
+- Add experimental instruction for installing SMAC in Windows via a WSL.
+- More detailed documentation regarding continuing runs.
 
 ## Bugfixes
 - Fix bug in the incumbent selection in the case that multi-fidelity is combined with multi-objective (#1019).

docs/10_experimental.rst

@@ -0,0 +1,48 @@
+Experimental
+============
+
+.. warning::
+    This part is experimental and might not work in each case. If you would like to suggest any changes, please let us know. 
+
+
+Installation in Windows via WSL
+------------------------------
+
+SMAC can be installed in a WSL (Windows Subsystem for Linux) under Windows.
+
+**1) Install WSL under Windows**
+
+Install WSL under Windows. This SMAC installation workflow was tested with Ubuntu 18.04. For Ubuntu 20.04, 
+it has been observed that the SMAC installation results in a segmentation fault (core dumped).
+
+**2) Get Anaconda**
+
+Download an Anaconda Linux version to drive D under Windows, e.g. D:\\Anaconda3-2023.03-1-Linux-x86_64
+
+In the WSL, Windows resources are mounted under /mnt:
+
+.. code:: bash
+
+    cd /mnt/d
+    bash Anaconda3-2023.03-1-Linux-x86_64
+
+Enter this command to create the environment variable:
+
+.. code:: bash
+
+    export PATH="$PATH:/home/${USER}/anaconda3/bin
+
+Input 'python' to check if the installation was successful.
+
+**3) Install SMAC**
+
+Change to your home folder and install the general software there:
+
+.. code:: bash
+
+    cd /home/${USER}
+    sudo apt-get install software-properties-common
+    sudo apt-get update
+    sudo apt-get install build-essential swig
+    conda install gxx_linux-64 gcc_linux-64 swig
+    curl https://raw.githubusercontent.com/automl/smac3/master/requirements.txt | xargs -n 1 -L 1 pip install

docs/1_installation.rst

@@ -68,3 +68,11 @@ You must have `conda >= 4.9` installed. To update conda or check your current co
     
 
 Read `SMAC feedstock <https://github.com/conda-forge/smac-feedstock>`_ for more details.
+
+Windows via WSL (Experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SMAC can be installed under Windows in a WSL (Windows Subsystem for Linux). 
+You can find an instruction on how to do this here: :ref:`Experimental<Experimental>`
+However, this is experimental and might not work in each case. 
+If you would like to suggest any changes, please let us know. 

docs/advanced_usage/10_continue.rst

@@ -1,14 +1,23 @@
 Continue
 ========
 
-SMAC automatically restores states where it left off if a run was interrupted or finished. To do so, it reads in old
-files (derived from scenario's name, output_directory and seed) and sets the components.
+SMAC can automatically restore states where it left off if a run was interrupted or prematurely finished. To do so, 
+it reads in old files (derived from scenario's name, output_directory and seed) and obtains the scenario information
+of the previous run from those to continue the run.
+
+The behavior can be controlled by setting the parameter ``overwrite`` in the facade to True or False, respectively:
+
+* If set to True, SMAC overwrites the run results if a previous run is found that is consistent in the meta data with the current setup.
+* If set to False and a previous run is found that
+
+  * is consistent in the meta data, the run is continued. 
+  * is not consistent in the meta data, the user is asked for the exact behaviour (overwrite completely or rename old run first).
 
 .. warning::
 
-    If you changed any code and specified a name, SMAC will ask you whether you still want to resume or
-    delete the old run completely. If you did not specify a name, SMAC generates a new name and the old run is
-    not affected.
+    If you changed any code affecting the run's meta data and specified a name, SMAC will ask you whether you still 
+    want to overwrite the old run or rename the old run first. If you did not specify a name, SMAC generates a new name 
+    and the old run is not affected.
 
 
 Please have a look at our :ref:`continue example<Continue an Optimization>`.

examples/1_basics/5_continue.py

@@ -2,8 +2,16 @@
 Continue an Optimization
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-SMAC can also be continued. In this example, an optimization of a simple quadratic
-function is continued. We use a custom callback, to artificially stop the first optimization.
+SMAC can also be continued from a previous run. To do so, it reads in old files (derived from scenario's name,
+output_directory and seed) and sets the corresponding components. In this example, an optimization of a simple quadratic
+function is continued.
+
+First, after creating a scenario with 50 trials, we run SMAC with overwrite=True. This will
+overwrite any previous runs (in case the example was called before). We use a custom callback to artificially stop
+this first optimization after 10 trials.
+
+Second, we again run the SMAC optimization using the same scenario, but this time with overwrite=False. As
+there already is a previous run with the same meta data, this run will be continued until the 50 trials are reached.
 """
 
 from __future__ import annotations

smac/facade/abstract_facade.py

@@ -92,8 +92,10 @@ class AbstractFacade:
         Callbacks, which are incorporated into the optimization loop.
     overwrite: bool, defaults to False
         When True, overwrites the run results if a previous run is found that is
-        inconsistent in the meta data with the current setup. If ``overwrite`` is set to False, the user is asked
-        for the exact behaviour (overwrite completely, save old run, or use old results).
+        consistent in the meta data with the current setup. When False and a previous run is found that is
+        consistent in the meta data, the run is continued. When False and a previous run is found that is
+        not consistent in the meta data, the the user is asked for the exact behaviour (overwrite completely
+        or rename old run first).
     dask_client: Client | None, defaults to None
         User-created dask client, which can be used to start a dask cluster and then attach SMAC to it. This will not
         be closed automatically and will have to be closed manually if provided explicitly. If none is provided

smac/main/smbo.py

@@ -505,7 +505,7 @@ def _initialize_state(self) -> None:
                         logger.info("Since the previous run was not successful, SMAC will start from scratch again.")
                         self.reset()
                 else:
-                    # Here, we run into differen scenarios
+                    # Here, we run into different scenarios
                     diff = recursively_compare_dicts(
                         Scenario.make_serializable(self._scenario),
                         Scenario.make_serializable(old_scenario),