diff --git a/CHANGELOG.md b/CHANGELOG.md index d8dbab399..5eecccace 100644 --- a/CHANGELOG.md +++ b/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). diff --git a/docs/10_experimental.rst b/docs/10_experimental.rst new file mode 100644 index 000000000..a075498c4 --- /dev/null +++ b/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 diff --git a/docs/1_installation.rst b/docs/1_installation.rst index 54f910a44..7b8dd9c4b 100644 --- a/docs/1_installation.rst +++ b/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 `_ 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` +However, this is experimental and might not work in each case. +If you would like to suggest any changes, please let us know. diff --git a/docs/advanced_usage/10_continue.rst b/docs/advanced_usage/10_continue.rst index 8a254c4e5..e29c3f9c9 100644 --- a/docs/advanced_usage/10_continue.rst +++ b/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`. \ No newline at end of file diff --git a/examples/1_basics/5_continue.py b/examples/1_basics/5_continue.py index 04cca4aed..025856fee 100644 --- a/examples/1_basics/5_continue.py +++ b/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 diff --git a/smac/facade/abstract_facade.py b/smac/facade/abstract_facade.py index 1022034c8..a5db5ab52 100644 --- a/smac/facade/abstract_facade.py +++ b/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 diff --git a/smac/main/smbo.py b/smac/main/smbo.py index 30e01c2e9..2ce565e94 100644 --- a/smac/main/smbo.py +++ b/smac/main/smbo.py @@ -501,7 +501,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),