feat: Adding SpaceClaim/PyMAPDL Tesseract example and docs

docs/content/examples/ansys_gallery.md

@@ -0,0 +1,32 @@
+# Ansys Integration
+
+```{toctree}
+:name: ansys-gallery
+:caption: Ansys Gallery
+:maxdepth: 2
+:hidden:
+:glob:
+ansys_integration/spaceclaim_tess.md
+ansys_integration/pymapdl_tess.md
+```
+
+This is a gallery of Tesseract examples integrating with Ansys products in different ways, demonstrating the versatility that you can then use to build your own Tesseracts.
+
+You can find these Ansys Tesseracts in the `examples/ansys_integration` directory of the [code repository](https://github.com/pasteurlabs/tesseract-core).
+
+
+::::{grid} 2
+   :gutter: 2
+
+   :::{grid-item-card} Spaceclaim
+      :link: ansys_integration/spaceclaim_tess.html
+
+      A Spaceclaim Tesseract.
+   :::
+   :::{grid-item-card} PyMAPDL
+      :link: ansys_integration/pymapdl_tess.html
+
+      Draft PyMAPDL md.
+   :::
+
+::::

docs/content/examples/ansys_integration/pymapdl_tess.md

@@ -0,0 +1,106 @@
+# ANSYS MAPDL SIMP Compliance
+
+## Context
+
+Example that wraps ANSYS MAPDL as a differentiable Tesseract for SIMP (Solid Isotropic Material with Penalization) topology optimization.
+The Tesseract computes structural compliance using finite element analysis and provides analytical sensitivities for gradient-based optimization.
+
+## Prerequisites
+
+This example requires a running ANSYS MAPDL server accessible via gRPC:
+
+```bash
+# Linux
+/usr/ansys_inc/v241/ansys/bin/ansys241 -grpc -port 50052
+
+# Windows
+"C:/Program Files/ANSYS Inc/v241/ansys/bin/winx64/ANSYS241.exe" -grpc -port 50052
+```
+
+## Example Tesseract (examples/ansys_integration/pymapdl_tess)
+
+### Core functionality --- schemas and `apply` function
+
+The Tesseract accepts a hexahedral mesh, density field, and boundary conditions as inputs. The density field `rho` is marked as `Differentiable` to enable gradient computation:
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: HexMesh
+:language: python
+```
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: InputSchema
+:language: python
+```
+
+The outputs include compliance (the optimization objective), element-wise strain energy, and sensitivity values:
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: OutputSchema
+:language: python
+```
+
+The `apply` function connects to MAPDL, creates the mesh, assigns SIMP-interpolated materials based on density, applies boundary conditions, solves the static analysis, and extracts results:
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: apply
+:language: python
+```
+
+### SIMP material interpolation
+
+The solver creates a unique material for each element with properties scaled by the density field using the SIMP formula:
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: SIMPElasticity._define_simp_materials
+:language: python
+```
+
+This interpolation scheme penalizes intermediate densities, encouraging binary (solid/void) designs in topology optimization.
+
+### Vector-Jacobian product endpoint
+
+For compliance minimization, the adjoint solution equals the negative displacement field. This allows computing sensitivities analytically without an explicit adjoint solve:
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: SIMPElasticity._calculate_sensitivity
+:language: python
+```
+
+The cached sensitivity is loaded during the VJP computation and multiplied by the upstream gradient:
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: vector_jacobian_product
+:language: python
+```
+
+### Abstract evaluation
+
+The `abstract_eval` function computes output shapes based on input shapes without running the ANSYS solver, enabling static analysis and memory pre-allocation:
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/tesseract_api.py
+:pyobject: abstract_eval
+:language: python
+```
+
+## Demo script
+
+The demo script (`examples/ansys_integration/pymapdl_tess/demo.py`) shows a complete workflow for a cantilever beam problem:
+
+The demo requires you set environment variables pointing to the MAPDL server:
+
+```bash
+export MAPDL_HOST=192.168.1.100
+export MAPDL_PORT=50052
+```
+
+```{literalinclude} ../../../../examples/ansys_integration/pymapdl_tess/demo.py
+:pyobject: main
+:language: python
+```
+
+The script verifies correctness by checking that total strain energy equals half the compliance, which holds for linear elastic problems.
+
+![Cantilever beam sensitivity analysis](pymapdl_simp_compliance.png)
+
+*Figure: Element-wise sensitivity gradient (∂compliance/∂ρ) for the cantilever beam test case.*

docs/content/examples/ansys_integration/spaceclaim_tess.md

@@ -0,0 +1,158 @@
+# SpaceClaim Tesseract
+
+## Context
+Complex CAD models are often imported from parametric CAD software and require pre-processing by e.g. extracting a fluid volume for simulatuion, or naming domain faces such that appropriate boundary conditions can be applied.
+
+SpaceClaim is commonly used to perform these pre-processing actions, and additionally can be used to generate geometry. In this example we demonstrate the use of SpaceClaim through SpaceClaim scripts (`.scscript`) within a Tesseract.
+
+## What is different about this Tesseract?
+
+Tesseracts are most commonly used in their self-contained built form; however SpaceClaim is not containerization friendly. Instead we use the Tesseract [`tesseract-core[runtime]`](https://docs.pasteurlabs.ai/projects/tesseract-core/latest/content/api/tesseract-runtime-cli.html to  [`serve`](https://docs.pasteurlabs.ai/projects/tesseract-core/latest/content/api/tesseract-runtime-cli.html#tesseract-runtime-serve) the SpaceClaim (or any other proprietary software that cannot be containerized). This will allow us to setup a Tesseract on an e.g. Windows machine with Ansys installed and easily expose its functionality over as an HTTP API.
+
+## Setting up a generic Tesseract Runtime Server
+
+When creating a Tesseract you should have a Tesseract directory with three files like so:
+
+```bash
+$ tree examples/helloworld
+examples/helloworld
+├── tesseract_api.py
+├── tesseract_config.yaml
+└── tesseract_requirements.txt
+```
+
+If this isn't familiar then you can learn about Tesseract basics [here](../../introduction/get-started.md). Normally this directory would be passed to `tesseract build`, but instead we can install and make use of the `tesseract-runtime` CLI application which will provide us an interface with the Tesseract:
+
+```bash
+pip install tesseract-core[runtime]
+```
+
+Now with an a open port of your choice, and from within the Tesseract directory, we can execute:
+
+```bash
+tesseract-runtime serve --port port_number
+```
+
+The result is a Tesseract Runtime Server.
+
+```bash
+$ tesseract-runtime serve --port 443
+INFO:     Started server process [14888]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:443 (Press CTRL+C to quit)
+```
+
+## Example SpaceClaim Tesseract (`examples/ansys_integration/spaceclaim_tess`)
+
+For this specific example we are looking at the SpaceX Grid Fin geometry shown in this [demo](https://si-tesseract.discourse.group/c/showcase/11). This specific example requires `trimesh` as a dependency. For an easy setup navigate to  `examples/ansys_integration/spaceclaim_tess` and install the requirements in your python environment of choice
+
+```bash
+pip install -r tesseract_requirements.txt
+```
+
+This Tesseract accepts goemetry parameters to create `N` Grid Fin geometries simulatanously. The API was setup this way to hide the startup latency of SpaceClaim when requesting a large number of geometries. 
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: InputSchema
+```
+
+The output of the Tesseract is a list of `TriangularMesh` objects representing the N Grid Fin meshes.
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: OutputSchema
+```
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: TriangularMesh
+```
+
+The explanation and intuation behind the inputs is explained further in the [demo](https://si-tesseract.discourse.group/c/showcase/11).
+
+Now that we understand the inputs and outputs of the Tesseract we can use it. From within the Tesseract directory setup the runtime server with a port of your choice:
+
+```bash
+tesseract-runtime serve --port 443
+```
+
+If we want to manually test the Tesseract it should now be possible to make a HTTP request for two Grid Fin geometries either from the same computer, as shown here, or a seperate one. __Make sure to change the URL IP and port to reflect your setup, along with the SpaceClaim.exe path__:
+
+```bash
+#Bash
+curl -d '{
+  "inputs": {
+    "differentiable_parameters": [
+    [200, 600, 0, 3.14, 0.39, 3.53, 0.79, 3.93, 1.18, 4.32, 1.57, 4.71, 1.96, 5.11, 2.36, 5.50, 2.75, 5.89],
+    [400, 400, 0, 3.14, 0.39, 3.53, 0.79, 3.93, 1.18, 4.32, 1.57, 4.71, 1.96, 5.11, 2.36, 5.50, 2.75, 5.89]
+    ],
+    "non_differentiable_parameters": [
+      [800, 100],
+      [800, 100]
+    ],
+    "string_parameters": [
+      "F:\\Ansys installations\\ANSYS Inc\\v241\\scdm\\SpaceClaim.exe",
+      "geometry_generation.scscript"
+    ]
+  }
+}' \
+-H "Content-Type: application/json" \
+http://127.0.0.1:443/apply
+```
+
+Or:
+
+```powershell
+# Windows PowerShell
+curl -Method POST `
+     -Uri "http://127.0.0.1:443/apply" `
+     -ContentType "application/json" `
+     -Body '{"inputs":{"differentiable_parameters":[[200,600,0,3.14,0.39,3.53,0.79,3.93,1.18,4.32,1.57,4.71,1.96,5.11,2.36,5.50,2.75,5.89],[400,400,0,3.14,0.39,3.53,0.79,3.93,1.18,4.32,1.57,4.71,1.96,5.11,2.36,5.50,2.75,5.89]],"non_differentiable_parameters":[[800,100],[800,100]],"string_parameters":["F:\\Ansys installations\\ANSYS Inc\\v241\\scdm\\SpaceClaim.exe","geometry_generation.scscript"]}}'
+```
+
+After about (~15 seconds) the mesh output is returned and displayed in text form in your terminal. The point coordinates and cells correspond to a Grid Fin like below (shown with randomised cross beam locations).
+
+![Example Grid Fin geometry](../../../img/grid_fin_stl.png)
+
+*Figure: Grid Fin geometry shown with randomised beam locations.*
+
+The `apply` function that we are invoking with the above command builds each of the Grid Fin geometries and extracts the mesh data from the `trimesh` objects.
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: apply
+```
+
+To build the geometries we first prepare the SpaceClaim `.scscript` by replacing placeholder values with the user inputs via string substituation. SpaceClaim is then run, outputting `.stl` meshes that are read with `trimesh`.
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: build_geometries
+```
+
+The `.scscript` preperation is unique to this Grid Fin example, with the user input values being processed into dictionaries that are then used within the string substituation. For a different geometry one would have to create their own dictionaries with all the neccessary inputs required by their new `.scscript`.
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: _prep_scscript
+```
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: _find_and_replace_keys_in_archive
+```
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: _safereplace
+```
+
+Once the `.scscript` is ready the final step is to run SpaceClaim. Here it is easy to see how this proecss could be extended to any software that cannot be containorized. For example Ansys Fluent could also be wrapped in a Runtime Tesseract, with the Adjoint solver used to produced gradient information allowing the Tesseract to be differentiable.
+
+```{literalinclude} ../../../../examples/ansys_integration/spaceclaim_tess/tesseract_api.py
+:language: python
+:pyobject: run_spaceclaim
+```
+
+See this Runtime Tesseract in action in our Grid Fin optimisation [demo](https://si-tesseract.discourse.group/c/showcase/11).

docs/index.md

@@ -101,6 +101,7 @@ content/using-tesseracts/advanced.md
 
 content/examples/example_gallery.md
 content/demo/demo.md
+content/examples/ansys_gallery.md
 Tesseract Community Showcase <https://si-tesseract.discourse.group/c/showcase/11>
 ```