Website design

.devcontainer/Dockerfile

@@ -0,0 +1,28 @@
+FROM almalinux:9
+
+# Install basic dependencies
+RUN dnf install -y --allowerasing \
+    git \
+    curl \
+    wget \
+    which \
+    tar \
+    gzip \
+    bzip2 \
+    ca-certificates \
+    && dnf clean all
+
+# Install OpenCode
+RUN curl -fsSL https://opencode.ai/install | bash
+
+# Install Pixi
+RUN curl -fsSL https://pixi.sh/install.sh | sh
+
+# Add Pixi to PATH
+ENV PATH="/root/.pixi/bin:${PATH}"
+
+# Set working directory
+WORKDIR /workspace
+
+# Verify installations
+RUN pixi --version || echo "Pixi installation will be verified on container start"

.devcontainer/devcontainer.json

@@ -0,0 +1,20 @@
+{
+  "name": "Blop Dev Container",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "mounts": [
+    "source=${localEnv:HOME}/.cache/rattler,target=/root/.cache/rattler,type=bind,consistency=cached"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-toolsai.jupyter"
+      ]
+    }
+  },
+  "postCreateCommand": "pixi info",
+  "remoteUser": "root"
+}

.github/workflows/README.md

@@ -1,6 +1,5 @@
 # GitHub Actions CI Overview
 
-
 ## Workflow
 
 ### `ci.yml`
@@ -21,7 +20,6 @@ If one of these conditions are met, than the following occurs:
 
 This structure avoids duplicate CI jobs when both a PR and a branch push happen.
 
-
 ### `_check.yml`
 
 Used to see if the current branch (on `push`) is already part of an open pull request.

.github/workflows/_docs.yml

@@ -6,12 +6,9 @@ on:
       deploy_key:
         required: false
 
-
 jobs:
   build_docs:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
 
     defaults:
       run:
@@ -28,19 +25,10 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Install documentation-building requirements with apt/dpkg
-        run: |
-          set -vxeuo pipefail
-          wget --progress=dot:giga "https://github.com/jgm/pandoc/releases/download/3.1.6.1/pandoc-3.1.6.1-1-amd64.deb" -O /tmp/pandoc.deb
-          sudo dpkg -i /tmp/pandoc.deb
-          # conda install -c conda-forge -y pandoc
-          which pandoc
-          pandoc --version
-
       - name: Install pixi and activate environment
-        uses: prefix-dev/setup-pixi@v0.8.14
+        uses: prefix-dev/setup-pixi@82d477f15f3a381dbcc8adc1206ce643fe110fb7 # v0.9.3
         with:
-          pixi-version: v0.46.0
+          pixi-version: v0.60.0
           environments: docs
           cache: false
           activate-environment: docs
@@ -51,21 +39,13 @@ jobs:
       - name: Build Docs
         run: pixi run build-docs
 
-      - name: Upload JupyterLite docs artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: jupyterlite-docs
-          path: docs/build/jupyter_execute
-          if-no-files-found: error
-
       - name: Upload HTML docs artifact
         uses: actions/upload-artifact@v4
         with:
           name: ${{ env.REPOSITORY_NAME }}-docs
           path: docs/build/html/
 
       - name: Deploy documentation to nsls-ii.github.io
-        # if: github.repository_owner == 'NSLS-II' && github.ref_name == 'main'
         if: github.event_name == 'release'
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions

.github/workflows/_testing.yml

@@ -35,7 +35,17 @@ jobs:
           activate-environment: ${{ matrix.python-version }}
 
       - name: Run unit tests
-        run: pixi run unit-tests
+        run: |
+          if [ "${{ matrix.python-version }}" = "py313-cpu" ]; then
+            pixi run -e ${{ matrix.python-version }} pytest --cov=blop --cov-report=xml --cov-report=term src/blop/tests
+          else
+            pixi run tests
+          fi
 
-      - name: Run integration tests
-        run: pixi run integration-tests
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == 'py313-cpu'
+        uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238  # v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+          verbose: true

.opencode/skills/blop-overview/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: blop-overview
+description: Overview of the Blop project structure, workflow, and use-cases
+compatibility: opencode
+---
+
+## What is Blop?
+
+Blop (Beamline Optimization Package) is a Python library for Bayesian optimization of experimental systems, particularly beamline experiments at synchrotron facilities. It bridges optimization algorithms (using Ax platform, BoTorch, GPyTorch) with the Bluesky ecosystem for data acquisition and device control, enabling efficient exploration of expensive-to-evaluate parameter spaces.
+
+## Project Structure
+
+- **`src/blop/ax/`** - Core Agent implementation and Ax platform integration (DOFs, objectives, constraints)
+- **`src/blop/bayesian/`** - Bayesian optimization components and models
+- **`src/blop/plans.py`** - Bluesky plans for running experiments and optimization iterations
+- **`docs/`** - Comprehensive Sphinx documentation with tutorials, how-tos, and explanations
+
+## Basic Workflow
+
+1. **Define DOFs** - Specify degrees of freedom (parameters to optimize) using `RangeDOF` or `ChoiceDOF`
+1. **Define Objectives** - Specify what to maximize or minimize with `Objective` or `ScalarizedObjective`
+1. **Add Constraints** (optional) - Set boundaries with `DOFConstraint` or `OutcomeConstraint`
+1. **Create Agent** - Instantiate the optimization agent with DOFs, objectives, and an evaluation function
+1. **Run Optimization** - Execute iterations using Bluesky's RunEngine to collect data and update models
+1. **Analyze Results** - Review health metrics, convergence, and Pareto frontiers for multi-objective problems
+
+## Common Use-Cases
+
+- **Beamline alignment** - Optimizing mirror positions, angles, and curvatures for X-ray focusing
+- **Multi-objective optimization** - Balancing competing goals like maximizing intensity while minimizing beam spot size
+- **Parameter tuning** - Finding optimal experimental settings when measurements are expensive or time-consuming
+- **Automated calibration** - Systematic exploration of device parameters for optimal performance
+
+## Documentation
+
+The project has excellent documentation at `/docs/` with detailed tutorials and explanations. **Refer to the docs for specific implementation details, API references, and worked examples.**

.opencode/skills/build-docs/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: build-docs
+description: Build and test Sphinx documentation for the blop project
+compatibility: opencode
+---
+
+## What I do
+
+Build Sphinx documentation using pixi tasks.
+
+## Commands
+
+**Build HTML docs:**
+
+```bash
+pixi run build-docs
+```
+
+**Run doctests:**
+
+```bash
+pixi run doc-tests
+```
+
+## When to use me
+
+Use me when building or testing documentation.

.opencode/skills/dev-workflow/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: dev-workflow
+description: Run development checks: tests, linting, formatting, and type checking for the blop project
+compatibility: opencode
+---
+
+## What I do
+
+Run fast development checks using pixi tasks.
+
+## Commands
+
+**Run tests:**
+
+```bash
+pixi run tests
+```
+
+**Run all checks (lint, format, typecheck):**
+
+```bash
+pixi run check
+```
+
+## When to use me
+
+Use me when running tests or checks during development.

.opencode/skills/install-deps/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: install-deps
+description: Install and manage blop dependencies using pixi or pip
+compatibility: opencode
+---
+
+## What I do
+
+Install project dependencies.
+
+## Commands
+
+**Using pixi:**
+
+```bash
+pixi install
+```
+
+## Adding dependencies
+
+Add to `pyproject.toml` as the single source of truth. `pixi.toml` should install most dependencies via the `pyproject.toml` with few exceptions.
+
+## When to use me
+
+Use me when setting up the project or syncing dependencies.

.pre-commit-config.yaml

@@ -34,3 +34,11 @@ repos:
     rev: 0.8.1
     hooks:
       - id: nbstripout
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.21
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-ruff
+          - mdformat-frontmatter

README.md

@@ -1,13 +1,34 @@
 # Blop - Beamline Optimization Package
 
-
-[![Testing](https://github.com/NSLS-II/blop/actions/workflows/ci.yml/badge.svg)](https://github.com/NSLS-II/blop/actions/workflows/ci.yml)
+[![Testing](https://github.com/bluesky/blop/actions/workflows/ci.yml/badge.svg)](https://github.com/bluesky/blop/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/bluesky/blop/branch/main/graph/badge.svg)](https://codecov.io/gh/bluesky/blop)
 [![PyPI](https://img.shields.io/pypi/v/blop.svg)](https://pypi.python.org/pypi/blop)
 [![Conda](https://img.shields.io/conda/vn/conda-forge/blop.svg)](https://anaconda.org/conda-forge/blop)
 
-* Free software: 3-clause BSD license
-* Documentation: <https://NSLS-II.github.io/blop>.
+- Free software: 3-clause BSD license
+- Documentation: <https://NSLS-II.github.io/blop>.
+
+## Installation
+
+```bash
+pip install blop
+```
+
+or with conda:
+
+```bash
+conda install -c conda-forge blop
+```
+
+## Development
+
+A devcontainer is available with OpenCode and Pixi pre-installed. To use it:
+
+```bash
+./launch-devcontainer.sh
+```
 
+Or open in VS Code and select "Reopen in Container".
 
 ## Citation
 

docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  devcontainer:
+    build:
+      context: .devcontainer
+      dockerfile: Dockerfile
+    volumes:
+      - .:/workspace
+      - ${HOME}/.cache/rattler:/root/.cache/rattler:cached
+    working_dir: /workspace
+    stdin_open: true
+    tty: true
+    command: /bin/bash

docs/source/_includes/installation-code-snippets.rst

@@ -0,0 +1,24 @@
+.. snippet-pip-standard-start
+.. code:: bash
+
+   $ pip install blop
+.. snippet-pip-standard-end
+
+.. snippet-conda-standard-start
+.. code:: bash
+
+   $ conda install -c conda-forge blop
+.. snippet-conda-standard-end
+
+.. snippet-pip-cpu-start
+.. code:: bash
+
+   $ pip install uv
+   $ uv pip install blop[cpu]
+.. snippet-pip-cpu-end
+
+.. snippet-conda-cpu-start
+.. code:: bash
+
+   $ conda install -c conda-forge blop pytorch cpuonly -c pytorch
+.. snippet-conda-cpu-end

docs/source/_static/css/fix-content-height.css

@@ -0,0 +1,29 @@
+/* Let notebook Plotly outputs fill available space */
+.content {
+    overflow: hidden;
+    height: auto;
+    min-height: 0;
+    max-height: none;
+    width: 100%;
+    min-width: 0;
+    max-width: none;
+}
+
+.content > * {
+    max-height: none;
+    width: 100%;
+    max-width: none;
+}
+
+.content .js-plotly-plot,
+.content .plotly-graph-div,
+.content .plotly,
+.content .plot-container {
+    width: 100% !important;
+    max-width: none;
+}
+
+.card-box > * {
+    overflow: hidden;
+    left: 0;
+}