doc: add jax-fem example

docs/index.md

@@ -18,4 +18,5 @@ api
 :hidden:
 
 examples/vectoradd_jax/README.md
+examples/jax_fem/README.md
 ```

examples/jax_fem/README.md

@@ -0,0 +1,93 @@
+# 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 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 ~/Documents/tesseract-streamlit/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
+cd ~/Documents/tesseract-streamlit/examples/jax_fem
+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,38 @@
+#!/usr/bin/env bash
+
+# the parent dir of this script:
+scriptdir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+workdir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# a temporary dir to store the downloads for the example:
+tmpdir=$(mktemp -d)
+
+if [ "$(basename $workdir)" != "tesseract-streamlit" ]; then
+    echo "Path mismatch: please contact the developers."
+    echo $workdir
+    exit 1
+fi
+
+# 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