Skip to content

Get results via MPCO (STKO)

Record an OpenSees run into a STKO .mpco HDF5 file and read it back with Results.from_mpco. Reach for this when you live in the STKO ecosystem (or run big parallel jobs) and want STKO's battle-tested recorder writing the database — including fibers, shell layers, and modal shapes, which the classic .out recorders can't carry.

Recipe

Declare a resolved recorder spec, drive the analysis under spec.emit_mpco, then open the file. emit_mpco issues a single ops.recorder('mpco', ...) on entry and flushes the HDF5 on exit — no per-stage begin_stage / end_stage ceremony.

import numpy as np
import openseespy.opensees as ops
from apeGmsh.opensees import apeSees, OpenSeesModel
from apeGmsh.results import Results
from apeGmsh.results.spec import ResolvedRecorderSpec, ResolvedRecorderRecord

# fem = g.mesh.queries.get_fem_data(dim=3)   # from the meshed session

# Typed bridge: declare model, materials, elements, supports, patterns.
# MP constraints declared via g.constraints.* auto-emit. Loads are opt-in:
# import each g.loads case into a pattern with p.from_model("<case>").
# Masses and support fixities ARE re-declared on the bridge (ops.mass / ops.fix).
ops_bridge = apeSees(fem)
ops_bridge.model(ndm=3, ndf=3)
# ... materials, elements, fix, mass, pattern, analysis chain ...

# Persist the canonical two-zone model.h5 — from_mpco needs it (model_h5=).
ops_bridge.h5("model.h5")

# Resolve WHAT to record (target by PG name, never raw tags).
spec = ResolvedRecorderSpec(
    fem_snapshot_id=fem.snapshot_id,
    records=(
        ResolvedRecorderRecord(
            category="nodes", name="top",
            components=("displacement_x", "displacement_y", "displacement_z"),
            dt=None, n_steps=None,
            node_ids=np.asarray(fem.nodes.select(pg="Top").ids),
        ),
        ResolvedRecorderRecord(
            category="gauss", name="body",
            components=("stress_xx",),
            dt=None, n_steps=None,
            element_ids=np.asarray(fem.elements.select(pg="Body").ids),
        ),
    ),
)

# Build the declared model into openseespy, then drive the run; MPCO
# writes ONE file with every stage inside.
ops_bridge.run()
with spec.emit_mpco("run.mpco"):
    for _ in range(n_steps):
        ops.analyze(1, dt)

# Read it back — model_h5= is REQUIRED (a sibling path, not the in-memory
# model object). Omitting it raises TypeError. The archive also supplies the
# physical groups and the ops.stage() names, so pg= and results.stage("...")
# resolve from files alone; fem= is optional and wins when given.
results = Results.from_mpco("run.mpco", model_h5="model.h5")

disp = results.nodes.get(pg="Top", component="displacement_z")
sigma = results.elements.gauss.get(pg="Body", component="stress_xx")

Prefer to run under STKO instead of in-process? Declare the recorder on the bridge so it rides into the exported deck, run the deck under STKO's OpenSees, then read identically:

ops_bridge.recorder.MPCO(file="run.mpco", nodal_responses=("displacement",),
                         elem_responses=("stresses",))
ops_bridge.tcl("model.tcl", analyze_steps=n_steps, analyze_dt=dt)
# ... run model.tcl under an OpenSees that has the MPCO recorder ...
results = Results.from_mpco("run.mpco", fem=fem, model_h5="model.h5")

The read-side Results API is identical to every other strategy — results.nodes.get(...), results.elements.{gauss,fibers,layers}.get(...), results.stages, results.modes. Nothing about querying changes because the data came from MPCO.

Notes / gotchas

  • model_h5= is required and is a path. from_mpco loads the broker via OpenSeesModel.from_h5(model_h5); MPCO files carry no /opensees/ zone, so there's nothing to auto-resolve from. Omitting model_h5= raises TypeError.
  • Write .mpco to local disk, never to a SeaDrive / cloud-synced folder. Closing the file collides with the sync client and aborts the kernel (leaving a stale open-for-write flag). Write to a local temp path; copy afterward if you must.
  • MPCO needs a build that has it. Vanilla openseespy distributions don't ship the MPCO recorder (STKO's bundled Python and the Ladruno fork do); emit_mpco.__enter__ raises a RuntimeError with a remediation pointer. Without one, record with spec.emit_default(...): on pip openseespy it falls back to classic .out recorders, which cover nodes, element forces, gauss points, line stations and fibres, but not layers. Modes come from ops.eigen(n).results() on any build.
  • Loads are opt-in. g.loads.* cases do not auto-emit; import each into a pattern with p.from_model("<case>"). Because nothing auto-emits, there is no double-count trap.
  • Multi-partition runs: pass any one part to from_mpco("run.part-0.mpco", model_h5="model.h5") — .part-N siblings are auto-discovered and merged. At a node shared by several ranks, displacements and other kinematics keep one copy, and reactions and unbalanced forces are summed, because each rank stores only its own elements' share. Pass merge_partitions=False to read only the named partition.
  • MPCO vs the default route: use MPCO for STKO interoperability and parallel runs; use spec.emit_default(...) for one in-process script across builds: the fork's .ladruno, or pip's .out files, all read with the same API. On a stock build with MPCO the default route converts the .mpco to .ladruno when the program declares its stages with ops.stage(...), and refuses an unstaged program by name; it never reads the .mpco with from_mpco. Run such a program as a deck emitted with analyze_steps and read it with read_deck_mpco.

See also


Next: Running & reading: choose your path.