Merge pull request #49 from iraikov/vitepress-docs

Add vitepress-based documentation

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: docs
+on:
+  push:
+    branches: [main]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      - uses: oven-sh/setup-bun@v1
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Install dependencies
+        run: make docs-install
+      - name: Build with VitePress
+        run: |
+          make docs-build
+          touch docs/.vitepress/dist/.nojekyll
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -1,3 +1,8 @@
+# Documentation
+node_modules
+docs/.vitepress/dist
+docs/.vitepress/cache
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Makefile

@@ -0,0 +1,9 @@
+docs-build:
+	bun x vitepress build docs
+
+docs-dev:
+	bun x vitepress dev docs
+
+docs-install:
+	bun install
+

docs/.vitepress/config.mts

@@ -0,0 +1,44 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "dmosopt",
+  description: "Distributed multi-objective surrogate-assisted optimization",
+  base: '/dmosopt/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/introduction' },
+      { text: 'Examples', link: '/examples/zdt1' }
+    ],
+
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Guide',
+          items: [
+            { text: 'Installation', link: '/guide/installation' },
+            { text: 'Introduction', link: '/guide/introduction' },
+          ]
+        }
+      ],
+      '/examples/': [
+        {
+          text: 'Examples',
+          items: [
+            { text: 'ZDT1', link: '/examples/zdt1' },
+          ]
+        }
+      ]
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/iraikov/dmosopt' }
+    ],
+
+    search: {
+      provider: 'local'
+    }
+  }
+})

docs/examples/zdt1.md

@@ -0,0 +1,87 @@
+# ZDT1
+
+Let's consider a hello-world example using the ZDT1 objective. 
+
+Below, we define our own function and perform minimization.
+
+```python
+import sys, logging
+import numpy as np
+from dmosopt import dmosopt
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def zdt1(x):
+    """This is the Zitzler-Deb-Thiele Function - type A
+    Bound: XUB = [1,1,...]; XLB = [0,0,...]
+    dim = 30
+    """
+    num_variables = len(x)
+    f = np.zeros(2)
+    f[0] = x[0]
+    g = 1.0 + 9.0 / float(num_variables - 1) * np.sum(x[1:])
+    h = 1.0 - np.sqrt(f[0] / g)
+    f[1] = g * h
+    return f
+
+
+def obj_fun(pp):
+    """Objective function to be minimized."""
+    param_values = np.asarray([pp[k] for k in sorted(pp)])
+    res = zdt1(param_values)
+    logger.info(f"Iter: \t pp:{pp}, result:{res}")
+    return res
+
+
+def zdt1_pareto(n_points=100):
+    f = np.zeros([n_points, 2])
+    f[:, 0] = np.linspace(0, 1, n_points)
+    f[:, 1] = 1.0 - np.sqrt(f[:, 0])
+    return f
+
+
+if __name__ == "__main__":
+    space = {}
+    for i in range(30):
+        space["x%d" % (i + 1)] = [0.0, 1.0]
+    problem_parameters = {}
+    objective_names = ["y1", "y2"]
+
+    # Create an optimizer
+    dmosopt_params = {
+        "opt_id": "dmosopt_zdt1",
+        "obj_fun_name": "obj_fun",
+        "obj_fun_module": "example_dmosopt_zdt1",
+        "problem_parameters": problem_parameters,
+        "space": space,
+        "objective_names": objective_names,
+        "population_size": 200,
+        "num_generations": 200,
+        "initial_maxiter": 10,
+        "optimizer": "nsga2",
+        "termination_conditions": True,
+        "n_initial": 3,
+        "n_epochs": 2,
+    }
+
+    best = dmosopt.run(dmosopt_params, verbose=True)
+    if best is not None:
+        import matplotlib.pyplot as plt
+
+        bestx, besty = best
+        x, y = dmosopt.sopt_dict["dmosopt_zdt1"].optimizer_dict[0].get_evals()
+        besty_dict = dict(besty)
+
+        # plot results
+        plt.plot(y[:, 0], y[:, 1], "b.", label="evaluated points")
+        plt.plot(besty_dict["y1"], besty_dict["y2"], "r.", label="best points")
+
+        y_true = zdt1_pareto()
+        plt.plot(y_true[:, 0], y_true[:, 1], "k-", label="True Pareto")
+        plt.legend()
+
+        plt.savefig("example_dmosopt_zdt1.svg")
+
+```

docs/guide/installation.md

@@ -0,0 +1,11 @@
+# Installation
+
+dmosopt is available via [pip](https://pypi.org/project/dmosopt/). Install the current release
+
+```bash
+$ pip install dmosopt
+```
+
+::: info
+dmosopt currently supports Python 3.8 and higher
+:::

docs/guide/introduction.md

@@ -0,0 +1,12 @@
+# Welcome!
+
+*dmosopt* aims to simplify distributed multi-objective surrogate-assisted optimization while staying out of your way.
+
+
+::: info Installation
+
+To get started, run `pip install dmosopt`.
+
+[Learn more](./installation)
+
+:::

docs/index.md

@@ -0,0 +1,25 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "dmosopt"
+  text: "Distributed Multi-Objective Surrogate-Assisted Optimization"
+  tagline: ""
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/introduction
+    - theme: alt
+      text: API Examples
+      link: /examples/zdt1
+
+# features:
+#   - title: Feature A
+#     details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+#   - title: Feature B
+#     details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+#   - title: Feature C
+#     details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+---
+