Metadata-Version: 2.4
Name: loadpath
Version: 0.1.3
Summary: Generative design for printed parts: topology optimization from keep-outs, preserved geometry and loads, verified in real units.
License-Expression: MIT
Project-URL: Homepage, https://github.com/connorwhite-online/loadpath
Project-URL: Documentation, https://github.com/connorwhite-online/loadpath/tree/main/docs
Project-URL: Repository, https://github.com/connorwhite-online/loadpath
Project-URL: Issues, https://github.com/connorwhite-online/loadpath/issues
Keywords: topology optimization,generative design,3d printing,fea,cad
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Manufacturing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: pyamg>=5.0
Requires-Dist: scikit-image>=0.22
Requires-Dist: trimesh>=4.0
Requires-Dist: manifold3d>=3.0
Requires-Dist: rtree>=1.0
Requires-Dist: numba>=0.59
Provides-Extra: render
Requires-Dist: matplotlib>=3.8; extra == "render"
Requires-Dist: shapely>=2.0; extra == "render"
Requires-Dist: fast_simplification>=0.1; extra == "render"
Provides-Extra: mcp
Requires-Dist: mcp>=2.0; extra == "mcp"
Requires-Dist: matplotlib>=3.8; extra == "mcp"
Requires-Dist: shapely>=2.0; extra == "mcp"
Provides-Extra: gpu
Requires-Dist: torch>=2.2; extra == "gpu"
Provides-Extra: flow
Requires-Dist: numba>=0.59; extra == "flow"
Provides-Extra: crosscheck
Requires-Dist: gmsh>=4.11; extra == "crosscheck"
Requires-Dist: pytetwild>=0.4; extra == "crosscheck"
Requires-Dist: pyvista>=0.44; extra == "crosscheck"
Provides-Extra: fast
Requires-Dist: pypardiso>=0.4; extra == "fast"
Provides-Extra: critic
Requires-Dist: anthropic; extra == "critic"
Requires-Dist: matplotlib>=3.8; extra == "critic"
Requires-Dist: shapely>=2.0; extra == "critic"
Provides-Extra: step
Requires-Dist: cadquery-ocp>=7.7; extra == "step"
Requires-Dist: embreex>=4.3; extra == "step"
Provides-Extra: 3mf
Requires-Dist: lib3mf>=2.4; extra == "3mf"
Requires-Dist: pillow>=9; extra == "3mf"
Dynamic: license-file

# loadpath

Generative design for 3D printed parts (and cast or milled ones), built to be
driven by coding agents. Tell your agent what a part has to carry and where it
mounts; loadpath grows the part with topology optimization, meshes it as a
watertight solid with the interfaces cut exactly, and checks that mesh with a
fresh finite element analysis. You get an STL, 3MF or STEP and a report: mass,
safety factor, deflection, thinnest member, printability, pass or fail.

<table>
<tr>
<td align="center" width="50%"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/grip-wrist-link-mjf-part.png" height="420"></td>
<td align="center" width="50%"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/stress/grip-wrist-link-mjf.png" height="420"></td>
</tr>
<tr>
<td align="center" width="50%"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/grip-wrist-yoke-part.png" width="380"></td>
<td align="center" width="50%"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/stress/grip-wrist-yoke.png" width="380"></td>
</tr>
<tr>
<td align="center" colspan="2"><sub>Two robot-arm parts as loadpath delivered them (left) and their stress from a fresh
analysis of that mesh (right), blue (none) to red (the part's 98th percentile), on the shape bent by the worst
load case. Top: a wrist link between two servos, MJF nylon, 40.2 g, safety factor 5.8. Bottom: a servo cradle
held only at its eight screw bosses, glass-filled SLS nylon, 17.3 g, safety factor 3.9. More in
<a href="#examples">Examples</a>.</sub></td>
</tr>
</table>

## Point your agent at it

```bash
pip install "loadpath[mcp]"
claude mcp add loadpath -- loadpath mcp   # any MCP client: {"command": "loadpath", "args": ["mcp"]}
```

Then ask in plain words:

> Design a PETG bracket for a 10 kg shelf. It screws to the wall with two
> M5 bolts 40 mm apart and the shelf sits 60 mm out. Safety factor 2,
> printed on an FDM printer.

The agent writes the study, checks it, runs it in the background and reads
the report back. Its guide is [loadpath/SKILL.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/loadpath/SKILL.md) (the
`loadpath_guide` tool returns it); the tools and the loop are in
[docs/agents.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/agents.md). The server runs locally and nothing
leaves the machine. Units are millimetres, newtons and megapascals. MIT
licensed.

## Where it fits

A designed part needs a shape, the loads it carries, and a way to make it.
The open tools each cover one of those:

- **Topology optimization codes** (top88, top3d, ToPy, FEniCS scripts) are
  research solvers. They stop at a density field on a grid: no printable
  part, and nothing checks the result.
- **Script CAD** (CadQuery, build123d, OpenSCAD) and AI CAD tools draw exact
  geometry but don't know the loads.
- **Commercial generative design** (Fusion, nTop) does the whole job, but
  it's built around a GUI, not an agent.

loadpath is the layer in between. Your CAD defines the interfaces; loadpath
takes those plus the loads, material and process, and returns a watertight
part checked by an analysis independent of the optimizer, with a JSON report
an agent can act on. Its STEP output goes back into CAD.

Where it is strongest:

- **The analysis behind the shape**: buckling, fatigue and creep,
  large-deflection compliant mechanisms, loads of unknown direction, thermal
  loads and print warp, all checked on the delivered mesh.
- **Implicit modelling**: field graphs, graded and conformal lattices (TPMS,
  strut, Voronoi), blends, and exact STEP of lattice parts.
- **Process awareness**: FDM, SLS, MJF, resin and powder-bed metal rules,
  plus casting and milling constraints.
- **Heat exchangers**: lattice-Boltzmann flow and conjugate heat transfer
  for gyroid cores and cold plates.

Not yet: draft-angle and machining-time checks for cast and milled parts,
or a ranked spread of outcomes across materials and processes by cost.
There is no GUI on purpose; it's a library.

## What it does

- **Topology optimization** on a voxel grid (SIMP with a density filter,
  Heaviside projection and a robust minimum-member formulation), searching
  for the lightest part that meets a safety factor and a deflection limit
  across several load cases. A stress-constrained mode (MMA) is available.
- **Verification of the delivered mesh**, not the optimizer's density
  field: the STL is analysed again, on a tetrahedral mesh when the
  `crosscheck` extra is installed and on a fine voxel grid otherwise. Keep-out
  intrusion and lost interface geometry are measured with exact booleans.
- **Process rules** for FDM (overhangs, bridges, layer bond), SLS and MJF
  (trapped powder, escape holes, warp-prone panels), resin (supports, peel,
  suction cups) and powder-bed metal (internal ceilings, powder
  clean-outs), plus milling and casting constraints.
- **Field modelling**: a part as a graph of implicit fields, so skins,
  lattices (TPMS and strut) and fillets can be graded by stress or by
  distance ([docs/fields.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/fields.md)).
- **Other analyses**: large deflection and buckling, compliant mechanisms,
  thermal loads, fatigue and creep estimates, lattice crush and impact,
  vibration, lattice-Boltzmann flow and conjugate heat for heat exchangers
  and cold plates, and layer-by-layer warp and residual stress
  ([docs/BUILDSIM.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/BUILDSIM.md)).
- **CAD in and out**: a STEP or STL part becomes a draft study with its
  bores and bolt patterns found ([docs/IMPORT.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/IMPORT.md)); results
  export as STL, 3MF, and STEP with exact planes and cylinders at the
  interfaces; a lattice part (strut cells, TPMS, graded, skinned or open)
  goes to STEP lattice and all, as smooth patches on its true surface ([docs/fields.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/fields.md#the-lattice-itself-in-the-step-lattice-exact)).
- **Mesh checks without a study** (`loadpath.checks`): wall thickness,
  overhangs, trapped voids, fluid-network isolation, component fit.

## How much to trust it

Read [docs/VALIDATION.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/VALIDATION.md) before relying on a number.
In short:

- **The solvers match analytic answers** in the test suite: beam
  deflection within 3-5%, stress at a hole within about 13%, Lamé pressure
  vessels within 5-11%, Poiseuille flow exactly.
- **The structural check is cross-checked**: CalculiX and loadpath's own
  tetrahedral solver agree within 0.1% on the same mesh. The voxel check
  reads 24-49% higher stress than the tet check, so it errs safe.
- **The optimizer is benchmarked**: 1-5% less stiff than top88 and top3d at
  equal material on three of their textbook problems, stiffer on the fourth.
- **Printed lattices match published tests**: against 33 published
  compression tests of printed lattices, the stiffness check has a median
  error of 1.23x (held out) and the strength check stays under the measured
  value on all 33.
- **Warp prediction is fitted to measured data** (NIST AM-Bench 2018 for
  LPBF IN625, a published ABS study for FDM) and misses other alloys and
  materials by 30-60%.
- **Everything else is simulation only**, including every part mass and
  safety factor in the case studies. The analysis is linear elastic with
  datasheet material values; printed parts vary with the printer.

## Case studies

Each states the problem, the setup, the numbers against a named baseline,
and the limitations ([docs/case-studies/](https://github.com/connorwhite-online/loadpath/tree/v0.1.3/docs/case-studies/)).

| Case study | Result | Baseline |
| --- | --- | --- |
| [Eval suite](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/case-studies/evals.md) | 15 of 15 parts meet their requirements on a fresh analysis of the delivered mesh | Each part's own requirements |
| [GRIP robot arm](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/case-studies/grip.md) | A load sweep over the arm's URDF found 3 of 5 links below SF 1; the regrown set meets SF 2 and is 18% smaller | GRIP's committed parts, made by an earlier loadpath with hand-written loads |
| [Arm link cores](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/case-studies/arm-link-cores.md) | 42.2 g box section for FDM, 36.8 g hollow link for SLS, both at 0.5 mm and SF 3 | 54.9 g solid web; 54.2 g free-form topology optimization |
| [Liquid cold plate](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/case-studies/cold-plate.md) | A die-graded gyroid ties streamline channels; channels filled with a graded gyroid run 7% cooler | Streamline channels and pin fins, equal metal and pressure drop |
| [TPU finger](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/case-studies/tpu-finger.md) | up to 8 mm of tip curl for a 5 mm pull; a tendon finger grips 8x harder | A linear-model design (2.5 mm, then the solve fails); a plain bar of equal volume |
| [Benchmarks](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/case-studies/benchmarks.md) | 1-5% less stiff than top88/top3d at equal material, in 57-60 iterations instead of 130-410 | Ports of top88 and top3d |

## Command line and Python

```bash
loadpath examples shelf-bracket > bracket.json
loadpath check bracket.json            # every problem at once, with suggestions
loadpath run bracket.json --out out/   # optimize, mesh, verify, render
```

`out/` gets an STL and a render per outcome and `report.json`. Every command
takes `--quick` for a first look in a minute or two.

Optional extras: `crosscheck` (tetrahedral verification; recommended),
`render`, `step` (STEP in and out, OpenCascade), `flow` (lattice-Boltzmann,
numba), `gpu` (PyTorch for large grids on CUDA, Apple Silicon or CPU
threads).

Studies are validated against a published JSON Schema
([`schema/`](https://github.com/connorwhite-online/loadpath/tree/v0.1.3/schema/)), and `loadpath check` returns every problem at once
with its JSON path, so an agent can fix a study in one round trip. Long
solves run as background jobs the agent polls. Each finished outcome has an
`attention` list of numbers to look at before trusting it, and renders a
vision model can inspect.

From Python:

```python
from loadpath.spec import study_from_dict
from loadpath.study import run_study

result = run_study(study_from_dict(study))
best = result.outcomes[result.best]
best.mesh.export("part.stl")
print(best.report["mass"], best.report["safetyFactor"])
```

## Documentation

- [Quickstart](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/quickstart.md): install to a checked part.
- [Tutorials](https://github.com/connorwhite-online/loadpath/tree/v0.1.3/docs/tutorials/): eleven end-to-end workflows, each run by CI
  (an FDM bracket to 3MF, an SLS lattice with drain holes, a metal heat
  exchanger, an impact bumper, a STEP part round trip, LPBF distortion
  compensation, and more).
- [Reference](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/loadpath/README.md): the method, every study field, the
  report, the limits.
- [Validation](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/VALIDATION.md): what each model has been checked
  against.
- [Case studies](https://github.com/connorwhite-online/loadpath/tree/v0.1.3/docs/case-studies/) and [benchmarks](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/BENCHMARKS.md).
- Topics: [fields](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/fields.md), [materials](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/materials.md),
  [build simulation](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/BUILDSIM.md), [calibration](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/CALIBRATION.md),
  [CAD import](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/IMPORT.md), [slicer](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/slicer.md),
  [multi-material](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/MULTIMATERIAL.md), [impact](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/IMPACT.md),
  [mechanisms](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/MECHANISMS.md).

<!-- gallery:start -->

## Examples

The eval suite (15/15 passing): robot-arm links, brackets, a bell crank and a hook, each optimized and then checked by a fresh analysis of the delivered mesh. "Under envelope" compares with the design space filled solid, not with a conventionally designed part. These are simulated results; see [docs/VALIDATION.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/VALIDATION.md). Blue arrows are loads, red is keep-out. Every view, stress map and number is in [docs/GALLERY.md](https://github.com/connorwhite-online/loadpath/blob/v0.1.3/docs/GALLERY.md).

<table>
<tr>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/arm-link.png" width="250"><br><b>arm-link</b><br><sub>55.3 g · 56% under envelope · SF 8.92 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/arm-link-cast.png" width="250"><br><b>arm-link-cast</b><br><sub>67.8 g · 46% under envelope · SF 20.11 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/arm-link-driven.png" width="250"><br><b>arm-link-driven</b><br><sub>48.4 g · 61% under envelope · SF 11.17 · pass</sub></td>
</tr>
<tr>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/bell-crank.png" width="250"><br><b>bell-crank</b><br><sub>23.4 g · 84% under envelope · SF 3.22 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/grip-turret.png" width="250"><br><b>grip-turret</b><br><sub>140.4 g · 91% under envelope · SF 2.85 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/grip-upper-arm.png" width="250"><br><b>grip-upper-arm</b><br><sub>207.7 g · 88% under envelope · SF 7.33 · pass</sub></td>
</tr>
<tr>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/grip-wrist-link-mjf.png" width="250"><br><b>grip-wrist-link-mjf</b><br><sub>40.2 g · 95% under envelope · SF 5.83 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/grip-wrist-yoke.png" width="250"><br><b>grip-wrist-yoke</b><br><sub>17.3 g · 93% under envelope · SF 3.88 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/mbb-beam.png" width="250"><br><b>mbb-beam</b><br><sub>13.8 g · 79% under envelope · SF 1.51 · pass</sub></td>
</tr>
<tr>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/motor-mount.png" width="250"><br><b>motor-mount</b><br><sub>27.6 g · 69% under envelope · SF 3.65 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/printed-hook.png" width="250"><br><b>printed-hook</b><br><sub>24.2 g · 84% under envelope · SF 2.73 · pass</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/wall-bracket.png" width="250"><br><b>wall-bracket</b><br><sub>26.9 g · 94% under envelope · SF 2.85 · pass</sub></td>
</tr>
<tr>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/cases/wall-bracket-fasteners.png" width="250"><br><b>wall-bracket-fasteners</b><br><sub>26.5 g · 94% under envelope · SF 2.57 · pass</sub></td>
</tr>
</table>

Where the load goes: von Mises stress, blue (none) to red (the part's 98th percentile), on the part bent by its worst load case:

<table>
<tr>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/stress/bell-crank.png" width="250"><br><sub>bell-crank</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/stress/grip-upper-arm.png" width="250"><br><sub>grip-upper-arm</sub></td>
<td align="center" valign="top"><img src="https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/stress/printed-hook.png" width="250"><br><sub>printed-hook</sub></td>
</tr>
</table>

Two-fluid heat exchangers: two isolated channel networks through one sheet gyroid, with headers that print without support.

![box-crossflow](https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/heatx/box-crossflow.png)

Printed in metal, nothing inside can be supported: the channels end in peaked roofs instead of flat ceilings (red).

![metal ceilings](https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/heatx/lpbf-ceilings.png)

Made another way: the same arm link printed, cast (no undercuts along z), 3-axis milled from both sides with a 6 mm cutter, and with members capped at 6 mm. Each meets SF 3 and 0.5 mm.

![manufacturing constraints](https://raw.githubusercontent.com/connorwhite-online/loadpath/v0.1.3/docs/images/manufacturing/arm-link.png)

<sub>Rendered 2026-11-03 from `6c97b57` by `python docs/gallery.py`.</sub>

<!-- gallery:end -->
## Limits

- Linear elastic, small deflection in the main check; large deflection and
  buckling are separate analyses (`nonlinear.py`), with contact (rigid
  obstacles and self contact, optionally with Coulomb friction) and
  tendons there only.
- Printed layers are modelled as transversely isotropic stiffness plus a
  tension-across-layers strength check. Interlayer shear is not checked
  separately.
- Material cards are datasheet values until you calibrate your printer
  (`loadpath calibrate`).
- Results depend on the grid: mass at a target safety factor moves about
  5% with small changes of grid size or starting point.
- Pure Python with NumPy and SciPy. A 40,000-cell study takes a few minutes
  on one laptop core; a safety-factor search runs several of those, and the
  larger eval parts take 15-60 minutes on four cores.

## Tests

```bash
python tests/run_tests.py && python tests/test_loadpath.py        # core
python tests/test_tutorials.py                                    # every tutorial, quick mode
python -m loadpath.evals.run --tier coarse --corpus 6 \
    --baseline loadpath/evals/baselines/coarse.json --gate regressions   # under 30 min
python -m loadpath.evals.run --out evals-out/                     # full eval suite, hours
python -m loadpath.benchmarks.run --out bench-out/                # top88 / top3d benchmarks
python docs/gallery.py --evals evals-out/                         # refresh the Examples renders
```

`.github/workflows/tests.yml` lists the full set CI runs.

## License

MIT
