How-to recipes

Task-oriented. You have a goal; this is the shortest path to it.

Each recipe answers one "how do I…?" question. They assume you already know your way around apeGmsh — if you don't yet, work through the Tutorials first, and lean on the Concepts pages when you want to understand why something works the way it does.

Most tasks below have a dedicated recipe page. A few still link into the topic guide where the answer lives — so this index is useful for every task, not just the ones with a tidy page yet.

Geometry & CAD

• Import and heal a STEP file — load CAD, diagnose and heal dirty geometry, name faces, and get a meshable model.
• Tag a face as a physical group — name an imported or constructed face by query so you can target it later.
• Set a local mesh size — refine the mesh on a specific entity instead of globally.

Build & assemble

• Build a multi-part assembly — template a Part, place copies, and fragment them into one conformal mesh.
• Save a model and reload it — persist to model.h5 with save_to / g.save, and bring it back with FEMData.from_h5 / apeGmsh.from_h5.
• Compose models from saved modules — combine independently-saved .h5 parts with g.compose / apeGmsh.from_h5 (and the sub-path Assembly builder).

Physics

• Apply gravity / self-weight — add a gravity body force to a part or the whole model.
• Apply a face pressure or traction — put a distributed load on a named face or edge.
• Add a point load — apply a concentrated force or moment at a node set.
• Fix supports & boundary conditions — pin, roller, or fully-fix nodes, and prescribe a non-zero support displacement (SP).
• Tie two non-matching meshes — couple two members across a non-conformal interface; the constraint auto-emits through the bridge.
• Add a rigid diaphragm or rigid link — constrain a set of nodes to move as a rigid body.

Solve (the OpenSees bridge)

• Compute section properties for a custom section — mesh a flat face, run SectionProperties (geometric / warping / plastic / stress), and bind it to the bridge with ComputedSection.
• Author a section document — build a section as saveable, re-editable JSON (SectionDocument), open it in the Qt builder, run moment–curvature, and hand it to a frame model.
• Run a static analysis — drive a gravity/lateral static solve through apeSees(fem).
• Run a modal (eigenvalue) analysis — set up mass, call ops.eigen, and pull periods and mode shapes.
• Run a pushover — displacement-controlled nonlinear static analysis to a target drift.
• Export to a Tcl or openseespy script — emit a standalone runnable deck with ops.tcl / ops.py instead of solving in-process.
• Checkpoint & resume an analysis — save committed solver state with database/save, recover it with restore, and benchmark that a restart reproduces the uninterrupted run.

Results

• Read a node's displacement and reactions — pull nodal results back by physical-group name.
• Plot a deformed shape or contour — fill a slot, set the pose, render() a still off results.session() with no Qt.
• Arrange panes, slots and time in code — the ResultsSession document results.viewer() opens: panes, the seven-slot catalog, legends, snapshots.
• View results in a notebook — the kernel-safe show_web viewer.
• Get results via MPCO (STKO) — record to .mpco and read with Results.from_mpco(model_h5=...).
• Choose how to get results — the run × read decision: in-process vs export, and from_native / from_recorders / from_mpco.
• Drive Studio / MCP habitat — spawn MCP + Qt host, project root, file ownership, poll contract, cold start.

---

Next: Import & heal a STEP file.