Skip to content

Backend capabilities

Most of apeGmsh needs nothing but pip install apeGmsh. Solving needs an OpenSees backend, and a minority of the OpenSees surface needs one particular backend — the Ladruno fork. This page is the map: what runs where, how a missing capability announces itself, and how to check the environment you are actually in.

The short version:

Tier Needs What it covers
0 nothing beyond the install extras Geometry, meshing, parts, the FEM broker, model.h5, loads / masses / constraints, deck emission, results, viewers, sections, Studio
1 stock openseespy In-process solving: ops.run(), ops.analyze(), ops.eigen(), recording a run with emit_default
2 the Ladruno fork build The primitives listed under The fork-only surface

Deck emission is never gated

ops.tcl(...) and ops.py(...) write a runnable deck for every primitive on every build, fork-only ones included. You can model and emit on a laptop with stock openseespy — or with no OpenSees at all — and run the deck on a machine that has the fork. Only the in-process run (ops.run() / ops.analyze()) is gated.

Which build am I on?

python -m apeGmsh doctor

Finding D5 names the resolved backend. A warn D5 reading "Stock openseespy backend" is normal and not an error — it means tier 2 is unavailable, nothing more.

In code:

from apeGmsh.opensees import apeSees

ops = apeSees(fem)
ops.capabilities().has_fork      # True on a Ladruno build

Resolution order is APEGMSH_OPENSEES_BIN → a bare import opensees → import openseespy.opensees. To use a fork build, point the environment variable at the folder holding opensees.pyd before the first emit:

set APEGMSH_OPENSEES_BIN=C:\path\to\Ladruno\dist\bin

When your own code talks to the model the bridge built, such as a custom analysis loop after ops.run() or a query after ops.analyze(), take the module from the same resolver rather than importing one by name:

from apeGmsh.opensees.emitter.live import get_ops

opspy = get_ops()     # the module, and so the domain, the bridge drives

Beside a fork build, import openseespy.opensees binds a second module with its own, empty domain, and every query answers from that one.

A fork build recent enough to answer ladrunoSchema() (fork PR #972) also says what it can do: the commands its engine registers and the option tokens each fail-closed parser accepts. get_backend_info() reads it, so info.supports_option("LadrunoRCConcrete", "-implexControl") answers True or False. apeGmsh reads schema versions 0 and 1. Version 1 is version 0 plus a capabilities list of the behaviours the build promises, read on info.schema.capabilities; every other key keeps its version 0 meaning. A version 0 schema (older fork builds) reads with an empty capabilities set. An older build with no ladrunoSchema(), a schema version other than 0 or 1, a schema whose keys are not exactly that version's, or a schema that disagrees with ladrunoBuild() reads as unknown capabilities, and the same query answers None. An unknown answer is never False, and it never changes whether the build counts as the fork. Command answers speak only for the in-process engine, not for a Tcl binary that a subprocess runs.

The fork is mostly a source build

The Ladruno fork lives at nmorabowen/OpenSees and publishes no wheels. The build that apeGmsh's nightly live-fork lane tests, the one FORK_PIN names, is a Linux release tarball built for Python 3.11 and linked against MKL. For any other platform, such as Windows, tier 2 still means compiling OpenSees yourself. If you are evaluating apeGmsh, plan on tiers 0 and 1 and treat tier 2 as opt-in.

How a missing capability fails

Nothing in tier 2 fails silently — but the two classes read differently, so it is worth knowing which you are looking at.

Class What you see Which primitives
Gated by apeGmsh RuntimeError naming the fork, what still works, and the stock alternative Elements, integrators, the LadrunoProjection handler, contact, FEAST, profiler, the modal family, the mpm family (live route, every build)
Rejected by the engine OpenSeesError: See stderr output, with an unknown … warning on stderr Materials, system Pardiso, the fork recorders

The first class exists because those commands are the ones stock OpenSees would otherwise accept. The fork integrators, for example, are unknown to stock, yet integrator ExplicitBathe is accepted silently and the analysis steps on with the previous integrator — a converged wrong answer instead of an error. The gates convert that into a refusal.

A few stock behaviours are refused for the same reason even though nothing in them is fork-only. See Stock engine defects.

The fork-only surface

Elements

BezierTet10, BezierTri6, LadrunoBrick, LadrunoBrick20, LadrunoCST, LadrunoDispBeamColumn, LadrunoDistributingCoupling, LadrunoEmbeddedNode, LadrunoEmbeddedRebar, LadrunoForceBeamColumn, LadrunoIMKBeam, LadrunoKinematicCoupling, LadrunoLST, LadrunoMembrane, LadrunoQuad, LadrunoRigidBody, LadrunoUP

Reached through ops.element.*, and also indirectly: g.reinforce (embedded rebar), g.embed (embedded node), and g.constraints.kinematic_coupling / distributing_coupling (RBE2 / RBE3) all emit elements from this list.

LadrunoMembrane's diaphragm_nodes= (-diaphragmNodes) and f11= / f22= / f12= (-f11 / -f22 / -f12) need fork build c83ee812e or later. From that build on, every node of the panel (outer loop, holes, supports and diaphragm nodes) gets in-plane stiffness. An older build condenses the diaphragm onto the outer loop only. The diaphragm passes the constant-strain patch test from fork build b6d3e3d2 on; on c83ee812e its in-plane stiffness reads about a quarter low. So the live route and every emitted deck refuse these options on a build not measured to carry b6d3e3d2.

Integrators

CentralDifferenceLadruno, CentralDifferenceSMS, ExplicitBathe, ExplicitBatheLNVD, ExplicitBatheLNVDSMS, ExplicitBatheSMS, LadrunoArcLength, LadrunoDynamicRelaxation, LadrunoGeneralizedAlpha, LadrunoHHT, LadrunoIndirectControl, LadrunoLoadControl

LadrunoLoadControl also needs a recent fork build (2026-08-04; its default -tangentPredictor 2026-09-04). An older fork build accepts the unknown integrator and keeps the previous one, so the in-process run checks for the fork's ladrunoLoadControl command and then confirms the predictor was armed — an older build is refused, not run as stock LoadControl.

Stock schemes — Newmark, HHT, CentralDifference, ExplicitDifference, LoadControl, DisplacementControl, ArcLength — are unaffected and run on any build.

Constraints and coupling

  • enforce="equation" ties are not fork-only. g.constraints.tie(...) and Assembly.couple(...) with enforce="equation" emit equationConstraint (EQ_Constraint, ADR 0068), which stock has had since OpenSees 3.8.0 (openseespy ≥ 3.8.0; on Linux that needs Python ≥ 3.12). On stock the rows are enforced exactly, and the in-process run works for one tied model per process — see Stock engine defects. The same holds for ops.equation_constraint(...), a hand-written row (constrained=(node, dof), retained=[(node, dof, coef), ...]): Lagrange / LadrunoProjection auto-emitted, Transformation refused, serial only. ops.h5(...) archives each row, and OpenSeesModel.from_h5(...) replays it. An enforce="equation" interface tie is different: deck replay does not re-emit it, and ops.h5(...) says so with an H5LedgerWarning. What is fork-only is the explicit path: under an explicit integrator the bridge picks LadrunoProjection.
  • Contact. g.constraints.contact(...) → contactSurface / contact, and g.constraints.contact_plane(...) → contactPlane (rigid analytical plane). Both lanes work in 2D as well as 3D, and both are serial only — parallel 2D contact is out of scope in the fork and refused by name once the model is partitioned.
  • LadrunoProjection constraint handler, and the ladrunoProjectionTieForce query.

Analysis and solvers

  • ops.eigen_feast(...) — band-targeted FEAST eigensolver.
  • ops.complex_eigen(...) — complex / state-space modal.
  • Modal family — ops.modal_response_history(...), responseSpectrumAnalysis with -combine, ops.frequency_response(...), ops.steady_state_dynamics(...), ops.random_response(...).
  • ops.profiler / analyze(profile=...), and ops.critical_time_step() / ops.analyze_explicit(...).
  • system Pardiso — threaded MKL sparse-direct.

Fork build c83ee812e (2026-10-22)

These need fork build c83ee812e or later. FORK_PIN (ladruno-v20261023) carries it. An older build does not refuse what it cannot do: some features give a different answer, and one ends the process. No command marks these features, so apeGmsh checks the build by its ladrunoBuild sha, against the builds measured to carry c83ee812e. It refuses stock OpenSees and every other build, including an unmeasured newer one.

  • ASDShellQ4 / ASDShellT3 p_delta=True (-pDelta) adds the initial-stress stiffness of the current membrane forces, for gravity, then loadConst, then eigen. It cannot be combined with corotational=True. Stock OpenSees and older fork builds accept the token and run without the stiffness. So the in-process run refuses p_delta=True on them, and a Tcl or Python deck that carries -pDelta stops at its start.
  • ElasticTimoshenkoBeam (3-D) honours a PDelta or Corotational transformation and answers basicForce (N, Mz1, Mz2, My1, My2, T). Older builds ignore the transformation's geometric terms.
  • response_spectrum_analysis(..., scale=s) multiplies Sa by s. apeGmsh scales the -Sa values itself and does not emit the fork's -scale, which older builds parse and ignore. The result is the same on every build.
  • eigen_feast(..., trace_stop=True) (-traceStop) selects MKL's trace stopping criterion. The default stops on the relative residual and returns the same eigenpairs. An older build refuses -traceStop as an unknown option.
  • EigenResult.modal_properties() runs modalProperties on the band that eigen_feast solved. On an older build, modalProperties after eigen -feast ends the process, so apeGmsh refuses the call before it reaches the build. apeSees.modal_properties(num_modes) runs its own ARPACK solve and works on any build.

Materials

LadrunoBondSlip, LadrunoCohesiveHinge, LadrunoCohesiveHingeBiaxial, LadrunoConcrete3D, LadrunoJ2, LadrunoJ2Finite, LadrunoRCConcrete, LadrunoRCFiniteStrain, LadrunoRebarBuckling, LadrunoUniaxialJ2

LadrunoConcrete3D's tension_law= / eps_fc= / gc_legacy= need fork build 1334d1e24 or later, and flow_potential= needs 916576661. An older build refuses the material (unknown option) rather than ignoring them. The same 1334d1e24 commit changed the defaults (bilinear tension law, Gc read as a compressive fracture energy), so a deck that sets none of them means different things on either side of it; pin tension_law when that matters.

LadrunoRCConcrete / LadrunoRCFiniteStrain's beta_c= and cracked_nu= (-betaC / -crackedNu) are not on any build of the fork's ladruno branch yet. Fork PR #873 was closed unmerged, and fork PR #877 re-lands them. Unlike LadrunoConcrete3D, this parser ignores an unknown option, so a build without them runs the deck with the flags discarded. The in-process run therefore refuses them. ops.tcl(...) / ops.py(...) emit them with a LadrunoRCBuildWarning. The floor is LADRUNO_RC_C2_MIN_BUILD, which stays None until #877 merges. The vc tension-stiffening coefficient that tens_stiff_c=None leaves to the build is 500 on the ladruno branch.

877 changes it to 200, so pass tens_stiff_c explicitly to pin the curve.

The vanilla DruckerPrager runs on any build, but its tension-cutoff return map is only correct from fork build 61b3efa04 on (fork ADR-95). An older engine parses the same deck and answers differently — quadratic solid elements hit a false collapse floor. Its two read-only diagnostics, material.ladrunoBranch and material.ladrunoTangent, need that build too: an empty ops.eleResponse(e, "material", gp, "ladrunoBranch") is the probe for an older one.

ASDPlasticMaterial3D with a DruckerPrager_YF yield function has a second, later floor — 67474aeb7 — for its apex classification (fork ADR-94 wp/94f). The two floors are independent: 61b3efa04 fixes the UW material's cutoff, 67474aeb7 fixes the ASD one's region test, and a build can have the first without the second. Unlike the UW material, the ASD one exposes no response token, so there is nothing to probe — compare the build stamp instead.

The minimum useful build, and how to check it

Want Minimum fork build
A believable UW DruckerPrager tension cutoff, and the ladrunoBranch diagnostic 61b3efa04
A believable ASDPlasticMaterial3D + DruckerPrager_YF apex 67474aeb7

Neither is enforced — a bare hash cannot prove ancestry, and an older engine parses the identical deck. What it gets wrong is the answer, so there is nothing to refuse at construction. Two ways to find out where you stand:

from apeGmsh.opensees._element_capabilities import probe_ladruno_branch
from apeGmsh.opensees.emitter.live import get_backend_build

get_backend_build()                      # the exact commit, or None off-fork
probe_ladruno_branch(ops_module, e_tag)  # False on a pre-61b3efa04 engine

The probe must be aimed at an element of a class that forwards material <gp> <token> to its NDMaterial — LadrunoBrick, LadrunoBrick20, BezierTet10, TenNodeTetrahedron — using a UW DruckerPrager. Anywhere else it answers False for reasons that have nothing to do with the build.

Once the response is there, results.elements.gauss reads it back under eight names (dp_branch, dp_gamma_cone, dp_gamma_cutoff, dp_f1_trial, dp_f2_trial, dp_forced_accept, dp_i1, dp_det_a_min) and offers two censuses over it — corner_census() for dp_branch == 3, and the material-agnostic tension_census() for mean_stress >= 0. See ADR 0108.

Recorders

recorder ladruno (the HDF5 .ladruno recorder) and recorder Monitor (live SWMR telemetry). Every other recorder — including the plain text recorders that Results.from_recorders reads — works on any build.

Material-level response tokens (material.<token>) are a fork-recorder feature: the fork splits them into material <k> <token> per Gauss point. The bare spelling records nothing, so ops.recorder.Ladruno / MPCO refuse it and name the prefixed form.

MPM (the mpm engine)

The fork's Material Point Method engine is driven by ops.mpm.*, one member per mpm sub-command (ADR 0134). It needs a fork release that carries mpm (ladruno-v20261114, build f0b9a1df6, or later).

Member Fork line Notes
ops.mpm.grid(origin=, h=, cells=, basis=) mpm grid <tag> -origin .. -h .. -cells .. [-basis ..] one per model; its tag is written above every pattern tag and every other member's tag, and ops.tag_for(grid) returns it
ops.mpm.body(pg, material=, density=, ppc=, name=) none: the body is seeded into the particle set lattice seeding of the physical group's tri3 / quad4 / tet4 / hex8 elements; every body shares one ppc
ops.mpm.fix(face, components) mpm fix <face> <components>
ops.mpm.wall(face, mu) mpm wall <face> <mu>
ops.mpm.gridvel(name, box, v, start=, translate=, profile=) mpm gridvel <name> box <lo..> <hi..> v <v..> [start ..] [translate ..] [profile <t0> <Tr> <t1>] prescribes the grid velocity on the nodes inside box = (lo, hi), a component of v may be "free"; needs ladruno-v20261118b or later, which applies it in mode F (earlier releases ignore it); translate needs start or profile; no track
ops.mpm.gridvelAffine(name, box, L, ref=) mpm gridvel <name> box <lo..> <hi..> affine <L> [ref ..] prescribes L (x - ref), L given by rows; same release; no setAffine
ops.mpm.gravity(*g) mpm gravity <g..>
ops.mpm.timeSeries(series) mpm timeSeries <tsTag>
ops.mpm.damping(alpha) mpm damping local <alpha>
ops.mpm.flip(alpha) mpm flip <alpha>
ops.mpm.massCutoff(c) mpm massCutoff <c>
ops.mpm.safety(s) mpm safety <s>
ops.mpm.units(L, F, T, system=) mpm units <L> <F> <T> [-system ..] without it the particle set takes the bridge's units=; each symbol, and system, is one word
ops.mpm.output(path, ...) mpm output <path> ... the particle results, a .ladruno file
ops.mpm.analyze(steps, dt) mpm analyze <n> <dt>

MPM is deck-only. ops.tcl(path) and ops.py(path) seed the bodies and write <deck stem>.particles.h5 beside the deck, and the deck reads it from its own folder. The two are written together or not at all, and an existing particle set is replaced only when an apeGmsh emit wrote it. A deck with no mpm member written over an MPM deck removes the apeGmsh set that deck read, once the new deck is written in its place, so a viewer never pairs it with a stale set. Any other file of that stem (a set a sibling deck such as case.tcl reads while case.py is written, or a file no apeGmsh emit wrote) is kept, and the emit warns (StaleParticleSetWarning) naming it. The live route (ops.run(), ops.analyze(), every in-process procedure) refuses a model with an mpm member on every build, before the domain is touched, and so do a partitioned or per-rank emit and a staged model (staged MPM is not in this version). A fork v1 run also needs every FE node fixed: fix the seeding mesh's nodes with ops.fix.

Stock engine defects

Two stock OpenSees behaviours give a converged wrong answer with no warning, so the in-process run refuses them on a stock build. Both are fixed on the fork; deck emission is unaffected.

TenNodeTetrahedron is 6× too soft. Upstream's element applies the tetrahedral 1/6 volume factor twice, so its stiffness, mass, body force and reactions are all exactly 6× too small. That holds for every stock release through openseespy 3.8.0, and for upstream master as of 2026-09-25. The fork fixed it in PR #520. On stock, ops.element.TenNodeTetrahedron raises in the live run; mesh tet4 (FourNodeTetrahedron) or hexahedra instead. A fork build without the ladrunoBuild stamp (older than 2026-08-10) reads as stock, so it is refused the same way; rebuild the fork.

wipe() keeps equation-tie rows. Upstream Domain::clearAll() clears nodes, elements, SP/MP constraints and patterns, but not equationConstraint rows, and no stock command removes one. So the rows of one model survive wipe() into the next, and the next model enforces them. In one measured case the second model converged to twice the right stiffness; a model that lacks a stale row's node aborts the process. The first tied model in a process is exact. After it, the live emitter refuses to start another model in that process on a stock build. Restart the process (or the kernel), or run tied decks with ops.tcl(run=True) / ops.py(run=True), which start a fresh one. The fork clears the rows (fork PR #312).

Install extras

Everything above assumes the right extras are installed. apeGmsh itself pulls only gmsh, h5py, numpy and pandas.

Extra Enables
opensees Stock openseespy — tier 1
viewer Qt + web viewers (PySide6, pyvista, vtk, trame)
plot matplotlib / scipy plotting helpers
dxf DXF import / export
animation Video export from the results viewer
mcp The Studio MCP server (python -m apeGmsh.studio.mcp)
partition-pymetis Weighted mesh partitioning (no Windows wheel)
all opensees + viewer + plot + dxf + mcp

all covers everything that installs cleanly everywhere, Studio included:

pip install "apeGmsh[all]"

scripts/make-venv.bat builds a venv this way under C:\venv\<name>.

What all leaves out, and why

animation (ffmpeg is a large binary payload) and the two partition-* extras. pymetis has no PyPI Windows wheel — it comes from conda-forge — so folding it into all would break pip install "apeGmsh[all]" on Windows; partition-networkx is inert without nxmetis, which installs only from git. Ask for those by name when you need them.

Going the other way, all is broad: the Qt and VTK render stack, and through mcp a small server stack (uvicorn, starlette, pydantic, opentelemetry-api). Narrow it when you do not need all of that:

pip install "apeGmsh[viewer,opensees]"

Before 2026-08 all also omitted mcp, installing the Studio package without the SDK to start it. On an older release, add "mcp>=1.2" by hand.