Release 1.0.0

* Quickstart to sphinx gallery
* Fixed hover text
* Renamed examples to be picked up by sphinx-gallery
* Changed func back to not being an example
* Fixed toc labels
* Added build command to not run examples
* Actual fix for toc label "Quickstart"
* Rename func to not be run
* Changed back broken `Branin` ref to what it was before
* Fixed gitignore for doc generated files
* fix a link in the quickstart
* Fixed warning of installation header
* Fixed broken links in quickstart
* Ignore sphinx gallery smac output
* Changed anonymous links to named ones
* Fixed failing example for use with sphinx gallery
* Renamed BOHB4HPO -> SMAC4MF
* Removed SMAC4HPO rf example
* Fixed .gitignore for smac output on examples
* Moved examples to subfolders
* Moved examples that require external func to parallel
* Makefile no defaults to build doc without examples
* Added README.rst so examples are run
* Fixed __file__ not defined
* Flattened examples to one folder, changed index to seperate
* Fixed literal includes
* String 'examples/brainin' 'examples/quickstart/branin'
* Fixed folder location of spear_qcp for tests
* Flake8 fixes
* Updated terminal_example paths
* Fixed path for spear_qcp scripts for build tests
* More path fixes to examples...
* Fixed sphinx-gallery config param for sphinx-gallery 0.9
* Updates sphinx gallery to newest version
* Matplotlib required for building docs with sphinx==0.9.0
* Removed updated sphx-gallery version and matplotlib dependancy
* Fixed installation link
* Quickfix links fixed, `make linkcheck` still complains
* Fixed links
* Included api building and linkchecking in make doc
* Changed from html links to use rst anchors
* Added mac support for examples
* README link fixes
* Typo fix
* Added example to the filenames
* Added example suffix to two examples
* Typo fix
* Doc warning fixes
* Flake8'd
* Updated changelog for 1.0.0
* Fixed strings in changelog back again
* Renamed BO facade to BB
* Added SMAC4BB into changelog
* Thompson sampling (#756)

Co-authored-by: eddiebergman <[email protected]>
Co-authored-by: Matthias Feurer <[email protected]>
Co-authored-by: dengdifan <[email protected]>
Co-authored-by: Difan Deng <[email protected]>

.github/workflows/terminal_examples.yml

@@ -28,26 +28,26 @@ jobs:
       run: |
         # Activate anaconda so default python is from conda
         export PATH="$CONDA/envs/testenv/bin:$PATH"
-        cd examples/spear_qcp
+        cd examples/quickstart/spear_qcp
         bash run_SMAC.sh
     - name: Spear QCP ROAR
       timeout-minutes: 20
       run: |
         # Activate anaconda so default python is from conda
         export PATH="$CONDA/envs/testenv/bin:$PATH"
-        cd examples/spear_qcp
+        cd examples/quickstart/spear_qcp
         bash run_ROAR.sh
     - name: Spear QCP Successive halving
       timeout-minutes: 20
       run: |
         # Activate anaconda so default python is from conda
         export PATH="$CONDA/envs/testenv/bin:$PATH"
-        cd examples/spear_qcp
+        cd examples/quickstart/spear_qcp
         python SMAC4AC_SH_spear_qcp.py
     - name:  Branin from the command line
       timeout-minutes: 20
       run: |
         # Activate anaconda so default python is from conda
         export PATH="$CONDA/envs/testenv/bin:$PATH"
-        cd examples/branin
-        python ../../scripts/smac --scenario scenario.txt
+        cd examples/quickstart/branin
+        python ../../../scripts/smac --scenario scenario.txt

.gitignore

@@ -9,6 +9,7 @@ dist
 
 # IDEs
 .idea
+.history
 
 # SMAC output
 runhistory.json
@@ -32,6 +33,11 @@ doc/main_options.rst
 doc/scenario_options.rst
 doc/smac_options.rst
 doc/apidoc
+doc/examples
+doc/quickstart
+
+# Generated from running Sphinx-Gallery
+*smac3-output_*
 
 # Dask created work space
 dask-worker-space

Makefile

@@ -5,7 +5,17 @@ test:
 
 .PHONY: doc
 doc:
+	make -C doc clean
+	make -C doc buildapi
+	make -C doc html-noplot
+	make -C doc linkcheck
+
+.PHONY: doc-with-examples
+doc-with-examples:
+	make -C doc clean
+	make -C doc buildapi
 	make -C doc html
+	make -C doc linkcheck
 
 .PHONY: clean
 clean: clean-data

README.md

@@ -125,28 +125,7 @@ target algorithms.
 
 # Examples
 
-We provide a bunch of examples in the [examples folder](examples), such as:
-
-  * Optimization of a Python function directly with SMAC
-    * [branin/branin_fmin.py](examples/branin/branin_fmin.py)
-    * [fmin_rosenbrock.py](https://automl.github.io/SMAC3/master/examples/fmin_rosenbrock.html#sphx-glr-examples-fmin-rosenbrock-py) - Optimization of the 2D Rosenbrock function
-    * [fmin_rosenbrock_parallel.py](https://automl.github.io/SMAC3/master/examples/fmin_rosenbrock_parallel.html#sphx-glr-examples-fmin-rosenbrock-parallel-py) - Example of parallel SMAC using dask
-  * Optimization of a black-box function with SMAC
-    * [SMAC4BO_rosenbrock.py](https://automl.github.io/SMAC3/master/examples/SMAC4BO_rosenbrock.html#sphx-glr-examples-smac4bo-rosenbrock-py) [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1v0ZH5S9Sfift30GxHAp96e0yZZUFS0Ah)
-    * [SMAC4BO_acq_rosenbrock.py](https://automl.github.io/SMAC3/master/examples/SMAC4HPO_acq_rosenbrock.html#sphx-glr-examples-smac4hpo-acq-rosenbrock-py) - Example to select the acquisition function
-  * Hyperparameter Optimization with SMAC
-    * [SMAC4HPO_rosenbrock.py](https://automl.github.io/SMAC3/master/examples/SMAC4HPO_rosenbrock.html#sphx-glr-examples-smac4hpo-rosenbrock-py) [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1v0ZH5S9Sfift30GxHAp96e0yZZUFS0Ah)
-    * [SMAC4HPO_rf.py](https://automl.github.io/SMAC3/master/examples/SMAC4HPO_rf.html#sphx-glr-examples-smac4hpo-rf-py) - Optimization of a random forest
-    * [SMAC4HPO_svm.py](https://automl.github.io/SMAC3/master/examples/SMAC4HPO_svm.html#sphx-glr-examples-smac4hpo-svm-py) - Optimization of an SVM [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1v0ZH5S9Sfift30GxHAp96e0yZZUFS0Ah)
-  * Optimization of a SAT solver across problem instances with SMAC
-    * [spear_qcp/run_SMAC.sh](examples/spear_qcp/run_SMAC.sh)
-  * Optimization of an MLP
-    * [parallel_sh_mlp.py](https://automl.github.io/SMAC3/master/examples/parallel_sh_mlp.html#sphx-glr-examples-parallel-sh-mlp-py) - Parallel Successive Halving
-    * [hyperband_mlp.py](https://automl.github.io/SMAC3/master/examples/hyperband_mlp.html#sphx-glr-examples-hyperband-mlp-py) - Hyperband
-    * [SMAC4MF_mlp.py](https://automl.github.io/SMAC3/master/examples/SMAC4MF_mlp.html#sphx-glr-examples-smac4mf-mlp-py) - SMAC4MF
-    * [SMAC4MF_sgd_instances.py](https://automl.github.io/SMAC3/master/examples/SMAC4MF_sgd_instances.html#sphx-glr-examples-smac4mf-sgd-instances-py) - SMAC4MF across instances
-
-An overview of all examples can be seen in our [documentation](https://automl.github.io/SMAC3/master/examples/index.html).
+Please see an overview of all examples in our [documentation](https://automl.github.io/SMAC3/master/examples/index.html).
 
 # Contact
 

changelog.md

@@ -1,3 +1,28 @@
+# 1.0.0
+
+The main purpose of this release is to be synchronized with our upcoming paper.
+Since many urgent features were already taken care of in 0.14.0, this release mainly focuses on better documentation and examples.
+
+## Features
+* Examples and quickstart guide can now be generated by [sphinx-gallry](https://sphinx-gallery.github.io/stable/index.html).
+* Added make command `make doc` and `make doc-with-examples`.
+
+## Major changes
+* Examples are separated into categories.
+* Renamed facade SMAC4BO to SMAC4BB (black-box).
+* Add thompson sampling as a new acquisition function
+
+## Minor Changes
+* Included linkcheck and buildapi to the `make doc` command.
+* `quickstart.rst` was converted to `quickstart_example.py` to be processed by sphinx-gallery.
+* Examples renamed from `*.py` to `*_example.py`, unless file name was `*_func.py`, in which case it was unchanged.
+* Flake8 fixes for spear_qcp as there were a lot of complaints running `pre-commit`.
+* Fixes pydoc issues.
+* Fixed links in the README.
+* Fixed warnings given during the doc build.
+* Fixed inconsistent output shape described in `smac.epm.gaussian_process.GaussianProcess.sample_functions`
+* Examples are wrapped inside `if __name__ == "__main__"`, fixing problems on mac.
+
 # 0.14.0
 
 ## Breaking Changes

doc/Makefile

@@ -18,6 +18,7 @@ PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+MAKEFILE_DIR     = $(shell pwd)
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
@@ -51,6 +52,7 @@ help:
 
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf $(MAKEFILE_DIR)/examples
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -167,7 +169,7 @@ changes:
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	$(SPHINXBUILD) -D plot_gallery=0 -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
@@ -192,6 +194,11 @@ pseudoxml:
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
 
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 buildapi:
 	sphinx-apidoc -fePTMo apidoc/ ../smac/
 	rm apidoc/smac.rst

doc/basic_usage.rst

@@ -4,10 +4,10 @@ Basic Usage
 There are two ways to use *SMAC*, either over the commandline or within your
 Python-code.
 
-Either way, you need to provide the `target algorithm <tae.html#tae>`_ you want to
-optimize and the `configuration space <options.html#pcs>`_, which specifies the legal ranges and
+Either way, you need to provide the :ref:`target algorithm <tae>` you want to
+optimize and the :ref:`configuration space <paramcs>`, which specifies the legal ranges and
 default values of the tunable parameters. In addition, you can configure the
-optimization process with the `scenario <options.html#scenario>`_-options.
+optimization process with the :ref:`scenario <scenario>`-options.
 
 The most important scenario-options are:
 
@@ -19,17 +19,17 @@ The most important scenario-options are:
   are used to control maximum wallclock-time, number of algorithm calls and
   cpu-time used for optimization respectively.
 - **instance_file**, **test_instance_file** and **feature_file** specify the
-  paths to the instances and features (see `file-formats <options.html#instance>`_)
+  paths to the instances and features (see :ref:`file-formats <instance>`)
 
-For a full list, see `scenario-options <options.html#scenario>`_.
+For a full list, see :ref:`scenario-options <scenario>`.
 
 .. _commandline:
 
 Commandline 
 ~~~~~~~~~~~
-To use *SMAC* via the commandline, you need a `scenario-file <options.html#scenario>`_ and a `PCS-file <options.html#pcs>`_.
+To use *SMAC* via the commandline, you need a :ref:`scenario-file <scenario>` and a :ref:`PCS-file <paramcs>`.
 The script to invoke *SMAC* is located in *scripts/smac*. Please see the
-`Branin <quickstart.html#branin>`_-example to see how to use it.
+:ref:`Branin <branin-example>`-example to see how to use it.
 
 *SMAC* is called via the commandline with the following arguments:
 
@@ -38,7 +38,7 @@ The script to invoke *SMAC* is located in *scripts/smac*. Please see the
         python3 smac --scenario SCENARIO --seed INT --verbose_level LEVEL --mode MODE
 
 Required:
-     * *scenario*: Path to the file that specifies the `scenario <options.html#scenario>`_ for this *SMAC*-run.
+     * *scenario*: Path to the file that specifies the `scenario <scenario>` for this *SMAC*-run.
 Optional:
      * *seed*: The integer that the random-generator will be based upon. **Default**: 12345
      * *verbose_level*: in [INFO, DEBUG], specifies the logging-verbosity. **Default**: INFO
@@ -48,17 +48,16 @@ Optional:
 In the scenario file, there are two mandatory parameters: The **algo**-parameter
 defines how *SMAC* will call the target algorithm. Parameters will be appended to the call
 with ``-PARAMETER VALUE``, so make sure your algorithm will accept the parameters in this
-form. Read more in the section on `target algorithms <tae.html#tae>`_.
-The **paramfile**-parameter defines the path to the `PCS-file <options.html#pcs>`_,
+form. Read more in the section on :ref:`target algorithms <tae>`.
+The **paramfile**-parameter defines the path to the `PCS-file <paramcs>`,
 which describes the ranges and default values of the tunable parameters.
 Both will interpret paths *from the execution-directory*.
 
 .. note::
 
     Currently, running *SMAC* via the commandline will register the algorithm with a
-    `Target Algorithm Evaluator (TAE) <tae.html#tae>`_, that requires the target algorithm to print
-    the results to the console in the following format (see `Branin
-    <quickstart.html#branin>`_):
+    :ref:`Target Algorithm Evaluator (TAE) <tae>`, that requires the target algorithm to print
+    the results to the console in the following format (see :ref:`Branin <branin-example>`):
 
     .. code-block:: bash
     
@@ -82,30 +81,29 @@ because the budget is still exhausted.
 to unexpected behaviour!**
 
 For an example of restoring states from within your Python code, there is an
-implementation with the Branin-example in "examples/branin/restore_state.py".
+implementation with the Branin-example in "examples/quickstart/branin/restore_state.py".
 
 
 .. _inpython:
 
 Usage in Python
 ~~~~~~~~~~~~~~~
-The usage of *SMAC* from your Python-code is described in the `SVM-example
-<quickstart.html#svm-example>`_.
+The usage of *SMAC* from your Python-code is described in the :ref:`SVM-example <svm-example>`.
 Scenario and configuration space are both build within the code. The target
-algorithm needs to be registered with a `Target Algorithm Evaluator (TAE) <tae.html#tae>`_,
+algorithm needs to be registered with a :ref:`Target Algorithm Evaluator (TAE) <tae>`,
 which communicates between *SMAC* and the target algorithm. To optimize a function, you can instantiate
-`ExecuteTAFuncDict <apidoc/smac.tae.execute_func.html#smac.tae.execute_func.ExecuteTAFuncDict>`_ or
-`ExecuteTAFuncArray <apidoc/smac.tae.execute_func.html#smac.tae.execute_func.ExecuteTAFuncArray>`_.
+:class:`ExecuteTAFuncDict <smac.tae.execute_func.ExecuteTAFuncDict>` or
+:class:`ExecuteTAFuncArray <smac.tae.execute_func.ExecuteTAFuncArray>`.
 In that case, the algorithm needs to return a cost, representing the quality of
 the solution, while time- and memory-limits are measured and enforced by `Pynisher
 <https://github.com/sfalkner/pynisher>`_, so no wrapper is needed for your
 algorithm here.
 
-- `ExecuteTAFuncDict <apidoc/smac.tae.execute_func.html#smac.tae.execute_func.ExecuteTAFuncDict>`_:
+- :class:`ExecuteTAFuncDict <smac.tae.execute_func.ExecuteTAFuncDict>`:
   The target algorithm is called with a dict-like configuration and optionally
   with seed and instance, returning either the loss as a float or a tuple (loss,
   additional information).
-- `ExecuteTAFuncArray <apidoc/smac.tae.execute_func.html#smac.tae.execute_func.ExecuteTAFuncArray>`_:
+- :class:`ExecuteTAFuncArray <smac.tae.execute_func.ExecuteTAFuncArray>`:
   The target algorithm is called with an array-like configuration and optionally
   with seed and instance, returning either the loss as a float or a tuple (loss,
   additional information).

doc/conf.py

@@ -130,8 +130,10 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-# Insert options
-  'collapse_navigation': False
+    # Insert options
+    'collapse_navigation': False,
+    'includehidden': False,
+    'titles_only': True,
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -227,24 +229,24 @@
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
 
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
+    # Latex figure (float) alignment
+    # 'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'SMAC3.tex', u'SMAC3 Documentation', smac.__author__, 'manual'),
+    (master_doc, 'SMAC3.tex', u'SMAC3 Documentation', smac.__author__, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -287,9 +289,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'SMAC3', u'SMAC3 Documentation',
-   author, 'SMAC3', 'One line description of project.',
-   'Miscellaneous'),
+    (master_doc, 'SMAC3', u'SMAC3 Documentation',
+     author, 'SMAC3', 'One line description of project.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -312,12 +314,23 @@
 cmd_reader.write_smac_options_to_doc()
 cmd_reader.write_scenario_options_to_doc()
 
+from sphinx_gallery.sorting import ExplicitOrder
+
 # Sphinx-gallery configuration.
 sphinx_gallery_conf = {
     # disable mini galleries clustered by the used functions
-    'backreferences_dir': False,
+    'backreferences_dir': None,
     # path to the examples
     'examples_dirs': '../examples',
+
+    # Ordering
+    'subsection_order': ExplicitOrder(['../examples/quickstart',
+                                       '../examples/function_minimization',
+                                       '../examples/parallel',
+                                       '../examples/SMAC4HPO',
+                                       '../examples/SMAC4BB',
+                                       '../examples/SMAC4MF',
+                                       '../examples/hyperband']),
     # path where to save gallery generated examples
     'gallery_dirs': 'examples',
     # compile execute examples in the examples dir

doc/faq.rst

@@ -10,19 +10,19 @@ or try to run the installation first.
 
 Ensure that the gcc used to compile the pyrfr is the same as used for linking
 during execution. This often happens with Anaconda -- see
-`Installation <installation.html>`_ for a solution.
+:ref:`Installation <installation>` for a solution.
 
 .. rubric:: My target algorithm is not accepted, when using the scenario-file.
 
 Make sure that your algorithm accepts commandline options as provided by
-*SMAC*. Refer to `commandline execution <basic_usage.html#commandline>`_ for
+*SMAC*. Refer to :ref:`commandline execution <commandline>` for
 details on how to wrap your algorithm.
 
 You can also run SMAC with :code:`--verbose DEBUG` to see how *SMAC* tried to call your algorithm.
 
 .. rubric:: Can I restore SMAC from a previous state?
 
-Use the `restore-option <basic_usage.html#restorestate>`_.
+Use the :ref:`restore-option <restorestate>`_.
 
 .. rubric:: I discovered a bug or SMAC does not behave as expected. Where should I report to?
 

doc/index.rst

@@ -20,11 +20,11 @@ Contents:
    :maxdepth: 1
 
    installation
-   quickstart
+   Quickstart <examples/quickstart/quickstart_example>
    usage_recomendation
+   smac_examples
    manual
    api
-   examples/index
    faq
    contact
    license

doc/installation.rst

@@ -1,3 +1,5 @@
+.. _installation:
+
 Installation
 ============