part-to-topopt
Skill26 starsChanged 19 days agoMITView on GitHub
Use when the user describes a physical part in plain words (for example "a wall hook for a T-shirt", "a bracket for a 2 kg shelf", "a phone stand"), or gives an STL of their own part ("here is my part", "keep the screw holes"), and wants it optimized or made lighter with topopt. Turns the description or the STL into a valid problem YAML and region STL files, checks them, and prints the assumptions. Do not use when the user already has the region STL files and the problem YAML.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- part-to-topoptSkill
- start-hereSkill
- start-hereSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
29 rules. About 0 are common, 12 are distinctive, and 17 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Before the run, state the assumptions: write them down (Step 5 has the format).
- Distinctive: line 10
Ask the user when an answer changes the part (for example the load, the mounting or the size).
- Very specific: line 13
When the user wants a result and you have the answers to your questions, you may start the optimizer and watch it through the MCP tools or …
- Distinctive: line 45
If the description does not say what the part holds or carries (no object, no mass and no force), ask the user for it.
- Distinctive: line 47
Add a second load case for abuse: 5 to 10 times the static force, in a different direction (a pull, a knock, a side force).
- Distinctive: line 52
Keep-out regions: screw holes with clearance for the screw head and the screwdriver, the space of the user's hand, and the space of the …
- Very specific: line 66
Do this before the first run.
- Very specific: line 110
Leave out the material block, the print block or settings.voxel_size, and build_regions takes the missing one from the preferences.
- Very specific: line 116
When exists is false, the skill start-here (Step 1b) asks the user once and save_preferences keeps the answers.
- Very specific: line 120
Write runs/<name>/spec.yaml.
- Very specific: line 179
Do not give a region the name of a primitive (for example box, stl or screw_ring).
- Very specific: line 181
Use voxel_size: auto unless you have a reason.
- Distinctive: line 204
Write one line for each of these:
- Distinctive: line 209
Keep-outs: what stays empty and why.
- Distinctive: line 227
Use this when the user has an STL of the part.
- Very specific: line 229
Put the file in the work folder, or use its absolute path.
- Distinctive: line 232
Ask only what changes the problem.
- Very specific: line 237
Write the spec (below), call build_regions and check_problem, and fix errors as in Step 4.
- Very specific: line 277
Use --check to test a spec and write nothing.
- Very specific: line 281
After build_regions, call record_brief with the brief and your assumptions.
- Very specific: line 290
If the action is fix_pypardiso_load, pypardiso is already installed but does not load.
- Very specific: line 292
If the check prints this line, offer the install to the user, with the speed-up as the reason.
- Very specific: line 296
Read the message. Change the spec.
- Very specific: line 302
Read the numbers of the message, the memory estimate (check_problem.memory_estimate, or the line that the helper prints) and the RAM of the …
- Very specific: line 305
If the user gave the voxel size, it is a requirement (its origin in record_brief is user): a larger voxel loosens it, so ask the user first …
- Very specific: line 355
Default aim of auto: voxel = cbrt(active_volume_mm3 / target_active), rounded up to 0.05 mm.
- Distinctive: line 373
Do fixed, load, solid and design shapes touch or overlap each other?
- Distinctive: line 385
Write a short summary for the audience in plain words.
- Distinctive: line 398
Write the summary in the user's language, in plain words, with short sentences.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Part description to topopt problem
Goal: build a valid problem YAML and region STLs that match what the user wants.
Before the run, state the assumptions: write them down (Step 5 has the format).
Ask the user when an answer changes the part (for example the load, the mounting or the size). For a small detail, make a sensible assumption and write it down.
The load changes the shape of the part, so the load has no default. If the user does not say what the part holds or carries (no object, no mass and no force), ask for it before the run. Do this also when the user says "run it". You can give a typical value in the question. Then wait for the answer. If the user names the object (for example a coat or a plant pot), use a typical mass for it and write it in the assumptions.
The tools give facts, estimates and options. You decide the method. The user decides the load, the mounting and the size.
When the user wants a result and you have the answers to your questions, you may start the optimizer and watch it through the MCP tools or topopt run.
Units are mm, N, MPa, g. The MCP server instructions carry the short version of this guidance for any client. This file has the detail.
Where things run. Files go in the work folder: the folder where the client runs (runs/<name>/).
This skill is in .claude/skills/part-to-topopt/ and, as a copy, in .agents/skills/part-to-topopt/ (Codex, Gemini, Cursor and VS Code read that folder).
A path below starts at the repo root, unless the text says "in the folder of this skill" (the folder that holds this SKILL.md; the Agent Skills rule for files next to a skill).
In the Claude Code plugin, the repo root is ${CLAUDE_PLUGIN_ROOT}.
In the Claude Code plugin topopt, the tools of the MCP server (build_regions, check_problem, run_topopt, ...) work with no setup, and the plugin has its own Python environment.
To run a Python command in it, use this prefix (Claude Code fills in the two paths):
CLAUDE_PLUGIN_DATA="${CLAUDE_PLUGIN_DATA}" sh "${CLAUDE_PLUGIN_ROOT}/scripts/topopt-env.sh" python ...In a source checkout of topopt (no plugin), use sh scripts/topopt-env.sh python ... in the repo root: it uses the same environment as the MCP server of the client configs. .venv/bin/python also works after the dev install.
Two entries
- A part in words: Step 1 to Step 5 below.
- Your own STL: the user has a file of the part (an exported CAD file). Use the section "Your own STL" (after Step 2). It takes the place of Step 1 and uses Step 2 to Step 5.
Step 1. Infer the part (think, do not write long text)
Decide each item from the description.
- Function: what does the part hold or carry?
- Mounting: which faces are fixed? A wall plate, screw bosses, or a clamp ring. Make the fixed region a thick plate or ring, 3 mm or more.
- A fixed region is a full clamp. To fix only some axes (a roller or a slider), name them in
fixed_axes(see Step 2). A per-axis region is a solid body in the part: its nodes are fixed along the named axes only, so it carries load along the other axes and adds its stiffness (outside the part, a slab of one voxel makes a half model 12 to 22 percent too stiff, and a slab of 3 mm 40 percent). For a symmetry plane, make the slab one voxel thick and put it inside the part, or give the full symmetric part and usemirror. The supports together need to block all six rigid-body modes (three rollers on three planes do, one roller does not). If they do not, the engine stops before the run and names the free modes. - A part that sits on a soft mount (a rubber foot, a spring clip) has a spring instead of a clamp: add the mount body to
loadand aspringsentry for it,{region: <load name>, stiffness: [kx, ky, kz]}in N/mm (the total for the region, global axes). The spring acts on all faces of that body that look into free space or a keep-out region, so give the body a free face only where the mount touches the ground. The body is solid and carries load. A spring can replace thefixedregion (a part on springs only is valid), but a very soft spring makes a part that is nearly free: the check prints a warning. - A part that hangs on a rod, a pin or a tube that is not in the grid has a joint: add the body that the rod goes through (a sleeve, a boss) to
load, and ajointsentry{region: <load name>, to: [x, y, z], section: {kind: round, d: 4}}.tois the fixed far end of a beam (mm), in any direction. Sections:round {d},tube {od, id},rect {b, h},props {A, Iy, Iz, J}(mm). The faces of the body that look into free space are bonded to one rigid body, and an Euler-Bernoulli beam joins that body to the far point. A joint can replace thefixedregion (a part on joints only is valid). Optional keys:origin(the start of the beam),orient(the section y axis of a section that is not round),E,nu,bond_stiffness_per_area. The check prints the beam length and L/d (the model has no shear: a beam with L/d 10 is 0.6 percent more flexible than the model says, L/d 5 2.3 percent, L/d 3 6.3 percent, L/d 2 14 percent, L/d 1 57 percent), the bond stiffness with its source,rhoand the bond share. The result has the wrench on the part and the ground reaction of each joint. The solvers pardiso, cholesky, amg andgpu-mgtake joints (and springs);gpu-mgtakes per-axis supports (fixedwithaxes) too; in its case C (a device without 64-bit float) the joint term is computed in 32-bit float:checkgives the ratio of the beam to the bond stiffness and the cases that were measured, and a run that stops gives the ratio and the options (another solver, a device with 64-bit float, a stiffer beam: a larger section or a shorter beam). The voxel buckling check gives the fact and the options.
- A fixed region is a full clamp. To fix only some axes (a roller or a slider), name them in
- Load: where does the force act? A load region is a forced-solid body. Make it the WHOLE solid feature that the force acts on (a hook tip, a bowl, a shelf lip). A small patch on a thin wall is a poor load region: the optimizer can cut it off and remove it. Give its force in N as
[Fx, Fy, Fz].- If the description does not say what the part holds or carries (no object, no mass and no force), ask the user for it. Do not start a run on a load that you chose.
- Static force = mass in kg x 9.81. Example: 0.2 kg gives 1.96 N.
- Add a second load case for abuse: 5 to 10 times the static force, in a different direction (a pull, a knock, a side force). Give it weight 1.0.
- Give the static case a bigger weight only if you want it to dominate.
- A moment (a twist or a bending couple) is
moment: [Mx, My, Mz]in N mm in a force entry. A force that acts away from its region is a remote force: addat: [x, y, z]in mm. Both are spread over the nodes of the load region, with no added stiffness (a distributing coupling, RBE3-like). A rigid coupling is not available. A stiff link can be a load region of solid voxels. - A pressure (N/mm2, MPa) is a
pressuresentry of a load case:{region: <load name>, value_mpa: 0.2}. It acts on the faces of that load region that look into free space or a keep-out region. A positive value pushes into the part. A pressure on a fixed region or on the design space is refused, with the reason. Shape the load region so that only the wanted face is free.
- Dimensions: use real sizes. Use common sizes for the object (a screw is 4 to 5 mm, a shelf is 200 mm deep). A sketch, a photo or a drawing with no dimension gives proportions, not a size. Get the scale from one real dimension that the user gives, or from a known object in the picture (a standard screw, a coin, a known product). When there is none, ask for one before the run: the size is one of the answers that change the part (the top of this file), and a guessed size can give, for example, a hook that does not fit. Take the other sizes from the proportions of the sketch. Write each number that you took or guessed as an assumption (origin
inferredinrecord_brief), and show the list to the user. The part has to fit the print bed. Take the bed size fromprint.bed_mmof the spec or the problem YAML, or from the printer model (print.printer_model; see "The printer" below). If nothing is given, the tools use 220 x 220 mm (the default, labelled "assumed").topopt checkgives the fit of the design-space box as a fact, and theprintsection ofmetrics.jsongives it for the final mesh. - Keep-out regions: screw holes with clearance for the screw head and the screwdriver, the space of the user's hand, and the space of the held object. Keep-out regions overlap the design space.
- Material: PLA or PETG. Use E 3500, nu 0.35, density 1.24 unless the user names another material. If the user names the filament they have, call
find_materialand putfilament: <id>in thematerialblock (see "The filament" below): the profile gives E and density. - Volume fraction: it is the mean density of the FREE design voxels (without the fixed, load and solid regions, which are solid on top). Use 0.2 for a light part, 0.25 default, 0.3 for a part with a big abuse load. The YAML keeps your value, as CONTRACTS.md and the engine read it. The helper prints the basis once, then the free and the forced-solid voxels, the target volume in mm3 and the target mass in g of the run (the numbers of
topopt check), and the share of all active voxels (for information only; it is written nowhere). - Solid bodies: a body that must stay solid, but has no clamp and no force, goes in
solid(for example a cap or a rim). The builder writes it asregions.solidin the problem YAML. The engine freezes it at density 1. A load region keeps its voxels where it overlaps a solid body (priority: keep-out, fixed, load, solid, design). - Use in the world: think about how the part touches the objects around it. A sketch or a description often does not show this. For example, a hook for a hanging object needs a lip, so the object does not slide off. A part that nests in another object needs clearance around that object. Add these features to the spec, and write them in the assumptions.
- Symmetry: if the part and its loads are symmetric about a plane, you may add the optional
mirrorkey (see "Themirrorkey"). It makes the design mirror-symmetric. It is a choice for the part, not a default.
Coordinate rule: pick one frame for all regions. Put the mount at x = 0, with the part out in +x, and z up. Make the design space a box (or a prism) that wraps all the load and fixed regions with a margin. The design space must touch both the fixed regions and the load regions. A load region and a fixed region must not overlap each other. Load regions can overlap the design space.
Load inventory, verify and ask, buckling
Do this before the first run. Write the result in the assumptions list (Step 2) and in the brief (record_brief).
The size of the inventory follows the part. There are three levels:
- A simple part with clear loads (a wall hook, a shelf bracket): one or two lines. Example: "Shirt at the tip (1.96 N); the wall plate holds it; an abuse pull of 30 N." Then go on.
- The user gives exact loads: use them. Check that each interface that carries force has a load or a support. Ask only about a gap.
- A part that joins other parts or carries a person: fill each column for each interface (a bore, a socket, a face, a clamp, a tip). Look at the neighbour parts. A force that a person puts on one part can reach this part through the assembly.
| Column | Content |
| Interface | each place where the part touches another part or the world |
| Neighbour | the part or the person on the other side |
| Load sources | weight, the user, the neighbour parts, the assembly (preload, press fit), heat |
| Service cases | static, operation, fatigue (cycles), impact, misuse: one line each, or "not applicable" with the reason |
| Standard | a test standard for this kind of product, or "none known" |
| Brief trace | each requirement about strength, stiffness or life, mapped to a load case or marked "not modelled, because ..." |
| Model | a load case, a support, a joint, a spring, a row, or "outside the tool" |
Worked inventory for a part that joins other parts: a bracket that holds a motor on a flange and bolts to a frame.
| Interface | Neighbour | Load sources | Service cases | Standard | Model |
| Four bolt bosses | Frame | Motor weight (4 kg x 9.81 = 39 N); reaction of the motor torque (6 N m) | Static; torque peak (twice the rated torque); fatigue from vibration; a drop in transport | Product standard, if the user has one | Weight and torque as two load cases; the bosses are fixed |
| Motor flange | Motor | Motor weight; bolt preload | Static; misuse (a person pulls on the cable, 50 N) | None known | The flange is a load region with a moment; preload is outside the tool |
Brief trace: "the motor must not move more than 0.5 mm" maps to the displacement limit of the torque case. "Must last 10 years" is fatigue: not modelled, because the tool has no fatigue analysis; the user must check it.
Verify and ask. Before the first run, say what you are not sure of: a load you guessed, a support you simplified, a requirement of the brief that you did not model. If an answer changes the part, ask the user. A sub-agent returns the questions to its caller. If you go on with a guess, write it as a guess (origin inferred in record_brief) and say it again in the final review. A plan item that you wrote and did not do is a fact for the final review.
Buckling. Turn on the check (buckling: {check: true}, CONTRACTS.md section 33) when the part has members in compression and one of these: a low volume fraction (below about 0.3), a metal, slender struts or thin walls. When the check gives a low load factor, add the row buckling.min_factor (CONTRACTS.md section 39; direct solver only). The buckling block is a top-level key of the spec; the helper copies it into the problem YAML. Report the lowest factor of each load case in the final review, or say why the check did not run.
The printer
The user names the printer; the tools fill the bed and the printer type. When the user says which printer they print on ("I print on a Prusa MK4S"), call find_printer with the name, show the user the values of the profile (derives, profile), and put printer_model: <id> in the print block of the spec. A key that the spec gives (bed_mm, printer_type) wins over the profile. With ambiguous, ask which printer. With none, follow the skill start-here, Step 1b ("A printer that is not in the catalog"): look up the maker page, show the values with their source, and call save_printer after the user agrees. A value that the profile does not give is null: say that it is unknown and do not guess it.
The filament
The user names the filament; the catalog gives the modulus and the density. When the user says which spool they print with ("PolyLite PETG"), call find_material with the name and show the user the values of the profile (derives, profile). Put filament: <id> in the material block of the spec: the YAML then gets E (the lower of the XY and Z modulus of the data sheet) and density from the profile, and nu stays the assumed 0.35, because no data sheet gives it. A key that the spec gives (E, nu, density) wins over the profile. With ambiguous, ask which filament (a family such as "PLA" gives ambiguous). With none, follow the skill start-here, Step 1b ("A filament that is not in the catalog"): look up the data sheet of the maker, show the values with their source, and call save_material after the user agrees. A value that the profile does not give is null: say that it is unknown and do not guess it. A sheet that gives no tensile modulus but a bending modulus gives E from it, and derives says so. A filament with no modulus at all needs E in the block. A density that the profile does not give is the median of its family in the catalog, labelled assumed; tell the user.
printer_materials shows what the printer can print, as facts (ok, care, no, unknown, with the reasons). topopt check and check_problem give the same answer for the filament of the YAML in the key material (compat) when the YAML names a printer. These are facts: tell the user, and the user decides. A no does not stop a run.
Preferences
The reply of environment has the key preferences. When exists is true, the file topopt-preferences.yaml in the work folder holds what the user said once: print (printer model, printer type, bed, build direction), material (E, nu, density, filament, name), filaments (the filaments the user has), quality (the voxel size) and outputs. You may use these values in the spec. You decide, and you tell the user which values came from there.
- Leave out the
materialblock, theprintblock orsettings.voxel_size, andbuild_regionstakes the missing one from the preferences. It says so inpreferences_facts: tell the user each fact in one line, for example "material from your preferences: PETG, E 2100 MPa". - Or write the values in the spec yourself. A block that the spec gives is used as it is:
build_regionsdoes not add a value of the preferences to it. A partial block (for examplematerial: {E: 1800}) keeps the defaults of the problem YAML for the keys that it does not give. Write the whole block if you want the other values of the preferences in it. - What the user says for this part wins over the preferences. If the user names another bed or another material, put it in the spec, and say that it differs from the preferences.
check_problemalso names a difference between a YAML and the preferences inpreferences_facts. That is a fact, and the YAML stays as it is. - After a run, offer the outputs that the preferences list in
outputs:renders(render_part: the images that the user gets; your own look instart-hereis a separate check),step(export_step) andverify(verify_run). Give the cost where you know it. The user decides. The final STL and the part card are made in every run. - When the preferences have
print.printer_model,build_regionswritesprint: {printer_model: <id>}into a spec that has noprintblock, and the fact names the printer and the values that it gives. Tell the user, for example "printer from your preferences: Bambu P1S, bed 256 x 256 mm, build height 256 mm". - When the preferences have
material.filament,build_regionswritesmaterial: {filament: <id>}into a spec that has nomaterialblock, and the fact says what the run takes (E, nu and density, each with its source). Tell the user, for example "filament from your preferences: Polymaker PolyLite PETG, E 1898.7 MPa". If the user has several filaments (filaments.available), ask which one is for this part. - When
existsis false, the skillstart-here(Step 1b) asks the user once andsave_preferenceskeeps the answers. If the user gives a new value for later runs ("my bed is now 300 mm"), callsave_preferenceswith it.
Step 2. Write the spec file
Write runs/<name>/spec.yaml. Use a short lower-case name with no spaces.
name: shelf_bracket
regions:
design: # one shape: a list of primitives
- box: {min: [0, 0, 0], max: [80, 30, 60]}
- subtract: {sphere: {center: [80, 15, 60], radius: 6}}
fixed: # name -> list of primitives
wall_plate:
- box: {center: [-2, 15, 30], size: [4, 36, 66]}
keep_out:
screw_hole: # today a name with "hole" in it marks a screw hole (path checks)
- cylinder: {p0: [-3, 15, 50], p1: [6, 15, 50], radius: 2.25}
load: # whole feature, with a force in load_cases
shelf_edge:
- capsule: {p0: [70, 5, 6], p1: [70, 25, 6], radius: 3}
solid: # optional: solid, no clamp, no force
end_cap:
- box: {min: [75, 0, 0], max: [80, 30, 12]}
# springs: [{region: foot, stiffness: [0, 0, 80]}] # optional: an elastic support on a load region (N/mm, total). `fixed` may then be empty.
# joints: [{region: sleeve, to: [60, 10, 6], section: {kind: round, d: 4}}] # optional: a beam from a load region to a fixed point (mm). `fixed` may then be empty.
# fixed_axes: {side_wall: [y]} # optional: the fixed region `side_wall` fixes only y (a roller, a solid body in the part). Others are full clamps.
load_cases: # same format as CONTRACTS.md sections 2 and 26.2 (moment, at, pressures)
- {name: static, weight: 1.0, forces: [{region: shelf_edge, force: [0, 0, -19.6]}]}
- {name: knock, weight: 1.0, forces: [{region: shelf_edge, force: [30, 0, -60]}]}
material: {E: 3500, nu: 0.35, density: 1.24} # optional, these are the defaults; or {filament: <id>} for a filament of the catalog (see "The filament")
assumptions: # optional: short strings, copied into the problem YAML and run.json
- "Shelf load 2 kg, so 19.6 N down"
- "Screw holes M4, clearance 2.25 mm radius"
settings: {volume_fraction: 0.25, iterations: 80, voxel_size: auto} # fraction of FREE voxels; or target_mass_g: 30 (grams the user asks for) in place of volume_fraction: one of the two keys
print: {bed_mm: 180} # optional: add only the keys that the user gave (CONTRACTS.md section 18)The print block takes printer_model (the id or the name of a printer; it gives bed_mm and printer_type when the block does not, and the print report compares the part height with the build height of the printer), build_direction (default [0, 0, 1]), bed_mm (default 220), printer_type (fdm default, sla, lpbf, sls) and self_supporting_angle_deg (default by printer type, 45). It also takes limit keys that topopt printcheck and the tool print_check compare with the finished STL: min_wall_mm, min_wall_area_pct, max_closed_void_mm3, max_bodies, max_overhang_area_mm2, max_support_volume_mm3, min_plate_contact_mm2 (CONTRACTS.md section 32). Add a limit key only when the user gives a limit. A key that the user did not give stays out of the spec, so the report and topopt check label it "assumed". Do not copy the defaults into the spec: that hides the label.
The settings block takes every key of the problem YAML settings (the cards of the keys: topopt levers, or the resource topopt://levers). The builder copies each key into the YAML as you wrote it, and the YAML loader checks the value. For example: objective (mass makes volume_fraction the start density), solver, penal, move_limit, beta_schedule, case_combine, mesh_method, objective_scale, filter_radius, min_member_mm, filter_solid_neighbours, stop_rules, perimeter_max_mm2, robust, eta_eroded, max_grid_voxels, max_active_voxels, the stress_* keys, the gpu_* keys and part_only_min_film_mm. Do not add a key to the YAML by hand after the build. Some keys have a rule of their own:
voxel_size,iterations,volume_fractionandtarget_mass_gare written by the builder from your value:voxel_sizeis the size of the grid it built (a number,auto, or--voxel),iterationsdefaults to 80, andvolume_fractiondefaults to 0.25. Give one ofvolume_fractionandtarget_mass_g.target_activeandallow_large_gridare read by the builder only. The YAML does not have them.- A key that is not in the list of the YAML stops the build before it writes a file. The message names the key and the known keys ("unknown key 'objectve' in 'settings'. Known keys: ... Options: use a known key, or remove 'objectve'"). Write the key under a known name, or remove it.
The top level works the same way. The builder copies each top-level key of the problem YAML that it does not write itself, as you wrote it, and the YAML loader checks it: springs, joints, assumptions, mirror, print, limits, buckling, interfaces, acceptance and bore_checks. A null is the same as no key. The builder writes name, regions, load_cases, settings and material itself; material takes E, nu and density only. fixed_axes is read by the builder only. A key that is in none of these lists, and a material key other than E, nu and density, stops the build before it writes a file. The message names the key and the known keys. The spec has no measure or not_printed region role (the builder refuses it), so a limits row names a load region.
Primitives (every item is one key):
| Key | Parameters |
box | min + max, or center + size |
cylinder | p0, p1 (end centres), radius |
sphere | center, radius |
capsule | p0, p1, radius (cylinder with round ends) |
bowl | center, radius (outer), wall, open (direction the cup opens to, default [0,0,1], so the shell is below the centre): a hollow hemisphere |
prism | plane (xy, xz or yz), points (polygon, 3 or more), extent ([min, max] along the third axis) |
stl | The user's own STL as a solid: path, optional plug_holes, screw_holes, ring_mm (see "Your own STL"). A closed mesh, read as mm. Not the stl kind of the interfaces block |
screw_ring | The frozen ring round one screw hole of an STL, for fixed, load or solid: path, hole, optional ring_mm |
subtract | One primitive to cut out of the items before it |
Items in one region join (union). Each fixed, load, solid and keep_out name becomes one STL.
Do not give a region the name of a primitive (for example box, stl or screw_ring). Use a clear name such as ladle_bowl.
Each load name is the name that forces[].region uses.
Use voxel_size: auto unless you have a reason. Section "Voxel size" explains the rule.
The mirror key
mirror is an optional top-level key of the spec. The design is then mirror-symmetric about up to 3 planes. The builder copies the list into the problem YAML as it is. Each plane is {normal: x|y|z, at_mm: <mm>}, with an optional align: auto|face|centre. The planes are axis-aligned and have distinct axes.
mirror:
- {normal: y, at_mm: 0.0} # the part is symmetric about the plane y = 0Facts and options:
- The engine moves the grid origin along the plane axis by less than one voxel, so that the plane is a grid plane. It tries the plane on a voxel face and through the voxel centres, and it keeps the parity with fewer label mismatches (voxels whose mirror image has another label).
align: faceoralign: centresets the parity.build_regions,topopt checkandrun.jsongive both counts. - A design voxel with no design partner is an orphan. Its mirror image is outside the grid, or it is empty, keep-out, fixed or load. An orphan stays a free variable. The tools give the count, the share and the cause. Regions that are symmetric about the plane give 0 orphans. When all or most design voxels are orphans (for example when
at_mmis far from the part), the tools say that the mirror has no or little effect, give the extent of the grid along the plane axis, and name the options: checkat_mm, move the plane, make the regions symmetric about it, or remove the key. - The loads are not mirrored. For each load case, the tools give
|f - R f| / |f|about each plane (0 is symmetric, 2 is antisymmetric). A case that is not symmetric, for example apull_offcase with a side force, gives the best symmetric design for that load and not the best design. Options: leave the plane out, make the load symmetric, or keep it and tell the user. - A plane that is not axis-aligned, a repeated axis and more than 3 planes are refused with a one-line message. The option is to re-orient the part (the regions and the loads) so that the plane is axis-aligned.
- The mirror gives no speed-up. The finite element model and the optimizer keep the full size. The run time is the same.
The assumptions key
assumptions is a list of short strings. The builder copies it into the problem YAML. The engine ignores it. run.json keeps it.
It does not block a run. It is a fact list for the user.
Write one line for each of these:
- Critical dimensions: the sizes that the part must keep (a hole spacing, a lip height, a gap).
- Scale of a sketch: the dimension or the object that gave the scale, and each size taken from the proportions.
- Loads: the source of each force (for example "0.2 kg x 9.81 = 1.96 N down") and the abuse case.
- Keep-outs: what stays empty and why.
- Minimum printable dimension: the thinnest member you accept. The tools give a fact: members thinner than about one voxel or one filter radius (the larger) are not resolved.
settings.min_member_mm(optional, in the specsettings) asks for a minimum member. The engine derives the filter radius from it by one rule (filter_radius = 1.877 * min_member_mm: a wall of the requested thickness just survives the filter). It is an estimate, not a guarantee: in one calibration case the 5th percentile of the interior thickness was 8 to 22 percent below the request, a skin at a free face of the design space was about 1 voxel, and a thin rod of the request size is removed. The radius is large, sotopopt checkalso prints the filter size and the filter memory (the matrix is part of the memory estimate), and amin feature:line that says in mm what the radius keeps (walls and rods, interior and free faces). An explicitfilter_radiuswins.topopt checkprints the request, the derived radius and the facts with options (for example a request below 2 voxels).settings.filter_solid_neighbours(optional):density_one(default) lets the filter see fixed, load and solid voxels as density 1.ignoreleaves them out, so a design voxel next to them is not pulled to solid.topopt checkprints asolid pull:line with the number of design voxels that the default rule pulls (a filtered density above 0.1 from solid neighbours alone) and the largest pull.settings.robust(optional):off(default),erodedorwall. Eroded mode keeps the volume and the printed shape on the nominal design and computes the stiffness on a thinner (eroded) design, so a member that is too thin for the filter radius gets no credit.settings.eta_eroded(optional, between 0.5 and 1, default 0.55) sets the erosion threshold. Write both keys in the specsettings; the builder copies them into the problem YAML. In an eroded runcompliance_finaland the stiffness inmetrics.jsonare the printed (nominal) design, and the history curve is the eroded design.topopt checkprints therobust:lines and the facts with options (the radius rule is for the default threshold; the last beta; a solver without a parity test).wallis the eroded form aimed at the print wall: it takes the wall w fromprint.min_wall_mm(a YAML error with options without it), setseta_erodedto 0.7 unless you write it, derives the filter radius R = max(w / L(eta_e), 1.5 voxels) (R = 1.52 mm at w 1.2 mm; a writtenfilter_radiuswins andmin_member_mmis only reported), and pads the density filter with void so that a wall at a face of the design space is as thick as an inner wall. On the hook example (voxel 0.5 mm, wall 1.2 mm) the share of the surface area under 1.2 mm fell from 4.145 to 0.000 percent for +7.9 percent compliance and 1.07 times the run time. Whenprint.min_wall_mmis set androbustis notwall,topopt checkgives a fact with these numbers; the mode is your choice, and it is not on by itself.
The perimeter_max_mm2 setting
settings.perimeter_max_mm2 is optional (in the spec settings; a number above 0, in mm2). It adds one constraint row: the surface area P of the part stays at or below the bound. Use it when the user gives a limit on the surface (for example a coating area, or a print time that follows the surface). Without the key the run is the same as before. The builder copies the key into the problem YAML.
Pis the area of the voxel faces between the part and the void (a staircase surface; in one measured problem about 1.24 times the area offinal.stl). Solid regions (fixed, load, solid, spring) count as part. Faces to keep-out voxels and to the outside of the grid count as void. The unit is mm2.topopt checkprints aperimeter:line with the bound, the fixed part (solid voxels next to void), the smallest possibleP(a minimum cut of the design space) and the bound over the smallestP.check_problemgives the same numbers under the keyperimeter. The ratio is a fact. A bound near the smallestPleaves little material to spend, so the stiffness drops or another row (volume, compliance) stays unmet.- The engine refuses a bound below the smallest
P: no design with density 0 or 1 can meet it (a gray design can be a little below it, only near void). The message gives the bound, the fixed part, the smallestP(rounded up to 0.1 mm2, so the engine accepts the shown value as a bound) and the options: raise the bound, reduce the solid regions, make the design space bigger. The filter can keepPabove the smallest value, so the smallestPis a floor and not a promise. - A mass objective keeps its volume ceiling: the row limits the surface and not the material (in the measured problems the empty design had the smallest
P). The row has price 1000 and a compliance limit has price 100, so a tight bound can leave a compliance limit not met; the run log says so and gives the option to raise the bound. run.json(perimeter),history.jsonl,metrics.json(constraints,rows) andrun.loggivePat the start and at the end, and say if the bound is met.
Your own STL
Use this when the user has an STL of the part. It takes the place of Step 1. Step 2 to Step 5 stay. CONTRACTS.md sections 45, 45.1 and 45.2 have the detail.
- Put the file in the work folder, or use its absolute path. Call
find_featureswith the path. It reads the file and changes nothing. - Check the size. An STL has no unit: topopt reads every file as mm. The reply has
mesh.size_mm. If the size looks like metres or inches (for example a hand-size part that is 0.2 across), ask the user. There is no scale key: the user exports the file again in mm. A mesh that is not closed, or has inward faces, is an error with the cause. The builder does not repair a mesh. - Show the holes and the big flat faces in a short table, one line each (equal holes in one line):
H1d 4 mm, 4 mm long, through, at (30, 10, 0);F1760 mm2, normal (0, 0, -1). The ids are stable for one file. - Ask only what changes the problem. Do not ask what the file shows.
- Which holes take a screw? Each gets a frozen ring (
screw_holes). - Which holes should be filled, so that the optimizer may use that material? (
plug_holes.) A hole that you do not name stays as the file has it. - What is mounted: which holes (a
screw_ringitem infixed) or which face (aboxon that face)? Where does the load act, and how large? The load has no default (top of this file). - May the part grow? A growth box is one more item in the design region. Ask how far.
- Which holes take a screw? Each gets a frozen ring (
- Write the spec (below), call
build_regionsandcheck_problem, and fix errors as in Step 4. - Say the assumptions (Step 5). Add: the size that you read in mm, the thickness t of each ring and why (the report has one line for each screw hole), the holes that you plugged, and the growth box.
name: bracket
regions:
design:
- stl: {path: bracket.stl, screw_holes: [H2, H3], plug_holes: [H4]} # the part: a ring round H2 and H3, H4 filled
- box: {min: [0, 0, 10], max: [60, 30, 18]} # optional: a growth box
fixed:
wall:
- screw_ring: {path: bracket.stl, hole: H2} # screwed to the wall at H2
load:
pull:
- screw_ring: {path: bracket.stl, hole: H3} # the force acts on the ring of H3
load_cases:
- {name: static, weight: 1.0, forces: [{region: pull, force: [0, 0, -30]}]}
settings: {volume_fraction: 0.4, iterations: 80, voxel_size: auto}path: a relative path starts at the work folder for the toolbuild_regions, and at the folder of the spec file for the script.plug_holes: hole ids, orall. The plug fills the wall of the hole. A chamfer at the mouth and a drill point stay.screw_holes: hole ids, orall. Each hole gets atubeinterface (CONTRACTS.md section 23): a solid ring that the optimizer does not remove, and the hole stays free and round. No support and no force act on this ring: for that, use ascrew_ringitem infixedorload. A hole is plugged or it takes a screw, not both. A notch and a cavity take no ring.- The thickness t of a ring: 0.5 x the hole diameter, at least 2 voxels (the default).
ring_mmsets it: a number for all rings of the item, or{H2: 2.5}for one hole. It is a method setting: set it when the user asks for a thicker or thinner ring, and say so. A user who gives a wall thickness gives a requirement: use it asring_mmand say it. screw_ring: the same ring as a region item. Give it the samering_mmas thescrew_holesof that hole (aWARNING:says when the two differ).- Another exact interface (a bore, a boss, a face) is the spec key
interfaces: a list as in CONTRACTS.md section 23. The builder copies it into the YAML, before the rings.references/patterns.mdhas the rules of theinterfacesblock, also for these rings: what to set, and what to read incheck_problemandrun_result. - A ring that leaves the part (a hole near an edge) gets a
note:with the volume: the exact union adds that material outside the part. A keep-out region wins over a ring (WARNING:).
Step 3. Build and check
The MCP tool build_regions does this from a spec given as data (a dict, or the YAML text). The same code runs as a script:
CLAUDE_PLUGIN_DATA="${CLAUDE_PLUGIN_DATA}" sh "${CLAUDE_PLUGIN_ROOT}/scripts/topopt-env.sh" python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/part-to-topopt/build_regions.py" runs/<name>/spec.yaml --out runs/<name>A relative path of an stl or screw_ring item starts at the work folder for the tool, and at the folder of the spec file for the script.
The script is a thin wrapper for topopt/regions_builder.py. (In a source checkout: .venv/bin/python .claude/skills/part-to-topopt/build_regions.py runs/<name>/spec.yaml --out runs/<name>.)
The command writes the STL files and runs/<name>/<name>.yaml. Then it runs the topopt input layer.
It prints the grid, the voxel counts for each region, the active voxel count, the volume basis (free and forced-solid voxels, the target volume and mass), the free dofs, two time estimates (the model value, and the model value scaled by the fill of the part), and a memory estimate line (GiB against the RAM of the machine).
Use --check to test a spec and write nothing. Use --voxel H to force a voxel size.
The last line is RESULT: OK or RESULT: FAILED.
The MCP tool build_regions and topopt check also give the derived numbers: the force of each load case in N (vector and size), the design block in mm3, the target mass in g, the mass of the full block in g, the voxel size and the minimum feature size.
State these numbers with your assumptions. Ask the user before the run when an answer changes the part (the top of this file has the rule).
After build_regions, call record_brief with the brief and your assumptions. The case file keeps them beside the YAML with the hashes of its input files, and run_topopt says when an input file changed since (CONTRACTS.md section 30).
Also run the official check once: the MCP tool check_problem with runs/<name>/<name>.yaml (the CLI gives the same data: topopt check runs/<name>/<name>.yaml).
The check prints a solver: line. On Linux x86_64 without pypardiso (--json gives the same data as JSON) it also prints a recommendation: line. The facts in it:
- The run uses the AMG solver. PARDISO is faster. The factor depends on the problem (
speedup_factorin the line). The line gives the time estimate for this problem with and without PARDISO (a rough model, the same one as for the Mac). install_commandinstalls the optional extrapardisointo the environment that runs topopt.pypardisopulls Intel packages (about 456 MB in a fresh venv).mkl,tbbandtcmlibhave the Intel Simplified Software License.intel-openmpandintel-cmplr-lib-urhave the Intel EULA for Developer Tools, which has more limits (for example, no use in a hosted service).umfis Apache-2.0. Themklversion is not pinned. Thelicense_notefield has the same text. Tell the user this before you install.- If the action is
fix_pypardiso_load, pypardiso is already installed but does not load. Theerrorfield has the cause (often the MKL library). A new install often does not fix a load error. Theerrorfield gives the cause.
If the check prints this line, offer the install to the user, with the speed-up as the reason. When the user agrees, run install_command. If the user declines, the run goes on with AMG.
Step 4. Fix errors
Read the message. Change the spec. Run again. If the same problem stays, tell the user what you tried.
The auto retry grows the voxel only for a voxel-count guard failure. A bigger voxel does not fix other errors (for example separate pieces). Fix the spec.
Some messages are WARNING: lines. They are facts and do not stop the build. Decide if you act on them.
A guard stop is not an error in the spec. The guards are max_grid_voxels and max_active_voxels (the engine) and the RAM block (allow_large_grid). They are method settings: you decide with the facts and report what, why and the price. An override uses more memory and time. The risk: a run above the RAM can freeze the machine (a 0.5 mm whole-domain grid crashed a 16 GB Mac).
- Read the numbers of the message, the memory estimate (
check_problem.memory_estimate, or the line that the helper prints) and the RAM of the machine. - The options of the message have names: the override (for example
settings.max_grid_voxels) and the voxel size that fits. Take one. - Tell the user what you took, why and the price (memory, time, a coarser voxel). If the estimate is above the RAM, say the risk with it.
- If the user gave the voxel size, it is a requirement (its origin in
record_briefisuser): a larger voxel loosens it, so ask the user first and bring these facts.
| Message | Fix |
WARNING: region '...' is small or thin | The region has fewer than 30 voxels, or it is less than 3 voxels across. The optimizer can cut it off. Make it the whole solid feature, or use a smaller voxel size. A small region is allowed. |
WARNING: force is lost: ... | Load nodes touch fixed nodes. The solver drops their force. The warning gives the lost N and percent (lost_force in the check data, per load case and per region). Move the load region off the fixed region (keep a gap of one voxel or more), shrink the overlap, or accept it. Tell the user the number. |
load region '...' has no force | Add a force in load_cases, or move the region to solid. |
min_member_mm ... voxels (a fact, with options) | The request is below 2 voxels at this voxel size. Use a smaller voxel size (3 voxels across), a bigger request, or accept it. |
settings.filter_radius ... is set, so it is used (a fact) | Both filter_radius and min_member_mm are set. The explicit radius wins. Remove one of them, or keep both. |
settings.perimeter_max_mm2 is ... no design with density 0 or 1 can have a perimeter below ... | The bound is below the smallest possible P (a minimum cut). Raise the bound to the value in the message or above (the value is rounded up to 0.1 mm2, so the engine accepts it), reduce the solid regions, or make the design space bigger. |
the supports leave ... rigid-body modes free | The roller axes do not block every motion of the part. The message names the free motions. Add axes, or add a support that blocks them. |
... cannot carry the moment | The nodes of the load region lie on a line along the moment axis. Make the region wider across that axis, or use a force pair. |
pressure on load region '...': no face ... | No face of the region looks into free space or a keep-out region. Shape the region so that the loaded face is free. |
WARNING: forced-solid voxels are ... percent | Fixed, load and solid regions are more than 60 percent of the model. Little is left to optimize. Make them smaller, or make the design space bigger. |
ERROR: the active voxels make N separate pieces ... (topopt run stops with this error) | A piece has no support: no fixed voxel (and no spring or joint region) in it, because a region shares no face with the rest of the part. The run would stop. Move the region, or make the design space bigger so they touch. |
WARNING: the active voxels make N separate pieces ... each holds a fixed voxel | A fact. Every piece holds a support, so each piece is fixed and the run works. A load on one piece does not reach the other pieces. If you want one part, make the pieces touch. |
note: region planes off the voxel grid: N of M change the part ... (also in warnings and check.region_planes) | A fact, and most parts have it. A voxel belongs to a region when its centre is inside the region, so a flat face whose plane is not on a voxel face moves to the nearest voxel face. The note gives the voxel size, the grid origin (the min corner of all regions: it moves when such a region moves), and one item for each plane that changes the part: the region, the plane, and how much larger or smaller than your shape the region is. It matters where two regions should meet at one plane (a wall and the part, a keep-out and a surface). Move or resize the region so that the plane is on a voxel face, choose a voxel size that divides the distance from the grid origin, or extend a keep-out region past the part. check.region_planes has all planes, and changes_part is false for a plane under a region of higher priority or outside the part. Nothing is snapped for you. |
WARNING: no fixed voxel touches a design voxel | A fact. The fixed region shares no face with the design space. The message gives the distance and says if every design voxel is in a piece that holds a support (then the part is held through load or solid voxels, and the run is not stopped). If you want the plate to touch the design, overlap them by 1 or 2 mm. If the path through a solid body is what you want, keep it. |
no voxel left | A keep-out region covers a whole region. Shrink the keep-out. |
WARNING: the estimate is above your time budget of ... s (settings.stop_rules.time_budget_s) | A fact, and only for a YAML that sets settings.stop_rules.time_budget_s: the budget is the user's own. It is a stop rule, not a note, and the message says what it does in this YAML. With the stop rules on (a stop_rules mapping turns them on), the run stops at the first pass after the budget (rule time_budget), and the part is the design of that pass. With enabled: false the budget is set but the rules are off, so the run does not stop at it. The options: a larger voxel (the voxel size that the message names), another budget (ask the user), or all passes with the stop rules off (enabled: false in the YAML, or run_topopt(stop_rules=false) for one run). |
grid would have ... voxels at voxel_size ..., the limit is ... or model has ... active voxels | The engine guard (max_grid_voxels, max_active_voxels). Options: a larger voxel_size, or a higher setting in settings of the spec if the machine has the memory. Decide with the facts (see above). With auto the helper grows the voxel 8 percent and tries again, up to 3 times. |
ERROR: the memory estimate ... is above the RAM | The estimate is above the RAM of this machine. A run can crash it. Options: a larger voxel, or allow_large_grid: true in settings to build anyway. Decide with the facts and say the risk (see above). |
ERROR: the grid alone needs about ... GiB | The grid is too big for the RAM before any solve. Options: a larger voxel, or allow_large_grid: true (and maybe max_grid_voxels) in settings. Decide with the facts and say the risk (see above). |
SPEC ERROR ... | The message names the region and the item, or the key path of the value (for example load_cases[0].forces[1] must be a mapping, for example {region: tip, force: [0, 0, -2]}, got int 5). It says what the spec has and what it expects. Fix that key. |
not a closed solid | A subtract removed everything, or a primitive has zero size. For an stl item: the file is not a closed solid (the message counts the open edges), its faces point inward, or a plug left the mesh open. The builder does not repair a mesh: ask the user for a closed file. |
...screw_holes: ... is also in plug_holes, ... not a closed ring, ... a cavity | A hole is plugged or it takes a screw. A notch (an arc) and a cavity take no ring: leave them out of screw_holes (a list, not all). |
...: a screw ring is a frozen shape | A ring is for the part. Put the stl item in design, fixed, load or solid, and a screw_ring item in fixed, load or solid; not in keep_out or subtract. |
note: ... the ring of H1 ... outside the part | A fact. The hole is near an edge or a face, so part of the ring is outside your part, and the exact union adds that material. Tell the user the volume, or give a thinner ring with ring_mm. |
WARNING: ... the ring of H1 ... overlaps the keep_out region | The keep-out region wins: the ring is cut there. Move the keep-out region, or give a thinner ring. |
WARNING: ... ring_mm: ... under 2 voxels | The ring is less than 2 voxels thick at this voxel size. Use a smaller voxel, a thicker ring, or accept it. |
Voxel size (time and memory)
The helper has no time limit of its own. The only time budget is the one of the user, settings.stop_rules.time_budget_s in the YAML. The helper reports the time as an estimate and you choose. Tell the user the estimate in plain words, and say that it is an estimate: a run can take less or more time. Where the reply has a band, give the band.
The cost depends on the number of free dofs, which is about 3 x the number of active voxels.
The shape of the part also matters. A compact part costs more than a slender part, because the solver needs more fill-in for it.
| Run (measured 2026-10-11) | Active | Free dofs | Estimate | Real | Real / estimate |
| T-shirt hook (compact, fill 0.36) | 39,944 | 115,836 | 145 s | 148 s | 1.0 |
| Ladle (slender, fill 0.06 to 0.09) | 33,407 | 114,780 | 143 s | 38 s | 0.27 |
"Fill" is active voxels divided by grid voxels. The model estimate is the number for a compact part: the hook ran 1.0 times it and the slender ladle ran 0.27 times it (a factor of about 3.7). Both are runs on Apple silicon. On a shared Linux host, experiment E1 (a run-time study) found finished PARDISO runs with 50,000 free dofs and more at a median of 2.19 times the model total, so the model is not an upper bound. check_problem gives the measured "up to" value in derived.time_estimate_up_to_s and derived.memory_estimate_up_to_gib (facts only; null on macOS and below 10,000 free dofs, where E1 found the time estimate high).
The time model is calibrated on Apple silicon with the Accelerate Cholesky solver. For amg, the check scales the time per iteration with a rough factor (CONTRACTS.md section 4); use its estimate for the solver that runs.
Facts and options:
- The helper prints the model value and the model value scaled by the fill of the part (an estimate each). The scale goes from 0.27 (fill 0.085 or less) to 1.0 (fill 0.30 or more).
- When the YAML sets
settings.stop_rules.time_budget_sand the estimate is above it, the helper prints a warning with a voxel size that would fit. The helper does not change the voxel and does not stop the build. The run is different:time_budget_sis a stop rule. Astop_rulesmapping turns the stop rules on (the ruleconvergedtoo), and the run stops at the first pass that ends after the budget. The part is the design of that pass. The clock of the rule is the run time at the end of a pass: it counts the setup and the passes, not the post step, but the estimate counts all three. So a run with an estimate just above the budget can still make all its passes. Withenabled: falsethe run does not stop at the budget. Tell the user which case it is, and give the options of the table (a larger voxel, another budget, or all passes with the stop rules off). Without a budget of the user there is no time warning: the estimate is a fact. - Voxel size against time: free dofs grow as 1 / voxel^3, and the time per iteration grows about as dofs^2.4. A voxel 10 percent bigger gives about 25 percent fewer dofs and about half the time per iteration.
- Default aim of
auto:voxel = cbrt(active_volume_mm3 / target_active), rounded up to 0.05 mm. The active volume is design + fixed + load + solid, minus keep-out. The defaulttarget_activeaims at an estimate of about 120 s for 80 iterations (the model scaled by the fill; an aim, not a limit), at most 41,000 active voxels. A compact part gets about 36,000 (estimate about 120 s). A slender part gets 41,000 (the scaled estimate is 70 to 85 s, and the model value is 190 to 230 s). - To aim elsewhere, set
settings.target_active(withvoxel_size: auto) or give avoxel_sizenumber. The helper uses your value as it is. - Memory: the helper prints a rough memory estimate (grid arrays, the Cholesky factor and the filter) and the RAM of the machine. A 0.5 mm whole-domain grid crashed a 16 GB Mac. The helper blocks only when the estimate is above the RAM.
settings.allow_large_grid: true(a real boolean) overrides this block. Read the estimate against the RAM first (Step 4). - On Linux, the RAM that the helper shows is the host RAM or the cgroup (container) memory limit, whichever is lower (
topopt.cli.physical_ram_bytes). It is the size of the limit, not the free memory. Other processes in the container can use a part of it. - The memory model is fitted to the peak RSS of measured Cholesky runs. The AMG backend uses less.
- The engine has its own guards:
max_grid_voxels(5,000,000 by default) andmax_active_voxels(100,000 by default). To go beyond, set them insettingsof the spec (Step 4 has the facts to read first). The error message names the setting. - A thin feature needs about 3 voxels across to survive. If it is thinner, make it thicker in the spec, use a smaller voxel, or accept a rough result.
- A thin feature can need a finer voxel than the run has. When it does,
check_problemhas the keyfine_pass(recommendis true;topopt checkprints one line): the voxel that the part needs (voxel_mm, one value: the thickness is twice the radius of the largest sphere inside the region, over 2.8, rounded down to 0.05 mm; the fine pass tests it on its own grid and goes down in steps of 0.05 mm if a region has too few voxels across there), the feature that sets it (limiting: 2.8 voxels across a thin region, 3 acrosssettings.min_member_mm), and estimates of the time and the memory of a fine pass. The option is a fine pass. It runs the same problem on the finer voxel and starts from the design of a finished run:run_topopt(yaml_path, out_dir=NEW, fine_from=PARENT), orrun_topopt(yaml_path, out_dir, fine_pass=true)for the first run and the fine pass in one call (the fine pass goes to<out_dir>-fine, and the reply names both folders). The same YAML works. The voxel of the fine pass is the voxel of the part, orfine_voxel. The fine pass ends when its loss has settled (the change of the objective between passes is at mostfine_tol, orsettings.fine_pass.objective_changein the YAML, default 0.001), or at the maximumfine_passes(default: the pass count of the parent run);stop_rules=falseturns every early stop off.check_problem.fine_pass.guardssays if the fine grid failsmax_active_voxels,max_grid_voxelsor the memory, with the finest voxel that passes (fine_voxel). In two measured parts the result came within 0.5 % and 2.1 % of the compliance of a run from zero at the fine voxel, with fewer passes at the fine voxel. The first run is extra time, and every time and memory number is an estimate. Give the user the numbers and the choice. A fine pass starts only when you call it.
Patterns (read on demand)
Read references/patterns.md in the folder of this skill when the part is a bowl, cup, scoop, ladle, dish or container; a handle or a grip; or has a surface that a neighbour touches or that needs an exact size (a socket, a seat, a press fit, a sealing face, an end trim, a bore or a boss with machining stock). It has three patterns, and the interfaces block of the spec.
Pre-flight checklist (do this in your head before the helper)
- Does each load region cover the whole feature, with about 3 voxels across at the planned voxel size?
- Does each load region have a force in
load_cases? Does a no-force body usesolid? - Do fixed, load, solid and design shapes touch or overlap each other? Is there one body only?
- Are the forced-solid regions (fixed + load + solid) less than about 60 percent of the active volume? (Above this the helper warns.)
- Is the volume fraction the fraction of the FREE voxels, and is it between 0.15 and 0.4?
- Today the screw-hole check finds holes by "hole" in the keep-out name. Does each screw hole have it, and no other keep-out?
- Is the part smaller than the bed (
print.bed_mm, or the bed ofprint.printer_model; the default is 220 mm) in two directions, and lower than the build height of the printer, if it has one? Are all numbers in mm and N? - Does the abuse case have its own direction and a weight?
- Does the part work with the objects around it (a lip for a hanging object, clearance for a nested object)?
- Does each surface that a neighbour touches (a socket, a seat, a press fit) have
full_surface: true, and does each end face haveradius_mm? (references/patterns.md) - For an STL of the user: did you read the size in mm, show the holes, and ask which holes take a screw, which are plugged and what is mounted? Does the summary say the ring thickness and the plugged holes?
Step 5. Print the summary
Write a short summary for the audience in plain words. Use at most 10 lines.
- What the part is, and its size in mm.
- How it is held (fixed regions, in words).
- The loads: the force in N, its direction, and why (for example "0.2 kg x 9.81 = 1.96 N down"). Name the abuse case. For a moment, a remote force or a pressure, give the value and where it acts. The stiffness figure of such a case is
n/a: say so. - What stays empty (keep-out regions) and why.
- Material and the volume fraction. If a value came from the preferences file, say so.
- The assumptions you made and the open questions (one line each). Use the
assumptionslist and thederivednumbers. - The time estimate in plain words, and any WARNING line. Give the voxel size, the active voxel count and the memory estimate when the user asks.
- The YAML path, and how the run starts: the MCP tool
run_topoptwith that path (the CLI:topopt run runs/<name>/<name>.yaml --out runs/<name>_run --dashboard).run_topoptreturns the dashboard URL. Give it to the user.
Write the summary in the user's language, in plain words, with short sentences.
After the first finished run: offer the stress check
When the first run of a part has finished, you can offer the stress check once. It answers "will it break under these loads?" with a second model of the finished part (verify_run: another mesh, quadratic tets, one line for each load case). Say what it costs: it needs the extra verify, and verify_run with estimate_only (the default) gives the memory and the time first and starts nothing. Say that a yes or no needs an allowable stress, and the user gives it (allowable_mpa). Without one, the check gives the stress values only, and topopt://materials/reference has typical data sheet values. This is an offer: the user decides, and a "no" ends it for this part. When the job is done, verify_status has plain: one plain line for each load case, with the source of the allowable and the margin. Give these lines to the user as they are. A margin is a ratio of two numbers.
Worked example
examples/hook_spec.yaml in the folder of this skill rebuilds the T-shirt hook. It uses a prism for the design space and two cylinders for each screw hole.
Blind test record (read on demand)
references/blind-test.md in the folder of this skill is the record of a blind test of this skill (2026-10-12, a gravy ladle). Read it only when you check how this skill did in a test.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

