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=nororientation=on the transform; - a snapshot with no source curves (a
model.h5older 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.
loadConstfreezes 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.0in thatloadConstresets the pseudo-time. It stays at 0 unless the next stage callss.set_time(t), which emitssetTimeright after the wipe. APathseries that would read 0 at every increment raisesSeriesOutsideStageWindowWarning. - The analysis chain is wiped and re-emitted.
wipeAnalysisdiscards the test, algorithm, integrator, constraints handler, numberer, system and analysis; every stage writes them all again from its owns.analysis(...). Nothing carries over, so a stage that omits one is an error, not a default. The one exception is the test of aLinearstage, 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.
wipeAnalysisdoes 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'sdt: the integrator alone sets the step, so aLoadControlstage withdlam=0.25andn_increments=4reachest0 + 1.0. Adtthat differs fromdlamraisesInertStaticDtWarning(fromapeGmsh.opensees) when the stage closes; leavedtout, or set it equal todlam. Every other static integrator (DisplacementControl,ArcLengthand the fork's path-following ones) has nodlam, so anydtgiven to it warns: leave it out.dtis the step only underTransient.
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.