Move Xopt docs to this repo

.github/workflows/gh-pages.yml

@@ -0,0 +1,68 @@
+name: Documentation
+
+on:
+  push:
+  workflow_dispatch:
+  pull_request:
+  repository_dispatch:
+    types: [ release ]
+
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: write
+  actions: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: "Build docs"
+    env:
+      # `uv pip ...` requires venv by default. This skips that requirement.
+      UV_SYSTEM_PYTHON: 1
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          git clone https://github.com/xopt-org/xopt.git
+          cd xopt
+          uv pip install ".[doc]"
+      - name: Build Docs
+        shell: bash -l {0}
+        run: mkdocs build
+      - name: Extract examples
+        shell: bash -l {0}
+        run: |
+          zip -r xopt-examples.zip docs/examples/
+          mv xopt-examples.zip ./site/assets/
+      - name: Upload docs artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+  deploy:
+    if: ${{ github.repository_owner == 'xopt-org' && (github.ref == 'refs/heads/main') }}
+    needs: build
+    name: "Deploy docs"
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment # TODO: set environment and url
+#    environment:
+#      name: github-pages
+#       url: ${{ steps.deployment.outputs.page_url }}
+
+    # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1 +1,3 @@
-# Xopt-docs
+# Xopt Docs
+
+New repository for Xopt documentation. Under development.

docs/algorithms.md

@@ -0,0 +1,76 @@
+Pre-Configured Generators in Xopt
+===============
+A number of algorithms are implemented in Xopt using the ```Generator``` class for
+off-the-shelf usage.
+Below is a
+description of the different generators that are available in Xopt and their target
+use cases.
+
+RandomGenerator
+===============
+Generates random points in the input space according to ```VOCS```.
+
+Bayesian Generators
+==
+All of the generators here use Bayesian optimization (BO) type methods to solve single
+objective, multi objective and characterization problems. Bayesian generators
+incorperate unknown constrianing functions into optimization based on what is
+specified in ```VOCS```
+
+- ```ExpectedImprovementGenerator```: implements Expected Improvement single
+  objective BO. Automatically balances trade-offs between exploration and
+  exploitation and is thus useful for general purpose optimization.
+- ```UpperConfidenceBoundGenerator```: implements Upper Confidence Bound single
+  objective BO. Requires a hyperparameter ```beta``` that explicitly sets the tradeoff
+  between exploration and exploitation. Default value of ```beta=2``` is a good
+  starting point. Increase $\beta$ to prioritize exploration and decrease ```beta``` to
+  prioritize exploitation.
+- ```BayesianExplorationGenerator```: implements the Bayesian Exploration algorithm
+  for function characterization. This algorithm selects observation points that
+  maximize model uncertainty, thus picking points that maximize the information gain
+  about the target function at each iteration. If the target function is found to be
+  more sensative to one parameter this generator will adjust sampling frequency to
+  adapt. Note: specifying ```vocs.objective[1]```
+  to ```MAXIMIZE``` or ```MINIMIZE``` does not change the behavior of this generator.
+- ```MOBOGenerator```: implements Multi-Objective BO using the
+  Expected Hypervolume Improvement (EHVI) acquisition function. This is an ideal
+  general purpose multi-objective optimizer when objective evaluations cannot be
+  massively parallelized (< 10 parallel evaluations).
+- ```MGGPOGenerator```: implements Multi-Generation Gaussian Process Optimization using
+  the
+  Expected Hypervolume Improvement (EHVI) acquisition function. This is an ideal
+  general purpose multi-objective optimizer when objective evaluations can be
+  massively parallelized (> 10 parallel evaluations) .
+- ```MultiFidelityGenerator```: implements Multi-Fidelity BO which can take
+  advantage of lower fidelity evaluations of objectives and constraints to reduce
+  the computational cost of solving single or multi-objective optimization problems
+  in sequential or small scale parallel (< 10 parallel evaluations)
+  contexts.
+
+Evolutionary Generators
+=====
+- ```CNSGAGenerator```: implements Continuous Non-dominated Sorted Genetic Algorithm
+  which as a good general purpose evolutionary algorithm used for solving
+  multi-objective optimization problems where evaluating the objective is relatively
+  cheap and massively parallelizable (above 5-10 parallel evaluations).
+
+Extremum Seeking Generators
+===
+- ```ExtremumSeekingGenerator```: implements the Extremum Seeking algorithm which is
+  ideal for solving optimization problems that are suceptable to drifts.
+
+Scipy Generators
+===
+These generators serve as wrappers for algorithms implemented in scipy.
+- ```NelderMeadGenerator```: implements Nelder-Mead (simplex) optimization.
+
+RCDS Generators
+===
+- ```RCDSGenerator```: implements the RCDS algorithm. RCDS could be applied in noisy
+  online optimization scenarios
+
+Custom Generators
+====
+Any general algorithm can be implemented by subclassing the abstract ```Generator```
+class and used in the Xopt framework. If you implement a generator for your use case
+please consider opening a pull request so that we can add it to Xopt!

docs/api/evaluator.md

@@ -0,0 +1 @@
+::: xopt.evaluator.Evaluator

docs/api/generators.md

@@ -0,0 +1 @@
+::: xopt.generator

docs/api/generators/bayesian.md

@@ -0,0 +1,18 @@
+::: xopt.generators.bayesian.bayesian_generator.BayesianGenerator
+::: xopt.generators.bayesian.bayesian_exploration.BayesianExplorationGenerator
+::: xopt.generators.bayesian.expected_improvement.ExpectedImprovementGenerator
+::: xopt.generators.bayesian.expected_improvement.TDExpectedImprovementGenerator
+::: xopt.generators.bayesian.mobo.MOBOGenerator
+::: xopt.generators.bayesian.upper_confidence_bound.UpperConfidenceBoundGenerator
+::: xopt.generators.bayesian.upper_confidence_bound.TDUpperConfidenceBoundGenerator
+::: xopt.generators.bayesian.multi_fidelity.MultiFidelityGenerator
+::: xopt.generators.bayesian.turbo.TurboController
+- get_trust_region
+- update_trust_region
+- get_data_in_trust_region
+- update_state
+- reset
+::: xopt.generators.bayesian.turbo.OptimizeTurboController
+- minimize
+::: xopt.generators.bayesian.turbo.SafetyTurboController
+::: xopt.generators.bayesian.turbo.EntropyTurboController

docs/api/generators/genetic.md

@@ -0,0 +1 @@
+::: xopt.generators.ga.cnsga.CNSGAGenerator

docs/api/generators/scipy.md

@@ -0,0 +1,3 @@
+::: xopt.generators.sequential.neldermead.NelderMeadGenerator
+::: xopt.generators.sequential.rcds.RCDSGenerator
+::: xopt.generators.sequential.extremumseeking.ExtremumSeekingGenerator

docs/api/vocs.md

@@ -0,0 +1 @@
+::: xopt.vocs.VOCS

docs/api/xopt.md

@@ -0,0 +1 @@
+::: xopt.Xopt

docs/examples/basic/checkpointing_and_restarts.ipynb

@@ -0,0 +1,180 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "source": [
+    "# Checkpointing and Restarts\n",
+    "If `dump_file` is provided Xopt will save the data and the Xopt configuration in a\n",
+    "yaml file. This can be used directly to create a new Xopt object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-05-03T19:55:02.557814300Z",
+     "start_time": "2024-05-03T19:54:59.954542500Z"
+    },
+    "execution": {
+     "iopub.execute_input": "2024-09-13T15:54:15.718571Z",
+     "iopub.status.busy": "2024-09-13T15:54:15.718173Z",
+     "iopub.status.idle": "2024-09-13T15:54:16.708491Z",
+     "shell.execute_reply": "2024-09-13T15:54:16.708212Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# Import the class\n",
+    "from xopt import Xopt\n",
+    "\n",
+    "# Make a proper input file.\n",
+    "YAML = \"\"\"\n",
+    "dump_file: dump.yml\n",
+    "generator:\n",
+    "    name: random\n",
+    "\n",
+    "evaluator:\n",
+    "    function: xopt.resources.test_functions.tnk.evaluate_TNK\n",
+    "    function_kwargs:\n",
+    "        a: 999\n",
+    "\n",
+    "vocs:\n",
+    "    variables:\n",
+    "        x1: [0, 3.14159]\n",
+    "        x2: [0, 3.14159]\n",
+    "    objectives: {y1: MINIMIZE, y2: MINIMIZE}\n",
+    "    constraints:\n",
+    "        c1: [GREATER_THAN, 0]\n",
+    "        c2: [LESS_THAN, 0.5]\n",
+    "    constants: {a: dummy_constant}\n",
+    "\n",
+    "\"\"\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "source": [
+    "## Checkpoints\n",
+    "Since we specified a dump file Xopt will dump the data and all of the options\n",
+    "required to create a new Xopt object that continues the run."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-05-03T19:55:02.741844900Z",
+     "start_time": "2024-05-03T19:55:02.558814400Z"
+    },
+    "execution": {
+     "iopub.execute_input": "2024-09-13T15:54:16.710304Z",
+     "iopub.status.busy": "2024-09-13T15:54:16.710154Z",
+     "iopub.status.idle": "2024-09-13T15:54:16.754153Z",
+     "shell.execute_reply": "2024-09-13T15:54:16.753777Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# create Xopt object.\n",
+    "X = Xopt.from_yaml(YAML)\n",
+    "\n",
+    "# take 10 steps and view data\n",
+    "for _ in range(10):\n",
+    "    X.step()\n",
+    "\n",
+    "X.data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
+   "source": [
+    "## Create Xopt object from dump file"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-05-03T19:55:02.813814500Z",
+     "start_time": "2024-05-03T19:55:02.740817500Z"
+    },
+    "execution": {
+     "iopub.execute_input": "2024-09-13T15:54:16.775975Z",
+     "iopub.status.busy": "2024-09-13T15:54:16.775763Z",
+     "iopub.status.idle": "2024-09-13T15:54:16.785072Z",
+     "shell.execute_reply": "2024-09-13T15:54:16.784799Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "X2 = Xopt.from_file(\"dump.yml\")\n",
+    "X2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-05-03T19:55:02.946844800Z",
+     "start_time": "2024-05-03T19:55:02.782814900Z"
+    },
+    "execution": {
+     "iopub.execute_input": "2024-09-13T15:54:16.786507Z",
+     "iopub.status.busy": "2024-09-13T15:54:16.786330Z",
+     "iopub.status.idle": "2024-09-13T15:54:16.842388Z",
+     "shell.execute_reply": "2024-09-13T15:54:16.842111Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "for _ in range(10):\n",
+    "    X2.step()\n",
+    "\n",
+    "X2.data"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}