Results¶
Post-processing container.
Construction — every Results has a model¶
Every Results carries a model, so the post-processing container always
has a read-side broker to resolve names, PGs, and connectivity against.
An in-process run recorded with spec.emit_default(...) opens with
run.results(), which picks the reader for the route the build took and
passes the model for you. Each reader can also be called directly:
from apeGmsh import Results
from apeGmsh.opensees import OpenSeesModel
# The default route: run.results() after `with spec.emit_default(...) as run:`
results = run.results()
# Ladruno fork .ladruno: model_h5= binds the archive's PGs and labels
results = Results.from_ladruno("run.ladruno", model_h5="model.h5")
# STKO .mpco: model_h5= points at the sibling model archive
results = Results.from_mpco("run.mpco", model_h5="model.h5") # model_h5= REQUIRED
# Classic recorder files: fem= and model=
model = OpenSeesModel.from_h5("model.h5")
results = Results.from_recorders(spec, "out/", fem=fem, model=model) # model= REQUIRED
# Native apeGmsh HDF5, e.g. the modes file EigenResult.to_native() writes
p = ops.eigen(3).to_native() # the file embeds the bridge's model
results = Results.from_native(p, model=OpenSeesModel.from_h5(p)) # model= REQUIRED
Omitting model= (from_recorders, from_native) or model_h5=
(from_mpco) raises TypeError. from_ladruno builds its broker from
the file's own MODEL group when model_h5= is left out, but then the
read has no physical groups or labels.
results.model is never None on a constructed Results (ADR 0020
INV-1). Reach the neutral FEMData zone through the broker chain:
osm = results.model # OpenSeesModel broker (never None)
fem = results.model.fem # neutral FEMData zone
results.fem is the locally-bound snapshot and may differ from
results.model.fem after a .bind().
Lineage — results.lineage warns, never raises¶
results.lineage returns a Lineage(fem_hash, model_hash,
results_hash, warnings) describing the git-style fem → model →
results hash chain. Stored-vs-recomputed mismatches surface as
[lineage] ... strings in lineage.warnings; the property itself
never raises. Call lineage.assert_clean() to escalate any
warnings to LineageError.
BindError is gone
Construction no longer rejects a mismatched FEM with BindError
(deleted in the three-broker refactor). results.bind(fem)
performs no hash validation — pairing a FEM with the right run is
the user's responsibility, reported through lineage.warnings.
Fluent selection — .nodes.select() / .elements.select()¶
results.nodes.select(...) and results.elements.select(...) are the
results entries of the unified, daisy-chainable
selection idiom. .select() returns a
MeshSelection (point
family); the terminal is .values(component=...), which forwards to
the retained results.<level>.get(...) reader and returns the
same slab (NodeSlab / ElementSlab) with id/value parity.
slab = (results.nodes.select(pg="Base")
.in_box(lo, hi) # half-open [lo, hi)
.on_plane((0, 0, 0), (0, 0, 1), tol=1e-6)
.values(component="displacement_x")) # -> NodeSlab
A bare results selection needs a component — .result() raises
RuntimeError; use .values(component=...). Element spatial verbs
operate on element centroids.
S5 — formerly-silent results paths now raise
results with selection= on an import-origin
(from_msh/MPCO/native) FEMData now raises RuntimeError
instead of resolving to an empty set; results element-centroid
computation raises KeyError on an unknown connectivity node,
which also makes the legacy
results.elements.in_box/nearest_to/on_plane helpers fail
loud. See the changelog.
See Selection for the full idiom; results
sub-composite .select() (gauss/fibers/layers/line_stations/
springs) is a tracked, not-yet-shipped follow-up.
apeGmsh.results.Results.Results ¶
Results(reader: ResultsReader, *, fem: 'Optional[FEMData]' = None, stage_id: Optional[str] = None, path: Optional[Path] = None, model: 'OpenSeesModel', model_path: Optional[Path] = None)
Top-level results object. Returned by Results.from_* constructors.
Stage scoping¶
Instances may be unscoped (top-level — accesses any stage) or
scoped to one stage (returned by .stage(name),
.modes[i]). Scoped instances expose stage metadata as
properties (.kind, .time, .n_steps); mode-scoped
instances additionally expose .eigenvalue, .frequency_hz,
.period_s, .mode_index.
Source code in src/apeGmsh/results/Results.py
fem
property
¶
The bound FEMData snapshot, or None if not bound.
Raises :class:SchemaVersionError on a native results file whose
embedded /model is below its floor and no fem= was
supplied (ADR 0113 D9): the zone is never read silently, and
the message says to pass fem= or call :meth:bind.
model
property
¶
The bound :class:OpenSeesModel broker.
Phase 8 (ADR 0020 INV-1) — always non-None on a constructed
:class:Results. The chain-forward handle from which the
OpenSeesModel and its embedded FEMData can be reached.
path
property
¶
The results file these Results read, or None when none.
The path the constructor opened: a .ladruno (the first
partition of a merged <stem>.part-<N>.ladruno set), an
.mpco, a native .h5, or the recorders' cache. Stage and
mode scopes carry it. Read-only. The Windows stills draw this
file with apeGmshViewer, which opens a .ladruno only
(ADR 0128 slice 6, VA6b).
units
property
¶
The active consistent unit system ID (e.g. "kN_m_s"), or
None when no unit system was declared.
source_units
property
¶
The native (as-recorded) unit system ID of the underlying file
or model, or None when undeclared and no source= was given.
lineage
property
¶
Phase-6 lineage chain — git-style fem → model → results.
ADR 0021 defines a three-link hash chain fem_hash →
model_hash → results_hash where each layer's hash includes
its parent's hash (one-directional, tamper-evident).
Mismatches between stored and recomputed hashes surface as
[lineage] ... warnings in :attr:Lineage.warnings; they
never raise from this property (INV-2).
Phase-8 derivation order:
- Inherit
fem_hash+model_hash+ accumulated warnings from :attr:model.lineage(the broker recomputes against the same file). - Read the stored
/meta/lineage/results_hashvia the reader'sresults_lineage_attrshelper and recompute from/stages/...viarecompute_results_hash; append a drift warning on mismatch.
Readers that don't implement the Phase-6 result-layer
protocol methods are tolerated via getattr cushions:
their lineage stays at the model layer, no warning emitted.
modes
property
¶
Stages with kind='mode' as a list of mode-scoped Results.
Order is the order the modes were written (typically by
ascending mode_index). For a stable lookup by index, sort:
sorted(results.modes, key=lambda m: m.mode_index).
eigen_modes
property
¶
Mode-kind stages as lightweight :class:EigenMode snapshots.
Each :class:EigenMode carries only the four scalar fields
(mode_index, eigenvalue, frequency_hz, period_s)
— no file handle, no mode-shape arrays. Use this when you
need the eigenvalue spectrum but not the per-node shapes
(e.g. an LTB Mcr probe, a pickle-able report, or a return
value from a function whose Results context is about to be
closed).
For the per-node mode shape arrays, use the mode-scoped
:class:Results from :attr:modes instead and query via
mode.nodes.get(component="displacement_x", ...).
Order matches :attr:modes. For a stable lookup by index,
sort: sorted(results.eigen_modes, key=lambda m: m.mode_index).
plot
property
¶
results.plot — static matplotlib renderer.
Mirrors the interactive viewer's diagram catalog as headless, publication-ready matplotlib figures::
results.plot.contour("displacement_z", step=-1)
results.plot.deformed(step=-1, scale=50, component="stress_xx")
results.plot.history(node=412, component="displacement_x")
Requires the [plot] extra (matplotlib).
from_native
classmethod
¶
from_native(path: str | Path, *, fem: 'Optional[FEMData]' = None, model: 'Optional[OpenSeesModel]' = None, model_path: 'Optional[str | Path]' = None) -> 'Results'
Open an apeGmsh native HDF5 results file.
Phase 8 (ADR 0020 INV-1) — model= is required. Missing
supply raises :class:TypeError. Pass
model=OpenSeesModel.from_h5(path_to_model_h5) (often the
same path as path when the file is a Composed-file
per ADR 0020).
If fem is omitted, the embedded /model/ snapshot is
used as the bound FEMData.
ADR 0113 D9 — a results file outlives its embedded model zones.
When the embedded /model is below its floor the file still
opens and /stages read: with fem= supplied the zone is
never read; without it :attr:fem raises the reader's refusal
(with a fem= hint) until :meth:bind supplies a snapshot.
The embedded /opensees is never read here, since model=
is required; OpenSeesModel.from_h5 on such a file refuses,
so the model comes from a sidecar archive.
model_path records the on-disk archive the model was read
from, for when it is not path itself — e.g. results whose
embedded /model zone is not independently readable. The
non-blocking subprocess viewer forwards it as --model-h5 so the
child re-reads the model from there instead of from path.
Source code in src/apeGmsh/results/Results.py
from_recorders
classmethod
¶
from_recorders(spec, output_dir: str | Path, *, fem: 'FEMData', cache_root: str | Path | None = None, stage_name: str | None = None, stage_kind: str | None = None, file_format: str = 'out', stage_id: str | None = None, model: 'Optional[OpenSeesModel]' = None, stages: 'Optional[Iterable[Any]]' = None) -> 'Results'
Open the result of an OpenSees run driven by Tcl/Py recorders.
model= is required (else :class:TypeError).
Parses the .out / .xml files emitted at output_dir
(matching what spec.emit_recorders(...) or the bridge's Tcl/Py
emit produced), caches the result at cache_root and opens it
(ADR 0131 D6). Nodal records only, over ops.stage blocks of model
with their kinds (any order or subset), are cached as <key>.ladruno
stamped against <key>.model.h5 (opensees_backend="unknown", the
stage names), read by name with from_ladruno(model_h5=) and bound to
model. Any other run (an element record, displacement_increment,
a stage the program does not declare or of another kind) is cached as
native HDF5 embedding model's /opensees/ zone (keeps the names).
A layers record refuses by name; modal records are not emitted.
Caching: unchanged input files, model, stage names and kinds reuse
the cached file (writers/_cache.py). Recorders sample every step
or every dt=, never at arbitrary caller instants.
stage_id matches the per-stage filename prefix used by
:meth:ResolvedRecorderSpec.emit_recorders together with
begin_stage(stage_id, ...). When set, only files prefixed
with <stage_id>__ are read; stage_name defaults to
stage_id, else "analysis", and stage_kind to
"transient". None (default) keeps the
legacy flat-naming used by Tcl/Py exports. stages=live.stages
reads every stage of a :meth:ResolvedRecorderSpec.emit_recorders
run into one file, one stage each with its name and kind; it
excludes stage_id / stage_name / stage_kind.
Rows are labelled with the spec's FEM ids, so the files must come
from an emit that translated them to OpenSees tags
(spec.emit_recorders(..., model=) or
spec.to_tcl_commands(model=)).
Source code in src/apeGmsh/results/Results.py
480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 | |
from_mpco
classmethod
¶
from_mpco(path: 'str | Path | list[str | Path]', *, fem: 'Optional[FEMData]' = None, merge_partitions: bool = True, model_h5: 'Optional[str | Path]' = None) -> 'Results'
Open a STKO .mpco HDF5 results file.
Phase 8 (ADR 0020 INV-1) — model_h5= is required. Missing
supply raises :class:TypeError. The broker is loaded via
:meth:OpenSeesModel.from_h5 and attached to the resulting
:class:Results; INV-3 — the broker is held in memory only
(no derived results.h5 is written copying the
/opensees/ zone in).
What the archive carries, the results use (#1324, #1325):
- FEMData.
fem=wins when given. Otherwise the neutral FEMData stored inmodel_h5(physical groups, labels) is bound whenever its node ids cover the capture's and sit at the capture's coordinates (the model'sndmcolumns: a 2-D model on an offset plane compares inx, y), sopg=queries work from files alone. An archive written byfem.to_h5carries no element tag map, so it is bound only when the capture's element ids and nodes are its own (ops tags are read as fem element ids on that route); amodel_h5from another model or another mesh of the same part warns (ModelFemMismatchWarning) and the partial FEMData synthesized from the MPCOMODEL/group is bound instead. - Stage names.
ops.stage(name=...)names from/opensees/stagesreplace the file'sMODEL_STAGE[<k>]names in order (results.stage("gravity"));MODEL_STAGE[<k>]stays resolvable as an alias. A partial run (fewer capture stages than program stages) names the prefix and warns (StageCountMismatchWarning); more capture stages than program stages warns and keeps the file's names. Two program stages with one name warn (DuplicateStageNameWarning);stage(name)picks the first, and the idsstage_<k>stay unique.
Single-file mode (default for non-partitioned analyses): pass
the path of one .mpco file.
Multi-partition mode (parallel OpenSees runs): pass either
- a single
<stem>.part-<N>.mpcopath — siblings are discovered automatically by globbing<stem>.part-*.mpcoin the same directory and merged into one virtual reader; - an explicit list of partition paths.
Boundary nodes deduplicate by ID (first-occurrence wins); elements concatenate (disjoint by partition); slabs stitch across partitions transparently. Stage and time vectors must match across partitions or construction raises.
Pass merge_partitions=False to opt out of auto-discovery
and read only the file at path even if it follows the
.part-N naming convention.
Source code in src/apeGmsh/results/Results.py
580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 | |
from_ladruno
classmethod
¶
from_ladruno(path: 'str | Path | list[str | Path]', *, fem: 'Optional[FEMData]' = None, merge_partitions: bool = True, model_h5: 'Optional[str | Path]' = None) -> 'Results'
Open a Ladruno .ladruno HDF5 results file.
The Ladruno recorder is the fork's canonical recorder. Unlike
.mpco (and unlike :meth:from_mpco, which requires
model_h5=), a .ladruno is self-sufficient — it carries
its own geometry, regions and beam local axes (schema Principle 0:
"this is the native path; no sibling file"). So model_h5= is
optional:
- omitted → the broker is built in-memory from the file's own
MODELgroup (geometry + inferredndm/ndf; bridge record zones empty). This is read-time interpretation, not a transcode. A file with noMODELgroup raises :class:ValueErrornaming the file;model_h5=opens it. - supplied → the richer broker is loaded via
:meth:
OpenSeesModel.from_h5(full bridge records + lineage), and — whenever the model records an element_meta pairing — the fem_eid↔ops-tag translator is attached (ADR 0043; required for composed models AND for any sparsely-renumbered mesh, e.g. a gmsh solid whose 2-D boundary elements consumed the low ids).
FEMData with model_h5= (#2329): as in :meth:from_mpco,
fem= wins when given; otherwise the FEMData archived in
model_h5 is bound, with its physical groups and labels, so
pg= and label= reads work. An archive of another model or
another mesh warns ModelFemMismatchWarning and the file's own
MODEL group (no physical groups) is bound instead. Without
model_h5= the file's MODEL group is bound, as before.
Stage names with model_h5= (ADR 0122 D3, #2101, #2823): the
ops.stage(name=...) names and each stage's analysis kind
from /opensees/stages replace the file's MODEL_STAGE[<k>]
names, which stay resolvable as aliases; a stage is never paired
with a program stage by position alone
(_bind.py::_bind_ladruno_stage_names):
- a file stamped with
INFO/PROVENANCE@stage_namesbinds each stage to the program stage its stamp names, in any order; a stage stamped with its ownMODEL_STAGEname (modes) keeps it. A stamped name the program does not declare, or a program stage of another kind than the recordedKIND, raisesStageStampRefusednaming it; - an unstamped file: a modes-only stage (
KIND=eigen, no step) is no program stage and keeps its name. The others pair one to one when they are as many as the program's stages, where a disagreeingKINDrenames nothing and warnsStageKindMismatchWarning(#2079 Q7;KIND=eigenor none is no evidence either way); fewer pair with the program's first stages only when theirKINDs fit no other run of program stages (a partial run,StageCountMismatchWarning), and otherwise keep their names withUnpairedStageWarning.
Without model_h5= the file's names stand.
The file records no per-node ndf, so the recorder writes 0.0 for
a rotation a node does not have (a solid node beside a shell).
With model_h5= a one-file read gives NaN there, from the
model's /opensees/nodes_ndf; without it a rotation read over
continuum elements warns AbsentDofWarning once (#1971).
MPM particles (ADR 0134 D3/D4): at ``INFO/FORMAT_MINOR_VERSION
= 2
a stage's particle group reads through :attr:`particles` (results.particles.get(component=...)). An all-particle file opens withoutmodel_h5=: it has no FEM (:attr:`fem` isNone``), its broker wraps the empty stage model, and a node or element read of a particle-only stage refuses by name. A part file with particles is refused.
Keys on INFO/GENERATOR="Ladruno" + a supported
FORMAT_VERSION (the reader rejects a .mpco / foreign file
or an out-of-window version loudly).
Multi-partition merge: a parallel run writes one
<stem>.part-<N>.ladruno per rank. Passing one partition path
auto-discovers its siblings (<stem>.part-*.ladruno) and merges
them into one virtual reader (node-union + element-concat);
passing a list merges exactly those paths. merge_partitions=False
opts out of sibling auto-discovery.
Source code in src/apeGmsh/results/Results.py
710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 | |
from_fem
classmethod
¶
from_fem(fem: 'FEMData', path: 'str | Path | list[str | Path]', *, kind: str = 'auto', merge_partitions: bool = True, cache_root: 'str | Path | None' = None) -> 'Results'
Open a results file against a bare :class:FEMData snapshot.
The one-call route to :class:Results / :meth:viewer for a
model that did not go through the apeSees bridge — e.g. a
physical-group model where fem = g.mesh.queries.get_fem_data()
drove a hand-written OpenSees deck. Without this the only routes
were the bridge-bound constructors (which need a bridge-emitted
model.h5 / OpenSeesModel) or the self-describing
:meth:from_ladruno.
from_fem materialises a neutral-only model.h5 from fem
(cached, keyed by fem.snapshot_id) and binds it to the reader
for path. Materialising a file — rather than an in-memory
model — is deliberate: it sets model_path so the non-blocking
/ web viewers work (they forward --model-h5), not just data
access.
Parameters¶
fem
The bound snapshot (from g.mesh.queries.get_fem_data() or
FEMData.from_h5). A composed fem is refused — see
below.
path
The results file (or a partition list).
kind
"mpco" / "ladruno" / "native", or "auto"
(default) to detect from the suffix (.mpco / .ladruno;
a native .h5 must pass kind="native").
merge_partitions
Forwarded to :meth:from_mpco / :meth:from_ladruno for
.part-N auto-discovery.
cache_root
Where the materialised model.h5 is written — under
<cache_root>/from_fem/ (default <cwd>/results/from_fem/
or $APEGMSH_RESULTS_DIR).
Raises¶
ValueError
When fem is composed (g.compose / from_h5
assembly). Element / Gauss results are relabelled through the
fem_eid ↔ ops-tag map that only a real bridge run records;
a neutral-only model.h5 carries none, so a composed model
would silently mislabel every element result. Build the model
through apeSees and pass its model.h5 (e.g.
apeSees(fem).h5(...) / g.save →
from_mpco(path, model_h5=...)).
Notes¶
A bare fem carries no envelope ndf (MeshInfo has none), so
the cached model's ndf is 0. This is harmless for reading
results and for the viewer; it only matters for deck re-emit
(model.build(...)), which is not this path's purpose.
Source code in src/apeGmsh/results/Results.py
899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 | |
unit_factor ¶
unit_factor(component: str, *, level: 'str | Any' = 'nodes', target: 'Any' = None, source: 'Any' = None) -> float
Return the multiplicative conversion factor for component at
level (1.0 when target=None, or converting to target).
Raises :class:ValueError when target is supplied on an
undeclared Results without an explicit source=.
Source code in src/apeGmsh/results/Results.py
unit_symbol ¶
Return the display unit symbol for component in :attr:units
(e.g. "kN", "MPa"), or "" when :attr:units is None
or the component is dimensionless.
Source code in src/apeGmsh/results/Results.py
to_units ¶
Return a new :class:Results view whose slabs and bound
:attr:fem coordinates are scaled to target consistent units.
- When :attr:
unitsis declared on the model or results file,sourceis inferred automatically and may be omitted (passing a conflictingsourceraises :class:ValueError). - When :attr:
unitsisNone(undeclared),sourceis required — omitting it raises :class:ValueErrorasking the caller to specify the source unit system explicitly.
Source code in src/apeGmsh/results/Results.py
energy ¶
Energy-balance time history — Ladruno-recorder feature.
Returns a :class:pandas.DataFrame of the closure components
KE / IE / DW / ULW / RES / ERR indexed by
simulation time, written by the recorder's -G energy verb.
region=None→ whole-domain balance (ON_DOMAIN).region=<tag>→ the per-region balance (ON_REGIONS) for the OpenSees region tag.
ERR (the normalized energy-balance error %) is the headline
solution-quality diagnostic for explicit runs. Raises
:class:TypeError on a non-Ladruno results object (MPCO / native
carry no energy balance) and ValueError if energy was not
recorded / the region is unknown.
results.plot.energy(...) renders this as a matplotlib
time-history figure.
Source code in src/apeGmsh/results/Results.py
energy_regions ¶
OpenSees region tags with a recorded per-region energy balance.
The bridge auto-allocates an integer region tag when a Ladruno
recorder is given energy_pg= (or a value filter + energy);
that tag is opaque to the author. This lists the tags actually
present in ON_REGIONS/energyBalance so you can pick one to pass
to :meth:energy — e.g. r.energy(region=r.energy_regions()[0]).
Returns [] when only the whole-model balance was recorded
(read it with energy(), no region=). Ladruno-recorder
feature; raises :class:TypeError on MPCO / native results.
Source code in src/apeGmsh/results/Results.py
node_envelope ¶
Per-node time-reduced extremes — Ladruno -envelope feature.
When a .ladruno is recorded with the recorder's -envelope
flag, each node channel stores componentwise running extremes
(MIN/MAX/ABSMAX and the step at which the abs-extreme
occurred) instead of a time series — the cheap way to capture peak
response over a long run without keeping every step.
Returns a :class:pandas.DataFrame indexed by node id with columns
min / max / absmax / arg_step for component (a
neutral name like "displacement_x"). Raises :class:TypeError
on a non-Ladruno results object, and :class:ValueError if the file
was not recorded with -envelope or the component is absent.
results.plot.node_envelope(...) paints a chosen measure on
the mesh as a matplotlib figure.
Source code in src/apeGmsh/results/Results.py
bind ¶
Re-bind to fem.
Useful when you've re-built the same mesh in a fresh session and want labels / Parts that the embedded snapshot doesn't carry. No hash validation is performed — pairing the FEMData with a results file from the same run is the user's responsibility.
Source code in src/apeGmsh/results/Results.py
stage ¶
Return a Results scoped to a stage (matched by id, name or alias).
combinations ¶
combinations(user_h5: 'Optional[str | Path]' = None, *, model_h5: 'Optional[str | Path]' = None, spectra: Any = None) -> 'UserCombinations'
The set's User Combinations, evaluated per quantity on read (ADR 0130 D4).
user_h5 is the set's <stem>.user.h5. Omitted, the first that
exists beside this file is used: <model stem>.user.h5, then this
file's stem without .part-<N> and .results. model_h5
(default: the archive this was opened with) brings its
/opensees/combinations into the table. spectra reads the
spectrum and reference terms; by default it is a
:class:~apeGmsh.results.user.UserSpectra over that .user.h5's
/spectra, judged stale against model_h5 (ADR 0130 A6), so a
stale zone's terms are refused unless evaluate(...,
allow_stale=True).
A term names a stage by its stamped name, else stage_<i> (A3).
The names are bound when the results are opened (model_h5=), never
here: a read does not rename the caller's stages. So when the model
(model_h5, or the one this was opened with) declares program stage
names and none of them names a stage here, every stage and
mode term is refused, with a reason that says to open the results
with model_h5=; otherwise a term could read a different stage than
the same set opened with its model. That holds however the
Results was opened (from_fem binds a neutral cache archive
that names no stage). A Results with no names from either source
keeps stage_<i>, and so does one whose reader declined that same
model's names when it was opened.
evaluate(state, component, level=...) combines a recorded result
(level="domain" a /spectra domain value such as
base_shear), evaluate(state, user_result=...) a user result. A state handle of
another Results is refused.
Source code in src/apeGmsh/results/Results.py
1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 | |
close ¶
demo
classmethod
¶
Return a ready-to-view demo :class:Results (cantilever pushover).
Zero-setup sample data so Results.demo().show_web() (or
.viewer()) renders without supplying an .mpco /
model.h5 pair — handy for docs, smoke tests, and trying the
viewer. A real apeSees-emitted model with a synthetic, ramped
cantilever deflection (no OpenSees solve). See
:func:apeGmsh.results.make_demo_results for the keyword options
(length / n_elements / n_steps / tip_drift /
path).
Source code in src/apeGmsh/results/Results.py
assess ¶
Compile a v1 :class:~apeGmsh.assess.AssessmentReport.
figures=True calls :meth:render_pack. Default is False.
Source code in src/apeGmsh/results/Results.py
session ¶
The presentation session for these results (ADR 0098 §1).
Presentation with no window: a ResultsSession (from
apeGmsh.results.session) bound to this broker, booted with
the default picture — ONE empty mesh view (grey analysis mesh,
no slots, no legends). Configure it (slots, deform, time), then
s.render("a.png") for a still; the Qt client (s.show())
arrives at S2 and viewer() flips onto it at S6.
Persisted section cuts boot as view clips (ADR 0098 S6b).
The retired section_cut diagram kind took its auto-load
contract with it, but not the contract itself: cuts persisted
under /opensees/cuts/ come back on the booted view as
clips. Only the ones that translate honestly do — a cut that
named a strict subset of the model's elements, or that carries
a bounding polygon, cuts LESS than a view clip does, so it is
skipped with one [session] line rather than silently
widening what disappears from the screen. Reading the cuts can
never fail this call: a bad zone is a line, not a traceback.
Source code in src/apeGmsh/results/Results.py
viewer ¶
viewer(*, blocking: 'Optional[bool]' = None, title: Optional[str] = None, restore_session: 'bool | str' = 'prompt', save_session: bool = True)
Open the post-solve results window on a ResultsSession.
Sugar for :meth:session + show() (ADR 0098 §1, flipped at
S6a). The one-liner is unchanged; what it opens is not. A
:class:~apeGmsh.results.session.ResultsSession is the
document — tiled mesh and plot panes, each with the closed §4
slot catalog — and the window is a client that projects it. The
retired Geometry / Composition / Diagram window is gone from
this door. Everything the window does, a script can do to the
same object::
s = results.session() # the document, no window
s.render("a.png") # a still, no Qt
results.viewer() # the human one-liner
Parameters¶
blocking
None (default) — auto: True in scripts and the
plain CLI, False inside a Jupyter / IPython ZMQ kernel,
where the blocking Qt loop would freeze (often kill) the
kernel. A hand-built, in-memory Results (no backing file)
in a notebook cannot spawn a subprocess and raises
:class:RuntimeError naming the from_* constructors to
open it from a file instead. The notebook path announces
itself with one line.
True — open the window in-process and block the calling
thread until it closes. Matches the signature of
:meth:g.mesh.viewer and :meth:g.model.viewer.
False — spawn a subprocess via
python -m apeGmsh.viewers <path> so the notebook /
kernel can keep running. Requires that the Results was
opened from disk (self._path is set); raises
:class:RuntimeError for in-memory Results.
title
Optional window title; defaults to "Results — <filename>".
restore_session
What to do with a session snapshot saved beside the results
file. True restores silently, False ignores it,
"prompt" (default) asks. No effect for in-memory
Results, which have no file to sit beside.
save_session
If True (default), the session — panes, slots, pose,
time link, selection — is written to
<results>.viewer-session.json when the window closes.
False disables auto-save. Auto-save also disarms itself
for a window that could not read an existing file there, so
the unreadable file survives (INV-SESSION-OPEN, see
apeGmsh.results.session._boot).
Returns¶
ResultsSession
The session the window projected, after the window
closes (blocking). Still live: query it, render stills off
it, snapshot it.
subprocess.Popen
The spawned process handle (non-blocking). Deliberately not
unified with the blocking return — a session in this
process is not what the child window is showing.
None
If APEGMSH_SKIP_VIEWER is set in the environment. This
lets the same cell run under jupyter nbconvert --execute
or in CI without spawning a GUI window.
Raises¶
RuntimeError
Auto mode (blocking=None) inside a notebook kernel on an
in-memory Results (_path is None): there is no file for
python -m apeGmsh.viewers to open. Open the results with
:meth:from_native, :meth:from_mpco, :meth:from_ladruno,
:meth:from_recorders or :meth:from_fem. Nothing is
converted to a temporary file: the reader protocol does not
carry everything a native .h5 needs, so a conversion
would lose data (#1664).
Notes¶
The v13 <results>.viewer-session.json written by the retired
window is not restorable (ADR 0098 Consequences). The first
flipped open says so in one line and renames it aside to
.legacy — never overwriting it, and never overwriting an
aside that is already there.
cuts= is retired with the diagram ontology (§1): a cut plane
is clip state on a view. Build cuts with :mod:apeGmsh.cuts and
add them as clips — results.session() then view.add_clip.
Source code in src/apeGmsh/results/Results.py
1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 | |
render ¶
render(path: 'str | Path', *, view: str = 'contour', component: Optional[str] = None, step: int = -1, deform: 'Optional[Any]' = None, camera: 'Optional[str]' = None, window_size: tuple[int, int] = (1280, 720)) -> 'Optional[Path]'
Write one offscreen still (ADR 0094 S1).
Drawn by :meth:ResultsSession.render (X2-d): view is
translated into one session mesh view (slots, pose, instant)
and rendered VTK-offscreen — no Qt window, no event loop, no
setup(plotter, director). view is a closed set:
mesh / contour / deformed / reactions.
The stage drawn is the scope of results.stage(s) (or
results.modes[i]), else the only stage; an unscoped
multi-stage Results draws its LAST stage. step indexes that
stage.
camera= defaults to xy for a planar model, iso
otherwise (ADR 0094 Amendment 3); pass it explicitly to
override.
Returns the written :class:~pathlib.Path, or None (and
prints the [skip viewer] notice) under
APEGMSH_SKIP_VIEWER=1 or with no GL.
Source code in src/apeGmsh/results/Results.py
render_pack ¶
render_pack(out_dir: 'str | Path', *, camera: 'Optional[str]' = None, window_size: tuple[int, int] = (1280, 720)) -> tuple[Path, ...]
Write the canned report pack (ADR 0094 S3).
Each still is a :meth:render call, so the pack is drawn by
:meth:ResultsSession.render too. Returns the tuple of written paths, or () under
APEGMSH_SKIP_VIEWER=1 / no GL (and prints the
[skip viewer] notice). Closed view= set only; no
setup(). There is no fem.render_pack. The stage is
:meth:render's: a stage-scoped Results packs that stage.
camera= defaults to xy for a planar model, iso
otherwise (ADR 0094 Amendment 3); pass it explicitly to
override.
Source code in src/apeGmsh/results/Results.py
export_animation ¶
export_animation(path: 'str | Any', *, fps: int = 30, step_stride: int = 1, stage: 'Optional[str]' = None, deform: 'Optional[Any]' = None, camera: 'Optional[Any]' = None, window_size: 'Optional[tuple[int, int]]' = (1280, 720), setup: 'Optional[Any]' = None)
Render the time history to a video / GIF without a GUI session.
Re-steps one :class:~apeGmsh.results.session.ResultsSession
mesh view (the results.session() picture) through an
offscreen plotter: the scene is realized once, then each
captured step moves the session instant and re-steps the pane
in place. No Qt window and no event loop. Frames are encoded to
the format chosen by path's suffix: .mp4 (H.264, needs
the apegmsh[animation] extra) or .gif (Pillow, no
extra). A failed frame leaves no file at path.
Parameters¶
path
Output file. Suffix selects the format (.mp4 / .gif).
fps
Frames per second of the output.
step_stride
Capture every N-th step (plus always the last). Useful to
keep long histories short.
stage
Stage id/name to animate. Defaults to this Results' own
stage (results.stage(...)), else the only stage; with
several stages and none picked it raises.
deform
Deformed-shape scaling. A number applies that scale to the
"displacement" field; a (field, scale) pair selects
another field. None (default) renders the undeformed
mesh.
camera
"iso" / "xy" / "xz" / "yz", or an explicit
value assigned to plotter.camera_position. None
uses the still rule: xy for a planar model, iso
otherwise.
window_size
(width, height) of the rendered frames. None uses
(1280, 720).
setup
Optional callback(plotter, view) invoked once after the
first frame's scene is built and the camera applied, before
capture. view is the session's
:class:~apeGmsh.results.session.MeshView: fill a slot
(view.contour = Contour("displacement_x")) and the
pane is realized again before the first frame. Before
X2-b (#1663) the second argument was the retired
ResultsDirector; a callback still written against it
fails loudly.
Returns¶
pathlib.Path
The resolved output path, or None when
APEGMSH_SKIP_VIEWER is set or no GL context is
available.
Source code in src/apeGmsh/results/Results.py
2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 | |
show_web ¶
show_web(*, stage: 'Optional[str]' = None, show: bool = True, controls: bool = True, render_mode: str = 'client')
Open the view-only web / Jupyter results viewer (ADR 0042 R-C).
Renders the FEM substrate plus any diagrams the director holds
through a pyvista.trame backend — the kernel-safe path that
replaces the blocking Qt :meth:viewer in a notebook. View-only
(picking is deferred to R-D), but with a step slider + per-layer
visibility checkboxes when ipywidgets is available.
No results file handy? Results.demo().show_web() renders a
zero-setup cantilever-pushover sample.
Parameters¶
stage
Stage id or name to activate; defaults to the first stage.
show
When True (default), display inline immediately. When
False, return the :class:~apeGmsh.viewers.web_viewer.WebViewer
unshown so diagrams can be added via viewer.director first.
controls
When True (default), stack an ipywidgets control panel
(step slider + layer toggles) above the view. Degrades to a
bare view if ipywidgets is absent.
render_mode
"client" (default) renders in the browser via WebGL — fast
camera interaction. "server" renders on the kernel and
streams images (laggy, most VTK-feature-complete; for very
large models). "hybrid" is pyvista's trame backend with
a local/remote toggle in the toolbar.
Returns¶
WebViewer
The viewer handle (.director / .set_step / .show).
Source code in src/apeGmsh/results/Results.py
serve_web ¶
serve_web(*, stage: 'Optional[str]' = None, render_mode: str = 'client', port: 'Optional[int]' = None, open_browser: bool = True, title: str = 'apeGmsh', **start_kwargs)
Serve the results as a standalone trame web app (ADR 0042 R-C).
The non-Jupyter counterpart of :meth:show_web: builds a vuetify3
single-page app (the FEM view plus a step slider and per-layer
switches) and serves it at a local URL, opening a browser tab and
blocking until stopped (Ctrl-C). In a notebook use :meth:show_web
instead.
Parameters¶
stage
Stage id or name to activate; defaults to the first stage.
render_mode
"client" (default), "server", or "hybrid" — see
:meth:show_web.
port
Port to serve on; None lets trame pick one.
open_browser
Open a browser tab at the served URL.
title
App title shown in the toolbar.
**start_kwargs
Passed through to the trame server.start (e.g.
exec_mode).
Returns¶
WebViewer The viewer handle.
Source code in src/apeGmsh/results/Results.py
save_definitions ¶
Persist this Results' custom scalar definitions to a JSON
sidecar (default <results>.defs.json).
Reloaded automatically by :meth:from_native / :meth:from_mpco
/ :meth:from_ladruno, and carried to the subprocess viewer.
Raises for an in-memory Results with no path= given.
Source code in src/apeGmsh/results/Results.py
load_definitions ¶
Load and register custom scalar definitions from a JSON sidecar
(default <results>.defs.json). Returns the count applied; a
missing file is a no-op returning 0. Idempotent / best-effort —
see :meth:_apply_definitions_payload.
Source code in src/apeGmsh/results/Results.py
Slabs¶
Tabular dataclasses returned by reader queries.
apeGmsh.results._slabs ¶
Slab dataclasses returned by ResultsReader implementations.
A slab carries one component's values plus enough location metadata
that the caller can interpret each row without re-deriving it. They
are numpy-native and immutable; the viewer wraps them in xarray
when it wants labeled axes.
Shape conventions (single-stage, post-stitching across partitions):
================ ======================== =================================================
Slab values shape Location index fields
================ ======================== =================================================
NodeSlab (T, N) node_ids: (N,)
ElementSlab (T, E, npe) element_ids: (E,)
LineStationSlab (T, sum_S) element_index, station_natural_coord: (sum_S,)
GaussSlab (T, sum_GP) element_index: (sum_GP,),
natural_coords: (sum_GP, dim)
FiberSlab (T, sum_F) element_index, gp_index, y, z, area,
material_tag: (sum_F,),
station_natural_coord: (sum_F,) | None
LayerSlab (T, sum_L) element_index, gp_index, layer_index,
sub_gp_index, thickness: (sum_L,)
ParticleSlab (S, nComp) ragged particle_ids: (S,), offsets: (T+1,)
================ ======================== =================================================
GaussCensus is not a slab: it is the subset of ONE GaussSlab
time row that met a predicate (see Results.elements.gauss's
tension_census / corner_census).
For a single time step (time_slice was a scalar), T is 1 and
the leading axis is preserved — the caller can squeeze if desired.
LocalAxes
dataclass
¶
Per-element local coordinate frames (beam / shell orientation).
Read from a .ladruno MODEL/LOCAL_AXES group — the orientation a
.mpco does not carry for beam-columns (so apeGmsh can orient
line / section-force diagrams straight from .ladruno for wired
element classes, instead of the native vecxz path).
quaternions are scalar-first (w, x, y, z), mapping global →
element-local at the reference configuration. The local axes are the
rows of the rotation matrix (OpenSees quatFromMat stores the
transpose convention), so matrices[k] has row 0 = local x, row 1 =
local y, row 2 = local z — each expressed in global coordinates.
Elements with no recorded frame get the identity quaternion.
NodeSlab
dataclass
¶
Node-level result values.
item ¶
The slab's one value, as a float (ADR 0115 D3).
Raises :class:ValueError unless values holds exactly one
value: one node at one time step. Narrow the read first, by node
(label=, pg=, ids=) and by time (time=-1). It
replaces .values[-1, 0], which answers silently from whatever
the slab holds.
Source code in src/apeGmsh/results/_slabs.py
ElementSlab
dataclass
¶
Per-element-node values (e.g. globalForce / localForce).
LineStationSlab
dataclass
¶
LineStationSlab(component: str, values: ndarray, element_index: ndarray, station_natural_coord: ndarray, time: ndarray, local_axes_quaternion: Optional[ndarray] = None)
Beam line-diagram values per integration station.
GaussSlab
dataclass
¶
GaussSlab(component: str, values: ndarray, element_index: ndarray, natural_coords: ndarray, local_axes_quaternion: Optional[ndarray], time: ndarray)
Continuum Gauss-point values.
natural_coords are gmsh reference coordinates for every family:
[-1, +1]^d for lines, quads and hexes, and (u, v[, w]) on the
unit simplex for triangles and tets, where node 0 carries
1 - u - v[ - w] and node k the k-th coordinate (the frame
the gmsh shape functions in :mod:apeGmsh.fem._shape_functions take).
Every reader converts its source's frame to this once, at the source
(#2228): an element's barycentric rule is never passed through. To get
global coordinates, call slab.global_coords(fem) — interpolates
through the bound FEMData's element shape functions for hex8 /
quad4, falling back to a centroid + bbox-scaled approximation for
element types that don't yet have explicit shape-fn support.
global_coords ¶
Map per-GP natural coords to (sum_GP, 3) world coords.
Uses element shape functions for supported types (hex8, quad4);
falls back to centroid + 0.5 * bbox_span * natural for
others — visualization-faithful for axis-aligned elements.
Source code in src/apeGmsh/results/_slabs.py
GaussCensus
dataclass
¶
GaussCensus(component: str, predicate: str, count: int, examined: int, values: ndarray, element_index: ndarray, natural_coords: ndarray, time: float)
The Gauss points of a :class:GaussSlab that met a predicate.
A census answers "how many, and where" at ONE instant — the count
plus the location metadata needed to draw or tabulate the matching
points. It carries the same element_index / natural_coords
pair a :class:GaussSlab does, so
:meth:global_coords behaves identically.
count is element_index.size; examined is how many Gauss
points the predicate ran over, so count / examined is the
fraction without a second read. Both are needed: a census of 12 is
a different fact at 40 Gauss points than at 40 000.
global_coords ¶
Map the matching GPs to (count, 3) world coords.
Same reconstruction (and same
:class:~apeGmsh.results._gauss_world_coords.WarnGaussCoordsApproximate
caveat) as :meth:GaussSlab.global_coords.
Source code in src/apeGmsh/results/_slabs.py
FiberSlab
dataclass
¶
FiberSlab(component: str, values: ndarray, element_index: ndarray, gp_index: ndarray, y: ndarray, z: ndarray, area: ndarray, material_tag: ndarray, time: ndarray, station_natural_coord: Optional[ndarray] = None)
Fiber-level values within fiber-section GPs.
LayerSlab
dataclass
¶
LayerSlab(component: str, values: ndarray, element_index: ndarray, gp_index: ndarray, layer_index: ndarray, sub_gp_index: ndarray, thickness: ndarray, local_axes_quaternion: ndarray, time: ndarray)
Layered shell layer values (one row per (elem, surf_gp, layer, sub_gp)).
ParticleSlab
dataclass
¶
ParticleSlab(component: str, values: ndarray, particle_ids: ndarray, offsets: ndarray, time: ndarray, step: ndarray, registry_ids: ndarray, components: tuple[str, ...])
Particle values in the file's own ragged layout (ADR 0134 D4).
Particles move, appear and disappear, so an output's particle count
varies. The slab keeps the .ladruno CSR layout (contract 232a
§2.5): output k is rows offsets[k]:offsets[k + 1] of
values and particle_ids.
================ =============================================
values (S, nComp), concatenated over outputs
particle_ids (S,), sorted within each output
offsets (T + 1,), offsets[0] = 0, offsets[T] = S
time (T,) the Domain time; it may restart in a stage
step (T,) the Domain commit tag, strictly increasing
registry_ids (M,) the stage registry rows this read covers
components nComp labels, as the file spells them
================ =============================================
Outputs are keyed by index or step, never by time.
output ¶
Output k's (particle_ids (n,), values (n, nComp)).
Source code in src/apeGmsh/results/_slabs.py
dense ¶
(T, M, nComp) aligned to :attr:registry_ids, NaN where a
particle is absent from an output.
Source code in src/apeGmsh/results/_slabs.py
item ¶
The slab's one value, as a float (ADR 0115 D3).
Raises :class:ValueError unless values holds exactly one
value: one particle, one component, one output. Narrow the read
by particle (ids=), component ("FIELD/label") and output
(time=-1) first.
Source code in src/apeGmsh/results/_slabs.py
SpringSlab
dataclass
¶
Zero-length spring values (one column per element, one spring index).
component encodes which spring is represented (e.g.
"spring_force_0" for the force in the first configured spring
direction). Each column in values corresponds to one element;
element_index carries the raw OpenSees element tag so the
caller can correlate columns with elements without needing a
separate ID array.
================ ========================
values (T, E)
element_index (E,)
================ ========================
Readers¶
Reader protocol and supporting types shared by every backend.
apeGmsh.results.readers._protocol ¶
Reader protocol — backend-agnostic contract for the composite layer.
Two implementations:
NativeReaderreads apeGmsh native HDF5 (Phase 1).MPCOReaderreads STKO MPCO HDF5 (Phase 3).
The composite layer above (Results.nodes.get(...) etc.) talks
only to this protocol — it never branches on backend type.
ResultLevel ¶
Bases: Enum
The topology level a component lives at.
StageInfo
dataclass
¶
StageInfo(id: str, name: str, kind: str, n_steps: int, eigenvalue: Optional[float] = None, frequency_hz: Optional[float] = None, period_s: Optional[float] = None, mode_index: Optional[int] = None, aliases: tuple[str, ...] = ())
Stage metadata returned by ResultsReader.stages().
For kind="mode", the eigenvalue/frequency/period/index
fields are populated and n_steps is 1. For other kinds,
the mode-only fields are None.
aliases are further names Results.stage(...) resolves to
this stage. Empty under every reader's own naming; an MPCO reader
that has had the program's stage names attached (#1324) keeps the
file's MODEL_STAGE[<k>] group name here so older scripts still
find it.
EigenMode
dataclass
¶
Lightweight snapshot of one eigenmode — no file handle.
Returned by :attr:apeGmsh.results.Results.eigen_modes. Mirrors
the mode-only fields of :class:StageInfo but is detachable from
the Results context, so it is safe to pickle, pass between
processes, or return from a function whose Results was already
closed.
For the mode shape (per-node displacement vectors), use the
mode-scoped :class:apeGmsh.results.Results from results.modes
and query via results.nodes.get(component="displacement_x", ...)
— that path holds the file handle and reads the underlying arrays.
omega_rad_s
property
¶
Angular frequency omega = sqrt(eigenvalue) in rad/s.
Returns 0.0 for non-positive (rigid-body or numerical
zero) eigenvalues — the mode-stage writers' convention.
ResultsReader ¶
Bases: Protocol
Backend-agnostic reader protocol.
Implementations must support all six topology levels even if a
given file has no data at some of them; they should return empty
component lists from available_components() in that case
rather than raising.
stages ¶
time_vector ¶
partitions ¶
fem ¶
Embedded / synthesized FEMData snapshot.
NativeReader: reconstructs from/model/when the file carries it. An embedded/modelbelow its floor is listed inNativeReader.unavailable_zonesand this raisesSchemaVersionErrorwith that text instead of reading it (ADR 0113 D9);/stagesread regardless.MPCOReader: synthesizes a partial FEMData from/MODEL/(no apeGmsh labels, no Part provenance).
Source code in src/apeGmsh/results/readers/_protocol.py
opensees_model ¶
Embedded :class:OpenSeesModel from the file's /opensees/ zone.
Phase 4 (ADR 0020) — the Composed-file pattern. Native readers
auto-resolve from the file when the zone is present, and raise
SchemaVersionError when that zone or the /model it pairs
with is below its floor (ADR 0113 D9: the zone is flagged in
NativeReader.unavailable_zones and never read silently);
third-party file readers (MPCO) return None.
Returns¶
OpenSeesModel | None
The rehydrated broker when the file carries the zone,
None otherwise. INV-1 — Phase 4 callers must tolerate
None; the value becomes required only in Phase 8.
Source code in src/apeGmsh/results/readers/_protocol.py
available_components ¶
Live capture¶
Recorder wiring used during a live OpenSees analysis.
LiveRecorders¶
apeGmsh.results.live._recorders.LiveRecorders ¶
LiveRecorders(spec: 'ResolvedRecorderSpec', output_dir: 'str | Path', *, file_format: str = 'out', ops=None, model=None)
Context manager that owns stage-scoped OpenSees recorders.
Parameters¶
spec
The :class:ResolvedRecorderSpec whose records to emit.
output_dir
Directory the recorder .out / .xml files land in.
Created on __enter__ if missing.
file_format
"out" (text) or "xml". Defaults to "out".
ops
The OpenSees module (or a stand-in for testing). Defaults to
the module the bridge drives
(:func:~apeGmsh.opensees.emitter.live.get_ops), resolved
lazily on __enter__. Pass it when you drive another
module by hand.
model
The built :class:~apeGmsh.opensees.OpenSeesModel. Records name
elements by FEM id; OpenSees records by element tag, and under
element_tags="sequential" (the bridge default) the two differ.
The model's (fem_eid, tag) pairing translates every -ele
list, and its ndm and per-node ndf map every node record's
-dof list to the DOFs the nodes carry (a 2-D frame's
rotation_z is DOF 3). Required whenever the spec holds a node
or element record. A
:class:~apeGmsh.opensees._recorder_translate.LiveDomainFacts
(what emit_default passes for a FEMData archive) maps the
-dof lists from the live domain's ndm, per-node ndf and
element classes instead, and pairs elements as its archive does.
Raises¶
RuntimeError
On __enter__ if the spec contains any modal records.
ValueError
On __enter__ if the spec holds a layers record, or a node
or element record (fibres included) is emitted without
model=, names a FEM id the model has no element for, or
records a DOF its nodes do not carry.
Source code in src/apeGmsh/results/live/_recorders.py
begin_stage ¶
Issue recorders for a new stage. Files are prefixed <name>__.
kind is forwarded to Results.from_recorders(...,
stage_kind=kind) when the stage is read back; valid values
are "transient" or "static".
Source code in src/apeGmsh/results/live/_recorders.py
end_stage ¶
Remove the current stage's recorders and flush their files.
Source code in src/apeGmsh/results/live/_recorders.py
LiveMPCO¶
apeGmsh.results.live._mpco.LiveMPCO ¶
Context manager that owns a single in-process MPCO recorder.
Parameters¶
spec
The :class:ResolvedRecorderSpec whose records to emit.
path
Output .mpco HDF5 file path. Parent directory created on
__enter__ if missing.
ops
The OpenSees module (or a stand-in for testing). Defaults to
the module the bridge drives
(:func:~apeGmsh.opensees.emitter.live.get_ops), resolved
lazily on __enter__. Pass it when you drive another
module by hand.
Raises¶
RuntimeError
On __enter__ if ops.recorder('mpco', ...) fails — most
commonly because the openseespy build does not include the
MPCO recorder.
Source code in src/apeGmsh/results/live/_mpco.py
LiveDefault¶
The default route, returned by ResolvedRecorderSpec.emit_default.
apeGmsh.results.live._default.LiveDefault ¶
LiveDefault(spec: 'ResolvedRecorderSpec', path: 'str | Path', *, model_h5: 'str | Path', ops: Any = None, overwrite: bool = False)
Context manager that records one in-process run on the default route.
Parameters¶
spec
The :class:ResolvedRecorderSpec whose records to emit.
path
Names the run: the route replaces its suffix ("", .mpco or
the fork's suffix), so "run" records run.mpco on a stock
build.
model_h5
The model archive the live domain was built from: the bridge's
(ops.h5) or a FEMData archive (fem.to_h5). Required: every
route's read pairs with it. A FEMData archive declares no ndm and
archives no per-node ndf or element classes, so the
classic-recorder route reads them from the live domain
(getNDM, getNDF, eleType; #2251). It pairs no FEM
element id with an OpenSees tag either, so an element record pairs
each FEM element with the live element of its own id only when
that element's eleNodes is the FEM connectivity in order and
its class is known; any other id refuses, naming it (#2269).
A per-Gauss-point material record reads through that pairing
(#2290), and so does a fibers record: its elements' section
locations and fibre counts are read from the live domain at
__enter__, in place of a beamIntegration.
ops
The OpenSees module, or a stand-in for testing. Defaults to the
module the bridge drives.
overwrite
Replace the fork's file of an earlier run (on a stock MPCO build,
the .ladruno the run converts to). Without it a rerun onto an
existing file refuses at __enter__. With it, both routes
remove that file at __enter__, once the run will record: a
stock read that then refuses leaves no earlier .ladruno
beside the new .mpco.
Source code in src/apeGmsh/results/live/_default.py
results ¶
Open what the run recorded, on the route __enter__ picked.
cache_root is where the classic-recorder route caches its
transcoded file (:meth:Results.from_recorders); the other routes
read their file in place and ignore it.
The stock MPCO route converts its .mpco to the .ladruno
beside it (atomically; the .mpco is kept) and opens that. When
the file's stages do not pair with the declared ones, it refuses
with :class:~apeGmsh.results.readers._ladruno_from_mpco.StageKindRefused
and writes nothing; the .mpco is never read in its place.
Source code in src/apeGmsh/results/live/_default.py
read_deck_mpco¶
apeGmsh.results.live._default.read_deck_mpco ¶
Read the .mpco of a deck the bridge emitted, on the default route.
path is the .mpco written by running the bridge's own exported
deck (ops.py / ops.tcl) out of process, as it was emitted, and
model_h5 the archive of that bridge. An in-process run (ops.run()
then your own opspy.analyze loop) is not a deck and writes no run
record: record it with :meth:ResolvedRecorderSpec.emit_default,
whose stock MPCO route converts the same way when model_h5
declares its stages and otherwise refuses by name (ADR 0131 D5).
The .mpco (or any part of a partitioned set) converts to the fork's
format beside it, which is then opened; the .mpco is always kept.
A staged program converts: each ops.stage records its kind. An
unstaged program converts only through convert_mpco's private
_implicit_stage path, which only this function passes, when the
deck's run record (<recorder file>.run.json, written by a deck
emitted with analyze_steps) passes the checks in the converter's
module docstring. Otherwise it refuses by name: a refusal about stage
kinds
(:class:~apeGmsh.results.readers._ladruno_from_mpco.StageKindRefused)
raises again as one, quoting it, naming the remedies (declare the
stages with ops.stage(...), or emit the deck with
analyze_steps), and chained from the converter's refusal
(__cause__), which ops.results quotes under its own
remedies. No kind is defaulted, the .mpco is never read in its
place, and nothing is written. Every other
refusal (the archive is another model's, an incomplete partition set,
a staging directory in the way) raises as it is. A converted file from
an earlier run refuses unless overwrite=True.
Source code in src/apeGmsh/results/live/_default.py
Inspect¶
apeGmsh.results._inspect.ResultsInspect ¶
results.inspect — what's available.
Source code in src/apeGmsh/results/_inspect.py
summary ¶
Multi-line human-readable summary.
Source code in src/apeGmsh/results/_inspect.py
components ¶
Available components per topology level for one stage.
If no stage is given, defaults to the only stage when there is exactly one; otherwise raises.
Source code in src/apeGmsh/results/_inspect.py
diagnose ¶
Explain where a component lives (or doesn't) in this stage.
When a viewer or downstream consumer asks for a component and
gets nothing back, this is the routing-side answer to "why
is the slab empty?". Walks every topology, calls each
composite's available_components(), and returns a
human-readable report that shows where component was
found and what's actually available at each level.
Parameters¶
component
Canonical component name (e.g. "axial_force",
"displacement_z", "stress_xx").
stage
Stage id or name. Defaults to the only stage when there
is exactly one.
Returns¶
str Multi-line report. Print it or include it in an error message.
Source code in src/apeGmsh/results/_inspect.py
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 | |
Vocabulary¶
Canonical result names and shorthand expansion.
apeGmsh._vocabulary ¶
Canonical component names and shorthand expansion.
apeGmsh speaks one canonical name per result component, chosen to be
verbose and human-readable. Backend adapters (MPCO, recorder
transcoders, domain capture, OpenSees recorder declarations) translate
to these names on the way in. Users can also write shorthands
("displacement", "stress") which expand here, clipped to the
active ndm/ndf.
This is the single source of truth for "what components exist."
Location history. This module originally lived at
apeGmsh.results._vocabulary (results-side ownership). Phase 9
moved it to the top-level apeGmsh._vocabulary so that both the
OpenSees bridge (declaration-side) and the results module
(consumer-side) can import without creating a layering inversion. The
content is solver-neutral — future second-solver work consumes the
same vocabulary. The legacy apeGmsh.results._vocabulary shim has been removed.
ALL_CANONICAL
module-attribute
¶
ALL_CANONICAL: frozenset[str] = frozenset(NODAL_KINEMATICS + NODAL_FORCES + PER_ELEMENT_NODAL_FORCES + LINE_DIAGRAMS + LINE_STATION_DEFORMATIONS + SHELL_STRESS_RESULTANTS + SHELL_GENERALIZED_STRAINS + STRESS + STRAIN + PLASTIC_STRAIN + DERIVED_SCALARS + FIBER + SPRING + MATERIAL_STATE)
expand_shorthand ¶
Expand a shorthand or pass through a canonical name.
Translational shorthands clip to ndm axes (e.g. ndm=2 →
displacement_x/y only). Rotational shorthands require
rotational DOFs in the active ndf and return () if there
are none. Tensor shorthands ("stress", "strain") clip to
3 components in ndm=2 (xx, yy, xy) and 6 in ndm=3.
Raises ValueError if name is neither a known shorthand
nor a canonical name.
Source code in src/apeGmsh/_vocabulary.py
is_canonical ¶
True if name is a known canonical component name.