forked from 1b-agent/fieldcraft-upstream
jyvikoandClaude Opus 5.5
b19277ae7a
docs/crash-reports.md: what is kept where, what a bug report carries (and only when ticked), the CLI and commands for agents; README's privacy note; the control protocol's new prompt answers. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01UhhZMBTviDQxZvwnyP89fo
153 lines
11 KiB
Markdown
153 lines
11 KiB
Markdown
# FieldCraft
|
||
|
||
An open-source, clean-room CAE application in pure Rust: from a parametric SolidCraft part to a
|
||
verified finite element analysis, with tetrahedral and hexahedral meshing, its own implicit,
|
||
explicit, thermal and lattice Boltzmann solvers, and decks for Abaqus, Nastran and LS-DYNA. The
|
||
desktop app, the command line and AI agents (over MCP) drive the same commands.
|
||
|
||
**Status:** early but working end to end — open a part, mesh it, define the analysis, solve,
|
||
see the results — with a nonlinear implicit solver (large deformation, plasticity, rubber) now
|
||
in place. Hex meshing is the centre of gravity. Next: buckling and arc-length, contact, then
|
||
the wider material and multiphysics library. See [ROADMAP.md](ROADMAP.md).
|
||
**Want to help?** Pick an issue labelled
|
||
[good first issue](https://github.com/jyviko/fieldcraft/labels/good%20first%20issue) or
|
||
[help wanted](https://github.com/jyviko/fieldcraft/labels/help%20wanted) and read
|
||
[CONTRIBUTING.md](CONTRIBUTING.md).
|
||
|
||
|
||
|
||
*Claude driving FieldCraft through its [MCP server](docs/mcp.md): one prompt, and it opens the part, meshes it, defines and solves the analysis, then checks the tip deflection against beam theory. Real session, waits shortened. [Full video](docs/media/claude-mcp.mp4).*
|
||
|
||
|
||
|
||
An AI agent drives FieldCraft over [MCP](docs/mcp.md), each stage captioned with the tool it
|
||
calls: it opens an I-beam, hex meshes it, defines the material, the clamp and a 1000 N tip load,
|
||
solves, and shows the von Mises stress and the deformed shape (tip deflection 0.176 mm; beam
|
||
theory with shear 0.177 mm).
|
||
[MP4](docs/media/ibeam-analysis.mp4) · regenerated by [tools/demo-video](tools/demo-video/README.md).
|
||
|
||
## Download
|
||
|
||
[](https://github.com/jyviko/fieldcraft/releases/latest)
|
||
[](https://github.com/jyviko/fieldcraft/releases/latest)
|
||
[](https://github.com/jyviko/fieldcraft/releases/latest)
|
||
[](https://jyviko.github.io/fieldcraft/)
|
||
|
||
- **macOS:** open the `.dmg` and drag FieldCraft into Applications (Apple silicon and Intel).
|
||
- **Windows:** unzip and run `fieldcraft.exe`.
|
||
- **Linux:** the `.AppImage` (allow it to run as a program), or the `.tar.gz`.
|
||
- **Browser:** [try it at jyviko.github.io/fieldcraft](https://jyviko.github.io/fieldcraft/), no install.
|
||
- **Command line:** `fieldcraft-cli` ships in every package; AI agents connect to it over MCP
|
||
([docs/mcp.md](docs/mcp.md)).
|
||
|
||
Every release lists its checksums in `SHA256SUMS.txt`. Building from source is in
|
||
[CONTRIBUTING.md](CONTRIBUTING.md#get-it-running-about-10-minutes-on-a-fast-machine).
|
||
|
||
## Hex meshing a part that does not sweep
|
||
|
||
A filleted L-bracket with a hole through each leg cannot be swept in one piece. Split into 30
|
||
cells in SolidCraft, FieldCraft meshes it all-hex as one conforming mesh — O-grids round the holes,
|
||
graded through the fillet — and its hex20 tip deflection matches a fine tet10 solution to 0.1 %.
|
||
The same part also meshes all-hex automatically with the octree mesher (`mesh.hex.octree`).
|
||
|
||
| Cells | Conforming hex mesh | Von Mises (clamp and load drawn) |
|
||
|---|---|---|
|
||
|  |  |  |
|
||
|
||
## What it does today
|
||
|
||
- **Geometry in:** SolidCraft designs (`.solidcraft`) with persistent face, edge and body names,
|
||
and face-tagged 3MF meshes; surface checks (weld, manifold, orientation, self-intersection).
|
||
- **Meshing:** constrained Delaunay tetrahedra (tet4, tet10) with exact predicates and a
|
||
certified validity gate; Delaunay refinement, smoothing and sliver removal; structured hex by
|
||
sweeping, revolving and mapping (hex8, hex20), and conforming multi-block hex across a part
|
||
split into cells (`mesh.hex.blocks`); unstructured octree all-hex for any part
|
||
(`mesh.hex.octree`); 2D quad and tri meshes; quality metrics per element and set.
|
||
- **Elements:** solids (tet4, tet10, wedge6, hex8 with incompatible modes, hex20 full and
|
||
reduced, hybrid u–p for near-incompressible materials), plane stress, plane strain and
|
||
axisymmetric, trusses, Timoshenko beams, MITC3/MITC4 shells, springs, dashpots and point masses.
|
||
- **Model:** sets bound to geometry names, so they survive remeshing; isotropic and orthotropic
|
||
elasticity, J2 plasticity (isotropic and kinematic hardening, Johnson–Cook), Johnson–Cook
|
||
damage, neo-Hookean, Mooney–Rivlin and Yeoh hyperelasticity, thermal properties; fixed, displacement,
|
||
symmetry and temperature conditions; forces, moments, pressure, gravity, centrifugal and heat
|
||
loads; reference points with kinematic and distributing couplings; undo, redo and a
|
||
text-diffable `.fieldcraft` file.
|
||
- **Solvers:** linear static and frequency (supernodal Cholesky, block Lanczos); nonlinear static
|
||
by Newton–Raphson with automatic increments — large deformation (total Lagrangian) on every
|
||
solid element, follower pressure, finite- and small-strain plasticity sharing one return map
|
||
with the explicit solver, rubber and thermal strain, with measured quadratic convergence; steady and
|
||
transient heat transfer and coupled thermal stress; explicit dynamics with plasticity, damage,
|
||
erosion and rigid walls; D3Q19 lattice Boltzmann flow with forces on the part's faces. Results
|
||
never depend on the thread count.
|
||
- **Decks:** Abaqus, Nastran and LS-DYNA writers, each refusing by name what it cannot express.
|
||
- **Results:** contours of stress, strain and displacement with a legend, deformed shapes, mode
|
||
shapes, explicit and nonlinear frames, probes and reaction sums; supports, loads, reference
|
||
points and couplings drawn in the viewport.
|
||
- **Verification:** every capability is checked against closed forms and published benchmarks
|
||
(NAFEMS, MacNeal–Harder, Scordelis–Lo, the elastica, Hill's plastic cylinder, Rivlin's tube) in [`tests/oracle`](tests/oracle), with results frozen
|
||
so they cannot drift: 170 of 176 quantities pass in 50 cases, the 6 others documented known
|
||
failures ([docs/oracle.md](docs/oracle.md)).
|
||
- **Driving it:** a desktop app in the Craft family's layout, a CLI, a JSON control channel and an
|
||
MCP server; every capability is a command ([docs/features.md](docs/features.md)).
|
||
|
||
|
||
|
||
## Examples
|
||
|
||
Ready-to-solve samples: open one from **File ▸ Samples** (or the start screen), or start the app
|
||
with `fieldcraft --sample NAME`, and press **Solve**. Each opens and solves within half a minute and is checked
|
||
against a closed form or a reference solution ([docs/examples.md](docs/examples.md)).
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="33%" valign="top"><img src="docs/media/examples/drop-test.png" alt="Drop test" width="100%"><br><b>Drop test</b> (<code>drop-test</code>): an aluminium bracket dropped 2 m onto a tilted floor; explicit dynamics, the strike's stress waves</td>
|
||
<td width="33%" valign="top"><img src="docs/media/examples/rubber-seal.png" alt="Rubber seal" width="100%"><br><b>Rubber seal</b> (<code>rubber-seal</code>): a Mooney–Rivlin gasket ring squeezed 25 %; nonlinear static, large strain</td>
|
||
<td width="33%" valign="top"><img src="docs/media/examples/heated-bracket.png" alt="Heated bracket" width="100%"><br><b>Heated bracket</b> (<code>heated-bracket</code>): a clamped steel bracket heated at one end; steady heat and thermal stress</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="33%" valign="top"><img src="docs/media/examples/bracket-hex.png" alt="Hex-meshed bracket" width="100%"><br><b>Hex-meshed bracket</b> (<code>bracket-hex</code>): the bracket split into 30 cells, meshed all-hex (hex20), von Mises</td>
|
||
<td width="33%" valign="top"><img src="docs/media/examples/crank-arm.png" alt="Bicycle crank arm" width="100%"><br><b>Bicycle crank arm</b> (<code>crank-arm</code>): an aluminium crank meshed structured all-hex (hex20) from a partitioned half and its mirror image, a rider's weight on the pedal; root bending within 0.3 % of M/Z</td>
|
||
<td width="33%" valign="top"><i>No picture yet: the viewport does not draw flow results (M12).</i><br><b>Flow past a bracket</b> (<code>flow-past</code>): air past an L-bracket on the floor; lattice Boltzmann flow, the drag and the force on each face</td>
|
||
</tr>
|
||
</table>
|
||
|
||
## Build
|
||
|
||
```sh
|
||
cargo xtask ci # fmt, assets, licences, layers, clippy, tests, wasm
|
||
cargo xtask test --heavy # the heavy (ignored) tests and the doc tests
|
||
cargo run -p fieldcraft-cli -- commands # every command and its parameters
|
||
cargo run -p fieldcraft-cli -- run script.json # run a command script
|
||
cargo run -p fieldcraft-cli -- mcp # MCP server on stdio for AI agents (docs/mcp.md)
|
||
```
|
||
|
||
Rust 1.95 or later, with the `wasm32-unknown-unknown` target for `cargo xtask ci`.
|
||
|
||
## Documentation
|
||
|
||
- [Examples](docs/examples.md): the ready-to-solve samples and their checks
|
||
- [Architecture](docs/architecture.md): crates, layers and the meshing pipeline
|
||
- [Element library](docs/elements.md) and [verification and validation](docs/verification.md)
|
||
- [Capability checklist](docs/parity.md) and [roadmap](ROADMAP.md)
|
||
- [Libraries and licences](docs/adr/0001-libraries.md)
|
||
- [AI agents (MCP)](docs/mcp.md): `claude mcp add fieldcraft -- /path/to/fieldcraft-cli mcp`
|
||
- [Control protocol](docs/control-protocol.md): driving the desktop app
|
||
- [Releasing](docs/releasing.md): how a release is built, verified and published
|
||
- [Contributing](CONTRIBUTING.md) and [agent instructions](AGENTS.md)
|
||
|
||
## Privacy
|
||
|
||
FieldCraft sends nothing anywhere on its own: no analytics, no telemetry, no automatic crash
|
||
upload. Crash reports and the log stay on your computer; Help › Report a Bug opens a GitHub issue
|
||
you review and submit yourself, with your session or model attached only if you tick them
|
||
([docs/crash-reports.md](docs/crash-reports.md)).
|
||
|
||
## License
|
||
|
||
Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option. Notices
|
||
are in [NOTICE](NOTICE); third-party licences in [THIRD-PARTY-LICENSES.txt](THIRD-PARTY-LICENSES.txt).
|
||
|
||
FieldCraft is an independent project, not affiliated with, sponsored or endorsed by Dassault
|
||
Systèmes, MSC Software, Siemens or Ansys. Abaqus, Nastran, MSC Nastran, Simcenter Nastran and
|
||
LS-DYNA are trademarks of their owners and are named only to describe file compatibility.
|