docs/major update to docs, sphinx, and docs ci script

.github/workflows/CI.yaml

@@ -53,14 +53,15 @@ jobs:
       - name: Lint
         shell: bash -l {0}
         run: |
-          invoke lint
-          invoke black --checkonly
-          invoke isort --checkonly
+          invoke style --checkonly
 
       - name: Run tests
         shell: bash -l {0}
-        run: pytest -s
+        run: invoke tests --options '-s -v'
 
+      - name: Test docs build with no errors
+        shell: bash -l {0}
+        run:  invoke docs -w
   mac:
 
     strategy:

.gitignore

@@ -6,6 +6,8 @@ docs/_build
 docs/api
 docs/_autosummary
 docs/jupyter_execute
+docs/code_reference/api
+*.log
 
 # autogenerated version file from setuptools-scm
 _version.py

boa/__init__.py

@@ -10,9 +10,13 @@
     __version__ = "0.0.0"
 
 from boa.ax_instantiation_utils import *  # noqa
+from boa.controller import *  # noqa
 from boa.instantiation_base import *  # noqa
+from boa.metrics.metric_funcs import *  # noqa
 from boa.metrics.metrics import *  # noqa
+from boa.metrics.modular_metric import *  # noqa
+from boa.metrics.synthetic_funcs import *  # noqa
 from boa.runner import *  # noqa
 from boa.storage import *  # noqa
-from boa.wrapper import *  # noqa
-from boa.wrapper_utils import *  # noqa
+from boa.wrappers.wrapper import *  # noqa
+from boa.wrappers.wrapper_utils import *  # noqa

boa/__main__.py

@@ -6,7 +6,7 @@
 import click
 
 from boa.controller import Controller
-from boa.wrapper_utils import cd_and_cd_back, load_jsonlike
+from boa.wrappers.wrapper_utils import cd_and_cd_back, load_jsonlike
 
 
 @click.command()
@@ -84,10 +84,12 @@ def _main(config_path, rel_to_here, experiment_dir=None):
             # since we just loaded the module where the wrapper class is, we can now load it
             WrapperCls = getattr(user_wrapper, wrapper_name)
         else:
-            from boa.wrapper import BaseWrapper as WrapperCls
+            from boa.wrappers.wrapper import BaseWrapper as WrapperCls
 
         controller = Controller(config_path=config_path, wrapper=WrapperCls)
-        scheduler = controller.run(append_timestamp=append_timestamp, experiment_dir=experiment_dir)
+
+        controller.setup(append_timestamp=append_timestamp, experiment_dir=experiment_dir)
+        scheduler = controller.run()
         return scheduler
 
 

boa/_doc_utils.py

@@ -0,0 +1,28 @@
+import importlib
+import pkgutil
+
+import boa
+
+
+def get_boa_submodules():
+    module_list = []
+    packages = []
+    for module_finder, modname, is_pkg in pkgutil.walk_packages(boa.__path__):
+        if is_pkg:
+            packages.append(modname)
+        if len(modname.split(".")) > 1:
+            module_list.append(modname)
+    return module_list
+
+
+def import_boa_submod(submod_str):
+    return importlib.import_module(f"boa.{submod_str}")
+
+
+def add_ref_to_all_submodules_inits():
+    module_list = get_boa_submodules()
+    for mod_str in module_list:
+        submod = import_boa_submod(mod_str)
+        info = f"""**Overview Information Here**: :mod:`{submod.__package__}`"""
+
+        submod.__doc__ = f"{submod.__doc__}\n\n{info}" if submod.__doc__ else info

boa/ax_instantiation_utils.py

@@ -1,3 +1,12 @@
+"""
+###################################
+Ax Instantiation Utility Functions
+###################################
+
+Utility functions to instantiate Ax objects
+
+"""
+
 from __future__ import annotations
 
 import copy
@@ -55,7 +64,7 @@ def get_scheduler(
     generation_strategy: GenerationStrategy = None,
     scheduler_options: SchedulerOptions = None,
     config: dict = None,
-):
+) -> Scheduler:
     scheduler_options = scheduler_options or SchedulerOptions(**config["optimization_options"]["scheduler"])
     if generation_strategy is None:
         if (

boa/controller.py

@@ -1,37 +1,95 @@
+"""
+###################################
+Controller
+###################################
+
+The Controller class controls the optimization.
+
+"""
+from __future__ import annotations
+
 import logging
+import os
 import time
 from pathlib import Path
+from typing import Type
+
+from ax.service.scheduler import Scheduler
 
 from boa.ax_instantiation_utils import get_experiment, get_scheduler
 from boa.runner import WrappedJobRunner
 from boa.storage import scheduler_to_json_file
 from boa.utils import get_dictionary_from_callable
-from boa.wrapper_utils import get_dt_now_as_str
+from boa.wrappers.wrapper import BaseWrapper
+from boa.wrappers.wrapper_utils import get_dt_now_as_str
 
 
 class Controller:
-    def __init__(self, config_path, wrapper):
+    """
+    Controls the instantiation of your :mod:`.wrapper` and the
+    necessary Ax objects to start your Experiment and control
+    the Ax scheduler. Once the Controller sets up your Experiment, it starts
+    the scheduler, which runs your trials. It then
+    saves the scheduler to a json file.
+
+    Parameters
+    ----------
+    config_path
+        Path to configuration yaml or json file
+    wrapper
+        Your Wrapper subclass of BaseWrapper to be instantiated
+
+    See Also
+    --------
+    :ref:`Creating a configuration File`
+
+    """
+
+    def __init__(self, config_path: os.PathLike | str, wrapper: Type[BaseWrapper]):
         self.config_path = config_path
         self.wrapper = wrapper
 
         self.config = None
 
-    def run(self, append_timestamp, experiment_dir, **kwargs):
-        start = time.time()
+        self.scheduler = None
+
+    def setup(
+        self, append_timestamp: bool = None, experiment_dir: os.PathLike = None, **kwargs
+    ) -> tuple[Scheduler, BaseWrapper]:
+        """
+        Sets up all the classes and objects needed to create the Ax Scheduler
 
+        Parameters
+        ----------
+        append_timestamp
+            Whether to append the output experiment directory with a timestamp or not
+            (default True)
+        experiment_dir
+            Output experiment directory to which the experiment and trials will be saved
+            (defaults to experiment_dir specified in the config script options
+            or working_dir/experiment_name [if working_dir specified in config]
+            or current_dir/experiment_name [if working_dir and experiment_dir and
+            not specified])
+
+        Returns
+        -------
+        returns a tuple with the first element being the scheduler
+        and the second element being your wrapper (both initialized
+        and ready to go)
+        """
         kwargs["config_path"] = self.config_path
         if experiment_dir:
             kwargs["experiment_dir"] = experiment_dir
         if append_timestamp is not None:
             kwargs["append_timestamp"] = append_timestamp
 
-        load_config_kwargs = get_dictionary_from_callable(self.wrapper.load_config, kwargs)
-        wrapper = self.wrapper(**load_config_kwargs)
-        config = wrapper.config
+        load_config_kwargs = get_dictionary_from_callable(self.wrapper.__init__, kwargs)
+        self.wrapper = self.wrapper(**load_config_kwargs)
+        config = self.wrapper.config
 
         log_format = "%(levelname)s %(asctime)s - %(message)s"
         logging.basicConfig(
-            filename=Path(wrapper.experiment_dir) / "optimization.log",
+            filename=Path(self.wrapper.experiment_dir) / "optimization.log",
             filemode="w",
             format=log_format,
             level=logging.DEBUG,
@@ -40,8 +98,34 @@ def run(self, append_timestamp, experiment_dir, **kwargs):
         logger = logging.getLogger(__file__)
         logger.info("Start time: %s", get_dt_now_as_str())
 
-        experiment = get_experiment(config, WrappedJobRunner(wrapper=wrapper), wrapper)
-        scheduler = get_scheduler(experiment, config=config)
+        experiment = get_experiment(config, WrappedJobRunner(wrapper=self.wrapper), self.wrapper)
+        self.scheduler = get_scheduler(experiment, config=config)
+        return self.scheduler, self.wrapper
+
+    def run(self, scheduler: Scheduler = None, wrapper: BaseWrapper = None) -> Scheduler:
+        """
+        Run trials for scheduler
+
+        Parameters
+        ----------
+        scheduler
+            initialed scheduler or None, if None, defaults to
+            ``self.scheduler`` (the scheduler set up in :meth:`.Controller.setup`
+        wrapper
+            initialed wrapper or None, if None, defaults to
+            ``self.wrapper`` (the wrapper set up in :meth:`.Controller.setup`
+
+        Returns
+        -------
+        The scheduler after all trials have been run or the
+        experiment has been stopped for another reason.
+        """
+        start = time.time()
+
+        scheduler = scheduler or self.scheduler
+        wrapper = wrapper or self.wrapper
+        if not scheduler or not wrapper:
+            raise ValueError("Scheduler and wrapper must be defined, or setup in setup method!")
 
         try:
             scheduler.run_all_trials()

boa/metaclasses.py

@@ -1,3 +1,14 @@
+"""
+########################
+Meta Classes
+########################
+
+Meta class modify class behaviors. For example, the :class:`.WrapperRegister` ensures that all subclasses of
+:class:`.BaseWrapper` will wrap functions in :func:`.cd_and_cd_back_dec`
+to make sure that if users do any directory changes inside a wrapper function,
+the original directory is returned to afterwards.
+
+"""
 import logging
 import traceback
 from abc import ABCMeta
@@ -7,7 +18,7 @@
 from ax.storage.metric_registry import CORE_METRIC_REGISTRY
 from ax.storage.runner_registry import CORE_RUNNER_REGISTRY
 
-from boa.wrapper_utils import cd_and_cd_back_dec
+from boa.wrappers.wrapper_utils import cd_and_cd_back_dec
 
 logger = logging.getLogger(__name__)
 
@@ -53,9 +64,3 @@ def __init__(cls, *args, **kwargs):
         CORE_DECODER_REGISTRY[cls.__name__] = cls
         next_pk = max(CORE_METRIC_REGISTRY.values()) + 1
         CORE_METRIC_REGISTRY[cls] = next_pk
-
-
-class MetricToEvalRegister(type):
-    def __init__(cls, *args, **kwargs):
-        CORE_ENCODER_REGISTRY[cls] = cls.to_dict
-        CORE_DECODER_REGISTRY[cls.__name__] = cls

boa/metrics/__init__.py

@@ -1,6 +1,14 @@
 """
-.. todo::
+################################################
+Metrics Overview & Advanced Usage
+################################################
 
-    Coming soon!
 
+Metrics are the objective functions we are optimizing over
+or functions that are added as further constraints of our problem.
+
+Metrics can be specified in your configuration file by passing in the name
+of one of the predefined :mod:`Metrics <boa.metrics.metrics>` in BOA.
+
+See :doc:`/user_guide/configuration` for details.
 """