# Catastrophe Theory — 3D Print Models

## Project Overview

This project generates 3D-printable STL models of surfaces from **catastrophe theory** — a branch of mathematics studying how small changes in parameters can cause sudden, discontinuous changes in a system's equilibrium state.

Two surfaces are being produced:

| Model | Catastrophe Type | Codimension | Potential |
|-------|-----------------|-------------|-----------|
| Cusp | Cusp catastrophe | 2 | x⁴ + ax² + bx |
| Butterfly | Butterfly catastrophe | 4 | x⁶ + ax⁴ + bx³ + cx² + dx |

---

## The Mathematics

Each surface is the **equilibrium manifold** — the set of all points where the system is in equilibrium. For a potential V(x), equilibria satisfy:

> dV/dx = 0

The 3D surface is swept over the control parameter space (a, b), with x (the state variable) as the third axis. Where the surface folds back on itself is the **bifurcation set** — the region where the system can catastrophically jump between states.

### Butterfly Catastrophe

- **Potential:** V(x) = x⁶ + ax⁴ + bx³ (with c=0, d=0 fixed)
- **Equilibrium condition:** dV/dx = 6x⁵ + 4ax³ + 3bx² = 0
- **Control space:** (a, b) swept over a 2D grid
- **State space:** up to 5 real roots x at any given (a, b)
- **Characteristic feature:** nested "butterfly wing" fold structure — more complex than the cusp, with additional inner fold lobes

---

## Files

- `butterfly_catastrophe.py` — generates the butterfly surface STL
- `butterfly_catastrophe.stl` — ready-to-slice output (ASCII STL, ~7,300 triangles)
- `CLAUDE.md` — this file

> A cusp catastrophe script also exists and was the starting point for this project.

---

## How the Generator Works

1. **Root finding** — at each (a, b) grid point, all real roots of dV/dx = 0 are found using Newton-Raphson with dense initial seeding across the x range
2. **Branch tracking** — roots are sorted and matched by branch index across adjacent grid cells
3. **Mesh construction** — adjacent grid quads on the same branch are triangulated into a surface mesh
4. **Base slab** — a flat rectangular base is added so the model is self-supporting on a print bed
5. **ASCII STL output** — written as ASCII (not binary) for maximum compatibility with slicers and viewers

---

## Running the Generator

```bash
python butterfly_catastrophe.py
```

Output: `butterfly_catastrophe.stl`

### Tuning Parameters (inside the script)

| Parameter | Default | Effect |
|-----------|---------|--------|
| `grid` | `40` | Resolution of the (a,b) control grid — increase for finer mesh |
| `a_vals` range | `(-2.5, 1.2)` | Range of control parameter a |
| `b_vals` range | `(-2.5, 2.5)` | Range of control parameter b |
| `x_range` | `2.2` | Search window for equilibrium roots |

For a final high-quality print, increase `grid` to `80`–`100`. The default of `40` is optimised for STL viewer compatibility.

---

## 3D Printing Tips

- **Orientation:** flat base down — no supports needed
- **Layer height:** 0.15–0.20 mm for good surface detail
- **Perimeters:** ≥ 2, as the fold regions are thin
- **Scale:** ~120 mm along the a-axis makes a good desk model
- **Material:** PLA or PETG both work well; the overhangs are gentle

---

## Dependencies

```
numpy
```

No other dependencies — STL writing uses Python's built-in `struct` module (binary) or plain file I/O (ASCII).