Skip to content

The OpenSees bridge

This page teaches you how a finished snapshot becomes a running OpenSees model — why the bridge speaks typed objects instead of command strings, what it carries across on its own, and how one set of declarations feeds a live solve, a Tcl deck, a Python deck, and an HDF5 archive alike.

The mental model ended with the hand-off: you build and name a model in the session, freeze it into a FEMData snapshot, and the solver side begins after that. The bridge is one class, apeSees, constructed from the snapshot — not a session composite, and not dependent on a live Gmsh kernel:

from apeGmsh.opensees import apeSees

fem = g.mesh.queries.get_fem_data(dim=3)
ops = apeSees(fem)
ops.model(ndm=3, ndf=3)

ops.model(ndm=, ndf=) comes first — everything after it depends on the declared dimensions. From there you declare materials, elements, supports, loads, and the analysis itself on ops, and the bridge resolves every declaration against the snapshot when it builds. Because the input is a snapshot rather than a live session, the same fem can feed several bridges — a gravity-only deck and a seismic deck from one geometry — and a snapshot reloaded from model.h5 works exactly like a fresh one.

Typed handles, not strings

Raw OpenSees scripting is string-templated: you invent integer tags, spell material names as strings, and a typo becomes a runtime error deep inside the solver — or worse, a command OpenSees silently ignores. The bridge replaces that with typed constructors. Every material, section, transform, and integration rule is a Python call with an explicit signature, and it returns a handle you pass to whatever consumes it:

conc = ops.nDMaterial.ElasticIsotropic(E=30e9, nu=0.2, rho=2400)
ops.element.FourNodeTetrahedron(
    pg="Block", material=conc,
    body_force=(0.0, 0.0, -9.81 * 2400),
)
ops.fix(pg="Base", dofs=(1, 1, 1))

There are no tag numbers and no name registry — the variable is the reference, and handles register themselves on the bridge. Misspell a keyword and Python tells you at the call site; forget the geomTransf a beam needs, pass a dofs mask of the wrong length, or assign an element type incompatible with the declared ndm/ndf, and build() raises a pointed error before a single solver line is written. That is the whole argument for typing: the class of mistakes that OpenSees reports late, cryptically, or not at all is moved to the moment you make them.

The typing goes one level deeper than signatures. Shells carry six DOFs per node, solids three — and you never declare which: the bridge infers each node's ndf from the elements you assigned to it, emits per-node DOF counts where they differ from the model envelope, and fails loud if two elements disagree about a shared node (a shell meeting a solid), because OpenSees would mis-assemble that node rather than complain.

Everything targets a name

Notice what the snippet above never does: loop over nodes. pg="Block" on the element call writes every mesh element in that physical group; pg="Base" on the fix clamps every node on that face, however many the mesher produced. The same pg= keyword appears on masses, loads, prescribed displacements, and recorders, and it resolves both physical groups and apeGmsh labels against the snapshot. This is the naming discipline from the selection page paying off on the solver side: the mesh can be refined, the geometry edited, the node numbering reshuffled — the bridge script does not change, because it never mentioned a node.

What crosses the boundary by itself

The session let you declare physics — loads, masses, constraints — before the mesh existed. How much of that reaches the deck automatically? The answer is deliberately narrow: multi-point constraints, and nothing else.

Ties, embedded regions, rigid links and diaphragms, and their relatives declared via g.constraints.* resolve into the snapshot and emit into the deck without any bridge-side step:

g.constraints.tie("ColumnTop", "SlabBottom", dofs=[1, 2, 3])
# ... mesh, snapshot, apeSees(fem), materials, elements ...
ops.tcl("model.tcl")   # the tie lines appear automatically

You declare the tie once, where the geometry lives; the bridge writes the equalDOF / rigidLink / rigidDiaphragm / embedded-element lines and switches on the constraint handler they need. Constraints auto-emit because they are part of what the model is — a tied interface is meaningless to omit.

Loads are different: which load cases belong in this analysis is a per-deck decision, so session loads are opt-in. The session groups loads by case — a label with no temporal meaning. Time enters on the bridge, where a pattern owns a time series, and the pattern imports the cases it wants:

ts = ops.timeSeries.Linear()
with ops.pattern.Plain(series=ts) as p:
    p.from_model("dead")                       # import the resolved "dead" case
    p.load(pg="Tip", forces=(0.0, 0.0, -5e4))  # + ad-hoc bridge-authored load

p.from_model(case) replays the resolved nodal records of a session case inside the pattern; p.load / p.sp author loads directly on the bridge. A case you don't import is simply not applied — there is exactly one channel into the deck, so the old double-counting trap (declared on the session and the bridge) cannot happen. Masses and support fixities are re-declared explicitly with ops.mass and ops.fix, or wholesale with ops.mass_from_model() and ops.fix_from_model(), for the same reason: the deck is authoritative, and reading it tells you exactly what the analysis contains. They are not a per-deck choice the way a load case is, though, so when the session declared g.constraints.bc supports or g.masses and the deck restates none of them, emit warns (UnconsumedModelDefinitionWarning) rather than writing an unsupported, massless model in silence. Everything the session declared — imported or not — still persists into model.h5 for the viewer and Results.

Frame members and joint offsets

A beam's geomTransf can carry rigid joint offsets: jnt_offset=((dXi, dYi, dZi), (dXj, dYj, dZj)) gives the global vector from each node to its element end, or an InsertionPoint rule gives an ETABS cardinal point, joint offsets and end-length rigid zones. The offsets are emitted as -jntOffset. A 3-D Corotational refuses them, because OpenSees zeroes them there.

ETABS puts a frame object's offsets at the object's two ends, and in apeGmsh that frame object is the gmsh curve. The mesh alone cannot tell one curve meshed into several elements from a girder of several members, so FEMData records, per element, the gmsh entity it was meshed on: fem.elements.entity holds the tags per element type, and fem.elements.source_entity(eids, dim=1) returns (module_label, entity), the key that names a curve in a composed model (the same tag in two Assembly instances is two curves). The stream is in model.h5 from neutral schema 2.36.

An offset that is the same transverse shift at both ends reads the same on every element, so it stays per element. An end-sensitive offset (an end length, an axial component, unequal ends) is split over each curve: the curve's first element takes the i-offset, its last the j-offset, and each interior node takes only the transverse part. A curve meshed into n elements behaves as one element with the same offsets. Elements that frame into the curve do not split it; to put a joint at mid-span, split the curve.

These cases refuse. Each message names the curve, except the 3-D one, which names the transform only, and the last, which names the elements and the node:

  • end-sensitive offsets on a curve that is not straight;
  • a transform that covers only part of a curve and would put an end zone or axial offset at a node interior to the curve (transverse-only interior nodes pass);
  • a curve whose elements run both ways, or a closed curve;
  • end lengths along the curve with different transverse offsets at its two ends (the offset axis would kink);
  • an end element no longer than the end offsets on it (no flexible length);
  • elements of one curve with different vecxz;
  • in 3-D, a split with neither vecxz= nor orientation= on the transform;
  • a snapshot with no source curves (a model.h5 older than 2.36, or a FEM not extracted from gmsh), wherever two of the transform's elements meet without a clear corner of 30 to 150 degrees.

Stages

Real analyses rarely happen in one shot: gravity first, then pushover; excavate, then install the lining, then shake. The bridge models this directly with ops.stage. A stage is a scoped block that owns its own patterns, its own analysis chain, and its own run:

with ops.stage(name="push") as s:
    with s.pattern(series=ops.timeSeries.Linear()) as p:
        p.from_model("live")
    s.analysis(...)
    s.run(n_increments=10)

Stages that share every chain slot but the integrator state them once with ops.analysis.chain(...) and pass that value to each stage. The chain is a plain value, not a primitive, so the deck is the same as with every slot spelled out:

solver = ops.analysis.chain(
    test=ops.test.NormDispIncr(tol=1e-8, max_iter=50),
    algorithm=ops.algorithm.Newton(),
    constraints=ops.constraints.Plain(),
    numberer=ops.numberer.RCM(),
    system=ops.system.UmfPack(),
    analysis=ops.analysis.Static(),
)
with ops.stage(name="gravity") as s:
    ...
    s.analysis(solver, integrator=ops.integrator.LoadControl(dlam=0.1))
    s.run(n_increments=10)

A chain plus a keyword for a slot it already holds is refused. The test may be left out only for ops.algorithm.Linear(), which solves once per step and never reads it; a strategy ladder (s.run(strategy=)) still needs one.

Loads from a finished stage are frozen (loadConst -time 0.0) before the next begins, and the pseudo-time restarts at 0. A stage's series is read on that clock, so a load history that continues from an earlier stage needs s.set_time(t); a Path series that would read 0 at every increment of the stage raises SeriesOutsideStageWindowWarning when the stage closes. Stages can bring element groups online with s.activate(pgs=[...]), and an MP constraint whose nodes only exist from a later stage onward is claimed by name inside that stage (s.tie(name=...)) instead of emitting globally. A model is either staged or not — a global pattern alongside stage blocks raises at build, because it would double-apply across stage boundaries. The staged-construction example shows the idiom at full length.

What a stage boundary does

When a stage closes, the emitted deck does five things before the next stage opens. Each is read off the emitted py deck, in this order:

ops.loadConst('-time', 0.0)    # end of stage 1
ops.wipeAnalysis()
# === Stage: s2 ===
ops.setTime(1.0)               # only if s2 called s.set_time(1.0)
ops.domainChange()
ops.constraints('Plain')       # the whole analysis chain, again
...
ops.analysis('Static')
ops.pattern('Plain', 2, 2)
  • Loads are held constant. loadConst freezes every pattern applied so far; they stay on the model as a baseline and the next stage adds to them.
  • Time returns to 0. The -time 0.0 in that loadConst resets the pseudo-time. It stays at 0 unless the next stage calls s.set_time(t), which emits setTime right after the wipe. A Path series that would read 0 at every increment raises SeriesOutsideStageWindowWarning.
  • The analysis chain is wiped and re-emitted. wipeAnalysis discards the test, algorithm, integrator, constraints handler, numberer, system and analysis; every stage writes them all again from its own s.analysis(...). Nothing carries over, so a stage that omits one is an error, not a default. The one exception is the test of a Linear stage, which is not written.
  • Domain state and recorders are kept. Nodes, elements, fixes, the displacements reached and the recorders declared once at the top of the deck survive the boundary. wipeAnalysis does not touch the domain, and the recorders are not re-emitted.
  • dt has no effect under Static; a given dt warns. A static analysis ignores analyze's dt: the integrator alone sets the step, so a LoadControl stage with dlam=0.25 and n_increments=4 reaches t0 + 1.0. A dt that differs from dlam raises InertStaticDtWarning (from apeGmsh.opensees) when the stage closes; leave dt out, or set it equal to dlam. Every other static integrator (DisplacementControl, ArcLength and the fork's path-following ones) has no dlam, so any dt given to it warns: leave it out. dt is the step only under Transient.

One declaration surface, four outputs

Everything above — model, materials, elements, fixes, patterns, stages, and the analysis chain itself (ops.constraints, ops.numberer, ops.system, ops.test, ops.algorithm, ops.integrator, ops.analysis) — is pure declaration. Nothing touches OpenSees until you pick an output:

ops.tcl("model.tcl")            # complete OpenSees Tcl deck
ops.py("model.py")              # equivalent openseespy script
ops.h5("model.h5")              # native HDF5: solver zone + neutral zone
ops.run()                       # in-process openseespy, right now
ops.analyze(steps=10, dt=0.01)

Each call builds the same resolved model internally and hands it to a different emitter; they are separate statements, not a chain, and you can call several on one bridge. This is the payoff of declare-then-emit: the deck you archive, the script a colleague runs, and the in-process solve are guaranteed to be the same model, because they came from the same declarations. The model.h5 written here carries both the runnable solver zone and the neutral zone the viewer reads — the session-side g.save() writes only the latter (see Save & reload a model).

On large models, close the apeGmsh session before you emit. The emit path reads the FEMData snapshot and never calls Gmsh, so a still-open kernel adds only overhead to your peak memory. On a 51 M-hex model, closing the session dropped memory use by 13 GB before build() even started; on smaller models this is a style choice, but past a few million elements it becomes essential.

Recorders, and reading back

Output declarations live on the same surface. ops.recorder.<Type>(...) declares classic OpenSees recorders that emit with the deck. The Node and Element recorders take precision=N, the significant digits written per value (OpenSees writes 6 unless told otherwise); left out, no flag is emitted and the deck is unchanged, and anything but a positive int raises. For in-process runs, a recorder spec names what to record, as node or element ids that a physical group resolves to, and emit_default records it on the route the OpenSees build supports: .ladruno on the Ladruno fork, .mpco on a stock build with the MPCO recorder, classic .out files on pip openseespy:

from apeGmsh.opensees.emitter.live import get_ops
from apeGmsh.results.spec import ResolvedRecorderRecord, ResolvedRecorderSpec

spec = ResolvedRecorderSpec(
    fem_snapshot_id=fem.snapshot_id,
    records=(ResolvedRecorderRecord(
        category="nodes", name="tip",
        components=("displacement_x", "displacement_y"),
        dt=None, n_steps=None, node_ids=fem.nodes.select(pg="Tip").ids,
    ),),
)
ops.h5("model.h5")
ops.run()                      # build the domain without analysing
with spec.emit_default("run", model_h5="model.h5") as run:
    get_ops().analyze(1)       # step the module the bridge built
results = run.results()

A live run keeps its recorder files open until something closes them. When the same script goes on to read those files, or to open an .mpco with Results.from_mpco, call ops.wipe() first. It closes the live domain, which flushes and closes every recorder, so a text recorder file holds every row and an .mpco file is complete. It also closes the bridge's read session: a later Node.read or NodeSet.read raises and names ops.wipe(). The declarations stay, so ops.analyze(...) or ops.run() builds the model again. wipe acts only on the live session and is never written into an emitted deck, which flushes its recorders when its process exits.

You saw this run end-to-end in the first tutorial: the same "Tip" name that placed the load fetches the deflection back out of Results. That symmetry — names in, names out — is where the bridge hands over to the results layer, which the next page covers.

The bridge's surface is larger than this page: eigen and modal analysis, damping declarations, fiber sections, explicit dynamics, and more all live on the same typed namespaces. The OpenSees API reference is the complete signature-level map, and the examples — modal analysis, pushover, non-matching-mesh ties — carry the full workflows. What stays constant everywhere is the concept you now have: typed declarations, resolved against a named snapshot, emitted wherever you need them.


Next: Results.