fomtools 0.0.2__tar.gz → 0.0.4__tar.gz

{fomtools-0.0.2 → fomtools-0.0.4}/.github/workflows/docs.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, documentation ]
 
 permissions:
   contents: write
@@ -54,13 +54,10 @@ jobs:
       - name: Export marimo notebooks
         env:
           GRB_LICENSE_FILE: ${{ github.workspace }}/gurobi.lic
-        run: |
-          for file in docs/tutorials/*.py; do
-            marimo export html "$file" -o "${file%.py}.html"
-          done
+        run: python scripts/export_marimo.py --force
 
       - name: Verify html generation
-        run: ls docs/tutorials
+        run: ls -R docs/tutorials
 
       - name: Configure Git Credentials
         run: |
@@ -79,11 +76,10 @@ jobs:
             mkdocs-material-
 
       - name: Build MkDocs site
-        run: mkdocs build
+        run: mkdocs build --strict
 
-      - name: Deploy to Cloudflare Pages with Wrangler
-        uses: cloudflare/wrangler-action@v4.0.0
-        with:
-          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          command: deploy
+      # Pull requests only build the site; pushes to main publish it to the gh-pages
+      # branch, which GitHub Pages serves at https://stellatogrp.github.io/fomtools/
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: mkdocs gh-deploy --force

{fomtools-0.0.2 → fomtools-0.0.4}/.github/workflows/update-skill.yml

@@ -20,6 +20,8 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
+          # The PR branch itself (not the detached merge ref), so the sync commit can be pushed.
+          ref: ${{ github.head_ref }}
           fetch-depth: 1
 
       - name: Run Claude Code to update skill
@@ -27,17 +29,8 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          prompt_file: skills/update-prompt.md
-
-          allowed_tools: |
-            Bash(git status)
-            Bash(git diff:*)
-            Bash(git log:*)
-            Bash(git add:*)
-            Bash(git commit:*)
-            Bash(find:*)
-            Bash(grep:*)
-            Bash(wc:*)
-            Read
-            Edit
-            Write
+          # v1 inputs: `prompt` and `claude_args` (the v0 `prompt_file` and `allowed_tools`
+          # are ignored, and without a prompt the action skips silently).
+          prompt: 'Follow the instructions in skills/update-prompt.md.'
+          claude_args: >-
+            --allowedTools "Bash(git status),Bash(git diff:*),Bash(git log:*),Bash(git add:*),Bash(git commit:*),Bash(git push:*),Bash(find:*),Bash(grep:*),Bash(wc:*),Read,Edit,Write"

{fomtools-0.0.2 → fomtools-0.0.4}/.gitignore

@@ -385,3 +385,8 @@ fomtools.project
 __marimo__/
 *.npz
 .ruff_cache/
+
+.vscode/
+
+# `marimo export html` output, generated by the docs workflow at build time.
+docs/tutorials/**/*.html

{fomtools-0.0.2 → fomtools-0.0.4}/AGENTS.md

@@ -82,3 +82,30 @@ execution of the CUDA checks; `FOMTOOLS_CODEGEN_BACKEND` selects the agent.
 - When the public API or docs change, the `update-skill` workflow refreshes
   `skills/fomtools/`; check its output rather than editing the skill by hand
   in the same PR.
+
+## Tutorial math notation
+
+All `mo.md` cells in `docs/tutorials/` (verification and codegen notebooks) use one notation per concept, following Boyd-style conventions. Keep new notebooks in sync with this table.
+
+| Concept | Write | Never |
+|---|---|---|
+| Reals, ones | `\mathbf{R}`, `\mathbf{R}^n_+`, `\mathbf{1}` | `{\bf R}`, `\R`, `\mathbb{R}` |
+| Transpose | `A^T` | `A^\top` |
+| Calligraphic | `\mathcal{X}` | `{\cal X}` |
+| Problem keywords | `\text{minimize}`, `\text{maximize}`, `\text{subject to}` | `\textnormal{...}` |
+| Delimiters | inline `$...$`, display `$$...$$`, problems and updates as bare `\begin{array}{ll}`/`{rcl}` | `\(...\)`, `\[...\]` |
+| Soft-thresholding | `\mathbf{soft}_{\lambda\eta}` (`soft_threshold` step) | `{\cal T}_\lambda`, `S_\lambda` |
+| Projection | `\Pi_C`: `\Pi_{\mathbf{R}^n_+}` (`relu` step), `\Pi_{[l,u]}` (`satlin` step / `IndBox`) | `\mathbf{ReLU}`, `\mathbf{prox}_{\mathbb{I}_C}` |
+| Proximal operator | `\mathbf{prox}_f` | `\operatorname{prox}` |
+| Fractions | inline slash: `(1/2) z^T P z`, `(t_k - 1)/t_{k+1}` | `\frac` |
+
+Norms always carry a subscript: `\|v\|_2`, `\|v\|_\infty` (never `\lVert v \rVert` or a bare `\|v\|`).
+Define soft-thresholding where it is first used: `\mathbf{soft}_\kappa(v)_i = \mathbf{sign}(v_i)\max\{|v_i| - \kappa, 0\}`, applied element-wise.
+Matplotlib labels (`label=`, `xlabel`, `ylabel`, `title`) are rendered by mathtext, not KaTeX: write `\geq`/`\leq` there (mathtext rejects `\ge`/`\le`), and keep `\|v\|_2` norms.
+
+Symbol roles: `x` problem parameter in `\mathcal{X}`; `z` decision variable and primal iterate, `z^0 \in \mathcal{Z}`, `z^\star` solution; `v, w` dual or auxiliary iterates; `y` (lasso) or `w` (NNLS) for the un-extrapolated proximal output of a momentum method, matching the helper code; `k` iteration, `K` horizon, `\eta` step size, `L` smoothness constant, `r^k` residual, `R` PEP initial radius.
+Search-box bounds are `x_\mathrm{lb}, x_\mathrm{ub}` and `z^0_\mathrm{lb}, z^0_\mathrm{ub}`; problem-data bounds keep `_{\min}, _{\max}`. Code names such as `x_lb` or `s0_samples` appear only in backticks in prose. When a math letter differs from the code name, say so once.
+
+Iterations are written `k \to k+1` for `k = 0, 1, \dots`. A momentum coefficient `\beta_k` uses the same index as the helper code (slot `k` uses `beta_k`, and `k` starts at 1), so the update reads `z^{k+1} = w^{k+1} + \beta_{k+1}(w^{k+1} - w^k)` with `\beta_1 = 0`. Use "Nesterov-type momentum" for `\beta_k = (k-1)/(k+2)` and reserve "FISTA" for the `t_k` schedule `\beta_k = (t_{k-1}-1)/t_k`.
+
+Known clashes kept on purpose because both uses are standard: control input `u_t` vs. OSQP upper bound `u(x)`, LQR weight `R` vs. PEP radius `R`, and `\mu` as network cost, portfolio return, or strong-convexity constant.

fomtools-0.0.4/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to FOMTools
+
+## Development setup
+
+Follow the environment instructions in [docs/get_started.md](docs/get_started.md) to create a
+virtual environment and install `fomtools` in editable mode with its `dev` and `docs` extras.
+
+Install the pre-commit hooks once per clone:
+
+    pre-commit install
+
+## Tests and linting
+
+    pytest                      # Run the test suite
+    ruff check                  # Check code style
+    ruff format                 # Auto-format
+    pre-commit run --all-files  # Run all hooks
+
+## Previewing the documentation
+
+Install the documentation dependencies and start the local MkDocs server:
+
+    uv sync --extra docs
+    make docs-serve
+
+The `docs-serve` target recursively discovers marimo notebooks under `docs/tutorials`, exports
+missing or stale notebooks to ignored HTML files, and then starts MkDocs. Restart the server after
+editing a notebook so that its HTML is refreshed.
+
+Use these targets to export or validate the documentation without starting the server:
+
+    make docs-export        # Export only missing or stale notebooks
+    make docs-export-force  # Regenerate every notebook
+    make docs-build         # Force export, then run a strict MkDocs build

fomtools-0.0.4/Makefile

@@ -0,0 +1,13 @@
+.PHONY: docs-export docs-export-force docs-serve docs-build
+
+docs-export:
+	uv run --extra docs python scripts/export_marimo.py
+
+docs-export-force:
+	uv run --extra docs python scripts/export_marimo.py --force
+
+docs-serve: docs-export
+	uv run --extra docs mkdocs serve
+
+docs-build: docs-export-force
+	uv run --extra docs mkdocs build --strict

{fomtools-0.0.2/fomtools.egg-info → fomtools-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fomtools
-Version: 0.0.2
+Version: 0.0.4
 Summary: FOMTools: A Python Toolbox for Analysis of First-Order Methods
 Author-email: Vinit Ranjan <vranjan1@mit.edu>, Daniel Deza <dd7022@princeton.edu>, Anushka Acharya <aa9078@princeton.edu>, Jisun Park <jisunpark@princeton.edu>, Bartolomeo Stellato <bstellato@princeton.edu>
 License: Apache 2.0
@@ -41,22 +41,40 @@ Provides-Extra: nn
 Requires-Dist: torch; extra == "nn"
 Requires-Dist: jax<0.11.2; extra == "nn"
 Requires-Dist: flax; extra == "nn"
+Provides-Extra: all
+Requires-Dist: fomtools[codegen,cvxpygen,gurobi,nn]; extra == "all"
+Requires-Dist: fomtools[gpu]; sys_platform != "darwin" and extra == "all"
+Requires-Dist: fomtools[cuda]; extra == "all"
 Provides-Extra: docs
 Requires-Dist: fomtools[gurobi]; extra == "docs"
 Requires-Dist: marimo; extra == "docs"
 Requires-Dist: matplotlib; extra == "docs"
-Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
 Requires-Dist: mkdocstrings-python; extra == "docs"
 Requires-Dist: mkdocs-marimo; extra == "docs"
 Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: networkx; extra == "docs"
+Requires-Dist: pepit; extra == "docs"
 Requires-Dist: pymdown-extensions; extra == "docs"
 Dynamic: license-file
 
-FOMTools
-========
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/stellatogrp/fomtools/main/docs/assets/logo/logo-dark.svg">
+    <img alt="FOMTools" src="https://raw.githubusercontent.com/stellatogrp/fomtools/main/docs/assets/logo/logo.svg" height="72">
+  </picture>
+</h1>
+
+[![PyPI](https://img.shields.io/pypi/v/fomtools.svg)](https://pypi.org/project/fomtools/)
+[![Docs](https://img.shields.io/badge/docs-stellatogrp.github.io%2Ffomtools-blue.svg)](https://stellatogrp.github.io/fomtools/)
 
 **Development, analysis, and code generation for first-order methods.**
 
+[Documentation](https://stellatogrp.github.io/fomtools/) |
+[PyPI](https://pypi.org/project/fomtools/) |
+[Paper](https://arxiv.org/abs/2610.26743) |
+[Benchmarks](https://github.com/stellatogrp/fomtools_experiments)
+
 FOMTools is an open-source Python package for developing, analyzing, and deploying
 first-order methods for parametric linear and convex quadratic optimization. You write the
 iteration in Python, with syntax close to its mathematical description, and FOMTools records
@@ -75,65 +93,73 @@ you can:
 
 ## Example
 
-The following code verifies FISTA on a family of Lasso problems
-```
-minimize        0.5 ||D s - x||_2^2 + lambda ||s||_1
-```
+The following code verifies projected gradient descent on the parametric quadratic program
+
+$$
+\begin{array}{ll}
+\text{minimize} & (1/2) z^T P z + q^T z \\
+\text{subject to} & z \geq 0,
+\end{array}
+$$
 
-where `s in R^n` is the optimization variable and the data vector `x` ranges over the box
-`[0, 1]^m`. After each iteration it computes the worst-case fixed-point residual
-`||s^{k+1} - s^k||_inf` over all such `x`.
+where $z \in \mathbf{R}^n$ is the optimization variable, $P$ is a fixed symmetric positive
+semidefinite matrix, and the parameter $q$ ranges over the box $[-1, 1]^n$. Starting from
+$z^0 = 0$, each iteration takes a gradient step with step size $\eta$ and projects onto the
+nonnegative orthant,
+
+$$
+z^{k+1} = \Pi_{\mathbf{R}^n_+}\left(z^k - \eta(Pz^k + q)\right),
+$$
+
+and FOMTools computes the worst-case fixed-point residual $`\|z^K - z^{K-1}\|_\infty`$ over all
+$q \in [-1, 1]^n$.
 
 ```python3
 import numpy as np
 import fomtools as ft
 
-# Problem data
-m, n, lambd, K = 10, 15, 0.1, 10
-D = np.random.normal(size=(m, n))
-eta = 1 / np.linalg.norm(D, 2) ** 2
-
-VP = ft.Verifier()  # MIP verification with HiGHS; use solver="gurobi" for Gurobi
+K, n, eta = 5, 3, 0.01
+A = np.random.default_rng(0).normal(size=(n, n))
+P = A @ A.T
 
-# Parameter set and initial iterate
-x = VP.add_param(m, lb=0, ub=1)
-s = [VP.add_iterate(n, lb=0, ub=0)]
-w, beta = s[0], 1.0
+vp = ft.Verifier()                      # HiGHS by default; solver="gurobi" for Gurobi
+q = vp.parameter(n, lb=-1, ub=1)        # q in [-1, 1]^n
+z = vp.iterate(n, lb=0, ub=0)           # z^0 = 0
 
-results = []
 for k in range(K):
-    # FISTA iteration
-    s.append(VP.step.soft_threshold(w - eta * D.T @ (D @ w - x), lambd=lambd * eta))
-    beta_old, beta = beta, 0.5 * (1 + np.sqrt(1 + 4 * beta**2))
-    w = s[k + 1] + (beta_old - 1) / beta * (s[k + 1] - s[k])
-
-    # Worst-case residual after k + 1 iterations
-    VP.set_objective_norm(s[k + 1] - s[k], np.inf)
-    results.append(VP.solve())
+    z_prev, z = z, vp.relu(z - eta * (P @ z + q))
+
+vp.maximize(ft.norm(z - z_prev, np.inf))
+print("worst-case residual:", vp.solve())
+print("worst-case q:", q.value)
 ```
 
 Steps can also be written with proximal operators and projections, e.g.,
-`VP.prox(NormL1(lambd), v, eta)` or `VP.project(Box(l, u), v)`. See the
-[documentation](https://github.com/stellatogrp/fomtools/tree/main/docs) for the full list of proxable functions and sets.
+`vp.prox(NormL1(lambd), v, eta)` or `vp.project(Box(l, u), v)`. See the
+[documentation](https://stellatogrp.github.io/fomtools/) for the full list of proxable functions and sets.
 
 ## Beyond worst-case verification
 
 **Simulation.** Write the same loop with `ft.Verifier(method="simulator")`, and give
-parameters sample arrays of shape `(N, d)` (or let them be sampled from their bounds). The
+parameters sample arrays of shape `(N, d)`, as in `vp.parameter(d, samples=X)`. The
 simulator runs all samples as batched operations, on a GPU through CuPy when one is
 available. It then reports summary statistics and a KL-inverse bound on the probability that
 the residual exceeds a tolerance `epsilon`:
 
 ```python3
-VP.solve(epsilon=1e-3)
-VP["quantiles"][0.95], VP["risk_bound"], VP["throughput"]
+vp.solve(epsilon=1e-3)
+vp["quantiles"][0.95], vp["risk_bound"], vp["throughput"]
 ```
 
-**Code generation.** Pass the recorded iterates, unchanged, to `codegen`. It produces a
-specialized solver together with a Python wrapper:
+**Code generation.** Keep the iterates in a list and pass them, unchanged, to `codegen`.
+It produces a specialized solver together with a Python wrapper:
 
 ```python3
-result = VP.codegen("out/fista", iterates=s, code_optimization=True)
+z = [vp.iterate(n, lb=0, ub=0)]
+for k in range(K):
+    z.append(vp.relu(z[-1] - eta * (P @ z[-1] + q)))
+
+result = vp.codegen("out/pgd", iterates=z, code_optimization=True)
 ```
 
 Targets include embedded C, multicore CPUs (OpenMP), and GPUs (CUDA). The package works with
@@ -174,11 +200,26 @@ Optional extras:
 | `codegen`  | LLM coding-agent backends for code generation      |
 | `cvxpygen` | CVXPYgen integration                               |
 | `nn`       | Neural-network verification (PyTorch, JAX, Flax)   |
+| `all`      | All of the above (GPU packages skipped on macOS)   |
 | `dev`      | Development tools                                  |
 | `docs`     | Documentation build dependencies                   |
 
 For example, `pip install "fomtools[gurobi,codegen]"`, or
-`pip install -e ".[gurobi,codegen]"` from source.
+`pip install -e ".[gurobi,codegen]"` from source. Use `pip install "fomtools[all]"`
+to install every optional feature.
+
+### Agent skill
+
+FOMTools ships an [Agent Skill](https://agentskills.io/) in
+[`skills/fomtools`](skills/fomtools/SKILL.md) that teaches coding agents (Claude
+Code, Codex, Cursor, and others) the FOMTools API. Install it with the
+[`skills` CLI](https://github.com/vercel-labs/skills) (requires Node.js):
+
+```bash
+npx skills add stellatogrp/fomtools -g
+```
+
+See [Get started](https://stellatogrp.github.io/fomtools/get_started/) for details.
 
 FOMTools is not a solver. It relies on mathematical programming solvers such as
 [HiGHS](https://highs.dev) (the default) and [Gurobi](https://www.gurobi.com) to solve
@@ -186,9 +227,14 @@ the verification problems it builds.
 
 ## Examples
 
-The [tutorials](https://github.com/stellatogrp/fomtools/tree/main/docs/tutorials) cover sparse coding (Lasso), nonnegative least squares,
-network optimization, optimal control, and portfolio rebalancing. Code to reproduce the
-experiments in our [paper](https://arxiv.org/abs/2610.26743) is available at
+The [tutorials](https://stellatogrp.github.io/fomtools/tutorials/) cover sparse coding (Lasso), nonnegative least squares,
+network optimization, optimal control, and portfolio rebalancing.
+
+## Benchmarks
+
+The benchmarks and the code to reproduce the experiments in our
+[paper](https://arxiv.org/abs/2610.26743) (verification, simulation, and code generation on
+CPU and GPU) are in a separate repository,
 [stellatogrp/fomtools_experiments](https://github.com/stellatogrp/fomtools_experiments).
 
 ## Contributing
@@ -215,3 +261,6 @@ If you use FOMTools for published work, we encourage you to cite our
   year    = {2026},
 }
 ```
+
+The mixed-integer verification method is described in
+[Exact Verification of First-Order Methods via Mixed-Integer Linear Programming](https://arxiv.org/abs/2412.11330).

{fomtools-0.0.2 → fomtools-0.0.4}/README.md

@@ -1,8 +1,20 @@
-FOMTools
-========
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/stellatogrp/fomtools/main/docs/assets/logo/logo-dark.svg">
+    <img alt="FOMTools" src="https://raw.githubusercontent.com/stellatogrp/fomtools/main/docs/assets/logo/logo.svg" height="72">
+  </picture>
+</h1>
+
+[![PyPI](https://img.shields.io/pypi/v/fomtools.svg)](https://pypi.org/project/fomtools/)
+[![Docs](https://img.shields.io/badge/docs-stellatogrp.github.io%2Ffomtools-blue.svg)](https://stellatogrp.github.io/fomtools/)
 
 **Development, analysis, and code generation for first-order methods.**
 
+[Documentation](https://stellatogrp.github.io/fomtools/) |
+[PyPI](https://pypi.org/project/fomtools/) |
+[Paper](https://arxiv.org/abs/2610.26743) |
+[Benchmarks](https://github.com/stellatogrp/fomtools_experiments)
+
 FOMTools is an open-source Python package for developing, analyzing, and deploying
 first-order methods for parametric linear and convex quadratic optimization. You write the
 iteration in Python, with syntax close to its mathematical description, and FOMTools records
@@ -21,65 +33,73 @@ you can:
 
 ## Example
 
-The following code verifies FISTA on a family of Lasso problems
-```
-minimize        0.5 ||D s - x||_2^2 + lambda ||s||_1
-```
+The following code verifies projected gradient descent on the parametric quadratic program
+
+$$
+\begin{array}{ll}
+\text{minimize} & (1/2) z^T P z + q^T z \\
+\text{subject to} & z \geq 0,
+\end{array}
+$$
 
-where `s in R^n` is the optimization variable and the data vector `x` ranges over the box
-`[0, 1]^m`. After each iteration it computes the worst-case fixed-point residual
-`||s^{k+1} - s^k||_inf` over all such `x`.
+where $z \in \mathbf{R}^n$ is the optimization variable, $P$ is a fixed symmetric positive
+semidefinite matrix, and the parameter $q$ ranges over the box $[-1, 1]^n$. Starting from
+$z^0 = 0$, each iteration takes a gradient step with step size $\eta$ and projects onto the
+nonnegative orthant,
+
+$$
+z^{k+1} = \Pi_{\mathbf{R}^n_+}\left(z^k - \eta(Pz^k + q)\right),
+$$
+
+and FOMTools computes the worst-case fixed-point residual $`\|z^K - z^{K-1}\|_\infty`$ over all
+$q \in [-1, 1]^n$.
 
 ```python3
 import numpy as np
 import fomtools as ft
 
-# Problem data
-m, n, lambd, K = 10, 15, 0.1, 10
-D = np.random.normal(size=(m, n))
-eta = 1 / np.linalg.norm(D, 2) ** 2
-
-VP = ft.Verifier()  # MIP verification with HiGHS; use solver="gurobi" for Gurobi
+K, n, eta = 5, 3, 0.01
+A = np.random.default_rng(0).normal(size=(n, n))
+P = A @ A.T
 
-# Parameter set and initial iterate
-x = VP.add_param(m, lb=0, ub=1)
-s = [VP.add_iterate(n, lb=0, ub=0)]
-w, beta = s[0], 1.0
+vp = ft.Verifier()                      # HiGHS by default; solver="gurobi" for Gurobi
+q = vp.parameter(n, lb=-1, ub=1)        # q in [-1, 1]^n
+z = vp.iterate(n, lb=0, ub=0)           # z^0 = 0
 
-results = []
 for k in range(K):
-    # FISTA iteration
-    s.append(VP.step.soft_threshold(w - eta * D.T @ (D @ w - x), lambd=lambd * eta))
-    beta_old, beta = beta, 0.5 * (1 + np.sqrt(1 + 4 * beta**2))
-    w = s[k + 1] + (beta_old - 1) / beta * (s[k + 1] - s[k])
-
-    # Worst-case residual after k + 1 iterations
-    VP.set_objective_norm(s[k + 1] - s[k], np.inf)
-    results.append(VP.solve())
+    z_prev, z = z, vp.relu(z - eta * (P @ z + q))
+
+vp.maximize(ft.norm(z - z_prev, np.inf))
+print("worst-case residual:", vp.solve())
+print("worst-case q:", q.value)
 ```
 
 Steps can also be written with proximal operators and projections, e.g.,
-`VP.prox(NormL1(lambd), v, eta)` or `VP.project(Box(l, u), v)`. See the
-[documentation](https://github.com/stellatogrp/fomtools/tree/main/docs) for the full list of proxable functions and sets.
+`vp.prox(NormL1(lambd), v, eta)` or `vp.project(Box(l, u), v)`. See the
+[documentation](https://stellatogrp.github.io/fomtools/) for the full list of proxable functions and sets.
 
 ## Beyond worst-case verification
 
 **Simulation.** Write the same loop with `ft.Verifier(method="simulator")`, and give
-parameters sample arrays of shape `(N, d)` (or let them be sampled from their bounds). The
+parameters sample arrays of shape `(N, d)`, as in `vp.parameter(d, samples=X)`. The
 simulator runs all samples as batched operations, on a GPU through CuPy when one is
 available. It then reports summary statistics and a KL-inverse bound on the probability that
 the residual exceeds a tolerance `epsilon`:
 
 ```python3
-VP.solve(epsilon=1e-3)
-VP["quantiles"][0.95], VP["risk_bound"], VP["throughput"]
+vp.solve(epsilon=1e-3)
+vp["quantiles"][0.95], vp["risk_bound"], vp["throughput"]
 ```
 
-**Code generation.** Pass the recorded iterates, unchanged, to `codegen`. It produces a
-specialized solver together with a Python wrapper:
+**Code generation.** Keep the iterates in a list and pass them, unchanged, to `codegen`.
+It produces a specialized solver together with a Python wrapper:
 
 ```python3
-result = VP.codegen("out/fista", iterates=s, code_optimization=True)
+z = [vp.iterate(n, lb=0, ub=0)]
+for k in range(K):
+    z.append(vp.relu(z[-1] - eta * (P @ z[-1] + q)))
+
+result = vp.codegen("out/pgd", iterates=z, code_optimization=True)
 ```
 
 Targets include embedded C, multicore CPUs (OpenMP), and GPUs (CUDA). The package works with
@@ -120,11 +140,26 @@ Optional extras:
 | `codegen`  | LLM coding-agent backends for code generation      |
 | `cvxpygen` | CVXPYgen integration                               |
 | `nn`       | Neural-network verification (PyTorch, JAX, Flax)   |
+| `all`      | All of the above (GPU packages skipped on macOS)   |
 | `dev`      | Development tools                                  |
 | `docs`     | Documentation build dependencies                   |
 
 For example, `pip install "fomtools[gurobi,codegen]"`, or
-`pip install -e ".[gurobi,codegen]"` from source.
+`pip install -e ".[gurobi,codegen]"` from source. Use `pip install "fomtools[all]"`
+to install every optional feature.
+
+### Agent skill
+
+FOMTools ships an [Agent Skill](https://agentskills.io/) in
+[`skills/fomtools`](skills/fomtools/SKILL.md) that teaches coding agents (Claude
+Code, Codex, Cursor, and others) the FOMTools API. Install it with the
+[`skills` CLI](https://github.com/vercel-labs/skills) (requires Node.js):
+
+```bash
+npx skills add stellatogrp/fomtools -g
+```
+
+See [Get started](https://stellatogrp.github.io/fomtools/get_started/) for details.
 
 FOMTools is not a solver. It relies on mathematical programming solvers such as
 [HiGHS](https://highs.dev) (the default) and [Gurobi](https://www.gurobi.com) to solve
@@ -132,9 +167,14 @@ the verification problems it builds.
 
 ## Examples
 
-The [tutorials](https://github.com/stellatogrp/fomtools/tree/main/docs/tutorials) cover sparse coding (Lasso), nonnegative least squares,
-network optimization, optimal control, and portfolio rebalancing. Code to reproduce the
-experiments in our [paper](https://arxiv.org/abs/2610.26743) is available at
+The [tutorials](https://stellatogrp.github.io/fomtools/tutorials/) cover sparse coding (Lasso), nonnegative least squares,
+network optimization, optimal control, and portfolio rebalancing.
+
+## Benchmarks
+
+The benchmarks and the code to reproduce the experiments in our
+[paper](https://arxiv.org/abs/2610.26743) (verification, simulation, and code generation on
+CPU and GPU) are in a separate repository,
 [stellatogrp/fomtools_experiments](https://github.com/stellatogrp/fomtools_experiments).
 
 ## Contributing
@@ -161,3 +201,6 @@ If you use FOMTools for published work, we encourage you to cite our
   year    = {2026},
 }
 ```
+
+The mixed-integer verification method is described in
+[Exact Verification of First-Order Methods via Mixed-Integer Linear Programming](https://arxiv.org/abs/2412.11330).

fomtools-0.0.4/docs/api/canonicalizer.md

@@ -0,0 +1,38 @@
+# Canonicalizers
+
+Canonicalizers translate a verification problem into a solver-ready formulation
+(MIP or SDP), including optimization-based bound tightening (OBBT).
+
+::: fomtools.canonicalizers.Canonicalizer
+
+## MIP canonicalizer
+
+::: fomtools.canonicalizers.mip
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      heading_level: 3
+
+## OBBT handler
+
+::: fomtools.canonicalizers.obbt_handler
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      heading_level: 3
+
+## Simulator
+
+::: fomtools.canonicalizers.simulator
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      heading_level: 3
+
+## SDP canonicalizer
+
+::: fomtools.canonicalizers.sdp
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      heading_level: 3

{fomtools-0.0.2 → fomtools-0.0.4}/docs/api/codegen.md

@@ -5,6 +5,10 @@ methods, plus a tiny Python wrapper. An LLM coding agent translates each step of
 the algorithm into the target language and iterates against a Python reference
 oracle until the generated code is numerically verified.
 
+The [code generation guide](../user_guide/codegen.md) is the narrative reference for
+the symbols below, and the [tutorials](../tutorials/codegen.md) work through five
+complete examples.
+
 ::: fomtools.codegen.generate_code
 
 ::: fomtools.codegen.CodegenConfig

fomtools-0.0.4/docs/api/constraint.md

@@ -0,0 +1,17 @@
+# Constraints
+
+Constraints are equalities and inequalities over linear expressions, used to
+encode assumptions on the problem data and the initial conditions.
+
+::: fomtools.constraint.Constraint
+::: fomtools.constraint.EqualityConstraint
+::: fomtools.constraint.InequalityConstraint
+
+## Objective atoms
+
+`ft.norm` and `ft.sum_squares` build the objective passed to
+[`Verifier.maximize`](verifier.md#fomtools.Verifier.maximize), for example
+`vp.maximize(ft.norm(z - z_prev, np.inf))`.
+
+::: fomtools.constraint.norm
+::: fomtools.constraint.sum_squares