forge

One repo to offload R&D into: a parametric design + multi-physics simulation loop.

   describe / measure            change a number
        a part                    and re-run
          │                           ▲
          ▼                           │
   ┌─────────────┐   ┌────────┐   ┌────────┐   ┌─────────┐
   │  GENERATE   │──▶│  MESH  │──▶│  TEST  │──▶│ REPORT  │
   │  CadQuery   │   │  gmsh  │   │ ccx    │   │ pass /  │
   │  (.step)    │   │ (tets) │   │ (FEA)  │   │  fail   │
   └─────────────┘   └────────┘   └────────┘   └─────────┘
          │                                         │
          └────────────── print ◀───────────────────┘
                       (.stl, once it passes)

You describe a part (or hand a reference image / measurements to an LLM that writes the CadQuery), the code makes a real parametric solid, the part gets meshed and tested against the physics you pick, and you get a verdict back. Change a number, re-run, repeat. The geometry is editable forever because the code is the part.

Install

Windows, one click: double-click INSTALL.bat. It installs Python if needed, the packages, downloads the CalculiX solver, puts a forge shortcut on your desktop, and runs the verification benchmark. Details and fallbacks: docs/INSTALL_WINDOWS.md. (Once the repo is on GitHub, tagged releases also build a forge-setup.exe - see .github/workflows/release.yml.)

Anywhere, by hand:

pip install -r requirements.txt          # cadquery + gmsh + pyvista
python run.py benchmark_cantilever       # 4 physics vs hand calcs - all must say OK

The viewer stack in requirements.txt (pyvista/vtk/numpy) is pinned as a validated-together set - newer vtk wheels have shipped missing slider widgets and freeze-on-interaction on Windows. Bump all three together or not at all, and re-run the viewer interactively afterward (the pins carry their own why-comments). On Windows, forge.bat deliberately prefers py -3.12 (then 3.11/3.10) over whatever python is first on PATH, so install packages into that interpreter: py -3.12 -m pip install -r requirements.txt.

Use

Double-click the desktop shortcut (or python forge_launcher.py) for the launcher: project browser (with each project's PARAMS and study shown on selection), Run / View in 3D / Open in FreeCAD buttons, a second row for Fit Check / Drawings / Slice / Converge, live console with colored verdicts, a New Part wizard that generates part.py + study.py from a template (bracket, plate, box, standoff; optional reference/ and mates/ folders), and each project's runs.csv history. The terminal does everything too:

python run.py example_bracket            # the loop, console verdict
python view.py example_bracket           # 3D window: sliders + stress maps
                                         # F solve, G geometry, R reference
                                         # ghost, C section view
python run.py example_bracket -a modal   # same part, different physics
python -m forge.templates my_mount bracket --material asa
python optimize.py example_bracket --tune thick=3:10 fillet=4:14
python converge.py example_bracket         # is the answer mesh-independent?
python fit.py courier --clearance 0.5      # clears its mates/ STEPs by 0.5 mm?
python slice.py example_bracket            # print time / filament / cost
python -m forge.handoff example_bracket    # fresh STEP -> straight into FreeCAD
python calibrate.py log example_bracket --actual 95   # after a break test
python calibrate.py fit --modeled 6.5 --measured 6.28 # printed-dimension ledger

That last one is the loop turning its own knobs: minimum mass subject to your safety factor, by real FEA runs (auditable in runs.csv). It optimizes to the margin you asked for - break-test the winner. Every generate stage also reports mass and rough material cost.

Linux system deps for mesh + test:

sudo apt-get install -y libglu1-mesa libxft2 libxrender1 libgomp1 calculix-ccx

What it tests (study["analysis"])

analysis	question it answers	validated against
static	does it break / how far does it bend? (+ optional gravity)	beam deflection, 1.4%
drop	survives a fall? (quasi-static equivalent-g, honest bound)	- (approximation by design)
modal	what frequency does it ring at / will it resonate?	beam f1, 0.2%
buckling	at what multiple of the load does it fold?	Euler column, 0.2%
thermal	how hot does it get? (fixed temps + heat input, mW)	conduction hand calc, 2.1%
thermal_stress	what stress does that temperature cause?	free-expansion hand calc
aero	drag/lift in a virtual wind tunnel (OpenFOAM; docs/CFD.md)	sphere drag, screening-grade

Electrical work rides along analytically: forge/electrical.py sizes wires (AWG), PCB traces (IPC-2221), computes voltage drop and I²R joule heat - and the heat lands in a thermal study as heat_input_mw. Real EM field simulation (antennas, motors) is out of scope: FEMM or Elmer.

Units: mm — N — MPa (load-bearing, read this)

CalculiX is unit-agnostic. Feed it mm geometry with a Pa modulus and it returns plausible-looking numbers ~6 orders of magnitude wrong - that bug shipped in v0.1 and was caught by a hand calc. One consistent set:

quantity	unit	example
length	mm	geometry, deflection out
force	N	load_vector
stress / modulus	MPa (= N/mm²)	PETG ~2000, alu ~70000, steel ~200000
density	tonne/mm³	steel 7.85e-9
heat / power	mW	heat_input_mw
conductivity	mW/(mm·K)	numerically = W/(m·K)
frequency	Hz	modal output

write_deck() rejects Pa-looking moduli, and benchmark_cantilever verifies units, elements, and parsers against hand calculations in one run. Materials come from forge/materials.py by name (material="petg") so you rarely type raw numbers anyway.

What's actually true (read before trusting it)

• Image → CAD is approximate, not magic. A photo captures the concept; calipers capture the fit. Anything that bolts to existing hardware gets measured.
• FEA is garbage-in-garbage-out. The material, fixed faces, and load in study.py are where your engineering judgment lives. Treat results as comparative first. Fixed and loaded regions must not overlap (enforced); stress reported AT the supports is flagged, because re-entrant corners there are mathematically singular.
• Printed parts are anisotropic. The materials library knocks yield down for layer adhesion BY DEFAULT (PETG 47→33 MPa; claiming XY strength is an explicit opt-in). Still: use FEA to compare, verify with a break test, log both in runs.csv.
• Drop is a bound, not a movie. Quasi-static equivalent-g from drop height / stop distance. Marginal verdicts → break test.
• Aero is out of scope. Structure yes; airflow is CFD (OpenFOAM).

Structure

forge/                     the toolkit
  pipeline.py              generate -> mesh -> test -> report -> log
  meshing.py               gmsh, C3D10 default (C3D4 fallback)
  fea.py                   decks for all analyses, solver, parsers
  materials.py             named materials + print knockdowns
  electrical.py            wire/trace/heat sizing (analytic, stdlib)
  reporting.py             per-analysis verdicts
  viewer.py                pyvista window internals
  handoff.py               FreeCAD handoff: find it, hand it a fresh STEP
  fitcheck.py              interference / clearance vs measured mates
projects/
  benchmark_cantilever/    4-physics hand-calc gate - run this first
  example_bracket/         a working part + load case - copy to start
  atrai/  drones/  courier/  (yours)
memory/                    the ten-file knowledge spine
tools/make_snapshot.py     flatten repo -> one Markdown knowledge doc
research.py                stdlib OpenAlex CLI (free API key required)
run.py                     python run.py <project> [-a analysis]
view.py                    python view.py <project>  - the 3D window
forge_launcher.py          the GUI front door (forge.bat / shortcut)
forge/templates.py         New Part wizard's generator (also a CLI)
optimize.py + forge/optimize.py   parameter search: min mass s.t. SF
docs/LANDSCAPE.md          the ecosystem survey + integration roadmap
CLAUDE.md                  conventions primer for LLM-written parts
converge.py                mesh-independence check (run before trusting decimals)
fit.py                     assembly fit: part vs projects/<name>/mates/ STEPs
calibrate.py               break-test + print-fit ledgers -> correction factors
slice.py + forge/printcost.py   PrusaSlicer post-pass: time, grams, dollars
INSTALL.bat + installer/   one-click Windows setup (+ Inno Setup script)
.github/workflows/         CI benchmark gate + release installer build
docs/                      WORKFLOW, INSTALL_WINDOWS, RESEARCH (decisions ledger)

Every completed run appends to the project's runs.csv - the versioned calibration ledger for lining predictions up against real break tests.

Drawings

python drawings.py <project> renders a reference drawing (front/top/ right/iso + title block with material, mass, bounding dims) as SVG - print it, or keep it with the build records. For fully dimensioned, toleranced sheets, open the STEP in FreeCAD's TechDraw.

FreeCAD

forge exports STEP; FreeCAD opens it natively - use it to inspect, measure, drawing-sheet, or hand-model on top of forge parts. On Windows, FreeCAD also provides forge's solver (bundled ccx.exe, auto-detected). For FEA beyond forge's scope (contact, assemblies), FreeCAD's FEM workbench and PrePoMax drive the same CalculiX engine - same units convention applies.

The handoff runs both directions, but geometry flows only one way:

• forge -> FreeCAD: the launcher's Open in FreeCAD button (or python -m forge.handoff <project>) regenerates the STEP if part.py is newer and opens it without blocking the launcher. Detection order: FORGE_FREECAD, the usual install dirs, PATH.
• inside FreeCAD: installer/forge_panel.FCMacro puts a forge panel in FreeCAD - browse projects, run the loop, open STEP and drawings without leaving it. The launcher's tools menu installs it into your Macro directory for you.
• never FreeCAD -> forge: edits made in FreeCAD are baked geometry (docs/WORKFLOW.md, editability ladder). Dimensions change in part.py.