Running & reading: choose your path¶
You have a meshed model and a typed apeSees(fem) bridge. This page settles
the two decisions between you and a results object, how to run OpenSees
and how to read what it wrote, and gives the working calls for each
combination. Whichever cell you pick, the Results query API you read with
afterwards is the same.
The two axes¶
Run decides where the analysis executes. In-process builds the model
into the live openseespy domain of your own Python session and steps it
there. Export writes a standalone .tcl or .py deck (ops.tcl(...) /
ops.py(...)) that you run somewhere else: a cluster, STKO, or a separate
process.
Read decides how the numbers get back into apeGmsh's label and query
world: the Ladruno fork's own recorder (a .ladruno HDF5 file),
classic recorders (OpenSees .out / .xml files), or MPCO
(STKO's .mpco HDF5).
On this page ops is always the bridge and opspy is the OpenSees module
the bridge builds into (opspy = get_ops(), from
apeGmsh.opensees.emitter.live). Beside a fork build,
import openseespy.opensees can bind a second module with its own, empty
domain, so the recipes never import it.
The grid¶
Read: .ladruno → from_ladruno |
Read: classic recorders → from_recorders |
Read: MPCO → from_mpco |
|
|---|---|---|---|
| Run: in-process | recorder_spec.emit_default("run", model_h5=...). The default: on the fork it records the fork's own file; on a stock build with MPCO it converts the .mpco of a staged program to .ladruno and refuses an unstaged one by name; on pip openseespy it falls back to the classic cell. |
recorder_spec.emit_recorders("out", model=model). Nodes, element forces, gauss points, line stations and fibres; layer and modal records raise by name. |
ops.recorder.MPCO(...) before ops.run(), or recorder_spec.emit_mpco(...). Fibres, layers and modes, on a build that has the MPCO recorder. |
| Run: export | read_deck_mpco("run.mpco", model_h5=...) converts the .mpco of the bridge's own deck to .ladruno beside it. |
recorder_spec.to_tcl_commands(...) in a driver around ops.tcl(...). Reproducible, check-in-able, cluster-friendly. |
ops.recorder.MPCO(...) before ops.tcl(...). One recorder mpco line in the deck; run it under an OpenSees that has the recorder. |
recorder_spec is a ResolvedRecorderSpec, which holds concrete node and
element IDs; a physical group resolves to them once, with
fem.nodes.select(pg=...).ids. The recipes below build one.
Modes are not a recorder record on any in-process route. ops.eigen(n)
returns an EigenResult, and its .results() writes the modes to a file
and opens them as a Results (to_native(path) keeps the file, and
to_ladruno(path) writes them as a .ladruno). The
modal example walks through it.
Start with the default route unless something pushes you off it. It needs nothing beyond the openseespy you have, picks the richest recorder your build offers, and is what the tutorials use. The other cells answer specific pressures: classic recorders when you want plain OpenSees output files, MPCO when the results must open in STKO, and export when the run has to happen somewhere your notebook is not.
The recipes¶
Every recipe solves the same model: a 3 m steel cantilever carrying a 10 kN tip load, applied in ten load steps. Its tip deflects PL³/3EI = 6.75 mm, and each recipe reads that number back.
import numpy as np
from apeGmsh import apeGmsh, Results
from apeGmsh.opensees import apeSees, OpenSeesModel
from apeGmsh.opensees.emitter.live import get_ops
from apeGmsh.results.spec import ResolvedRecorderRecord, ResolvedRecorderSpec
opspy = get_ops()
L, E, b, h, P = 3.0, 200e9, 0.10, 0.20, 10_000.0
A, Iz = b * h, b * h**3 / 12.0
with apeGmsh(model_name="cantilever") as g:
p0 = g.model.geometry.add_point(0.0, 0.0, 0.0)
p1 = g.model.geometry.add_point(L, 0.0, 0.0)
beam = g.model.geometry.add_line(p0, p1)
g.model.sync()
g.physical.add(1, [beam], name="Beam")
g.physical.add(0, [p0], name="Fixed")
g.physical.add(0, [p1], name="Tip")
g.mesh.sizing.set_global_size(L / 10.0)
g.mesh.generation.generate(1)
fem = g.mesh.queries.get_fem_data(dim=1)
def build_bridge():
"""A fresh bridge: the cantilever and a ten-step static analysis chain."""
ops = apeSees(fem)
ops.model(ndm=2, ndf=3)
transf = ops.geomTransf.Linear() # a 2-D transform takes no vecxz
ops.element.elasticBeamColumn(pg="Beam", transf=transf, A=A, E=E, Iz=Iz)
ops.fix(pg="Fixed", dofs=(1, 1, 1))
with ops.pattern.Plain(series=ops.timeSeries.Linear()) as pat:
pat.load(pg="Tip", forces=(0.0, -P, 0.0))
ops.constraints.Plain(); ops.numberer.Plain(); ops.system.BandGeneral()
ops.test.NormDispIncr(tol=1e-10, max_iter=10); ops.algorithm.Linear()
ops.integrator.LoadControl(dlam=0.1); ops.analysis.Static()
return ops
# What to record: the tip's displacement, by node id.
recorder_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=np.asarray(fem.nodes.select(pg="Tip").ids),
),),
)
Each recipe starts from a fresh bridge, because a recorder declared on a bridge rides along into everything that bridge emits afterwards.
In-process, the default route¶
ops.run() builds the model and its analysis chain into OpenSees without
analysing, and emit_default opens the recorder your build supports around
your own loop:
ops = build_bridge()
ops.h5("model.h5") # the model archive every route reads with
ops.run()
with recorder_spec.emit_default("run", model_h5="model.h5") as run:
for _ in range(10):
opspy.analyze(1)
opspy.wipe()
results = run.results()
run.route says which recorder ran:
| Build | Writes | run.results() |
|---|---|---|
| the Ladruno fork | run.ladruno |
stamps the file with model.h5's pairing, then Results.from_ladruno |
| stock, with MPCO | run.mpco |
converts it to run.ladruno beside it, then Results.from_ladruno; an unstaged program refuses at the with line |
| pip, no MPCO | classic .out files in run_out/ |
Results.from_recorders, after one DefaultRouteWarning |
Don't step with the bridge's own ops.analyze(steps=1) here: it rebuilds
the domain from scratch, and the recorder the block opened goes with it.
Read with run.results() after the block has closed.
On a stock build with MPCO the route converts only when each stage's kind
(static or transient) is a fact: the program declares it in an
ops.stage(...) block. An unstaged program has no kind as fact. Your loop
drives OpenSees directly, so a loadConst or a second
opspy.analysis(...) inside the block never reaches model.h5, and an
in-process run writes no run record. So emit_default refuses it by name
as the block opens, before your loop runs, with a StageKindRefused that
names the two remedies: declare the stages with ops.stage(...), or run
the program as a deck emitted with analyze_steps and read it with
read_deck_mpco (below). It never guesses a kind and never reads the
.mpco with from_mpco instead. ops.run() refuses a staged program
today, so a staged script runs as a deck (ops.py or ops.tcl) until
the in-process route can emit stages. A converted file whose stages do not pair
with the declared ones refuses on run.results() and writes nothing; the
.mpco is kept either way.
emit_default refuses a rerun onto an existing run.ladruno (on the fork,
or the converted file on stock) unless you pass overwrite=True. It has no route for modal records; modes come from
ops.eigen(n), as the grid says.
In-process, classic recorders¶
Reach for this when you want plain OpenSees recorder files from a notebook run whatever the build, and need nodes, element forces, gauss points, line stations or fibres:
ops = build_bridge()
ops.h5("model.h5") # the model archive the read needs
model = OpenSeesModel.from_h5("model.h5")
ops.run()
with recorder_spec.emit_recorders("out", model=model) as live:
live.begin_stage("load", kind="static")
for _ in range(10):
opspy.analyze(1)
live.end_stage() # removing the recorders flushes out/
opspy.wipe()
results = Results.from_recorders(recorder_spec, "out", fem=fem, stage_id="load",
model=model)
Each stage's files are prefixed <stage>__, which is why the read names
stage_id=. The spec names elements by FEM id, but OpenSees records them
by element tag, and the bridge numbers elements sequentially by default,
so the two differ. model= carries the pairing the model was built with,
and every element recorder is emitted under the right tags. A spec with an
element record refuses to emit without it; a node-only spec does not need
it, because nodes keep their FEM ids.
In-process, MPCO¶
Reach for this when the results must open in STKO. Declare the recorder on the bridge and it opens with the domain:
ops = build_bridge()
ops.recorder.MPCO(file="run.mpco", nodal_responses=("displacement",))
ops.h5("model.h5")
ops.run()
for _ in range(10):
opspy.analyze(1)
opspy.wipe() # closes the recorder, flushing run.mpco
results = Results.from_mpco("run.mpco", fem=fem, model_h5="model.h5")
If you already hold a recorder_spec, wrapping the loop in
with recorder_spec.emit_mpco("run.mpco"): does the same without touching
the bridge. The MPCO how-to covers partitioned runs and
where to write the file.
Export, classic recorders¶
Reach for this for cluster jobs and for decks you keep under version
control. ops.tcl writes the model and its analysis chain, and a short
driver adds the recorders and the analysis:
from pathlib import Path
ops = build_bridge()
ops.h5("model.h5")
model = OpenSeesModel.from_h5("model.h5")
ops.tcl("model.tcl")
Path("run.tcl").write_text("\n".join([
"source model.tcl",
"file mkdir out",
*recorder_spec.to_tcl_commands(output_dir="out", model=model),
"analyze 10",
"wipe",
]) + "\n")
Run run.tcl wherever OpenSees lives, bring out/ back beside model.h5,
and read it. A deck's files carry no stage prefix, so the read takes no
stage_id=:
For an openseespy deck,
recorder_spec.to_python_commands(output_dir="out", model=model) returns
the same recorders as ops.recorder(...) lines.
Export, MPCO¶
The STKO-shop production path, and the one that scales to parallel runs.
The bridge's MPCO recorder rides into the deck as one recorder mpco line:
ops = build_bridge()
ops.recorder.MPCO(file="run.mpco", nodal_responses=("displacement",))
ops.h5("model.h5")
ops.tcl("model.tcl", analyze_steps=10)
Run model.tcl under an OpenSees that has the MPCO recorder, then:
read_deck_mpco("run.mpco", model_h5="model.h5"), from
apeGmsh.results.live, reads the run as .ladruno instead. It is only for
a .mpco written by running the bridge's own exported deck (ops.py or
ops.tcl) out of process, as emitted. A staged deck (ops.stage blocks,
each recording its kind) converts beside itself, and the .mpco is kept.
An unstaged deck converts on its own run record: a deck emitted with
analyze_steps=, like the one above, writes run.mpco.run.json beside the
.mpco once its analyze loop has returned, and the conversion checks that
record against the .mpco, model.h5 and the program (one analysis
declaration, and the steps it ran). When a check fails, read_deck_mpco
refuses with a StageKindRefused that names the check and the remedies,
and writes nothing; it never falls back to from_mpco. Other refusals
raise as they are, such as an archive of another model or an incomplete
partition set. An in-process run is not a deck: it writes no run record,
so read_deck_mpco refuses its .mpco on check 1.
The read side is identical¶
Whichever recipe ran, the query is the same:
tip = results.nodes.get(pg="Tip", component="displacement_y")
print(f"tip deflection = {tip.values[-1, 0] * 1e3:.2f} mm")
results.close()
Everything else about reading, from stages and time slicing to modes, fibers and the viewers, works the same way whichever constructor opened the file; the Results concept page walks through it.
Notes / gotchas¶
- Every constructor needs the model.
from_recorders(andfrom_native, which opens the modes fileEigenResult.to_nativewrites) take an in-memorymodel=(OpenSeesModel.from_h5(...));from_mpcotakesmodel_h5=as a path, because MPCO files carry no/opensees/zone. Omitting it raisesTypeError.from_recordersalso needsfem=.from_ladrunotakesmodel_h5=too, and binds that archive's physical groups and labels.emit_defaultpasses the model for you. - Bridge-declared recorders are not what
from_recordersreads. The read finds files by the names its spec generates (out/tip_disp.outabove). Recorders declared on the bridge ride intoops.run()and every deck, but name their files their own way:ops.recorder.declare(...)after the declaration (out/default__default__disp.out),ops.recorder.Node(...)after itsfile=. Use them when you consume the.outfiles yourself, and generate the recorders from the spec when apeGmsh should read them back. - Layers and modes have no classic path.
emit_recordersrecords fibre records (section fiberData2at each integration point), and raises at__enter__on a layer or a modal record, naming it. Record layers with MPCO or on the fork; take modes fromops.eigen(n). - MPCO needs a build that has it. Not every openseespy build ships the
MPCO recorder (STKO's bundled Python does), and
emit_mpcoraises at__enter__with a remediation pointer when it is missing. Without such a build, the default route falls back to classic recorders, which record fibres but not layers. - Loads are opt-in (ADR 0051). MP constraints auto-emit, but
g.loads.*cases do not: import one into a bridge pattern withpat.from_model(case), or author loads withpat.load(...)as the recipes do. Masses and supports are re-declared on the bridge (ops.mass,ops.fix).
See also¶
- Concept: Results, the read model that every constructor on this page opens onto.
- How-to: Export to a Tcl or openseespy script · Get results via MPCO.
- API:
apeGmsh.results.Results:from_recorders,from_mpco, the fork'sfrom_ladruno, andfrom_nativefor modes.