doc: clean examples and add jax-fem

README.md

@@ -94,14 +94,14 @@ This setup gives you control over what to display and how to explain it, directl
 See the example README for a basic example walk-through, or simply run the following script to see the end result!
 
 ```bash
-bash examples/run.sh
+bash examples/vectoradd_jax/run.sh
 ```
 
 This will open a browser window with the Streamlit UI where users can input values and visualise the response.
 
-| ![](examples/screenshots/header-vec-a.png) | ![](examples/screenshots/outputs.png) |
+| ![](examples/vectoradd_jax/screenshots/header-vec-a.png) | ![](examples/vectoradd_jax/screenshots/outputs.png) |
 | --------------------------------- | ---------------------------- |
-| ![](examples/screenshots/vec-b.png)        | ![](examples/screenshots/plot.png)    |
+| ![](examples/vectoradd_jax/screenshots/vec-b.png)        | ![](examples/vectoradd_jax/screenshots/plot.png)    |
 
 ## ⚠️ Current Limitations
 

docs/conf.py

@@ -7,9 +7,13 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import re
+import shutil
+from pathlib import Path
 
 from tesseract_streamlit import __version__
 
+PARENT_DIR = Path(__file__).parent.resolve()
+
 project = "tesseract-streamlit"
 copyright = "2024, The tesseract-streamlit Team @ Pasteur Labs"
 author = "The tesseract-streamlit Team @ Pasteur Labs"
@@ -55,3 +59,10 @@
 
 html_theme = "furo"
 html_static_path = ["static"]
+
+# Copy example notebooks to docs/examples folder on every build
+for example_dir in Path("../examples").glob("*/"):
+    # Copy the example directory to the docs folder
+    shutil.copytree(
+        example_dir, PARENT_DIR / "examples" / example_dir.name, dirs_exist_ok=True
+    )

docs/examples/.gitignore

@@ -0,0 +1,2 @@
+**/*
+!.gitignore

docs/index.md

@@ -11,3 +11,11 @@
 self
 api
 ```
+
+```{toctree}
+:caption: Examples
+:maxdepth: 2
+:hidden:
+
+examples/vectoradd_jax/README.md
+```

examples/jax_fem/README.md

@@ -0,0 +1,92 @@
+# Using JAX with finite element methods (JAX-FEM)
+
+In this example, you'll generate a Streamlit app from a Tesseract which models a structure and computes its compliance with finite element methods.
+This is based on the excellent example for [shape optimisation in Tesseract JAX](https://docs.pasteurlabs.ai/projects/tesseract-jax/latest/examples/fem-shapeopt/demo.html) using JAX-FEM.
+This, of course, uses `tesseract-streamlit` to automatically generate an interactive web app, this time with an interactive PyVista plot of the structure! ⚡
+
+---
+
+## 📥 Step 1: Download the Example Code
+
+We've written a custom Tesseract for this example, mashing up the Design Tesseract and FEM Tesseract from the original Tesseract JAX tutorial, so clone `tesseract-streamlit` like so:
+
+```shell
+git clone --depth 1 https://github.com/pasteurlabs/tesseract-streamlit.git ~/Downloads/tesseract-streamlit
+```
+
+---
+
+## 📦 Step 2: Install Requirements
+
+Enter the example directory, and install the required packages:
+
+```bash
+cd ~/Documents/tesseract-streamlit/examples/jax_fem
+pip install -r requirements.txt
+```
+
+---
+
+## 🛠️ Step 3: Build and Serve the Tesseract
+
+Use the Tesseract CLI to build and serve `jax-fem`:
+
+```bash
+tesseract build ~/Downloads/tesseract-core/examples/jax_fem
+tesseract serve jax-fem
+```
+
+> [!NOTE]
+> Make note of the `PORT` and `PROJECT ID` printed to stdout — you'll need them shortly.
+
+---
+
+## ⚡ Step 4: Generate the Streamlit App
+
+With `tesseract-streamlit` installed, generate a ready-to-run Streamlit app:
+
+```bash
+tesseract-streamlit --user-code udf.py "http://localhost:<PORT>" app.py
+```
+
+`udf.py` can be found in under `tesseract-streamlit/examples/jax-fem/`.
+It contains a custom function that takes the Tesseract's inputs to render a PyVista plot of the design structure directly in the UI! ⚙️
+Check out the [source code to see how it works](https://github.com/pasteurlabs/tesseract-streamlit/examples/jax_fem/udf.py).
+
+---
+
+## ▶️ Step 5: Launch the App
+
+Run your new app with:
+
+```bash
+streamlit run app.py
+```
+
+This will launch a web interface for submitting inputs, running the Tesseract, and visualising the results.
+
+The form is populated from sensible defaults defined in `tesseract_api.py`.
+To easily provide the input parameters for the structure itself, you can upload the `bar_params.json` file in the current directory.
+
+---
+
+## 🖼️ Screenshots
+
+
+|     |     |
+| --- | --- |
+|     |     |
+
+---
+
+## 🧹 Step 6: Clean Up
+
+When you're done, you can stop the Tesseract server with:
+
+```bash
+tesseract teardown <PROJECT ID>
+```
+
+---
+
+🎉 That’s it — you've transformed a running Tesseract into a beautiful Streamlit web app with interactive plots, with minimal effort from the command line!

examples/jax_fem/bar_params.json

@@ -0,0 +1 @@
+[[[-30.0,-5.0,0.0],[-18.0,-5.0,0.0],[-6.0,-5.0,0.0],[6.000000953674316,-5.0,0.0],[18.0,-5.0,0.0],[30.0,-5.0,0.0]],[[-30.0,-2.5,0.0],[-18.0,-2.5,0.0],[-6.0,-2.5,0.0],[6.000000953674316,-2.5,0.0],[18.0,-2.5,0.0],[30.0,-2.5,0.0]],[[-30.0,0.0,0.0],[-18.0,0.0,0.0],[-6.0,0.0,0.0],[6.000000953674316,0.0,0.0],[18.0,0.0,0.0],[30.0,0.0,0.0]],[[-30.0,2.5,0.0],[-18.0,2.5,0.0],[-6.0,2.5,0.0],[6.000000953674316,2.5,0.0],[18.0,2.5,0.0],[30.0,2.5,0.0]]]

examples/jax_fem/requirements.txt

@@ -0,0 +1,2 @@
+pyvista==0.45.2
+numpy==2.2.5

examples/jax_fem/run.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# the parent dir of this script:
+scriptdir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# a temporary dir to store the downloads for the example:
+tmpdir=$(mktemp -d)
+workdir="${tmpdir}/tesseract-streamlit"
+
+# clone tesseract-core for its example subdirectory:
+git clone --depth 1 --branch jacan/examples [email protected]:pasteurlabs/tesseract-streamlit.git $workdir
+
+# install requirements for the udf.py module:
+pip install -r "${scriptdir}/requirements.txt"
+
+# build and serve the vectoradd_jax example tesseract:
+example=jax_fem
+tesseract build "${workdir}/examples/${example}"
+tessinfo=$(tesseract serve $example)
+tessid=$(echo $tessinfo | jq -r '.project_id')
+tessport=$(echo $tessinfo | jq -r '.containers[0].port')
+
+# automatically generate the Streamlit app from the served tesseract:
+tesseract-streamlit --user-code "${scriptdir}/udf.py" "http://localhost:${tessport}" "${tmpdir}/app.py"
+
+# launch the web-app:
+streamlit run "${tmpdir}/app.py"
+
+# stop serving the tesseract
+tesseract teardown $tessid
+
+# clean up the temporary directory:
+rm -rf $tmpdir
+
+exit 0