OpenSees bridge¶
apeGmsh's OpenSees deck is constructed via the explicit-constructor pattern after the session closes:
from apeGmsh.opensees import apeSees
fem = g.mesh.queries.get_fem_data(dim=3)
ops = apeSees(fem)
ops.model(ndm=3, ndf=6)
# … typed-primitive declarations, explicit fix / mass / patterns …
ops.tcl("model.tcl") # or ops.py(...), ops.h5(...), ops.run()
The legacy g.opensees session composite and its sub-composites
(materials / elements / ingest / inspect /
export) were removed in Phase 8 of the bridge teardown
(ADR 0009).
apeSees brings the session in three ways (ADR 0051): MP
constraints (g.constraints.*) auto-emit; loads (g.loads.*)
and prescribed displacements (g.displacements.*) are opt-in —
a resolved load case reaches the deck only when a bridge pattern
imports it with p.from_model(case) (or you author it with
p.load(...)); masses and support fixities / SPs are
re-declared explicitly on ops
(ops.fix(pg=, dofs=), ops.mass(pg=, values=)).
Loads do not auto-emit. A
g.loads.*case reaches the solver only viap.from_model(case)inside a pattern (or an ad-hocp.load). Nothing auto-emits, so there is no double-count trap; the deck is authoritative — the bridge applies exactly the cases you import and does not audit the geometry's declared cases, so a case you don't import is simply not applied. A staged model must keep every pattern stage-scoped (s.pattern(series=...)) — a global pattern +ops.stage(...)raisesBridgeError.
Since the teardown, the bridge has been progressively widened:
- Loads are opt-in (ADR 0051). A
g.loads.*case reaches the runnable Tcl/Py deck (and the live/run path) only when a bridge pattern imports it withp.from_model(case)— or you author the load directly withp.load(...). Nothing auto-emits; the deck is authoritative (see the note above). - MP constraints emit automatically from
fem.nodes.constraints/fem.elements.constraints(ADR 0022, Phase 7b) —equalDOF/rigidLink/rigidDiaphragm/ASDEmbeddedNodeElementlines land in the runnable Tcl/Py deck without aningeststep. TheapeSees.h5(path)write target persists per-record details under/opensees/constraints/(additive minor schema bump 2.6.0 → 2.7.0). Auto-emits aTransformationconstraint handler when MP constraints are present and the user has not declared one. - Staged analysis ships via
ops.stage(name)— see Staged analysis below for the user- surface walkthrough, and the in-repo internals doc at staged-analysis.md for the per-stage emit pipeline. - Read-side broker.
OpenSeesModel.from_h5(path, fem_root=)provides a frozen read-only view of the persisted/opensees/zone with the embeddedFEMDatalazily attached (ADR 0019). Re-emit viaom.build("tcl", path)/om.build("py", path)/om.build("live")without rehydrating the apeSees primitives.
For the full user-facing surface (typed materials, sections, elements, recorders, patterns, analysis chain, staged analysis, SSI helpers, cuts and sweeps), see the in-repo api-design.md.
Public surface¶
apeGmsh.opensees.apeSees ¶
apeSees(fem: 'FEMData', *, units: 'Any' = None, default_orientation: Orientation | None | _UnsetType = _UNSET, opensees: 'OpenSeesTarget | None' = None, element_tags: ElementTagMode = 'sequential', _artifacts: bool = True)
Bases: _ContactQueryMixin, _ModalMixin, _GravityModalMixin, _FrfMixin, _ExplicitMixin
The OpenSees bridge.
Construct with a :class:~apeGmsh.mesh.FEMData snapshot:
.. code-block:: python
ops = apeSees(fem)
ops.model(ndm=3, ndf=6)
steel = ops.uniaxialMaterial.Steel02(fy=420e6, E=200e9, b=0.01)
...
The bridge holds declared state. apeSees.build() returns a
:class:BuiltModel (immutable) that emitters consume.
Parameters¶
fem
The FEM snapshot the bridge is built against.
default_orientation
Orientation field substituted on any
ops.geomTransf.<Type>() call where the user supplied
neither orientation= nor vecxz=. Defaults to
Cartesian() (Z-up) which matches the prevailing structural
convention. Pass an explicit None for 2D models, where
vecxz is omitted at emit time and an orientation field makes
no sense. Pass a custom orientation (e.g.
Cartesian(reference_axis=(0,1,0)) for a Y-up CAD import)
to set the model-wide default once.
element_tags
How emitted elements are numbered. "sequential" (default)
tags them 1, 2, ... in declaration order. "fem" (ADR 0111
D2) keeps every physical-group element's FEM element id as its
OpenSees tag, so a deck translated from another pre-processor
(STKO) keeps that tool's element ids; elements the bridge
synthesises (node-pair springs, interface zeroLength,
embedded / rebar / rigid-body / coupling elements) are numbered
above the largest FEM id. "fem" refuses an id <= 0 and
an element fanned out by two declarations (BridgeError at
emit).
_artifacts
ADR 0112 D1: every terminal emit and live build leaves the full
model.h5 at the session's conventional path
(:mod:~apeGmsh.opensees._internal.artifact_write). False
is for the library's own bridges only (importers, strut_tie,
the emit-cost bench); it is not a user-facing opt-out.
Source code in src/apeGmsh/opensees/apesees.py
8763 8764 8765 8766 8767 8768 8769 8770 8771 8772 8773 8774 8775 8776 8777 8778 8779 8780 8781 8782 8783 8784 8785 8786 8787 8788 8789 8790 8791 8792 8793 8794 8795 8796 8797 8798 8799 8800 8801 8802 8803 8804 8805 8806 8807 8808 8809 8810 8811 8812 8813 8814 8815 8816 8817 8818 8819 8820 8821 8822 8823 8824 8825 8826 8827 8828 8829 8830 8831 8832 8833 8834 8835 8836 8837 8838 8839 8840 8841 8842 8843 8844 8845 8846 8847 8848 8849 8850 8851 8852 8853 8854 8855 8856 8857 8858 8859 8860 8861 8862 8863 8864 8865 8866 8867 8868 8869 8870 8871 8872 8873 8874 8875 8876 8877 8878 8879 8880 8881 8882 8883 8884 8885 8886 8887 8888 8889 8890 8891 8892 8893 8894 8895 8896 8897 8898 8899 8900 8901 8902 8903 8904 8905 8906 8907 8908 8909 8910 8911 8912 8913 8914 8915 8916 8917 8918 8919 8920 8921 8922 8923 8924 8925 8926 8927 8928 8929 8930 8931 8932 8933 8934 8935 8936 8937 8938 8939 8940 8941 8942 8943 8944 8945 8946 8947 8948 8949 8950 8951 8952 8953 8954 8955 8956 8957 8958 8959 8960 8961 8962 8963 8964 8965 8966 8967 8968 8969 8970 8971 8972 8973 8974 8975 8976 8977 8978 8979 8980 8981 8982 8983 8984 8985 8986 8987 8988 8989 | |
opensees
property
¶
The :class:OpenSeesTarget bound on construction, or None.
all_fix_records
property
¶
All fix records — global + every stage's pool.
Returns a tuple of (origin, record) pairs where origin
is either "global" or f"stage {stage.name!r}". Order:
global pool first (in registration order), then each stage in
stage_records order, then each record within a stage in
registration order.
all_mass_records
property
¶
All mass records — global + every stage's pool.
Same shape as :attr:all_fix_records.
all_region_records
property
¶
All region records — global + every stage's pool.
Phase SSI-2.D PR-C introspection symmetry (matches the
:attr:all_fix_records / :attr:all_mass_records shape).
Validator V3 (PR-A) guarantees no name= collision across
scopes, so the user-facing name is unambiguous per
(origin, record) pair.
all_recorder_specs
property
¶
All recorder specs — global + every stage's pool.
Global recorders are sourced from self._primitives
filtered to :class:Recorder instances and EXCLUDING any
spec claimed by s.recorder(...); the per-stage entries
come from each :class:StageRecord's recorder_specs.
Origin is "global" or f"stage {stage.name!r}".
critical_time_step ¶
Query the active explicit integrator's critical time step dt_cr.
Fork-only (Ladruno): builds + emits a throwaway live model
(like :meth:eigen), primes one tiny step to trigger the
integrator's dt_cr computation, then returns the usable
(Noh-Bathe) limit.
Requires a complete analysis chain with an explicit
integrator constructed with cfl=True (e.g.
ops.integrator.ExplicitBathe(cfl=True)), a Transient
analysis, and element mass density (-rho / -mass) —
the dt_cr eigensolve uses element mass+stiffness, not
ops.mass nodal mass.
Raises¶
BridgeError
If the analysis chain is incomplete.
NotImplementedError
If the model has registered stages (live execution of staged
models is unsupported — emit Tcl/Py instead).
ValueError
If dt_cr is not usable (no cfl flag, a non-explicit
integrator, or a pure nodal-mass model).
Source code in src/apeGmsh/opensees/procedures/_explicit.py
analyze_explicit ¶
analyze_explicit(*, duration: float, safety: float = 0.9, dt_max: float | None = None) -> 'ExplicitRunResult'
Run an explicit transient over duration, auto-sized to dt_cr.
Fork-only (Ladruno) driver implementing the explicit-dynamics
sub-stepping recipe (ADR D5): build + emit, prime one tiny step,
query the critical time step, then integrate duration in
n = ceil(duration / (safety * dt_cr)) equal sub-steps via a
single analyze(n, duration / n).
.. warning::
dt_cr is queried once, on the initial stiffness. For a
model whose tangent stiffens mid-run (contact closing,
geometric / material stiffening) the true critical step shrinks
and a fixed dt can go supercritical and diverge. Guard such
runs by constructing the integrator with cfl_abort=True (and
recompute=N) so a recomputed CFL violation aborts the run —
this method then re-raises that abort as an error rather than
returning silently. A one-shot run with an unguarded integrator
emits :class:OpenSeesExplicitSolverWarning.
Parameters¶
duration
Total physical time to integrate (> 0).
safety
Fraction of dt_cr used as the step (0 < safety <= 1;
default 0.9). Scales the value criticalTimeStep()
returns — do not re-base it on any larger Noh-Bathe bound.
dt_max
Optional upper bound on the sub-step — use a step finer than
stability requires (e.g. for output resolution). > 0.
Returns¶
ExplicitRunResult
(n, dt, dt_cr) — the sub-step count, the step actually used,
and the queried critical time step.
Raises¶
BridgeError / NotImplementedError / ValueError
As for :meth:critical_time_step, plus ValueError for an
out-of-range duration / safety / dt_max.
RuntimeError
If the explicit analyze returns non-zero (divergence, or a
mid-run -cflAbort when the integrator is guarded).
Source code in src/apeGmsh/opensees/procedures/_explicit.py
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 | |
frequency_response ¶
frequency_response(*, f_min: float, f_max: float, n_freq: int, node: 'int | Node', dof: int, num_modes: int, grid: str = 'lin', base_accel_dir: int | None = None, load: 'Plain | str | None' = None, amp: float = 1.0, damp: float | None = None, rayleigh: tuple[float, float] | None = None, modal_damp: Sequence[float] | None = None, resp: str = 'disp', modes: Sequence[int] | None = None, out: str | None = None, solver: str = '-genBandArpack') -> 'FrequencyResponseResult'
Compute the complex modal FRF of one response DOF, live.
Fork-only (Ladruno ADR-44 P2, frequencyResponse): for a
harmonic excitation amp·e^{iΩt} the steady response is a
dense post-processor on the mode basis — no time stepping.
Returns a :class:FrequencyResponseResult (frequencies in Hz
+ complex FRF).
Excitation: base_accel_dir= for uniform harmonic base
acceleration along a global direction (no timeSeries — the
sweep is per amp; relative response) XOR load= for
harmonic nodal forces amp·P·e^{iΩt} from a plain-nodal-load
pattern (absolute response).
grid: "lin" / "log" / "biased" — biased adds a
±5 % cluster around each in-band modal frequency so sharp
low-damping peaks are not stepped over.
resp: "disp" | "vel" (iΩ·û) | "accel"
(−Ω²·û). out= additionally writes the table to an
ASCII file.
Source code in src/apeGmsh/opensees/procedures/_frf.py
steady_state_dynamics ¶
steady_state_dynamics(*, f_min: float, f_max: float, n_freq: int, node: 'int | Node', dof: int, num_modes: int, grid: str = 'lin', base_accel_dir: int | None = None, load: 'Plain | str | None' = None, amp: float = 1.0, damp: float | None = None, rayleigh: tuple[float, float] | None = None, modal_damp: Sequence[float] | None = None, resp: str = 'disp', modes: Sequence[int] | None = None, out: str | None = None, solver: str = '-genBandArpack') -> 'SteadyStateResult'
Steady-state harmonic response amplitude |response| per
sweep frequency — the magnitude companion of
:meth:frequency_response (same flags, fork ADR-44 P2).
Source code in src/apeGmsh/opensees/procedures/_frf.py
random_response ¶
random_response(*, f_min: float, f_max: float, n_freq: int, node: 'int | Node', dof: int, num_modes: int, input_psd: 'TimeSeries | str', grid: str = 'biased', base_accel_dir: int | None = None, load: 'Plain | str | None' = None, damp: float | None = None, rayleigh: tuple[float, float] | None = None, modal_damp: Sequence[float] | None = None, resp: str = 'disp', modes: Sequence[int] | None = None, stats: bool = False, duration: float | None = None, out: str | None = None, solver: str = '-genBandArpack') -> 'RandomResponseResult'
Stationary random response RMS on the modal FRF, live.
Fork-only (Ladruno ADR-44 P3, randomResponse):
input_psd is a one-sided PSD G(f) in Hz ((excitation)²/
Hz), supplied as a registered timeSeries sampled at f in Hz
(Path with f→G breakpoints, Constant for white noise).
With base_accel_dir= it is the base-acceleration PSD; with
load= the PSD of the scalar multiplying the pattern's
nodal-load shape (fully correlated).
grid defaults to "biased" — the RMS is a band integral
and a linear grid mis-integrates sharp resonances (fork guide
P3). The band [f_min, f_max] must cover the input's
support and every resonance carrying response power; the fork
refuses zero-damped in-band modes and a rigid-body mode with
f_min = 0.
stats= adds ν₀ (mean zero-upcrossing rate, Hz) and the
spectral moments m0 / m2; duration= additionally
appends the Davenport expected peak over that exposure.
Source code in src/apeGmsh/opensees/procedures/_frf.py
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 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | |
modal_after_gravity ¶
modal_after_gravity(num_modes: int, *, p_delta: bool = True, solver: str = '-genBandArpack', basis: str = 'eigen', ritz_dirs: Sequence[int] = (), ritz_patterns: 'Sequence[Plain | str]' = (), residual: 'Sequence[int] | None' = None, residual_period: float | None = None) -> 'GravityModalResult'
Gravity preload, loadConst, then eigen + modalProperties
on the same live domain.
The sequence (ADR 0124 D1):
- Build and emit the model, as :meth:
analyzedoes. - Run the declared analysis chain to
λ = 1: every registered load pattern is the gravity preload (declare the gravity combination, e.g.D + SD + 0.25 L, as the patterns and their factors). The chain must beStaticwith a fixed-incrementLoadControl(dlam=1/N); the driver runs theNsteps, and the declaredtestandalgorithmset the tolerance and the iteration (Newtonconverges a P-Delta model; the step count is thedlam). loadConst -time 0: the gravity loads stay on, frozen.eigenon the current tangent, thenmodalProperties -return.
The mode set (fork chain M, Ladruno ADR 213). The order is
fixed: the basis, then the residual pseudo-modes, then
modalProperties, with no eigen in between (a later
eigen drops the pseudo-modes and the mode tags).
basis="eigen"(default) solveseigen;basis="ritz"runsritzVectors num_modesinstead, with the starting loadsM ι_dfor each ofritz_dirsand the reference loads of each ofritz_patterns(the gravity pattern gives a basis whose static participation in that load is 100 %). Ritz periods are Rayleigh periods, not natural periods.residual=dirsappendsresidualModes -dir dirs: the missing-mass pseudo-modes, so the modal mass of each direction reaches 100 %. On a Ritz basis the fork re-solves the joint set (all tagged Ritz).residual_period=Tadds-period T: a spectrum reads the pseudo-modes' Sa atTand combines them as one rigid mode (ADR 213 D3b). The fork refuses it on a Ritz basis, and so does the bridge.
Each mode's kind is on the result
(:attr:~apeGmsh.opensees.analysis.modal.ModalPropertiesResult.kinds).
What p_delta means. True solves step 4 after the preload,
so the stiffness is K - Kg with Kg from the gravity axial
forces. False solves it before step 2, on the unstressed
stiffness K (no initial axial force), and the gravity analysis
runs afterwards; the result's :attr:~GravityModalResult.gravity
is the same in both. The geometric stiffness comes from the element
formulation, not from this driver: geomTransf PDelta (or
Corotational) frames and geometrically nonlinear shells such as
:class:~apeGmsh.opensees.element.shell.ShellNLDKGQ carry it; a
Linear transformation or a linear shell gives the same modes
either way.
Solver. solver is passed to eigen verbatim. The default
-genBandArpack is the ARPACK ArpackSOE, which factors through
the analysis's own linear system, so the declared system
(UmfPack/BandGen on stock, Pardiso on the fork) is the
one the eigen solve uses. ARPACK needs num_modes below the free
DOF count; use -fullGenLapack on a tiny model.
The gravity state is snapshot right after step 3 and re-read after
step 4; a difference raises (the eigen solve must not move the
domain). The domain is left at the gravity state, and the bridge's
read session (Node.read) answers there.
Parameters¶
num_modes
Modes to extract, >= 1.
p_delta
True (default): modes on K - Kg after the preload.
False: modes on K before it.
solver
The eigen solver flag.
basis
"eigen" or "ritz" (num_modes Ritz vectors).
ritz_dirs, ritz_patterns
The Ritz starting loads (basis="ritz" only; at least one):
global translations, and ops.pattern.Plain handles or names.
residual
Directions (1, 2, 3) to complete with residualModes, or
None.
residual_period
The pseudo-modes' Sa period T (s), or None for their
Rayleigh periods. Needs residual; refused with
basis="ritz".
Raises¶
ValueError
num_modes < 1, the integrator is not a fixed-increment
LoadControl reaching λ = 1, or the mode-set options do
not fit together.
BridgeError
The analysis chain is incomplete, or not Static; or a Ritz
basis or residual is asked of an MPI (partitioned) model.
ForkTooOldError
basis="ritz" or residual on a build without chain M.
NotImplementedError
The model has registered stages (live runs flat models only,
ADR 0121 D2).
RuntimeError
The gravity analysis failed to converge, or the eigen solve
moved the gravity state.
Source code in src/apeGmsh/opensees/procedures/_gravity_modal.py
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 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | |
spectrum_after_gravity ¶
spectrum_after_gravity(num_modes: int, *, spectra: 'Sequence[DesignSpectrum]', extractors: 'Mapping[str, ResponseExtractor]', p_delta: bool = True, solver: str = '-genBandArpack', basis: str = 'eigen', ritz_dirs: Sequence[int] = (), ritz_patterns: 'Sequence[Plain | str]' = (), residual: 'Sequence[int] | None' = None, residual_period: float | None = None) -> 'SpectrumModalResult'
Per-mode response spectrum about the gravity state (ADR 0124 D4).
Runs :meth:modal_after_gravity's sequence, then settles the
reference state with unloaded Linear steps (so it is the
equilibrium, not wherever the declared test stopped). On the same
domain, for each mode k and each sign, it applies the probe
force ± a_k M φ_k as a nodal-load pattern, takes one Linear
step on the current tangent at dλ = 0 (the tangent the modes
were solved on, so the domain moves by exactly ± a_k φ_k / λ_k),
calls every extractor there, removes the pattern and settles back.
The per-mode value under spectrum d is
Γ_kd Sa_d(T_k) (Δr⁺ - Δr⁻) / (2 a_k), each Δr the leg's
change from its settled start: the state
responseSpectrumAnalysis -mode k imposes, about the reference
state instead of in place of it. Displacements are the modal ones to
round-off, PDelta included; element forces and reactions are those of
the elements at that state. The probe amplitude a_k does not
depend on the spectrum: the largest nodal translation moves by
1e-8 of the model's extent. A mode whose effective mass is below
1e-12 of the largest in every requested direction is skipped
(left at zero). The two legs must meet the same stiffness in every
element: a second difference of an element's resisting force above
1e-3 of its first difference (a no-tension brace or a gap at zero
strain, a material that loads and unloads on different branches,
such as Concrete01 on its backbone) raises. A mode that fails
that check is probed again at 100 times the amplitude, judged there,
and takes its values from that probe: a kink's ratio does not depend
on the amplitude, while round-off (a near-rigid link, whose force is
a large stiffness times a tiny deformation) shrinks with it. Combine
the result
with :meth:SpectrumModalResult.combine (CQC / SRSS) and
:meth:SpectrumModalResult.directional (100/30 / SRSS); the gravity
values are kept apart (:func:~apeGmsh.opensees.analysis.spectrum.seismic_envelope).
The reference state is the gravity state with p_delta=True and
the unloaded state with p_delta=False (modes and per-mode
responses on K, gravity run afterwards). With p_delta=True
the domain ends at the settled gravity state, checked against the
snapshot taken after settling; with a loose declared test that is
nearer equilibrium than the state the gravity analysis stopped at.
With p_delta=False it ends where the gravity analysis stopped.
Either way result.modal.gravity is the state the domain is left
at, so result.modal.gravity_drift() reads 0.0 right after the
call.
responseSpectrumAnalysis -mode k is not used: it replaces the
committed displacement with the modal one and commits, so the gravity
state is lost (ADR 0124, Context). Where the build takes the fork's
-increment flag (WP-207, ADR 0124 amendment) and every extractor
is a built-in one (NodeDisp, NodeReaction,
ElementResponse: they read the trial state), each leg is imposed
with responseSpectrumAnalysis -mode k -increment at the same
probe amplitude and returned with -revert, instead of the load
step and the return settling: the settled reference, the mode skip,
the kink check and the recorder refusal are the same on both routes,
and the imposed displacement is checked against ± a_k φ_k / λ_k.
Ritz and residual modes (basis, residual,
residual_period as in :meth:modal_after_gravity). A Ritz
vector or a pseudo-mode ψ is not an eigenvector, so a static
leg under a M ψ would move the domain by K⁻¹ M ψ, not by
a ψ / λ. Such a mode set therefore needs the -increment
route (imposed legs, every extractor a built-in one), and is
refused on the static one. The values are those of the fork's RSA:
ψ Γ Sa / λ with the Rayleigh λ. With residual_period=T
the pseudo-modes read Sa at T, and every combination on the
result sums them into one rigid mode at ω = 2π/T
(:attr:SpectrumModalResult.sa_periods, ADR 213 D3b). The modes'
kinds are :attr:SpectrumModalResult.kinds; a Ritz or pseudo-mode
period is a Rayleigh period.
Nodal mass only. The modal force is M φ built from the nodal
masses, so a model whose mass sits in its elements (a section or
material rho, an element mass=) is refused. Lump the mass to
the nodes (g.masses on the session, or ops.mass /
mass_from_model): that is the supported route.
The modes must carry the loaded mass. A spectrum direction is
refused when modalProperties counts less free mass along it
(totalFreeMass) than the nodes carry on DOFs no fix holds,
or when the modes' effective masses along it sum to at most
1e-6 of the free mass (every Γ zero to round-off). The first is
what stock OpenSees and Ladruno forks older than
ladruno-v20261027 (WP-211) give for mass on the constrained
nodes of a rigid diaphragm under constraints Transformation: a
zero response, or a Γ too low when only some floors lose their
mass. These checks need the modes, so with p_delta=True they
run after the gravity analysis (in the per-mode step, on the
gravity state), and with p_delta=False before it. On those older
builds, mass on a node that an equalDOF ties to a fixed node is
refused too, although its Γ is right: put that mass on the fixed
node, or use a fork with WP-211.
No recorders. Each probe leg and each return solve commits, and
on the -increment route each leg calls the domain's recorders on
its trial state, so a declared recorder would write extra rows for
every mode that are not states of the structure. A model with a declared recorder is
refused; the gravity state is in
:attr:SpectrumModalResult.gravity_values and in Node.read on
the bridge afterwards.
The driver always adds the extractor "base_shear" (the total
support reaction per translational direction), so
:meth:SpectrumModalResult.base_shear gives V_t per direction.
The result also carries each mode's inertia force m φ Γ Sa at
every massed node (:attr:SpectrumModalResult.inertia), from which
:meth:SpectrumModalResult.storey_forces sums storey shears and
moments per mode; each mode's total inertia is checked against its
total base reaction, and an
:class:~apeGmsh.opensees.analysis.spectrum.InertiaBalanceWarning is
issued when they differ by more than 1e-3 of the inertia.
Parameters¶
num_modes
Modes to extract and combine, >= 1.
spectra
One :class:~apeGmsh.opensees.analysis.spectrum.DesignSpectrum
per excitation; each names its translational direction.
extractors
Name -> extractor(ops) -> 1-D float array of fixed length
(:class:~apeGmsh.opensees.analysis.spectrum.NodeDisp,
:class:~apeGmsh.opensees.analysis.spectrum.NodeReaction,
:class:~apeGmsh.opensees.analysis.spectrum.ElementResponse, or
any callable, such as a story-shear aggregator). The name
"base_shear" is reserved.
p_delta, solver, basis, ritz_dirs, ritz_patterns, residual, residual_period
As :meth:modal_after_gravity.
Raises¶
BridgeError
The model carries element mass (refused: the modal force is
built from nodal masses), declares a recorder, or a spectrum
names a direction outside 1..ndm, or a direction a spectrum
loads has less free mass than unfixed nodal mass, or a zero Γ
(to round-off) in every mode.
ValueError
No spectra or extractors, or an extractor's length changed.
RuntimeError
A per-mode solve failed, a mode has a non-positive eigenvalue,
the two probe legs met different stiffnesses, or the domain did
not return to the reference state.
Source code in src/apeGmsh/opensees/procedures/_gravity_modal.py
417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 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 579 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 | |
eigen ¶
Build + emit + run a one-shot eigen solve via the live emitter.
Builds a :class:BuiltModel, drives a
:class:~apeGmsh.opensees.emitter.live.LiveOpsEmitter end-to-
end (model + nodes + elements + bcs + mass), then issues the
single eigen call and returns an :class:EigenResult
carrying the eigenvalues plus a back-reference to the live
emitter for lazy mode-shape access.
Unlike :meth:analyze, eigen does NOT require an analysis
chain (constraints / numberer / system / test / algorithm /
integrator / analysis): it only needs the assembled stiffness
and mass matrices.
Partitioned models — serial-gather stopgap (ADR 0077 Tier 0).
On a partition-authored model this runs the eigensolve serially
on the full, gathered model in one process (the live emitter has
supports_partitions = False): the modes are exact, but the
whole model is assembled on one rank, so it does not scale the
eigensolve. There is no distributed modal path yet — never run a
bare eigen under OpenSeesMP (it solves each rank's LOCAL
subdomain → wrong modes; ADR 0077 refuted v1). Distributed FEAST
(ADR 0077 Tier 1) is gated on the classic-Tcl -feast unlock.
Parameters¶
num_modes
Number of modes to compute. Must be >= 1.
solver
OpenSees eigen-solver flag, one of -genBandArpack
(default), -symmBandLapack, -fullGenLapack,
-frequency, -standard. Passed through verbatim to
ops.eigen(solver, num_modes).
Returns¶
EigenResult
Carries eigenvalues (λ_i = ω_i²) plus derived
omega / freq / periods and a
:meth:EigenResult.mode_shape accessor.
Raises¶
ValueError
If num_modes < 1.
NotImplementedError
If the model has any registered stages — live execution
of staged models is unsupported (Phase SSI-2.A).
Source code in src/apeGmsh/opensees/procedures/_modal.py
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 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | |
modal_properties ¶
modal_properties(num_modes: int, *, solver: str = '-genBandArpack', unorm: bool = False) -> 'ModalPropertiesResult'
Build + emit + run eigen + modalProperties live.
Like :meth:eigen, drives a
:class:~apeGmsh.opensees.emitter.live.LiveOpsEmitter end-to-end
and needs no analysis chain; after the eigen solve it issues
modalProperties -return (upstream DomainModalProperties)
and wraps the returned dict in a
:class:~apeGmsh.opensees.analysis.modal.ModalPropertiesResult
carrying participation factors, modal masses, and mass ratios
per mode and per global component.
The properties are also stored on the OpenSees Domain, which is the prerequisite state for the Ladruno fork's modal-response commands (fork ADR 44).
Partitioned models — serial-gather stopgap (ADR 0077 Tier 0).
Runs serially on the full, gathered model (see :meth:eigen), so
participation factors / effective modal mass are correct here.
This is the only correct way to get modal properties on a
partition-authored model today: the distributed path (ADR 0077
Tier 1) has no participation surface — upstream
modalProperties is MPI-blind — so a distributed run would
return wrong effective mass. It does not scale the eigensolve
(whole model on one rank).
Parameters¶
num_modes
Number of modes to compute. Must be >= 1.
solver
OpenSees eigen-solver flag, passed through verbatim (see
:meth:eigen). Use -fullGenLapack on tiny models —
ARPACK needs num_modes < n_dof.
unorm
Request the displacement-normalized eigenvector scaling
(modalProperties -unorm).
Raises¶
ValueError
If num_modes < 1.
NotImplementedError
If the model has any registered stages — live execution
of staged models is unsupported (Phase SSI-2.A).
Source code in src/apeGmsh/opensees/procedures/_modal.py
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | |
footfall_walking ¶
footfall_walking(*, num_modes: int, body_weight: float, g: float, response_nodes: 'int | Node | Sequence[int | Node]', excitation: str = 'self', excitation_nodes: 'int | Node | Sequence[int | Node] | None' = None, dof: int = 3, occupancy: str = 'office', limit: str = 'curve', damp: float | None = None, modal_damp: Sequence[float] | None = None, rayleigh: tuple[float, float] | None = None, f_max: float = 20.0, n_extra: int = 30, dt: float = 0.005, solver: str = '-genBandArpack') -> 'FootfallResult'
Evaluate walking footfall vibration on a live modal basis.
AISC Design Guide 11, 2nd ed., §7.4.1, as ADR 0109 lays it out: one
eigen + modalProperties pair through :meth:modal_properties,
the modal acceleration FRF A_ij(Ω) = −Ω² H_ij(Ω) summed in numpy
over the D4 sweep grid, and each response node checked against
both Design Guide branches — Eq 7-1 where the FRF peaks below
9 Hz (a low-frequency floor, resonant build-up) and Eq 7-4…7-6 where
it peaks in 9-f_max Hz (a high-frequency floor, footstep impulses
summed over every mode with f_n <= f_max). The larger governs,
and the result records which branch it was.
Runs on stock openseespy — eigen, modalProperties and
nodeEigenvector are all upstream; the fork is needed only for the
band solve the warning below points at.
Units are yours. body_weight (Q, model force units) and
g (model acceleration units) are required and have no defaults —
apeGmsh cannot know whether the model is in N·m or kip·in, and a
silently wrong g is a factor of 386 in the answer. Q = 168 lb
≈ 747 N is the Guide's recommended walker weight. Every
acceleration on the result is a fraction of g.
Where to put the nodes. The Guide walks the walker along the
mid-length of an unobstructed path and seats the occupant at the
maximum mode-shape ordinate; both at mid-bay is the conservative
default. excitation="self" checks the diagonal (j, j) — the
walker standing where the occupant sits. excitation="full"
checks every (i, j) pair and reports, per response node, the
excitation node that produced the largest a_p.
The eigenvector scale is asserted, not assumed (ADR 0109 D2): the
modal sum takes m̃_a = 1, and partiMass_C / partiFactor_C²
must be 1 for every checkable mode or the evaluation refuses. The
provenance lands on :attr:FootfallResult.normalization.
Parameters¶
num_modes
Modes to extract. The Eq 7-5 sum wants every mode with
f_n <= f_max; a basis that stops short of f_max warns.
body_weight
Walker weight Q in model force units. Must be > 0.
g
Gravitational acceleration in model units. Must be > 0.
response_nodes
Occupant node(s) — a tag, a Node, or a sequence of either.
excitation
"self" (the diagonal only) or "full" (every pair).
excitation_nodes
Walker node(s) for excitation="full"; defaults to
response_nodes. Refused under "self", where the
excitation set IS the response set.
dof
1-based DOF the FRF and the mode shapes are read at — the
vertical translation, 3 on a 3-D floor.
occupancy
Tolerance family: "office" / "residence" / "church" /
"school" (0.5 %g), "shopping" / "dining" /
"indoor_bridge" (1.5 %g), "outdoor_bridge" (5 %g).
limit
"curve" (Fig 2-1 — the flat value scaled by the ISO 2631-2
base curve) or "table" (the flat Table 4-1 value).
damp, modal_damp, rayleigh
Exactly one ADR 0075 damping channel (ADR 0109 D6): a uniform
ratio (Table 4-2 is a sum of component ratios), a per-mode list
in absolute mode order, or (a0, a1) converted per mode as
ξ_a = a0/(2ω_a) + a1·ω_a/2.
f_max
Upper band edge in Hz — also the Eq 7-5 basis cut. Table 7-1's
resonant harmonics stop at 20 Hz, so 0 < f_max <= 20.
n_extra
Linearly spaced sweep points on top of the modal frequencies and
their ±5 % clusters (ADR 0109 D4).
dt
Sampling step of the Eq 7-5 acceleration history, s.
solver
Eigen-solver flag, passed through verbatim (see :meth:eigen).
Returns¶
FootfallResult
One row per response node — see
:class:~apeGmsh.opensees.analysis.footfall_result.FootfallResult.
Warns¶
UserWarning
When the highest extracted mode is below f_max: the Eq 7-5
impulse sum is then missing modes it should carry. Raise
num_modes, or on the fork use eigen_feast over the band.
Raises¶
ValueError
If num_modes < 1, body_weight <= 0, g <= 0,
dof < 1, a node set is empty, excitation is not
"self" / "full", limit is not "curve" /
"table", occupancy is unknown, f_max is outside
(0, 20], the damping channel is not exactly one, or the
eigenvectors are not mass-normalised.
NotImplementedError
If the model has any registered stages.
Source code in src/apeGmsh/opensees/procedures/_modal.py
284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 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 579 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 | |
eigen_feast ¶
eigen_feast(f_min: float, f_max: float, *, certify: bool = False, trace_stop: bool = False) -> 'EigenResult'
Band-targeted FEAST eigensolve via the live emitter.
Fork-only (Ladruno ADR-43): eigen -feast fmin fmax
returns all modes whose natural frequency lies in
[f_min, f_max] Hz — the mode count is an output
(len(result.eigenvalues)), not an input, which is why this
is a separate method and not an :meth:eigen solver flag.
certify=True adds the fork's Sturm/inertia completeness
certificate: the band content is independently counted via
LDLᵀ inertia at the two band edges and the solve REFUSES on a
mismatch with FEAST's count.
Parameters¶
f_min, f_max
Frequency band in Hz; needs 0 <= f_min < f_max.
certify
Emit -certify (the completeness certificate).
trace_stop
Emit -traceStop: stop on MKL's trace criterion instead of
the relative residual, the fork's default from c83ee812e
(fork WP-203). The eigenpairs are the same either way; the
residual stop skips the refinement loops the trace stop runs.
Returns¶
EigenResult
The standard eigen result (possibly zero modes if the band
is empty) with lazy mode_shape access.
:meth:EigenResult.modal_properties runs modalProperties
on its modes.
Source code in src/apeGmsh/opensees/procedures/_modal.py
complex_eigen ¶
complex_eigen(num_modes: int, *, solver: str = '-genBandArpack', tol: float | None = None, closed_form: bool = False) -> 'ComplexEigenResult'
Complex / state-space modal analysis via the live emitter.
Fork-only (Ladruno ADR-46, complexEigen): true per-mode
damping ratios ζ_k, damped frequencies ω_d,k, and phased mode
shapes for non-classically damped models (localized
dashpots, bearings, radiation damping). Builds + emits a fresh
live domain, runs the real eigen (the projection basis),
then complexEigen and parses the flat 7-per-mode return
into a :class:ComplexEigenResult.
The default route projects the model's actual M and C
(element getDamp()/getMass() + nodal mass/alphaM) —
exactly the C a transient analysis feels. closed_form=True
uses the fast global-Rayleigh diagonal closed form instead
(refuses betaKinit/betaKcomm; blind to scoped
Rayleigh).
Contract traps (fork guide): damping that does not flow through
getDamp() is invisible (modalDamping, HHT-α numerical
damping, elements whose -doRayleigh defaults OFF — the
Truss/zeroLength families); the projection spans only
the retained num_modes real modes; complex mode shapes are
recorded via Node-recorder raw=("complexEigenRe<k>",) /
Im<k> tokens, not carried on this result.
Parameters¶
num_modes
Real modes to extract as the projection basis (retain
enough to cover the band of interest;
-fullGenLapack on tiny models).
tol
Optional residual tolerance (fork default 1e-8).
closed_form
Use the closed-form Rayleigh route (Route A).
Source code in src/apeGmsh/opensees/procedures/_modal.py
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 | |
modal_response_history ¶
modal_response_history(*, dt: float, n_steps: int, num_modes: int, base_accel: 'TimeSeries | str | None' = None, direction: int | None = None, load: 'Plain | str | None' = None, series: 'TimeSeries | str | None' = None, damp: float | None = None, rayleigh: tuple[float, float] | None = None, modal_damp: Sequence[float] | None = None, modes: Sequence[int] | None = None, t0: float = 0.0, solver: str = '-genBandArpack') -> 'ModalHistoryResult'
Run the fork's exact modal-superposition transient live.
Fork-only (Ladruno ADR-44 P1a, modalResponseHistory).
Builds + emits a fresh live domain, issues eigen +
modalProperties, then advances each retained mode by the
closed-form piecewise-linear recurrence — no iteration, no
factorization. One domain step is committed per station
(t0 … t0 + n_steps·dt), so every recorder declared on the
model captures the history exactly as in a direct run.
Linear models only — superposition is invalid under any
material or geometric nonlinearity (use analyze then).
Parameters¶
dt, n_steps
Time step and station count (n_steps + 1 commits).
num_modes
Modes to extract for the superposition basis (retain
enough to cover the band of interest).
base_accel, direction
Ground-acceleration channel: a registered
ops.timeSeries.* handle (or name) sampled at the
stations, plus the global excitation direction (1-based).
Response is relative to the moving base. Make the
record extend at least one sample past t0 + n_steps·dt.
load, series
Nodal-force channel P(t) = s(t)·P: an
ops.pattern.Plain handle (or name) whose plain nodal
loads give the reference shape P (the pattern's own
timeSeries is IGNORED by the fork), and the scalar
s(t) timeSeries. Response is absolute. Mutually
exclusive with the base-acceleration channel.
damp, rayleigh, modal_damp
Exactly one damping channel (ADR 0075): uniform ratio /
Rayleigh (a0, a1) / per-mode ratios.
modes
Optional 1-based subset of the extracted modes.
t0
Start time (base accel sampled at t0 + k·dt).
solver
Eigen-solver flag (-fullGenLapack on tiny models).
Source code in src/apeGmsh/opensees/procedures/_modal.py
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 898 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 | |
response_spectrum_analysis ¶
response_spectrum_analysis(direction: int, *, periods: Sequence[float], accels: Sequence[float], combine: str, num_modes: int, damp: float | None = None, modal_damp: Sequence[float] | None = None, solver: str = '-genBandArpack', scale: float | None = None, require_mass: float | None = None) -> 'ResponseSpectrumResult'
Run a response-spectrum analysis with native combination.
Fork-only (Ladruno ADR-44 P1b): the -combine stage on
responseSpectrumAnalysis. Builds + emits a fresh live
domain, issues eigen + modalProperties, computes the
per-mode modal displacements against the (periods, accels)
design spectrum, and commits the combined nodal design
displacement field, read back via
:meth:ResponseSpectrumResult.node_disp.
Combination is per-quantity and nonlinear — do NOT derive combined element forces / drifts from the combined displacements (combine those quantities' own per-mode peaks instead).
Displacements only. The committed field is the combined
nodal displacement; element forces, drifts and storey shears
read off that domain are not combined responses. For those use
:meth:spectrum_after_gravity, which combines each quantity's
signed per-mode values.
Parameters¶
direction
Global excitation direction (1-based).
periods, accels
The design spectrum Sa(Tn) as parallel lists.
periods must be non-negative and strictly increasing;
a leading T = 0 PGA anchor is legal (the fork clamps
T <= Tn[0] to Sa[0]).
combine
"SRSS" | "CQC" | "ABS" | "TenPercent".
CQC and TenPercent weight closely-spaced modes; CQC
requires a damping channel.
num_modes
Modes to extract; the combination spans all of them
(-combine and -mode are mutually exclusive — the
bridge never emits -mode).
damp, modal_damp
Optional damping channel (uniform ratio or per-mode).
Required for CQC.
scale
Optional factor on Sa (a unit conversion such as g to
model units, or an I/R factor). Must be finite and > 0;
None is scale 1. The bridge multiplies the -Sa values
by it and does not emit the fork's -scale, which only
builds from c83ee812e (fork WP-202) apply under
-combine and older ones parse and ignore: the scaled
ordinates give the same answer on every build.
require_mass
Optional ratio in (0, 1]: -requireMass (fork WP-212).
The fork refuses the analysis when the modes carry less than
this fraction of the free mass in direction, and prints
the shortfall. None (the default) emits nothing. Needs
chain M (ladruno-v20261027+); an older build refuses
before the model is built
(:class:~apeGmsh.opensees._target.ForkTooOldError).
Source code in src/apeGmsh/opensees/procedures/_modal.py
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 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 | |
residual_modes ¶
residual_modes(dirs: Sequence[int], *, num_modes: int, period: float | str = 'rayleigh', replace: bool = False, tol: float | None = None, solver: str = '-genBandArpack') -> 'ModalPropertiesResult'
Eigenmodes completed by the fork's missing-mass pseudo-modes, live.
Fork-only (chain M, WP-213). Builds and emits a fresh live
domain, then runs eigen (num_modes modes),
residualModes -dir ... (:class:~apeGmsh.opensees.analysis.
modal.ResidualModes) and modalProperties -return, in that
order: a later eigen would drop the pseudo-modes. The result
holds every mode of the completed set, the pseudo-modes last,
with the cumulative mass ratio of each direction in dirs at
100 %.
Parameters¶
dirs
Global translations (1, 2, 3) to complete, each once.
num_modes
Eigenmodes solved before the pseudo-modes are appended.
period
"rayleigh" (default): spectral analyses read each
pseudo-mode's Sa at its own Rayleigh period. A period T
(s): responseSpectrumAnalysis reads Sa at T and sums
the pseudo-modes into one rigid mode (ADR 213 D3b, ASCE 7-22
§12.9.1.1).
replace
-replace: drop pseudo-modes already in the set first.
tol
-tol, the relative drop tolerance in (0, 1); None
keeps the fork's default (1e-4).
solver
The eigen-solver flag (see :meth:eigen).
Raises¶
BridgeError
The model runs under MPI (a partitioned model or an MPI
system): the fork refuses residualModes on OpenSeesSP,
so the bridge refuses before emitting.
ForkTooOldError
The in-process build lacks residualModes; raised before
the model is built.
Source code in src/apeGmsh/opensees/procedures/_modal.py
1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 | |
ritz_vectors ¶
ritz_vectors(n: int, *, dirs: Sequence[int] = (), patterns: 'Sequence[Plain | str]' = (), cycles: Sequence[int] | None = None, tol: float | None = None) -> 'ModalPropertiesResult'
Load-dependent Ritz vectors as the mode set, live.
Fork-only (chain M, WP-215). Builds and emits a fresh live
domain, then runs ritzVectors (:class:~apeGmsh.opensees.
analysis.modal.RitzVectors) in place of eigen and
modalProperties -return. Ritz periods are Rayleigh periods,
not natural periods.
The starting loads are M ι_d for each direction in dirs,
then the reference loads of each pattern in patterns, in
that order. The fork factors K through the defined analysis,
so the bridge must declare one (ops.analysis.Static() and its
chain).
Parameters¶
n
Ritz vectors to generate (>= 1).
dirs
Global translations (1, 2, 3) whose inertia loads start the
sequence.
patterns
ops.pattern.Plain handles (or registered names) whose
reference loads start the sequence.
cycles
Blocks per start, one count per start (dirs then
patterns); 0 is no cap.
tol
-tol, the relative M-norm drop in (0, 1); None
keeps the fork's default (1e-10).
Raises¶
BridgeError
The model runs under MPI (a partitioned model or an MPI
system): the fork refuses ritzVectors on OpenSeesSP,
so the bridge refuses before emitting. Also when no analysis
is declared.
ForkTooOldError
The in-process build lacks ritzVectors; raised before
the model is built.
Source code in src/apeGmsh/opensees/procedures/_modal.py
1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 | |
ladruno_contact_force ¶
Total normal contact-force magnitude on an NTS slave node.
The sum over that node's active master-segment pairs of
tn = kn·<−gap>₊ (fork ladrunoContactForce, ADR-39 B3). Works in
2-D and 3-D. Requires a prior live :meth:analyze; fork-only.
Four limits, none of which the return value can tell you about — read them before using this number:
- NTS lane only. It is fed exclusively from the segment / end-cap
branch, so a mortar or rigid-plane slave always reads
0.0. Those lanes have no force query at all; recover their forces from reactions or the penalty-depth identity instead. - A magnitude, not a vector. Near a corner or the 2-D D4 end-cap the pair normal is not axis-aligned, so this does not equal any single global force component. The fork's own guide says so.
- Zero is ambiguous.
0.0means "not in contact" and "no contact engine in this domain". Call :meth:ladruno_contact_infoand checktotal_contactsto tell them apart — notn_contacts, which counts the NTS lane only and reads0on a perfectly live mortar-only model. - A released 3-D pair reports its last-active force forever — a
known, deferred fork defect (reproduced at
f_query = 1000.0againstf_true = 0.0). The 2-D lane carries the fix.
Source code in src/apeGmsh/opensees/procedures/_contact.py
ladruno_contact_info ¶
Engine counters — (n_contacts, n_commits, n_reverts,
n_mortar_contacts) (fork ladrunoContactInfo).
Mostly useful as the disambiguator for the other three queries: they
all return 0.0 both for "nothing happening here" and for "no
contact engine at all". Use info.total_contacts, the sum of the two
lane counters — n_contacts and n_mortar_contacts are disjoint
lanes, not a total and a subset, so a mortar-only model reports
n_contacts == 0 with a live engine (measured on fork
b17e8bd82). Requires a prior live :meth:analyze; fork-only.
Source code in src/apeGmsh/opensees/procedures/_contact.py
ladruno_mortar_penetration ¶
Max KKT-active normal penetration over all mortar slave nodes
(fork ladrunoMortarPenetration, ADR-41 C2.2).
A length, not a force — dimension-blind, and unaffected by the
mortar thickness=. It is the mortar lane's ALM convergence measure:
the quantity a held-load augmentation loop watches to decide it has
augmented enough. 0.0 with no mortar contact. Requires a prior live
:meth:analyze; fork-only.
Source code in src/apeGmsh/opensees/procedures/_contact.py
ladruno_mortar_tie_residual ¶
Max weighted relative-displacement bond residual over all mortar
tie slave nodes (fork ladrunoMortarTieResidual, ADR-41 C4).
The tie's ALM convergence measure, the counterpart of
:meth:ladruno_mortar_penetration for tie=True. 0.0 with no
tie declared. Requires a prior live :meth:analyze; fork-only.
Source code in src/apeGmsh/opensees/procedures/_contact.py
capabilities ¶
Probe the in-process openseespy build (live path).
Imports openseespy in the active interpreter and reports whether
it looks like the Ladruno fork (has_fork), exposes the
fork-only profiler command, its version() string, and its
build stamp (the exact git hash the binary was compiled from,
on fork builds that ship ladrunoBuild).
Raises if openseespy is not installed. This introspects the
live runtime only — the subprocess paths bind their own
interpreter / binary via :class:OpenSeesTarget.
Source code in src/apeGmsh/opensees/apesees.py
model ¶
Set the model dimensionality (ndm) and the envelope ndf.
Per-node ndf is inferred from the declared element
classes (ADR 0048) — ndf here is only the OpenSees model
envelope (model BasicBuilder -ndm K -ndf N) and the
fallback for nodes inference cannot see: element-less /
decoupled nodes, and nodes touched only by adaptive elements
(the zeroLength family). Element-attached nodes get their
inferred value as a per-node -ndf override, emitted only
where it differs from this envelope. There is no per-node
ndf to declare on the geometry session — g.node_ndf
was removed; the elements you declare determine it.
Source code in src/apeGmsh/opensees/apesees.py
fix ¶
fix(*, pg: str | None = None, nodes: Iterable[int | Node] | None = None, label: str | Sequence[str] | None = None, dofs: tuple[int, ...], name: str | None = None) -> None
Apply homogeneous SP constraints (fix).
Exactly one of pg / nodes / label must be supplied.
nodes accepts a mix of plain integer tags and :class:Node
instances (from ops.nodes.get(...)); both are normalized
to tags. The build pipeline expands pg to a per-node
fan-out at emit time. label (one geometry label or a list)
resolves on the snapshot here, so an unknown label raises
before anything registers, listing the labels that exist; it
never falls back to a physical group (ADR 0115 D4).
Homogeneous fixes merge within a tier (ADR 0115 D6): a later
fix (or fix_from_model) on a (node, DOF) this tier
already fixes emits only its remaining DOFs on that node, or
nothing. An overlap with a stage's s.fix / s.support
still raises at build.
name labels the declaration (opensees/fix/<name> in
model.h5's /opensees/decls, read back through
OpenSeesModel.declarations); unnamed, it is #k. Names
are unique among the fixes (flat and staged). A label only: the
deck and model_hash do not change with it.
Source code in src/apeGmsh/opensees/apesees.py
combination ¶
combination(name: str, terms: 'Iterable[object]', *, rule: str = 'linear', envelope: str = '', fraction: float | None = None, damping: float | None = None) -> Combination
Declare a combination, archived in model.h5 (ADR 0130 D4).
A term is (stage_name, factor) for a stage's last step,
(combination, factor) for a combination this bridge declared, or
a :class:CombinationTerm for a chosen step or a mode. rule is
linear, srss, cqc (over modes, damping required: a
case's per-mode damping lives in .user.h5), abs_sum,
directional (fraction) or envelope (envelope is
max, min or absmax).
Refused here, with nothing registered: a bad name, a repeated name,
a term naming an undeclared combination, and a spectrum or
reference term, whose case lives in .user.h5; declare that
combination there after the run. A stage's name is stamped by the
run, so it resolves when the combination is evaluated.
Source code in src/apeGmsh/opensees/apesees.py
equation_constraint ¶
equation_constraint(*, constrained: 'tuple[int | Node, int]', retained: 'Iterable[tuple[int | Node, int, float]]', coef: float = 1.0) -> None
Declare one equationConstraint row (OpenSees EQ_Constraint).
The row is the linear relation, in OpenSees' sum-to-zero form::
coef * u[cdof](cnode) + sum_i rcoef_i * u[rdof_i](rnode_i) = 0
with constrained=(cnode, cdof) and retained=[(rnode, rdof,
rcoef), ...]. So u_c = 0.5 u_a + 0.5 u_b is
constrained=(c, 1), retained=[(a, 1, -0.5), (b, 1, -0.5)].
Nodes are FEM node ids (or :class:Node handles); DOFs are
1-based.
Emitted in the MP-constraint pass, after the snapshot's
constraints. EQ_Constraint is enforced by Lagrange,
Penalty and the fork's LadrunoProjection only:
Transformation, Auto and Plain drop it without a word.
So with no declared handler the bridge auto-emits Lagrange
(implicit) or LadrunoProjection (explicit integrator), and a
declared Transformation / Auto raises — the same rules as
an enforce="equation" tie (ADR 0068 INV-4).
Validated here (non-zero finite coefficients, DOFs >= 1, a
non-empty retained set, the constrained DOF not among the retained
ones) and at emit (nodes exist, DOFs fit each node's ndf). The
in-process run needs a build with equationConstraint
(openseespy >= 3.8.0 — one such model per process, since stock
wipe() keeps the rows — or the fork); a partitioned emit
refuses the rows. ops.h5(...) archives each one as an
EquationConstraintRecord row of /opensees/decl_params, and
OpenSeesModel.from_h5(...) replays it.
Source code in src/apeGmsh/opensees/apesees.py
9215 9216 9217 9218 9219 9220 9221 9222 9223 9224 9225 9226 9227 9228 9229 9230 9231 9232 9233 9234 9235 9236 9237 9238 9239 9240 9241 9242 9243 9244 9245 9246 9247 9248 9249 9250 9251 9252 9253 9254 9255 9256 9257 9258 9259 9260 9261 9262 9263 9264 9265 9266 9267 9268 9269 9270 9271 9272 9273 9274 9275 | |
mass ¶
mass(*, pg: str | None = None, nodes: Iterable[int | Node] | None = None, label: str | Sequence[str] | None = None, values: tuple[float, ...], overwrite: bool = False, name: str | None = None) -> None
Attach lumped nodal mass.
Exactly one of pg / nodes / label must be supplied.
nodes accepts plain integers or :class:Node instances;
label resolves as for :meth:fix. Masses never merge: a
second mass on a node raises at build unless overwrite=True
(setMass is not idempotent; ADR 0115 D6).
overwrite (Phase SSI-2.E) opts the record out of validator
V2's cross-tier duplicate-mass check. Rare at the global tier
but kept for symmetry with the stage-bound :meth:_StageBuilder.mass
— see that method for the typical use case.
name labels the declaration (opensees/mass/<name> in
/opensees/decls), as for :meth:fix; a label only.
Source code in src/apeGmsh/opensees/apesees.py
mass_from_model ¶
Stream per-node lumped masses straight from the model snapshot.
In 3-D, equivalent to looping ops.mass(nodes=[m.node_id], values=m.mass)
over every entry in fem.nodes.masses (e.g. the per-node tributary
masses produced by g.masses.volume(...)), but without
materializing one bridge MassRecord per node — the snapshot
masses are streamed at emit time. On a multi-million-node model this
avoids a multi-GB resident list and millions of small objects (ADR
0065 Tier 2). Honours per-node ndf; each broker mass is spatially
ordered (mx, my, mz, Ixx, Iyy, Izz) and is mapped onto the node's
DOFs by broker_mass_components — byte-identical to the explicit
loop in 3-D, and (mx, my[, Izz]) on a 2-D (ndm=2) node.
Model-wide declaration (no arguments). May be combined with explicit
:meth:mass calls only on disjoint node sets — overlap raises at
emit (nodal mass is additive under MP assembly). Deck/live emit only;
the H5 archival emitter rejects it (masses already persist in
model.h5 via fem.nodes.masses).
Source code in src/apeGmsh/opensees/apesees.py
fix_from_model ¶
Fix every homogeneous SP on the model snapshot (ADR 0051 §4).
The support twin of :meth:mass_from_model: equivalent to a
:meth:fix for each node carrying homogeneous records on
fem.nodes.sp (g.constraints.bc(...), or a zero-valued
g.displacements), with the node's restrained DOFs folded
into one mask, so two targets sharing a node emit one fix.
The records' spatial components (ux uy uz rx ry rz) land on
the node's deck DOFs by ndm and ndf, and one the node lacks
is left out: bc's default [1, 1, 1] pins x and y on a
2-D solid or frame and leaves a frame's rz free. Prescribed
(non-zero) SPs are untouched: p.from_model(case) imports
those.
Model-wide declaration (no arguments), materialized into
ordinary fix records at :meth:build, so every emit path treats
them like :meth:fix. It belongs to the global tier, so it
merges with explicit :meth:fix calls (ADR 0115 D6, Q1): a
(node, DOF) both fix emits once. It may be combined with a
stage's s.fix / s.support only on disjoint (node, DOF)
pairs: that overlap raises at build, since OpenSees refuses a
second SP on a constrained DOF and the lifecycles differ.
Source code in src/apeGmsh/opensees/apesees.py
ndf ¶
State the per-node ndf of an element-LESS decoupled node
(ADR 0049 — the sole explicit per-node ndf channel).
Every other node's ndf is inferred from its incident element
classes (ADR 0048). ops.ndf exists only for nodes inference cannot
reach — a spring/dashpot ground, a control node, or a mass anchor
created via g.decouple_node(...) that no element touches.
Parameters¶
target
The decoupled-node handle returned by g.decouple_node(...) (a
DecoupledNodeDef) or its integer node tag. The handle is
resolved to its tag at build time (so a handle materialized
after meshing resolves correctly); a still-unmeshed handle fails
loud at build.
ndf
The DOF count to assign the node.
Raises (at build) :class:BridgeError if target is a mesh node, an
element-touched node (its ndf is inferred — restating it would create
a two-headed model), or an unresolved handle. The stated value is also
checked by gates G1–G3 (adaptive endpoints, constraint masters,
referenced fix/mass/load/sp DOFs).
Source code in src/apeGmsh/opensees/apesees.py
spring_bed ¶
spring_bed(ground: 'DecoupledNodeSetDef', *, at: 'DecoupledNodeSetDef | None' = None, k: 'SpringValues', c: 'SpringValues | None' = None, orient: 'OrientValues | None' = None, tributary: str | None = None, dirs: 'Sequence[int]' = (1, 2, 3), do_rayleigh: bool = False, fix: bool = True, ndf: int = 3, name: str | None = None) -> 'SpringBed'
A grounded zeroLength spring (and dashpot) on every node of a decoupled node set (ADR 0119 D2) — a distributed foundation bed.
Spring i joins the ground node i (a
g.decouple_node_set(...) handle) to the at node with the
same source node — the side nodes of a second set declared with
tie_dofs — or, with at=None, to the source node itself.
Per spring and direction the bed registers
uniaxialMaterial Parallel <m> <E1> <V1> -factors k c over one
Elastic 1.0 and one Viscous 1.0 1.0 shared by every bed of
the bridge (-factors k alone when c is None), one
zeroLength per spring, fix on the ground nodes (all
ndf DOFs) and the ndf of the ground and at nodes.
Parameters¶
ground, at
Resolved g.decouple_node_set handles on one source.
k, c
Stiffness and dashpot coefficient per spring and direction:
an (n, len(dirs)) array, len(dirs) values for every
spring, or a callable f(xyz, area) returning the array
(xyz: the (n, 3) source coordinates in source order;
area: the tributary areas, None without
tributary=). Values must be finite and >= 0.
orient
-orient: a 6-tuple, an (n, 6) array or f(xyz);
None keeps the global axes.
tributary
A 2-D label or physical group whose element areas, shared
equally among each element's corners, give area.
dirs
The -dir DOFs, distinct, each <= ndf.
do_rayleigh
False (default) keeps the springs out of Rayleigh
damping: the dashpots carry the foundation damping.
fix
Fix the ground nodes (default True).
ndf
The DOF count stated for the ground and at nodes; it must
equal the ndf of the node each spring reaches.
name
A label for the returned record.
Returns the :class:~apeGmsh.opensees._internal.spring_bed.SpringBed
record (node tags, k, c, areas, orientations, specs).
A partitioned emit routes each spring, its ground and side nodes and
their equalDOF to the rank of the structural node (ADR 0120).
Source code in src/apeGmsh/opensees/apesees.py
9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423 9424 9425 9426 9427 9428 9429 9430 9431 9432 9433 9434 9435 9436 9437 9438 9439 9440 9441 9442 9443 9444 9445 9446 9447 9448 9449 9450 9451 9452 9453 9454 9455 9456 9457 9458 9459 9460 9461 9462 9463 9464 9465 9466 9467 9468 9469 9470 9471 9472 9473 9474 9475 9476 9477 9478 9479 9480 9481 9482 9483 | |
initial_stress ¶
initial_stress(*, name: str, pg: str | None = None, elements: Iterable[int] | None = None, sigma_xx: float, sigma_yy: float, sigma_zz: float, ramp_steps: int, lambda_install: float = 1.0) -> 'InitialStressRecord'
Initialize an in-situ stress tensor on ASDPlasticMaterial3D elements.
Emits the OpenSees parameter / addToParameter /
updateParameter ramp pattern that STKO uses to inject a
pre-stressed state without applying gravity-driven body loads.
The factor ramps linearly 0 → 1 over ramp_steps analyze
calls and plateaus at 1.0 thereafter; the target stress baked
into the ramp is sigma_* × lambda_install, so passing
lambda_install < 1.0 produces a partial-installation
(convergence-confinement) result.
Exactly one of pg / elements must be supplied. This
primitive is declarative only — the actual stress
advancement happens at analyze time, via the per-step
dispatcher this primitive registers with. Call
ops.analyze(steps=ramp_steps, dt=...) or pass
analyze_steps=ramp_steps to :meth:tcl / :meth:py for
the ramp to take effect.
Parameters¶
name
Unique Tcl-identifier-safe label. Used to name the
emitted proc / state container.
pg
Physical group whose elements receive the ramped stress.
elements
Explicit list of FEM element ids. XOR with pg.
sigma_xx, sigma_yy, sigma_zz
Target Cauchy stress per component (compression negative).
ramp_steps
Number of analyze steps over which the factor reaches 1.0.
Must be >= 1.
lambda_install
Fraction of target to install (default 1.0). Must be in
(0, 1].
Source code in src/apeGmsh/opensees/apesees.py
9485 9486 9487 9488 9489 9490 9491 9492 9493 9494 9495 9496 9497 9498 9499 9500 9501 9502 9503 9504 9505 9506 9507 9508 9509 9510 9511 9512 9513 9514 9515 9516 9517 9518 9519 9520 9521 9522 9523 9524 9525 9526 9527 9528 9529 9530 9531 9532 9533 9534 9535 9536 9537 9538 9539 9540 9541 9542 9543 9544 9545 9546 9547 | |
convergence_confinement ¶
convergence_confinement(*, name: str, pg: str | None = None, elements: Iterable[int] | None = None, sigma_xx: float = 0.0, sigma_yy: float = 0.0, sigma_zz: float = 0.0, lambda_target: float, n_steps: int) -> 'InitialStressRecord'
Convergence-confinement helper (Phase SSI-3).
Thin wrapper over :meth:initial_stress for the tunnelling
convergence-confinement pattern: ramp a target stress on a
boundary region to lambda_target × sigma over
n_steps analyze steps. Matches the
_stressCtrl_11-style proc from
SSI/Interaccion/analysis_steps.tcl:19753-19767.
Differs from :meth:initial_stress in two cosmetic ways:
lambda_target(renamed fromlambda_install) — more natural reading at the call site for confinement / relaxation contexts.n_steps(renamed fromramp_steps) — matches the spec's naming.
At least one of sigma_xx / sigma_yy / sigma_zz must
be non-zero (typically only one — single-component relaxation
is the canonical SSI use case).
Returns the underlying :class:InitialStressRecord; pass it to
s.add(...) inside a stage block to bind to that stage.
Parameters¶
name
Unique Tcl-identifier-safe label.
pg, elements
Same XOR semantics as :meth:initial_stress.
sigma_xx, sigma_yy, sigma_zz
Target Cauchy stress per component (compression negative).
At least one must be non-zero.
lambda_target
Fraction of target stress to install — i.e. the relaxation
(or confinement) coefficient. Must be in (0, 1].
n_steps
Number of analyze steps over which the factor reaches 1.0
internally. After the cap, the cumulative is
sigma × lambda_target.
Source code in src/apeGmsh/opensees/apesees.py
9549 9550 9551 9552 9553 9554 9555 9556 9557 9558 9559 9560 9561 9562 9563 9564 9565 9566 9567 9568 9569 9570 9571 9572 9573 9574 9575 9576 9577 9578 9579 9580 9581 9582 9583 9584 9585 9586 9587 9588 9589 9590 9591 9592 9593 9594 9595 9596 9597 9598 9599 9600 9601 9602 9603 9604 9605 9606 9607 9608 9609 9610 9611 9612 9613 9614 9615 9616 | |
imposed_displacement ¶
imposed_displacement(*, pg: str | None = None, nodes: Iterable[int] | None = None, ux: float | None = None, uy: float | None = None, uz: float | None = None, pattern_factor: float = 1.0, series: 'TimeSeries | None' = None, name: str | None = None) -> 'Plain'
Imposed-displacement pattern helper (Phase SSI-3).
Emits one pattern Plain containing sp NODE DOF VALUE
prescribed-displacement entries for every (node, dof) pair
where the corresponding ux / uy / uz is non-None.
Used for fault-slip kinematics, support-settlement scenarios,
and any other prescribed-displacement driver.
STKO equivalent:
pattern Plain N tsTag -fact F { sp NODE DOF VAL ... }
from SSI/Interaccion y Falla/analysis_steps.tcl:22832-23253.
Where STKO uses -fact F on the pattern, this helper folds
the same scaling into the auto-created Linear(factor=F)
time series — numerically identical, simpler API.
Parameters¶
pg, nodes
XOR: exactly one of pg (physical-group name) or
nodes (iterable of FEM node ids) must be supplied.
ux, uy, uz
Scalar broadcast: every targeted node gets the same
prescribed displacement in this DOF. None (default)
skips the DOF. At least one of the three must be set.
pattern_factor
Multiplier folded into the auto-created Linear time
series. Default 1.0 (no scaling). Matches STKO's
-fact F semantics: the actual applied displacement
at simulation-time t is
value × pattern_factor × t.
series
Optional explicit :class:TimeSeries to use. Must be
already registered with the bridge. When supplied,
pattern_factor is ignored — the user is in full
control of the time-history shape.
name
Optional bridge-side alias for the pattern (as name= on
ops.pattern.Plain). It is also the <name> of the
call's provenance records,
opensees/pattern/imposed_displacement:<name> and, for the
auto-created series,
opensees/timeSeries/imposed_displacement:<name>; without
it <name> is #<k>, the call's 1-based ordinal on this
bridge, so a name may not start with #. A refused or
taken name raises before anything is registered. Both
records carry origin = "synthesised" and point at this
call (ADR 0112 D3, #1378).
Returns¶
Plain
The registered :class:Plain pattern. This is a global
(non-staged) pattern: it is valid only in a non-staged deck
(global pattern + ops.analyze). Per ADR 0051 §5 a model
may not mix a global pattern with stages — combining this
with ops.stage(...) raises :class:BridgeError at build.
For prescribed motion inside a staged deck, author the sp
on a stage pattern instead (with s.pattern(series=...) as
p: p.sp(...)).
Notes¶
Per-node-varying displacements are NOT supported in v1 —
every targeted node gets the same scalar. For different
values per node, call imposed_displacement multiple times
with disjoint nodes= lists, or construct the Plain
pattern manually via ops.pattern.Plain(...).
Source code in src/apeGmsh/opensees/apesees.py
9618 9619 9620 9621 9622 9623 9624 9625 9626 9627 9628 9629 9630 9631 9632 9633 9634 9635 9636 9637 9638 9639 9640 9641 9642 9643 9644 9645 9646 9647 9648 9649 9650 9651 9652 9653 9654 9655 9656 9657 9658 9659 9660 9661 9662 9663 9664 9665 9666 9667 9668 9669 9670 9671 9672 9673 9674 9675 9676 9677 9678 9679 9680 9681 9682 9683 9684 9685 9686 9687 9688 9689 9690 9691 9692 9693 9694 9695 9696 9697 9698 9699 9700 9701 9702 9703 9704 9705 9706 9707 9708 9709 9710 9711 9712 9713 9714 9715 9716 9717 9718 9719 9720 9721 9722 9723 9724 9725 9726 9727 9728 9729 9730 9731 9732 9733 9734 9735 9736 9737 9738 9739 9740 9741 9742 9743 9744 9745 9746 9747 9748 9749 9750 9751 9752 9753 9754 9755 9756 9757 9758 9759 9760 9761 9762 9763 9764 9765 9766 9767 9768 9769 9770 9771 9772 9773 9774 9775 9776 9777 9778 9779 9780 9781 9782 9783 9784 9785 9786 9787 9788 9789 9790 9791 9792 9793 9794 9795 9796 9797 9798 9799 9800 9801 9802 9803 9804 9805 9806 9807 9808 9809 9810 | |
stage ¶
Open a staged-analysis block (Phase SSI-2.A).
Nested with ops.stage(...) blocks are NOT supported —
opening a second stage builder while another is still open
raises RuntimeError. The lexical-vs-emit-order semantics
would otherwise be confusing (the inner builder's exit
fires first, registering the inner stage BEFORE the outer in
_stage_records, which is the opposite of what readers
expect).
Usage::
with ops.stage(name="insitu") as s:
s.add(ops.initial_stress(name="rock", ..., ramp_steps=10))
s.analysis(
test=ops.test.NormDispIncr(tol=1e-4, max_iter=150),
algorithm=ops.algorithm.Newton(),
integrator=ops.integrator.LoadControl(dlam=0.1),
constraints=ops.constraints.Plain(),
numberer=ops.numberer.RCM(),
system=ops.system.UmfPack(),
analysis=ops.analysis.Static(),
)
s.run(n_increments=10, dt=0.1)
Each stage emits its own analysis-chain primitives, its own
analyze loop (hook-wrapped if any s.add(initial_stress(...))
registered a ramp), and a between-stages cleanup block
(loadConst -time 0.0 + wipeAnalysis + hook-list clear).
Multiple with ops.stage(...) blocks accumulate in
registration order; they emit in that order at deck-emit time.
Validation happens on with exit: every stage must have a
complete analysis chain (all six chain kwargs + the analysis
directive) and an s.run(...) call.
Returns¶
_StageBuilder
Context manager that collects per-stage records and emits
a :class:StageRecord to the bridge on close.
Source code in src/apeGmsh/opensees/apesees.py
region ¶
Assign nodes to a named OpenSees Region.
Each name collects all nodes registered against it
(across multiple calls, across explicit nodes= and
pg= resolutions) and emits a single
region $tag -node n1 n2 ... line at build time with a
region tag from the build's tag plan. Useful for damping
assignments and any future recorder that filters by region.
Exactly one of pg / nodes must be supplied; nodes
accepts a mix of plain integer tags and :class:Node
instances (matching :meth:fix / :meth:mass).
End users typically call this through :meth:Node.region or
:meth:NodeSet.region rather than directly.
Source code in src/apeGmsh/opensees/apesees.py
analyze ¶
analyze(*, steps: int, dt: float | None = None, strategy: 'Ladder | None' = None, profile: str | None = None, profile_run: str | None = None, profile_deep: bool = False, profile_memory: bool = False, profile_per_step: bool = False) -> int
Build + emit + run the analysis chain via the live emitter.
Builds a :class:BuiltModel, drives a
:class:~apeGmsh.opensees.emitter.live.LiveOpsEmitter end-to-
end, then issues the analyze call. Returns the openseespy
analyze return value (0 on success).
strategy (ADR 0057 Phase A) attaches a solution-strategy
ladder to the analyze loop — on a failed increment the live
runner escalates through the ladder's algorithm rungs (the
declared chain algorithm is rung 0), restoring rung 0 after a
rescue and logging escalations to the live emitter's
strategy_events. Exhaustion returns the failing rc.
When profile is given, the live run is bracketed by the Ladruno
fork's stack profiler: profiler start [flags] before the analyze
loop and profiler report <profile> [-run profile_run] after,
with profile_deep / profile_memory / profile_per_step
toggling the start flags. Requires the fork build: on stock
openseespy it refuses before the domain is wiped. (Deck-mode
profiling uses the explicit ops.profiler.* verbs instead, and
does NOT consume the profile= kwargs here.)
Raises :class:BridgeError if the analysis chain is incomplete
(one or more of constraints / numberer / system / test /
algorithm / integrator / analysis is missing).
Phase SSI-2.A: staged models (ops.stage(...) blocks
declared) are NOT supported by live execution. Emit a Tcl
or Py deck via :meth:tcl / :meth:py and run it via the
OpenSees binary / openseespy subprocess instead.
ADR 0115 D2: once the solve returns (whatever its return code),
the bridge keeps a read session, so Node.read /
NodeSet.read and ops.elements.get(...).read answer at the
last committed state. Calling analyze again closes it at the
start; eigen, run, a deck run and another bridge's live
work close it too.
Source code in src/apeGmsh/opensees/apesees.py
9927 9928 9929 9930 9931 9932 9933 9934 9935 9936 9937 9938 9939 9940 9941 9942 9943 9944 9945 9946 9947 9948 9949 9950 9951 9952 9953 9954 9955 9956 9957 9958 9959 9960 9961 9962 9963 9964 9965 9966 9967 9968 9969 9970 9971 9972 9973 9974 9975 9976 9977 9978 9979 9980 9981 9982 9983 9984 9985 9986 9987 9988 9989 9990 9991 9992 9993 9994 9995 9996 9997 9998 9999 10000 10001 10002 10003 10004 10005 10006 10007 10008 10009 10010 10011 10012 10013 10014 10015 10016 10017 10018 10019 10020 10021 10022 10023 10024 10025 10026 10027 10028 10029 10030 10031 10032 10033 10034 10035 10036 10037 10038 10039 10040 10041 10042 10043 10044 10045 10046 10047 10048 10049 10050 10051 10052 10053 10054 10055 10056 10057 10058 10059 10060 10061 10062 10063 10064 10065 10066 10067 10068 10069 10070 10071 10072 10073 10074 10075 10076 10077 10078 | |
ladruno_projection_tie_force ¶
Tie force f = M(a_raw - a_proj) at (node, dof) from the last
projection step (≈ LS-DYNA *DATABASE_NCFORC).
Recovers the interface force a non-matching equation-tied interface
(g.constraints.tie(..., enforce="equation")) carries, via the fork
ladrunoProjectionTieForce query (ADR-30 P3 / ADR 0068 P5). dof
is 1-based (OpenSees convention).
Requires a prior live :meth:analyze with a LadrunoProjection
constraint handler active. Fork-only: a stock build raises
RuntimeError (see :data:~apeGmsh.opensees.emitter.live.
_TIE_FORCE_FORK_REQUIRED).
For a recorded time history of the tie force instead of a single
post-run value, use the recorder route:
ops.recorder.Ladruno(nodal_responses=("constraintTieForce",)) and
read it back with
results.nodes.get(component="constraint_tie_force_x") (explicit
analyses only — the recorder channel is scattered by the explicit
CentralDifferenceLadruno integrator).
Source code in src/apeGmsh/opensees/apesees.py
augment ¶
augment(*, element: int, tol: float = 1e-08, max_passes: int = 10) -> 'AbstractContextManager[list[float]]'
Run an ADR-41 held-load augmentation sweep on a live run and yield its per-pass constraint-violation history.
The supported way to close an enforce="al" coupling's constraint
gap within one step (fork PR #839 §3.2): enforce="al" alone
advances its Uzawa recursion once per committed step, so a single
push leaves the penalty gap c/K_t standing. Forwards to
:meth:~apeGmsh.opensees.emitter.live.LiveOpsEmitter.augment, which
owns the whole recipe (ladrunoBeginAugment →
integrator LoadControl 0.0 → held passes polling
constraintViolation → ladrunoEndAugment + the caller's
integrator restored). Read that docstring for the semantics; the
passes all run on entry, so the with body is a placeholder
and displacements must be read after the block::
ops.analyze(steps=1) # the real step
with ops.augment(element=tag, tol=1e-8) as gaps:
pass
assert gaps[-1] < 1e-8
Parameters¶
element : int
Emitted OpenSees tag of the LadrunoKinematicCoupling.
apeGmsh has no name → emitted-tag lookup (the constraint
name rides the comment channel only), so the tag has to come
from the live domain: max(openseespy.opensees.getEleTags())
when the coupling is the last element emitted, or a scan of a
written model.h5 for the "LadrunoKinematicCoupling"
type_token (OpenSeesModel.elements()).
tol : float, default 1e-8
Stop once the violation falls below this.
max_passes : int, default 10
Hard cap on held-load passes; exceeding it raises.
Raises¶
BridgeError
When no live analysis has run; when no integrator was recorded
through the live emitter; when tol is not met within
max_passes. Also on a stock (non-fork) build, or a nested
sweep (RuntimeError).
Source code in src/apeGmsh/opensees/apesees.py
10112 10113 10114 10115 10116 10117 10118 10119 10120 10121 10122 10123 10124 10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 10139 10140 10141 10142 10143 10144 10145 10146 10147 10148 10149 10150 10151 10152 10153 10154 10155 10156 10157 10158 10159 10160 10161 10162 10163 10164 10165 10166 10167 10168 10169 10170 | |
tcl ¶
tcl(path: str, *, run: bool = False, bin: str | None = None, analyze_steps: int | None = None, analyze_dt: float | None = None, per_rank: bool = False, flat: bool = False, stream: bool = False, verbose: bool = False, log: str | None = None, progress: bool = True) -> 'RunReport | None'
Emit a Tcl deck to path; optionally subprocess OpenSees.
When run=True the OpenSees subprocess output is always
tee'd to a log file — log (a path) overrides, otherwise it
is <path>.log next to the deck. Console output is opt-in via
verbose: False (default) prints begin / op / end only;
True adds a live step counter (parsed from the
APEGMSH_PROGRESS markers progress=True injects into the
analyze loop) plus streamed warning lines. A failed run raises
RuntimeError carrying the log tail + path, never the whole
buffer: a non-zero exit, or an exit of 0 whose log lacks the
run driver's completion line (OpenSees.exe exits 0 after a
Tcl error, the deck's aborted-analyze guard included).
verbose / log / progress are inert when
run=False.
run=True returns a frozen
:class:~apeGmsh.opensees._run.RunReport (ADR 0106 Amendment 1):
returncode, log, elapsed_s, increments (the
analyze increments the deck's progress markers prove
completed; None with progress=False) and
solver_stats — the ADR 0106 D1
:class:~apeGmsh.opensees._solver_stats.RunSolverStats when the
deck declared Pardiso(stats=True) anywhere, else None.
run=False returns None.
When analyze_steps is supplied, an analyze line is
appended to the deck after every other primitive — wrapped in
a hook-dispatching for-loop if any
:meth:initial_stress calls registered step hooks (Phase
SSI-1). Without analyze_steps, the emitted deck declares
the model but does not drive an analysis. With it, the deck's last
action, once the loop returns, closes every recorder (.out
included) and writes <mpco file>.run.json beside each MPCO
recorder's output (#2210; read_deck_mpco); the automatic
model.h5 is then written before the deck file.
per_rank=True (ADR 0061) writes a driver deck at path
plus one ranks/rank<K>_<seq>.tcl fragment per
if {[getPID] == K} { ... } block; the driver guards each
fragment behind a one-line source so every MPI rank parses
only the driver plus its own fragments — O(global + model/np)
instead of O(model) per rank. Layout-only: the deck semantics
(including the single-process rank-0 fallback) are unchanged.
Requires a partitioned model (len(fem.partitions) > 1).
flat=True forces the single-domain (serial) emit even when
the model carries partitions — e.g. a composed model, which is
auto-partitioned one-rank-per-module (ADR 0038 §"Rank model")
and would otherwise take the per-rank fan-out. The deck
declares the whole model in one domain with no getPID
brackets, exactly as the live in-process runner and modal decks
emit it. This is the Tcl route for serial-only records
(g.embed ties; fork contact before ADR 0092 S4 landed
partitioned emit, and still the escape hatch for the contact
cases the partitioned path refuses) on a composed model.
Mutually exclusive with per_rank; a no-op on
an already-unpartitioned model.
stream=True (ADR 0065 Tier 2 / plan_emit_memory_columnar.md
A1–A3) writes the deck through a live file sink instead of
accumulating the line buffer, so peak emit memory stops scaling
with deck size. Output is byte-identical to the default list
mode, including under per_rank=True, where the fragment
files are live-routed (partition_open switches the sink)
rather than sliced post-hoc. Everything goes to .tmp
siblings promoted atomically on clean completion — a mid-emit
exception never leaves a half-written deck.
Source code in src/apeGmsh/opensees/apesees.py
10189 10190 10191 10192 10193 10194 10195 10196 10197 10198 10199 10200 10201 10202 10203 10204 10205 10206 10207 10208 10209 10210 10211 10212 10213 10214 10215 10216 10217 10218 10219 10220 10221 10222 10223 10224 10225 10226 10227 10228 10229 10230 10231 10232 10233 10234 10235 10236 10237 10238 10239 10240 10241 10242 10243 10244 10245 10246 10247 10248 10249 10250 10251 10252 10253 10254 10255 10256 10257 10258 10259 10260 10261 10262 10263 10264 10265 10266 10267 10268 10269 10270 10271 10272 10273 10274 10275 10276 10277 10278 10279 10280 10281 10282 10283 10284 10285 10286 10287 10288 10289 10290 10291 10292 10293 10294 10295 10296 10297 10298 10299 10300 10301 10302 10303 10304 10305 10306 10307 10308 10309 10310 10311 10312 10313 10314 10315 10316 10317 10318 10319 10320 10321 10322 10323 10324 10325 10326 10327 10328 10329 10330 10331 10332 10333 10334 10335 10336 10337 10338 10339 10340 10341 10342 10343 10344 10345 10346 10347 10348 10349 10350 10351 10352 10353 10354 10355 10356 10357 10358 10359 10360 10361 10362 10363 10364 10365 10366 10367 10368 10369 10370 10371 10372 10373 10374 10375 10376 10377 10378 10379 10380 10381 10382 10383 10384 10385 10386 10387 10388 10389 10390 10391 10392 10393 10394 10395 10396 10397 10398 10399 10400 10401 10402 10403 10404 10405 10406 10407 10408 | |
modal_deck ¶
modal_deck(path: str, *, solver: str = 'feast', band: 'tuple[float, float] | None' = None, num_modes: int | None = None, certify: bool = False, target: str = 'tcl', out: str = 'eigenvalues.out') -> None
Emit a distributed modal deck (ADR 0077 Tier 1) — two backends.
solver="feast" (default) emits the replicated FEAST deck
described below; solver="arpack" emits the partitioned
ARPACK deck (Tier 1B) — see
:meth:_modal_deck_arpack for that half. They invert each
other on the two facts that matter (flat vs partitioned emit;
system inert vs load-bearing), so the docs are kept apart
rather than merged.
Which to use. "arpack" when the model does not fit on one
node: it is the only backend where both the storage and the
factorization are distributed. "feast" when you want a
frequency window rather than the lowest N, or -certify
completeness. Neither for a model that fits on one node —
Tier 0 (:meth:eigen / :meth:modal_properties on the
unpartitioned build) is faster at every size measured and is the
only route to correct participation factors and effective modal
mass.
FEAST backend (solver="feast", needs band=)¶
Writes a flat Tcl deck — every MPI rank builds the FULL model —
that runs band-targeted FEAST under OpenSeesMP: eigen -feast
band[0] band[1] -rci routes each contour solve through the
distributed dmumps kernel (fork ADR 43, L3-only: every rank
holds the full (K, M) CSR and the kernel slices the 2n block
system's triplets across ranks). Distribution lives inside the RCI
kernel, not in domain decomposition — a partitioned
if {[getPID]==K} deck fails FeastEigenSOE::setSize (P2
live finding), so partitions on the model are ignored here (the
deck is emitted flat) and the deck's system line plays no part
in the FEAST solve. RAM trade-off: the full model is assembled on
every rank (the documented L3 regime, ~1e5–1e6 DOF).
The band (Hz) defines the mode count; there is no num_modes.
The deck is the HPC entry point (ops.run_remote /
Cluster.submit, ADR 0060) and also runs single-process under
plain OpenSees (serial FEAST — the getPID shim makes the
rank-0 write-out unconditional).
modalProperties is not emitted: it is MPI-blind upstream
(wrong effective mass under any multi-rank run; ADR 0077 INV-2).
For participation factors run the single-process
:meth:modal_properties (Tier 0). Harvest with
:meth:ParallelModalResult.from_job — eigenvalues from the
rank-0 write-out plus mode shapes (ADR 0077 P3): the deck
records one mode_shape_<k>.out per found mode from rank 0
(the replicated model puts ALL nodes on every rank) with a
mode_shapes.json sidecar pinning the node→column map
(sorted mesh node tags × ndf DOFs).
Parameters¶
path
Deck output path.
solver
"feast" (default, replicated band solve) or "arpack"
(partitioned lowest-N solve, Tier 1B).
band
(f_min, f_max) frequency band in Hz; needs
0 <= f_min < f_max. FEAST only — rejected for
solver="arpack", whose selection axis is a mode count.
num_modes
Number of modes to extract. ARPACK only — rejected for
solver="feast", where the contour is the band and the
found count is dynamic.
certify
Emit -certify (fork Sturm/inertia completeness check).
FEAST only.
target
"tcl" (the classic-Tcl deck). Each solver needs its own
fork build: FEAST the classic-Tcl -feast parity build
(fork PR #578), ARPACK the MP eigen wiring (fork PR #668,
5a522b03b). "pymp" (an
OpenSeesMP-Python deck, ADR 0077 unlock 2a) raises for both
solvers — for ARPACK because the modern interpreter still
builds its ArpackSOE bare (the same latent F1 defect;
#668 is classic-Tcl only).
out
Rank-0 eigenvalue write-out filename (read by
:meth:ParallelModalResult.from_job).
Raises¶
ValueError
If solver is unknown, if the band / mode-count arguments
do not match the chosen solver, if band is invalid, if
solver="arpack" is given an unpartitioned model, or if a
non-Mumps system is declared on an ARPACK deck.
NotImplementedError
If target != "tcl" or the model has registered stages.
Source code in src/apeGmsh/opensees/apesees.py
10410 10411 10412 10413 10414 10415 10416 10417 10418 10419 10420 10421 10422 10423 10424 10425 10426 10427 10428 10429 10430 10431 10432 10433 10434 10435 10436 10437 10438 10439 10440 10441 10442 10443 10444 10445 10446 10447 10448 10449 10450 10451 10452 10453 10454 10455 10456 10457 10458 10459 10460 10461 10462 10463 10464 10465 10466 10467 10468 10469 10470 10471 10472 10473 10474 10475 10476 10477 10478 10479 10480 10481 10482 10483 10484 10485 10486 10487 10488 10489 10490 10491 10492 10493 10494 10495 10496 10497 10498 10499 10500 10501 10502 10503 10504 10505 10506 10507 10508 10509 10510 10511 10512 10513 10514 10515 10516 10517 10518 10519 10520 10521 10522 10523 10524 10525 10526 10527 10528 10529 10530 10531 10532 10533 10534 10535 10536 10537 10538 10539 10540 10541 10542 10543 10544 10545 10546 10547 10548 10549 10550 10551 10552 10553 10554 10555 10556 10557 10558 10559 10560 10561 10562 10563 10564 10565 10566 10567 10568 10569 10570 10571 10572 10573 10574 10575 10576 10577 10578 10579 10580 10581 10582 10583 10584 10585 10586 10587 10588 10589 10590 10591 10592 10593 10594 10595 10596 10597 10598 10599 10600 10601 10602 10603 | |
py ¶
py(path: str, *, run: bool = False, analyze_steps: int | None = None, analyze_dt: float | None = None, python: str | None = None, stream: bool = False, verbose: bool = False, log: str | None = None, progress: bool = True) -> 'RunReport | None'
Emit an openseespy Python deck to path; optionally run it.
run=True streams the openseespy subprocess exactly like
:meth:tcl — full output always tee'd to a log (log path
override, else <path>.log), console opt-in via verbose,
a live step counter from the progress markers, and a
tail-only RuntimeError on a non-zero exit. verbose /
log / progress are inert when run=False. The return
is :meth:tcl's: a frozen
:class:~apeGmsh.opensees._run.RunReport for run=True
(ADR 0106 Amendment 1), None for run=False.
analyze_steps / analyze_dt semantics mirror :meth:tcl
(Phase SSI-1).
stream=True is out of scope for the Python deck emitter
(v1) and fails loud — the HPC path is Tcl (ADR 0065 Tier 2 /
plan_emit_memory_columnar.md A1–A3); use
ops.tcl(path, stream=True).
Source code in src/apeGmsh/opensees/apesees.py
10834 10835 10836 10837 10838 10839 10840 10841 10842 10843 10844 10845 10846 10847 10848 10849 10850 10851 10852 10853 10854 10855 10856 10857 10858 10859 10860 10861 10862 10863 10864 10865 10866 10867 10868 10869 10870 10871 10872 10873 10874 10875 10876 10877 10878 10879 10880 10881 10882 10883 10884 10885 10886 10887 10888 10889 10890 10891 10892 10893 10894 10895 10896 10897 10898 10899 10900 10901 10902 10903 10904 10905 10906 10907 10908 10909 10910 10911 10912 10913 10914 10915 10916 10917 10918 10919 10920 10921 10922 10923 10924 10925 10926 10927 10928 10929 | |
results ¶
The history of this bridge's last deck run, as a Results
(ADR 0115 D3).
path is required and must be the deck that
ops.py(path, run=True) or ops.tcl(path, run=True) wrote
and ran on this bridge (Q5). What the run recorded decides the
reader:
- one
ops.recorder.MPCO-> :meth:Results.from_mpco; ops.recorder.declare(nodes=...)and typedops.recorder.Node(..., time_format="dt")records -> one recorder spec synthesised from them, read by :meth:Results.from_recorders(Q3).
It raises :class:BridgeError, naming why, before writing any
file: when no deck run happened on this bridge, the last solve
was a live analyze (read that with .read; Q4), path
is another deck, the run did not finish, the declarations changed
since the run, no recorder was declared, or a record cannot be
read here (a typed recorder.Element, a declare element
category or raw_* token, a typed record without a time
column, a staged or partitioned run's text records, a missing or
malformed output file). It never returns a Results that
silently lacks a declared record.
A read writes under <path>.results/: the model archive
(model.h5) the reader binds, the text records in the reader's
layout (out/) and the reader's cache.
A single value, one node at one step, is
ops.results(path).nodes.get(label="tip",
component="displacement_y").item().
Source code in src/apeGmsh/opensees/apesees.py
run ¶
Drive an in-process LiveOpsEmitter through the full deck.
This emits every primitive but does NOT call analyze —
that is the user's call (or :meth:analyze's). Useful when
the user wants to declare a model, populate openseespy state,
and then run their own analysis driver.
A staged model is refused before the domain is touched (#2533):
the live emitter cannot replay stages, and its stage_open
would otherwise raise after the wipe.
Source code in src/apeGmsh/opensees/apesees.py
wipe ¶
Close the live OpenSees domain (R3-S5, maintainer ruling D6).
Calls OpenSees wipe on the in-process module. It removes the
model and destroys every recorder, which flushes and closes its
file: a text recorder Node / Element file then holds every
row the analysis recorded, and an .mpco file is complete, so
Results.from_mpco opens it in the same script, without a
subprocess.
It closes this bridge's read session (ADR 0115 D2): a later
Node.read / NodeSet.read / ops.elements...read raises,
naming ops.wipe(). It also moves the domain epoch, so the
read session of any other bridge over the same process-global
domain raises too. The declarations stay: ops.analyze(...) or
ops.run() builds the model again from them.
A live session action only, never emitted to a deck (a deck
flushes its recorders when its process exits). It has no
VERBS row and no emitter Protocol method: it calls the live
module through LiveOpsEmitter.ops, never command().
Source code in src/apeGmsh/opensees/apesees.py
run_remote ¶
run_remote(job_dir: str, *, cluster: 'str | Cluster', np: int | None = None, name: str | None = None, deck: str = 'main.tcl', binary: str | None = None, walltime: str | None = None, analyze_steps: int | None = None, analyze_dt: float | None = None, wait: bool = True, poll: float = 15.0, timeout: float | None = None, overwrite: bool = False) -> 'Job'
Emit the Tcl deck and run it on a SLURM cluster (ADR 0060 sugar).
One call for the whole loop: emit into job_dir -> push ->
sbatch -> poll to completion -> fetch results back into
job_dir. Wraps :class:apeGmsh.hpc.Cluster /
:class:apeGmsh.hpc.Job; use those directly for finer control
(or pass wait=False to get the live :class:Job handle back
right after submission).
Parameters¶
job_dir
Local directory the deck is emitted into and results are
fetched back into. Created if missing.
cluster
Cluster name in ~/.apegmsh/clusters.toml (e.g.
"esmeralda") or a constructed Cluster.
np
MPI ranks. Defaults to the model's partition count
(len(fem.partitions)), or 1 for a flat model.
analyze_steps / analyze_dt
Forwarded to :meth:tcl — appends the analyze drive
line exactly as the local emit would.
wait
True (default) blocks until the job ends and fetches.
False returns the submitted Job immediately;
poll/fetch it yourself (it survives sessions via
Job.load(job_dir)).
Raises¶
HPCError
If the job ends in any state other than COMPLETED
(results and logs are still fetched first; the message
carries the stderr tail).
Source code in src/apeGmsh/opensees/apesees.py
11038 11039 11040 11041 11042 11043 11044 11045 11046 11047 11048 11049 11050 11051 11052 11053 11054 11055 11056 11057 11058 11059 11060 11061 11062 11063 11064 11065 11066 11067 11068 11069 11070 11071 11072 11073 11074 11075 11076 11077 11078 11079 11080 11081 11082 11083 11084 11085 11086 11087 11088 11089 11090 11091 11092 11093 11094 11095 11096 11097 11098 11099 11100 11101 11102 11103 11104 11105 11106 11107 11108 11109 11110 11111 11112 11113 11114 11115 11116 11117 11118 11119 11120 11121 11122 11123 11124 11125 11126 11127 11128 11129 11130 | |
h5 ¶
h5(path: str, *, model_name: str | None = None, cuts: 'Sequence[SectionCutDef]' = (), sweeps: 'Sequence[SectionSweepDef]' = ()) -> None
Emit a model-definition HDF5 archive at path.
Phase 8.5 composes the file in two layers:
- The broker (
self._fem) writes/meta+ the neutral zone (/nodes,/elements/{type},/physical_groups,/labels,/constraints/{kind},/loads/{kind}/{pattern},/masses). Broker writers live in :mod:apeGmsh.mesh._femdata_h5_io. - The bridge (an :class:
H5Emitterdriven through the :class:BuiltModel) appends/opensees/...enrichment. - apeGmsh.cuts v4: if
cutsand / orsweepsare supplied, they're persisted under/opensees/cuts/and/opensees/sweeps/(writer in :mod:apeGmsh.cuts._h5_io).
If self._fem does not expose a real :class:FEMData
surface (e.g. integration tests using a hand-rolled stub),
the broker step is skipped: the file ends up with the
bridge's own /meta plus /opensees/..., but no neutral
zone. Real callers always get the full file shape.
Parameters¶
path
File path to write the HDF5 archive to.
model_name
Optional human-readable name written to /meta/model_name.
Defaults to the path's stem.
cuts
Optional sequence of :class:apeGmsh.cuts.SectionCutDef
to persist under /opensees/cuts/cut_{i}. Each cut
travels with the model definition; the viewer auto-loads
them from the file the next time Results.viewer(...)
is opened against a results.h5 carrying the same
/opensees/ zone (Phase 8 / ADR 0020 Composed-file
pattern).
sweeps
Optional sequence of :class:apeGmsh.cuts.SectionSweepDef
to persist under /opensees/sweeps/sweep_{i}. Each
sweep group carries its own cuts/ sub-group in sweep
order (see apeGmsh/cuts/ARCHITECTURE.md "## v4").
Source code in src/apeGmsh/opensees/apesees.py
11132 11133 11134 11135 11136 11137 11138 11139 11140 11141 11142 11143 11144 11145 11146 11147 11148 11149 11150 11151 11152 11153 11154 11155 11156 11157 11158 11159 11160 11161 11162 11163 11164 11165 11166 11167 11168 11169 11170 11171 11172 11173 11174 11175 11176 11177 11178 11179 11180 11181 11182 11183 11184 11185 11186 11187 11188 11189 11190 11191 11192 11193 11194 11195 11196 11197 11198 11199 11200 11201 11202 11203 11204 11205 11206 11207 | |
register ¶
Register a standalone primitive with the bridge (P11).
Idempotent on the object: registering an instance the bridge
already holds (a namespace handle, or a second register)
returns it unchanged, so it stays once in the primitive list
(#1409).
Source code in src/apeGmsh/opensees/apesees.py
tag_for ¶
Return prim's allocated tag, or None if unregistered.
An mpm grid answers the tag its deck line writes (ADR 0134,
:func:.mpm.host_tag): a fork load-pattern tag above every
registered pattern tag (and every other mpm member's tag),
so a pattern or member declared later moves it.
Source code in src/apeGmsh/opensees/apesees.py
build ¶
Freeze the declarations into a :class:BuiltModel.
Source code in src/apeGmsh/opensees/apesees.py
11612 11613 11614 11615 11616 11617 11618 11619 11620 11621 11622 11623 11624 11625 11626 11627 11628 11629 11630 11631 11632 11633 11634 11635 11636 11637 11638 11639 11640 11641 11642 11643 11644 11645 11646 11647 11648 11649 11650 11651 11652 11653 11654 11655 11656 11657 11658 11659 11660 11661 11662 11663 11664 11665 11666 11667 11668 11669 11670 11671 11672 11673 11674 11675 11676 11677 11678 11679 11680 11681 11682 11683 11684 11685 11686 11687 11688 11689 11690 11691 11692 11693 11694 11695 11696 11697 11698 11699 11700 11701 11702 | |
Staged analysis¶
Multi-stage workflows (in-situ stress install → excavate →
lining install → dynamic shake, or any other sequence of
analyze blocks with Domain mutations between them) use
the ops.stage(name) context manager:
with ops.stage(name="excavate") as s:
s.activate(pgs=["Lining"]) # bring new elements online
s.fix(pg="LiningAnchor", dofs=(1, 1, 1)) # stage-bound BC
s.embedded(name="lining_embed") # claim MP constraint by name
s.analysis(test=…, algorithm=…, integrator=…,
constraints=…, numberer=…, system=…, analysis=…)
s.run(n_increments=20, dt=0.05)
Each stage emits its own analysis chain + analyze loop with an
explicit inter-stage cleanup (loadConst -time 0.0 +
wipeAnalysis). Between-stage Domain mutators (s.remove_sp
/ s.remove_element / s.set_time / s.set_creep /
s.reset / s.mass(overwrite=True)) lift the append-only
constraint from earlier phases and unlock the atomic-replace
pattern (release prior support + re-fix the same DOF in one
stage).
Five validators gate stage-bound BCs at build time (H1 / V1 / V2
/ V3 / V4) and two more cover the SSI-2.E removal verbs (V5 /
V6). Each raises BridgeError with a clear offender list when
a stage references topology that doesn't yet exist or has
already been removed.
Tcl + Py text emit are the supported execution paths for staged
decks today. Live execution (ops.analyze / ops.eigen)
refuses staged models with NotImplementedError — emit via
ops.tcl(p, run=True) / ops.py(p, run=True) for the
OpenSees subprocess. H5 archival supports staged builds:
apeSees.h5(path) archives flat and partitioned staged models into
/opensees/stages (ADR 0055). The remaining staged refusals are a
stage-claimed interface (phantom nodes / node_to_surface).
The full lifecycle table, builder verbs, validator surface, MP partitioned + staged emit (Phase SSI-2.C), and the SSI-1 initial-stress ramp live in architecture/api-design.md §"Staged analysis"; the internals (deck layout, ownership computation, hook dispatcher, per-emitter dialect divergence, cleanup contract) live in architecture/staged-analysis.md and architecture/emitter.md.
Orientation helpers¶
Used as the orientation= argument on the typed geom_transf
primitives (Linear / PDelta / Corotational).
apeGmsh.opensees.Cartesian ¶
Constant Cartesian triad. reference_axis defines e3;
e1 and e2 are picked deterministically from the global
axis least aligned with e3.
The default reference_axis = (0, 0, 1) reproduces the legacy
"Z up" convention: horizontal beams get vecxz = (0, 0, 1) and
vertical columns fall back to vecxz = (-1, 0, 0) (the sign
follows the tangent direction; see :ref:shoebuckle).
Parameters¶
reference_axis : 3-vector
The axis e3. Need not be unit length.
Example¶
::
from apeGmsh.opensees import Cartesian
# Standard structural convention: Z is vertical
orientation = Cartesian() # reference_axis = +Z
# Mechanical CAD convention: Y is vertical
orientation = Cartesian(reference_axis=(0, 1, 0))
Source code in src/apeGmsh/opensees/_orientation.py
apeGmsh.opensees.Cylindrical ¶
Cylindrical orientation about an axis of revolution.
At a point p:
e1= radial outward, perpendicular toaxise2= circumferential,axis × e1e3=axis(constant) ← reference axis for the rule
Use this for ring beams, tank stiffeners, and any beam set whose natural "vertical" is the axis of revolution.
Parameters¶
origin : 3-vector Any point on the axis of revolution. axis : 3-vector Direction of the axis of revolution. Need not be unit length.
Example¶
::
from apeGmsh.opensees import Cylindrical
# Vertical tank
orientation = Cylindrical(origin=(0, 0, 0), axis=(0, 0, 1))
Source code in src/apeGmsh/opensees/_orientation.py
apeGmsh.opensees.Spherical ¶
Spherical orientation about a fixed origin. Polar axis is global +Z.
At a point p (with r = |p − origin|):
e1=e_θ— along the meridian (south at the equator)e2=e_φ— along the parallel (east)e3=e_r— outward radial ← reference axis for the rule
Useful for fan vaults, geodesic ribs, and any beam network with
natural radial structure. Note: for a planar curved beam (e.g.
a vertical-plane arch), :class:Cartesian with reference_axis
in the plane gives the same answer with less ceremony.
Parameters¶
origin : 3-vector Centre of the sphere.
Example¶
::
from apeGmsh.opensees import Spherical
orientation = Spherical(origin=(0, 0, 0))
Source code in src/apeGmsh/opensees/_orientation.py
Frame property modifiers¶
Passed as modifiers= on elasticBeamColumn,
ElasticTimoshenkoBeam, forceBeamColumn and dispBeamColumn. The
emitted section properties are the declared ones times the modifiers, in the
way ETABS frame property modifiers work.
apeGmsh.opensees.FrameModifiers
dataclass
¶
FrameModifiers(*, A: float = 1.0, Avy: float = 1.0, Avz: float = 1.0, J: float = 1.0, Iy: float = 1.0, Iz: float = 1.0, mass: float = 1.0, weight: float = 1.0)
Frame section property modifiers, in OpenSees local axes.
Every field defaults to 1.0 (gross section). The six stiffness
modifiers (A, Avy, Avz, J, Iy, Iz) must be
finite and > 0; mass and weight finite and >= 0.
Attach to an element spec with modifiers=::
cracked = FrameModifiers.etabs(I22=0.7, I33=0.7) # ACI 318-25 columns
ops.element.elasticBeamColumn(pg="Cols", transf=t, A=..., E=...,
Iz=..., Iy=..., G=..., J=...,
modifiers=cracked)
Use :meth:etabs to construct from ETABS-named modifiers.
etabs
classmethod
¶
etabs(*, A: float = 1.0, As2: float = 1.0, As3: float = 1.0, J: float = 1.0, I22: float = 1.0, I33: float = 1.0, mass: float = 1.0, weight: float = 1.0) -> 'FrameModifiers'
Build from ETABS frame property modifier names.
Axis mapping: ETABS local 1 runs along the member, as OpenSees
local x does. Choose the element's geomTransf vecxz along
ETABS local 3: OpenSees local z then equals ETABS 3, and since
both triads are right-handed with a common first axis, OpenSees
local y = z x x = 3 x 1 = ETABS 2. Under that vecxz the mapping
is As2 -> Avy, As3 -> Avz, I22 -> Iy (bending about
local 2 / y), I33 -> Iz (bending about local 3 / z, the major
axis of an ETABS frame section). A, J, mass and
weight carry no axis. With any other vecxz the 2 and 3
modifiers land on whichever OpenSees axes it defines, so check it.
For a vertical ETABS column (1 = +Z, 2 = +X, 3 = +Y) that is
vecxz=(0, 1, 0); for a beam along +X (1 = +X, 2 = +Z,
3 = -Y) it is vecxz=(0, -1, 0).
The ETABS importer does not use this convention.
interop/etabs_import.py (_VECXZ) gives a vertical member
vecxz=(1, 0, 0) and any other member (0, 0, 1): for a member
at its default orientation both are ETABS 2, not 3, and the
importer ignores Frame.rotation. Under that vecxz OpenSees
local z is ETABS 2, so I33 lands on the minor axis (and I22
on the major one). The importer passes no modifiers= today;
wiring it to this method needs vecxz along ETABS 3 first.
Source code in src/apeGmsh/opensees/element/frame_modifiers.py
non_unit ¶
The modifiers that differ from 1.0, by OpenSees name.
Recorders¶
Standalone recorder declaration helper. Recorder declarations live on
ops.recorder.* in the apeSees bridge (typed primitives —
Node / Element / MPCO / declarative fan-out via
ops.recorder.declare(...)).
apeGmsh.opensees.recorder ¶
Typed recorder primitives.
Phase 3B ships three concrete recorder classes mirroring the OpenSees
recorder command:
- :class:
Node—recorder Node ... - :class:
Element—recorder Element ... - :class:
MPCO—recorder mpco ...(HDF5)
Each class is a @dataclass(frozen=True, kw_only=True, slots=True);
the matching :class:apeGmsh.opensees._internal.ns.recorder._RecorderNS
methods take the same kwargs and call self._bridge._register(Cls(...)).
Recorders never compose other primitives (dependencies() returns
()). They are leaves in the dependency graph; the build pipeline
emits them after the topology + analysis chain so that each recorder
command sees fully-allocated node and element tags.
The pg= form (physical-group fan-out into node/element tags) is
materialized at build time by
:func:apeGmsh.opensees._internal.build.recorders.emit_recorder_spec, which
resolves pg through the FEM snapshot, rewrites the spec to its
explicit nodes= / elements= form via :func:dataclasses.replace,
and then delegates to _emit. End users drive this through
apeSees(fem).tcl(...) / .py(...) / .run() — never call _emit
directly with a pg spec, which raises :class:NotImplementedError
as a defense-in-depth guard.
OpenSees command shapes¶
::
recorder Node -file fname [-time] [-dT dT] [-node n...]
-dof d... response
recorder Element -file fname [-time] [-dT dT] [-ele e...]
response_tokens...
recorder mpco fname.mpco [-N nodal_responses...]
[-E elem_responses...]
[-T dt $dt | -T nsteps $n]
The -time flag (when time_format="dt") instructs OpenSees to
include the simulation-time column in the output file. The default
time_format="step" writes only the response columns.
Node
dataclass
¶
Node(*, file: str, response: str, nodes: tuple[int, ...] | None = None, pg: str | None = None, label: tuple[str, ...] | None = None, dofs: tuple[int, ...], dT: float | None = None, time_format: str = 'step', precision: int | None = None)
Bases: Recorder
recorder Node — record nodal response history.
OpenSees command::
recorder Node -file fname [-time] [-dT dT]
(-node n1 n2 ... | -nodeRange first last)
-dof d1 d2 ... response
Exactly one of nodes= (explicit list) or pg= (physical-group
label) must be supplied. The bridge build pipeline materializes the
pg= form against the FEM snapshot before driving _emit;
direct _emit calls on a pg= spec raise
:class:NotImplementedError as a defense-in-depth guard.
Parameters¶
file
Output file path.
response
OpenSees response token ("disp", "vel", "accel",
"reaction", "unbalance", ...).
nodes
Explicit tuple of node tags. Mutually exclusive with pg.
pg
Physical-group label whose nodes the recorder targets.
Mutually exclusive with nodes. Resolved by the bridge
build pipeline at emit time.
label
Provenance of an ops.recorder.Node(label=...) declaration
(ADR 0115 amendment R2-f): the geometry label name(s) the call
resolved to nodes. Never re-resolved and never emitted;
nodes stays authoritative. Needs nodes=, refuses pg=.
dofs
DOF indices (1-based, OpenSees convention). At least one
required.
dT
Optional cadence — record only every dT simulation
seconds. None records every step.
time_format
"step" (default) writes only response columns;
"dt" emits the OpenSees -time flag, prepending the
simulation-time column.
precision
Significant digits per written value (OpenSees -precision N;
its default is 6). None (default) emits no flag, so the deck
is unchanged. A positive int; anything else raises.
Element
dataclass
¶
Element(*, file: str, response: tuple[str, ...], elements: tuple[int, ...] | None = None, pg: str | None = None, label: tuple[str, ...] | None = None, dT: float | None = None, time_format: str = 'step', precision: int | None = None)
Bases: Recorder
recorder Element — record element-level response history.
OpenSees command::
recorder Element -file fname [-time] [-dT dT]
(-ele e1 e2 ... | -eleRange first last)
response_tokens...
response is a tuple of OpenSees response tokens — the simplest
case is ("globalForce",) or ("stresses",); element types
that nest responses (e.g. fiber sections) take multi-token forms
such as ("section", "1", "force").
Exactly one of elements= (explicit list) or pg= (physical-
group label) must be supplied. pg= is resolved against the FEM
snapshot by the bridge build pipeline before driving _emit;
direct _emit calls on a pg= spec raise
:class:NotImplementedError as a defense-in-depth guard.
Parameters¶
file
Output file path.
response
Tuple of OpenSees response tokens (at least one).
elements
Explicit tuple of element tags. Mutually exclusive with pg.
With label set they are the FEM element ids the label
resolved to, which the bridge translates to the emitted
OpenSees tags at build (as it does for pg=).
pg
Physical-group label whose elements the recorder targets.
Mutually exclusive with elements. Resolved by the bridge
build pipeline at emit time.
label
Provenance of an ops.recorder.Element(label=...)
declaration (ADR 0115 amendment R2-f): the geometry label
name(s) the call resolved to FEM element ids. Never
re-resolved and never emitted; it marks elements as FEM
ids. Needs elements=, refuses pg=. The archive stores
the translated OpenSees tags, as for every other Element
recorder.
dT
Optional cadence — record only every dT simulation
seconds. None records every step.
time_format
"step" (default) writes only response columns;
"dt" emits the OpenSees -time flag.
precision
Significant digits per written value (OpenSees -precision N;
its default is 6). None (default) emits no flag, so the deck
is unchanged. A positive int; anything else raises.
FilterableRecorder
dataclass
¶
FilterableRecorder(*, file: str, nodal_responses: tuple[str, ...] = (), elem_responses: tuple[str, ...] = (), dT: float | None = None, nsteps: int | None = None, nodes: tuple[int, ...] | None = None, nodes_pg: str | None = None, elements: tuple[int, ...] | None = None, elements_pg: str | None = None, _region_tag: int | None = None)
Bases: Recorder
Base for HDF5 recorders that share MPCO's region-filter surface.
Carries the four mutually-paired selectors (nodes / nodes_pg
/ elements / elements_pg) and the region-emit machinery that
turns them into an OpenSees region $tag -node ... -ele ... line
plus a -R $tag on the recorder command. :class:MPCO and
:class:Ladruno both inherit it; they differ only in the recorder
kind token and (Ladruno) the trailing -G energy channel.
Carries the shared value channels too (file + nodal_responses
/ elem_responses -N/-E + dT/nsteps -T cadence),
so :meth:_value_channel_args builds the common -N ... -E ... -T ...
-R ... tail once for both subclasses — only the recorder kind
token and (Ladruno) the trailing -G energy are subclass-specific.
Subclasses own only their required-response rule (MPCO needs nodal or
element responses; Ladruno also accepts energy); the cadence
mutex (:meth:_validate_cadence) and the four selector guards
(:meth:_validate_filter) are shared. The partition-aware build
pipeline (ADR 0027 INV-4) keys its per-rank region pass on
isinstance(spec, FilterableRecorder) via :meth:has_filter /
:meth:resolve_filter_ids.
has_filter ¶
True iff any node/element selector was supplied.
Used by the partition-aware build pipeline (ADR 0027 INV-4) to
decide whether the recorder needs a per-rank region pass — a
whole-model recorder (no filter) emits one recorder line
and nothing else.
Source code in src/apeGmsh/opensees/recorder.py
region_keys ¶
The regions this recorder writes, in the order they take tags.
"filter" is the value-channel filter region (-R), present
iff :meth:has_filter. :class:Ladruno adds "energy", its
decoupled energy region. The tag plan numbers them in this order.
Source code in src/apeGmsh/opensees/recorder.py
planned_region_tags ¶
The tag of each of :meth:region_keys, by key.
Read from tag_plan (ADR 0114 D4, amended): a plan made for
another model, or one that lacks a region this recorder writes,
raises :class:~._internal.build.errors.TagPlanMiss.
resolve_filter_ids ¶
resolve_filter_ids(fem: 'FEMData', fem_eid_to_ops_tag: 'FemToOpsTagMap | dict[int, int] | None' = None) -> tuple[tuple[int, ...], tuple[int, ...]]
Resolve nodes / nodes_pg / elements / elements_pg
to explicit id tuples — no emission, no tag allocation.
Returns (node_ids, elem_ids). Either may be empty when its
side was not requested; an empty result on a requested side
(e.g. nodes_pg="X" resolving to zero nodes) raises
:class:BridgeError to mirror the OpenSees runtime rejection of
an empty region.
fem_eid_to_ops_tag is the bridge-built {fem_eid: ops_tag}
map for element fan-out. When supplied AND elements_pg is
set, the resolved FEM eids are translated to OpenSees element
tags before they flow into the region's -ele arg list
(same drift as the Element recorder, closed by
:meth:Element.materialize). Lookup miss → :class:BridgeError.
When None (legacy direct callers) the FEM eids are returned
verbatim — the partition orchestrator uses this form so it can
intersect per-rank in FEM-eid space, then translate at the
final region-emit step.
This is the partition-aware split-point of the legacy single-
pass :meth:materialize: the partition orchestrator calls
resolve_filter_ids once globally to determine the full
filter id set, then intersects per-rank before emitting the
region. Whole-model recording (has_filter() is False) is
a no-op pass-through — callers should not invoke this method
in that case.
Source code in src/apeGmsh/opensees/recorder.py
705 706 707 708 709 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 | |
materialize ¶
materialize(emitter: 'Emitter', fem: 'FEMData', tag_plan: 'TagPlan | None', fem_eid_to_ops_tag: 'FemToOpsTagMap | dict[int, int] | None' = None) -> 'FilterableRecorder'
Resolve filter selectors against the FEM and emit the region.
Whole-model recording (no filter selectors) is a no-op pass-
through. When any of nodes / nodes_pg / elements /
elements_pg is set, this method:
- Resolves
*_pgto explicit id tuples via the bridge's PG-expansion helpers; refuses empty resolutions with :class:BridgeError(an empty OpenSees region is rejected at runtime). - Reads the region tag the build's tag plan gave it
(:meth:
planned_region_tags;tag_planmust be supplied — the bridge build pipeline forwards the emit's tag plan). - Emits one
region $tag -node ... -ele ...line onemitter. - Returns a clone with the filter selectors cleared and
_region_tagpopulated, so the subsequent_emitappends-R $tagto the recorder command.
Used by the flat emit path and by the stage passes. The
partitioned emit path (ADR 0027 INV-4) invokes
:meth:resolve_filter_ids once for each recorder of its global
pass and emits the per-rank region line itself; it then injects
_region_tag= onto the spec via :func:dataclasses.replace
directly, bypassing this method.
Source code in src/apeGmsh/opensees/recorder.py
MPCO
dataclass
¶
MPCO(*, file: str, nodal_responses: tuple[str, ...] = (), elem_responses: tuple[str, ...] = (), dT: float | None = None, nsteps: int | None = None, nodes: tuple[int, ...] | None = None, nodes_pg: str | None = None, elements: tuple[int, ...] | None = None, elements_pg: str | None = None, _region_tag: int | None = None)
Bases: FilterableRecorder
recorder mpco — write a single HDF5 .mpco file.
OpenSees command::
recorder mpco fname.mpco [-N nodal_responses...]
[-E elem_responses...]
[-T dt $dt | -T nsteps $n]
[-R $regTag]
The MPCO recorder captures the full response tensor for each
requested token (no per-DOF selection at write time); STKO /
apeGmsh consumers filter at read time. At least one of
nodal_responses or elem_responses must be non-empty.
Cadence is selected by exactly one of dT (seconds) or
nsteps (analysis steps). Supplying both raises ValueError;
supplying neither records every analysis step.
Filtering — MPCO records the whole model by default. To
restrict output to a subset of nodes/elements, supply any of
nodes= / nodes_pg= / elements= / elements_pg=:
the build pipeline auto-emits an OpenSees region $tag -node ...
-ele ... command before the recorder and passes -R $tag to
MPCO. nodes= is mutually exclusive with nodes_pg=; the
same applies to the element pair. When all four are None
(the default) MPCO records the whole model and no region is
emitted.
Parameters¶
file
Output .mpco (HDF5) file path.
nodal_responses
Tuple of MPCO -N tokens (e.g. ("displacement",
"reactionForce")). Empty tuple means no nodal recording.
elem_responses
Tuple of MPCO -E tokens (e.g. ("stresses",
"section.fiber.stress")). Empty tuple means no element
recording.
dT
Optional time-based cadence (seconds). Mutually exclusive
with nsteps.
nsteps
Optional step-based cadence (every N analysis steps).
Mutually exclusive with dT.
nodes
Explicit tuple of node tags to include in the region filter.
Mutually exclusive with nodes_pg.
nodes_pg
Physical-group label whose nodes the region filter targets.
Mutually exclusive with nodes. Resolved by the bridge
build pipeline at emit time.
elements
Explicit tuple of element tags to include in the region
filter. Mutually exclusive with elements_pg.
elements_pg
Physical-group label whose elements the region filter
targets. Mutually exclusive with elements. Resolved by
the bridge build pipeline at emit time.
Note¶
The bridge does not interpret -R-bearing MPCO arg tails when
_emit is called directly (outside the build pipeline); the
pg= form is materialised by
:func:apeGmsh.opensees._internal.build.recorders.emit_recorder_spec,
which resolves selectors, reads its planned region tag, emits the
region, and replaces the spec via :func:dataclasses.replace
with explicit nodes=/elements= before driving _emit.
Ladruno
dataclass
¶
Ladruno(*, file: str, nodal_responses: tuple[str, ...] = (), elem_responses: tuple[str, ...] = (), dT: float | None = None, nsteps: int | None = None, nodes: tuple[int, ...] | None = None, nodes_pg: str | None = None, elements: tuple[int, ...] | None = None, elements_pg: str | None = None, _region_tag: int | None = None, energy: bool = False, energy_pg: str | None = None, precision: Literal['f64', 'f32'] = 'f64', _energy_region_tags: tuple[int, ...] = (), _node_region_tag: int | None = None)
Bases: FilterableRecorder
recorder ladruno — write a single HDF5 .ladruno file.
Fork-only. The ladruno recorder exists only in the Ladruno
fork build of OpenSees (nmorabowen/OpenSees@ladruno); stock
openseespy does not have it. Per the opt-in contract, emission
works on any build (the deck line is just recorder ladruno
...); the fork requirement bites only when the deck actually runs
(ops.run() / the live emitter). Gate at the point of use, never
at import.
OpenSees command (value channels + region filter + energy balance)::
recorder ladruno fname.ladruno [-precision f32]
[-N nodal_responses...]
[-E elem_responses...]
[-T dt $dt | -T nsteps $n]
[-R $regTag [-RN $nodeRegTag]]
[-G energy]
The .ladruno recorder is forked from the frozen MPCORecorder
and shares its value-channel command grammar (the -N/-E/
-T channels reproduce the frozen recorder to 1e-12), so this
dataclass mirrors :class:MPCO for those channels and inherits the
same region-filter machinery from :class:FilterableRecorder. It
diverges only in the recorder kind token (ladruno vs mpco),
the output extension (.ladruno), and the trailing -G energy
channel.
Cadence is selected by exactly one of dT (seconds) or nsteps
(analysis steps). Supplying both raises ValueError; supplying
neither records every analysis step.
Filtering — like MPCO, Ladruno records the whole model by
default. Supply any of nodes= / nodes_pg= / elements= /
elements_pg= to restrict output: the build pipeline auto-emits an
OpenSees region $tag -node ... -ele ... command before the
recorder and passes -R $tag to ladruno. nodes= is
mutually exclusive with nodes_pg= (same for the element pair).
A node-only filter cannot be combined with elem_responses (and
vice versa) — the auto-region would carry no entries on the other
side and produce an empty stream. The -R $tag is emitted
before -G energy so the energy flag stays last.
Nodes and elements together (fork WP-234). An OpenSees
MeshRegion cannot hold a node list and an element list at once:
setNodes and setElements each wipe both, and -ele rebuilds
the nodes from the elements, so one region -node ... -ele ... line
silently keeps only the element nodes. When a node selector
(nodes=/nodes_pg=) and an element selector
(elements=/elements_pg=) are both given, Ladruno therefore
emits two regions — region $tag -ele ... and
region $nodeTag -node ... — and passes -R $tag -RN $nodeTag.
The fork records -N rows on the -R element nodes plus the
-RN nodes, and -E rows on the -R elements only. That is how
embedded rebar nodes (whose minted truss elements carry no FEM id and
must stay out of the file) get their displacements recorded. Only a
fork build whose ladrunoSchema lists the
recorderLadrunoNodeRegion capability reads -RN: the live route
refuses another build by name, and a Tcl / openseespy deck checks the
running build at its start and stops with the same message.
energy=True adds the fork's whole-model energy-balance channel
(-G energy → RESULTS/ON_DOMAIN/energyBalance, components
KE/IE/DW/ULW/RES/ERR), read back via Results.energy(). The
flag is emitted last: the fork's -G parser eagerly consumes
trailing region-tag integers and cannot rewind past a following
flag, so -G energy -T nsteps 10 is a parse error while
-T nsteps 10 -G energy runs (run-verified on the fork build).
Energy balance. Three forms, all run-verified on the fork build
(which always writes the whole-model balance,
RESULTS/ON_DOMAIN/energyBalance, and adds a per-region balance,
RESULTS/ON_REGIONS/energyBalance, whenever a region tag is given):
energy=Truealone → whole-model (-G energy, no tag).energy=True+ a value filter → energy over the same region the-Rfilter targets, reusing the filter's already-allocated tag (-G energy $filterTag). The coupled form.energy_pg="X"→ energy over an independent region X (-G energy $tagX), decoupled from the-Rvalue filter. X may differ from (or exist without) the value-channel filter; it gets its own region tag. The decoupled form.energy_pgtakes precedence over the coupled form, and implies energy recording (no need to also setenergy=True).
All three ride the flat / staged / partitioned region plumbing — the
decoupled region gets its own per-rank fan-out under partitioning, just
like the value filter (ADR 0064 §4). Read any region's balance via
Results.energy(region=<tag>); whole-model via Results.energy().
Precision. precision="f32" emits -precision f32 right after
the file name, and the fork stores the per-step result DATA as
float32 (about half the bytes, ~7 significant digits; the fork stamps
the choice in the file's INFO/STORED_PRECISION). The default
"f64" emits no flag, so a default deck is byte-identical to one
written before the field existed. The flag precedes -N/-E so
it never sits where the fork's -G parser eats trailing tokens.
The value is archived in ops.h5 with the recorder's other fields
(the /opensees/decl_params row), so a reader knows the recorded
precision without opening the .ladruno.
Parameters¶
file
Output .ladruno (HDF5) file path.
precision
On-disk element type of the recorded data: "f64" (default,
lossless) or "f32" (-precision f32, lossy). Anything else
raises ValueError; the fork would otherwise warn and keep f64.
nodal_responses
Tuple of -N tokens (e.g. ("displacement",
"reactionForce")). Empty tuple means no nodal recording.
elem_responses
Tuple of -E tokens (e.g. ("stresses",
"section.fiber.stress")). Empty tuple means no element
recording.
dT
Optional time-based cadence (seconds). Mutually exclusive with
nsteps.
nsteps
Optional step-based cadence (every N analysis steps). Mutually
exclusive with dT.
energy
Record the energy balance (-G energy). Whole-model when no
filter is set; per-region (over the -R filter region, plus
whole-model) when combined with a nodes=/elements= filter.
energy_pg
Physical-group label for a decoupled energy region — records
energy over that PG (-G energy $tag) independent of the value
filter. Implies energy recording. Resolved by the bridge build
pipeline; gets its own auto-emitted region (per-rank under
partitioning).
nodes
Explicit tuple of node tags for the region filter. Mutually
exclusive with nodes_pg.
nodes_pg
Physical-group label whose nodes the region filter targets.
Mutually exclusive with nodes. Resolved by the bridge build
pipeline at emit time.
elements
Explicit tuple of element tags for the region filter. Mutually
exclusive with elements_pg.
elements_pg
Physical-group label whose elements the region filter targets.
Mutually exclusive with elements. Resolved by the bridge
build pipeline at emit time.
resolve_energy_ids ¶
resolve_energy_ids(fem: 'FEMData', fem_eid_to_ops_tag: 'FemToOpsTagMap | dict[int, int] | None' = None) -> tuple[int, ...]
Resolve energy_pg to element ids for the energy region.
Mirrors the element side of :meth:resolve_filter_ids: returns
FEM eids verbatim when fem_eid_to_ops_tag is None (the
partition orchestrator intersects per-rank in FEM-eid space),
else translates to OpenSees element tags. Empty resolution →
:class:BridgeError. Energy is an element quantity, so the
region carries -ele only (the fork auto-derives the nodes).
Source code in src/apeGmsh/opensees/recorder.py
splits_filter ¶
True iff the filter needs a separate -RN node region.
Both a node selector and an element selector set: one OpenSees
region cannot carry both lists (MeshRegion::setNodes /
setElements each wipe both), so the nodes go to their own
region, read by the fork's -RN (WP-234).
Source code in src/apeGmsh/opensees/recorder.py
region_keys ¶
The value-filter region (base), the -RN node region when the
filter splits, then the decoupled energy region.
The energy region (energy_pg) is independent of the -R
value filter (the fork's -G energy <tag> list is orthogonal to
-R); it takes its own tag, after the filter's.
Source code in src/apeGmsh/opensees/recorder.py
Monitor
dataclass
¶
Monitor(*, sink: str, dofs: tuple[int, ...], nodes: tuple[int, ...] | None = None, pg: str | None = None, resp: str = 'disp', every: int | None = None, hz: float | None = None)
Bases: Recorder
recorder Monitor — live SWMR-HDF5 nodal-telemetry sink (fork-only).
Fork-only. The Monitor recorder exists only in the Ladruno fork
build; stock openseespy does not have it. Emission works on any
build (the deck line is just recorder Monitor ...); the fork
requirement bites only when the deck runs. Gate at the point of use.
Unlike the canonical :class:Ladruno recorder, the Monitor is a
lightweight live-telemetry sidecar: it streams a few selected nodal
scalars to a small SWMR-HDF5 file a viewer process can tail while the
analysis is still running. The same file is a valid at-rest result
once the run finishes — read both via
:func:apeGmsh.results.read_monitor / :func:apeGmsh.results.tail_monitor.
OpenSees command::
recorder Monitor (-node n1 n2 ... | -region tag) -dof d1 d2 ...
[-resp disp|vel|accel|reaction]
-sink fname.h5 [-every K] [-hz H]
Exactly one of nodes= (explicit tags) or pg= (physical-group
label, resolved against the FEM snapshot by the bridge build pipeline)
must be supplied. The recorded channels are the cartesian product of
nodes × dofs, labelled node<N>.<resp>.dof<D> in node-major order.
Parameters¶
sink
Output .h5 SWMR sink path.
dofs
DOF indices (1-based, OpenSees convention). At least one required.
nodes
Explicit tuple of node tags. Mutually exclusive with pg.
pg
Physical-group label whose nodes are monitored. Mutually exclusive
with nodes; resolved at emit time.
resp
Nodal response — one of disp / vel / accel /
reaction (the fork v1 set). Default disp.
every
Step decimation — emit a frame every K analysis steps. None
records every step.
hz
Wall-clock throttle — emit at most H frames per second of real
time (the first frame always passes). None means no throttle.
Independent of every; both may bound the stream.
RecorderRecord
dataclass
¶
RecorderRecord(*, category: str, components: tuple[str, ...] = (), raw: tuple[str, ...] = (), pg: tuple[str, ...] = (), label: tuple[str, ...] = (), selection: tuple[str, ...] = (), ids: tuple[int, ...] | None = None, dt: float | None = None, n_steps: int | None = None, name: str | None = None, n_modes: int | None = None, element_class_name: str | None = None)
One category-level declaration entry within a RecorderDeclaration.
Stores already-expanded canonical components (or raw OpenSees
tokens via the raw= escape hatch). Shorthand expansion
("displacement" → displacement_x/y/z) happens at
construction in the namespace method (Phase 9 commit 3), not in
this dataclass — by the time a record is built, components are
fully expanded.
Parameters¶
category
One of :data:ALL_RECORDER_CATEGORIES.
components
Tuple of canonical component names, each one the category
records (:func:apeGmsh._vocabulary.in_category: the
CATEGORY_COMPONENTS table plus its indexed canonicals,
state_variable_<n>, fiber_stress_<n>,
spring_force_<n>). A bare string is one component.
raw
Escape hatch for non-canonical OpenSees tokens (e.g. a
custom recorder response). Bypasses canonical validation.
pg / label / selection / ids
Target selectors. ids= is mutually exclusive with the
named selectors. Resolution against FEMData happens at
emit time (commit 3).
dt / n_steps
Recording cadence. At most one may be set; both None
records every step.
name
Optional user-supplied name for this record; auto-generated
when None.
n_modes
Required for category="modal"; rejected for other
categories.
element_class_name
Optional OpenSees C++ class name override for element-level
records. Used by the .out transcoder to disambiguate
elements that share a flat response size (e.g. tri31 vs
SSPquad). Carried from the legacy Recorders.elements
contract.
RecorderDeclaration
dataclass
¶
RecorderDeclaration(*, records: tuple[RecorderRecord, ...], name: str = 'default', ndm: int = 3, ndf: int = 6, file_root: str = '.')
Bases: Recorder
A bundle of recorder records, registered as a single Primitive.
Captures the bridge's ndm and ndf at construction time
(Phase 9 D8 — implicit source-of-truth binding). Drives the
file-emit path via :func:emit_recorder_spec in
:mod:apeGmsh.opensees._internal.build.
Parameters¶
records
Tuple of :class:RecorderRecord entries. Each is one
category-level declaration; emit fans them out into one or
more concrete OpenSees recorder commands.
name
Identifier for this declaration (defaults to "default").
Multiple named declarations can coexist on one bridge.
ndm, ndf
Snapshot of the bridge's ndm/ndf at construction time.
Used downstream for shorthand expansion and validation. The
bridge passes these in (Phase 9 D8 — user never repeats
ops.model(ndm=, ndf=) values).
file_root
Directory prefix for emitted .out files. Each record fans
out to <file_root>/<decl.name>__<record_name>__<token>.out.
Defaults to "." (current working directory).
build_recorder_declaration ¶
build_recorder_declaration(*, ndm: int, ndf: int, nodes: 'Iterable[str] | str' = (), elements: 'Iterable[str] | str' = (), line_stations: 'Iterable[str] | str' = (), gauss: 'Iterable[str] | str' = (), raw_nodes: 'Iterable[str] | str | None' = None, raw_elements: 'Iterable[str] | str | None' = None, raw_line_stations: 'Iterable[str] | str | None' = None, raw_gauss: 'Iterable[str] | str | None' = None, pg: 'str | Iterable[str] | None' = None, label: 'str | Iterable[str] | None' = None, selection: 'str | Iterable[str] | None' = None, ids: 'Iterable[int] | None' = None, dt: float | None = None, n_steps: int | None = None, name: str = 'default', record_name: str | None = None, element_class_name: str | None = None, file_root: str = '.') -> RecorderDeclaration
Construct a :class:RecorderDeclaration from declarative kwargs.
Single source of truth for shorthand expansion ("displacement"
→ displacement_x/y/z via the bound ndm/ndf) and
per-category record construction. Shared by
:meth:apeGmsh.opensees._internal.ns.recorder._RecorderNS.declare
(bridge-owned models) and
:meth:apeGmsh.opensees.ModelData.recorders (hand-written decks).
ndm / ndf are supplied by the caller (the bridge or
ModelData binds them at declaration time, Phase 9 D8 — the user
never repeats ndm=/ndf= here).
Source code in src/apeGmsh/opensees/recorder.py
1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 | |
Building tables¶
Story forces, story drifts, pier forces and story masses (the ETABS
Story Forces, Story Drifts, Pier Forces and Mass Summary by
Story tables), read in-process from the live domain. The extractor
classes are callables extractor(ops) -> ndarray with a labels
tuple, so a modal driver can evaluate them at each mode.
apeGmsh.opensees.building ¶
Story and pier aggregation on the live OpenSees domain.
The building tables an ETABS model reports — Story Forces, Story
Drifts, Pier Forces and Mass Summary by Story / Centers of Mass —
computed in-process from the domain the bridge built
(:func:~apeGmsh.opensees.emitter.live.get_ops, or an explicit ops=).
Every quantity is read from the current domain state, so the same object serves a static case, the gravity state of a P-Delta run, and each mode of a response-spectrum analysis.
Extractors¶
:class:StoryForces, :class:StoryDrifts and :class:PierForces are
extractors: callables extractor(ops) -> ndarray of a fixed length,
with a matching labels tuple (the :class:Extractor protocol). The
domain is scanned once, at construction (node coordinates, element
connectivity, the elements and nodes each cut needs, the checks below);
a call only reads element forces and node displacements for those, both
at the trial state (eleForce is the trial resisting force; a
displacement is nodeDisp, the committed value, plus nodeResponse
IncrDisp, trial minus committed). After a committed solve the two
states agree; an uncommitted trial state, such as gravity plus one mode
left by responseSpectrumAnalysis -increment, is read as is. A modal driver
evaluates an extractor at each mode and combines each entry of the
vector across modes; :meth:StoryForces.table (and the other table
methods) reshapes any such vector, combined or not, into a
:class:StoryTable. The plain functions :func:story_forces,
:func:story_drifts, :func:pier_forces and :func:story_masses are
the one-off forms.
The free body¶
A story or pier force is the resultant the part above a horizontal cut
transmits to the part below. The cut is node-aligned: it runs through
the nodes at the cut elevation, and an element belongs to the part above
when all its nodes are at or above the cut and it does not lie in the
cut plane. Elements in the plane (the floor slab, the level's beams)
belong to the part below; nodal loads on cut nodes act on the part below.
eleForce (the forces response: Element::getResistingForce, the
global nodal force vector the integrator assembles, element loads
included) of the elements above that touch the cut gives, at each cut
node, the force the node applies to them; the force they transmit is its
negative. Hence, for a structure loaded only above the cut,
``(VX, VY, P) = sum of the loads applied above the cut``
exactly (to solver round-off), and at the base it equals -sum(R)
(:func:base_shear_from_reactions). Negate the six components for the
reaction convention. The top of a story (location="top") is the cut
just below a level, read from the elements below it that touch the level.
Refusals¶
- an element whose nodes lie strictly on both sides of a cut (the cut is not node-aligned there);
- an MP constraint (rigid link, equalDOF, ...) joining a node of the part above to a node of the part below: it carries force past the elements, so the element free body would miss it;
- any EQ constraint in the domain (
equationConstraint, the fork'sLadrunoTie): OpenSees does not report their nodes, so whether one crosses a cut cannot be checked. The count comes from aprintModeldump to a temporary file, which :class:StoryForceswrites once, at construction, never per call. It costs about 30 µs per node and element on a fresh domain, and up to ~150 µs onceeigenhas run, becauseNode::Printthen writes every eigenvector (16.6 s and 42 MB for 10k shells aftereigen(50)): build the extractor beforeeigen, once, and evaluate it at every mode; - in :class:
StoryDriftsjoint mode, a node on a level with no node at the same plan position on the level below (a cantilever tip, a transfer level, an offset column), named; dropping it would hide its drift; - an element whose
forcesvector is not one value per DOF of its nodes (eleTypeis named); - nodes with an
ndfother than 3 or 6, and 2-D models.
Code checks¶
The tables carry what an ASCE 7 check reads; naming columns is the
caller's. AvgX / AvgY are the ASCE 7-22 average of the signed
values at the two ends of the structure (Table 12.3-1, Types 1a/1b;
delta_avg of Eq. 12.8-14), |d_A + d_B| / 2, the ends being the
entries farthest apart across the direction (:func:_max_avg). It is not
a mean over every joint, so the max/avg ratio and Ax do not move with
the mesh. For example, apeETABS's TorsionCheck drifts frame::
t = drifts.story_max(combined).to_frame().rename_axis("Story").reset_index()
h = dict(zip(drifts.stories, drifts.heights))
t["Elevation"] = list(drifts.levels[1:])
t["drift_max"] = t["DriftX"] * t["Story"].map(h)
t["drift_avg"] = t["AvgX"] * t["Story"].map(h)
and its displacements frame (for Ax) is StoryDisplacements.story_max()
with MaxX, AvgX renamed Maximum, Average.
Extractor ¶
Bases: Protocol
A live quantity: extractor(ops) returns a 1-D float64 array
of len(labels) entries, read from the current domain state.
StoryTable
dataclass
¶
StoryForces ¶
StoryForces(levels: Sequence[float], *, names: Sequence[str] | None = None, location: Literal['bottom', 'top'] = 'bottom', reference: tuple[float, float] = (0.0, 0.0), ops: ModuleType | None = None, tol: float | None = None)
Story shear and overturning per story, as an :class:Extractor.
Parameters¶
levels
Level elevations, strictly increasing, the base first. Story i
(i = 1..n) spans levels[i-1] to levels[i] and is named
after its top level.
names
One name per level (default "Base", "Story1", ...).
location
"bottom" (default): the cut just above levels[i-1], the
resultant of every load above that level. "top": the cut just
below levels[i], the resultant of every load at or above it.
reference
Plan point (x, y) the moments are taken about, at each cut's
elevation (default the origin). MZ is the story torsion.
ops
The OpenSees module; default :func:~apeGmsh.opensees.emitter.live.get_ops.
tol
Elevation tolerance; default 1e-6 of the model's size.
A call returns [VX, VY, P, MX, MY, MZ] per story, stories in level
order (labels names each entry "<story>:<component>").
Construction checks the domain for EQ constraints with one
printModel dump (see Refusals); a call does not repeat it. Build
the extractor before eigen (the dump then omits eigenvectors) and
evaluate the same object at every mode.
Source code in src/apeGmsh/opensees/building.py
table ¶
values (a call's vector, or any combination of them) as a
story × component table; evaluates now when values is None.
Source code in src/apeGmsh/opensees/building.py
StoryDrifts ¶
StoryDrifts(levels: Sequence[float], *, points: Sequence[tuple[float, float]] | None = None, names: Sequence[str] | None = None, method: Literal['nearest', 'rigid'] = 'nearest', max_offset: float | None = None, ops: ModuleType | None = None, tol: float | None = None)
Interstory drift ratios (u_top - u_bottom) / h, as an :class:Extractor.
Parameters¶
levels, names, ops, tol
As :class:StoryForces.
points
Plan points (x, y) to report. None (default) reports every
joint: each node at a level that has a node at the same plan
position (within tol) on the level below — ETABS Joint
Drifts, whose maximum per story (:meth:story_max) is ETABS
Story Drifts. A node on a level above the base with no node at
its plan position on the level below raises, named (its drift
would otherwise be left out).
method
How a point reads a level's displacement. "nearest": the
nearest node of the level in plan, which must lie within
max_offset (default tol). "rigid": the least-squares
in-plane rigid motion (ux, uy, rz) of all the level's nodes,
evaluated at the point (exact for a rigid diaphragm).
A call returns [DX, DY] per entry, entries per story in level
order; labels reads "<story>:<node>:DX" (joints) or
"<story>:P<j>:DX" (points). Displacements are the trial
displacements (see the module notes).
Source code in src/apeGmsh/opensees/building.py
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 709 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 | |
table ¶
Every entry as a row ("<story>:<node|P<j>>"), columns DX, DY.
Source code in src/apeGmsh/opensees/building.py
story_max ¶
The largest |DX| and |DY| of each story (ETABS Story
Drifts), and beside them AvgX, AvgY: the ASCE 7 average of
the signed story drifts at the two ends of the structure,
|d_A + d_B| / 2 (:func:_max_avg), the denominator of the
Table 12.3-1 torsional irregularity ratio. For a modal combination,
pass the combined vector: the maximum of the combined joint drifts,
not the combination of maxima.
Source code in src/apeGmsh/opensees/building.py
StoryDisplacements ¶
StoryDisplacements(levels: Sequence[float], *, points: Sequence[tuple[float, float]] | None = None, names: Sequence[str] | None = None, method: Literal['nearest', 'rigid'] = 'nearest', max_offset: float | None = None, ops: ModuleType | None = None, tol: float | None = None)
Level displacements UX, UY, as an :class:Extractor.
Every node on each level above the base (points=None), or the
given plan points read as :class:StoryDrifts reads them (method,
max_offset). :meth:story_max gives each level's largest
|UX|, |UY| and the ASCE 7 average of the signed values at the
two ends, |d_A + d_B| / 2: the input of a torsional-irregularity or
torsional-amplification check. labels read "<story>:<node>:UX"
or "<story>:P<j>:UX"; the other parameters are as for
:class:StoryDrifts.
Source code in src/apeGmsh/opensees/building.py
table ¶
Every entry as a row ("<story>:<node|P<j>>"), columns UX, UY.
Source code in src/apeGmsh/opensees/building.py
story_max ¶
Per level MaxX, MaxY, AvgX, AvgY: the largest |UX|,
|UY| over its entries, and the ASCE 7 average of the signed
displacements at the two ends of the structure, |d_A + d_B| / 2
(:func:_max_avg; delta_avg of Eq. 12.8-14). Pass a combined
vector for a modal combination.
Source code in src/apeGmsh/opensees/building.py
Pier
dataclass
¶
Pier(name: str, elements: tuple[int, ...], bottom: float | None = None, top: float | None = None, axis2: tuple[float, float] | None = None)
A wall pier: OpenSees element tags between two node-aligned cuts.
bottom / top default to the lowest / highest node of the
elements. axis2 is the plan direction of the pier's length (local
axis 2); by default the principal direction of the bottom cut's nodes,
oriented toward +X (+Y when it runs along Y). Axis 1 is +Z and axis
3 = axis 1 × axis 2.
from_pg
classmethod
¶
from_pg(bridge: 'apeSees', pg: str, *, name: str | None = None, bottom: float | None = None, top: float | None = None, axis2: tuple[float, float] | None = None) -> 'Pier'
The pier of physical group pg's elements in bridge.
FEM element ids map to OpenSees tags directly under
element_tags="fem"; otherwise through the bridge's live read
session (after a live analyze), which raises when there is none.
Source code in src/apeGmsh/opensees/building.py
PierForces ¶
Pier forces at the bottom and top of each pier, as an :class:Extractor.
P, V2, V3, T, M2, M3 in pier local axes (axis 1 up, axis 2 along
the pier in plan, axis 3 = 1 × 2), moments about the centroid of the
pier section at the cut (the length-weighted centroid of the element
edges on the cut, which assumes a uniform thickness). Both cuts give
the force the part above transmits to the part below, so P is
negative in compression and, under a lateral load H along axis 2 at
height L above the cut, V2 = H and M3 = H L.
A call returns, per pier, the bottom row then the top row; labels
reads "<pier>:bottom:P".
Source code in src/apeGmsh/opensees/building.py
centroids ¶
Each cut's section centroid (x, y, z): rows "<pier>:bottom|top".
Source code in src/apeGmsh/opensees/building.py
axes ¶
The (3, 3) local axes of pier name, rows axis 1, 2, 3.
table ¶
Rows "<pier>:bottom|top", columns P, V2, V3, T, M2, M3.
Source code in src/apeGmsh/opensees/building.py
story_forces ¶
story_forces(levels: Sequence[float], *, names: Sequence[str] | None = None, location: Literal['bottom', 'top'] = 'bottom', reference: tuple[float, float] = (0.0, 0.0), ops: ModuleType | None = None, tol: float | None = None) -> StoryTable
One-off :class:StoryForces table at the current domain state.
Source code in src/apeGmsh/opensees/building.py
base_shear_from_reactions ¶
base_shear_from_reactions(z_base: float, *, reference: tuple[float, float] = (0.0, 0.0), ops: ModuleType | None = None, tol: float | None = None) -> FloatArray
-sum(R) over the nodes at or below z_base, as
[VX, VY, P, MX, MY, MZ] about (reference, z_base).
The cross-check of the base story's :class:StoryForces row: the two
agree when no load is applied at or below the base. Calls
ops.reactions().
Source code in src/apeGmsh/opensees/building.py
story_drifts ¶
story_drifts(levels: Sequence[float], *, points: Sequence[tuple[float, float]] | None = None, names: Sequence[str] | None = None, method: Literal['nearest', 'rigid'] = 'nearest', max_offset: float | None = None, ops: ModuleType | None = None, tol: float | None = None) -> StoryTable
One-off drift table: the story maximum over every joint
(points=None), else one row per story and point.
Source code in src/apeGmsh/opensees/building.py
piers_by_story ¶
piers_by_story(pier: Pier, levels: Sequence[float], *, names: Sequence[str] | None = None, ops: ModuleType | None = None, tol: float | None = None) -> tuple[Pier, ...]
Split pier (one PG over many stories) into one pier per story.
Each story's pier holds the elements between its two levels and is
named "<pier>/<story>"; a story with none is left out. An element
that crosses a level raises.
Source code in src/apeGmsh/opensees/building.py
pier_forces ¶
pier_forces(piers: Sequence[Pier], *, ops: ModuleType | None = None, tol: float | None = None) -> StoryTable
One-off :class:PierForces table at the current domain state.
Source code in src/apeGmsh/opensees/building.py
story_masses ¶
story_masses(levels: Sequence[float], *, names: Sequence[str] | None = None, include_elements: bool = True, ops: ModuleType | None = None, tol: float | None = None) -> StoryTable
Translational mass and center of mass per level (ETABS Mass Summary by Story / Centers of Mass).
Rows are the level names (the base first); columns MassX, MassY,
MassZ, XCM, YCM. A node's mass is the nodal mass (nodeMass)
plus, with include_elements, what the elements lump to it (see
:func:_element_translational_mass: element rho, frame mass per
length, shell rho * h, whatever the build defines). A node on a
level goes to that level; a node between two levels is split between
them linearly in height (a lumped story element's mass goes half to
each level); a node at or below the base goes to the base row, one
above the top level to the top row. XCM, YCM weigh the horizontal
mass (MassX + MassY) / 2. modalProperties counts only free
DOFs, so with a fixed base its total mass is the sum of the rows above
the base.
Source code in src/apeGmsh/opensees/building.py
1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 | |
levels_from_pgs ¶
levels_from_pgs(fem: 'FEMData', pgs: Sequence[str], *, tol: float | None = None) -> tuple[float, ...]
The elevation of each physical group in pgs (one per level).
Every node of a group must lie at one elevation within tol
(default 1e-6 of the model's size); the result keeps pgs's
order, which must be strictly increasing.
Source code in src/apeGmsh/opensees/building.py
Numberer¶
apeGmsh.mesh._numberer.Numberer ¶
Renumbers a FEM mesh for solver consumption.
Parameters¶
fem_data : dict
Output of Mesh.get_fem_data(). Must contain:
node_tags, node_coords, elem_tags,
connectivity, used_tags.
Source code in src/apeGmsh/mesh/_numberer.py
renumber ¶
Produce a solver-ready mesh with contiguous IDs.
Parameters¶
method : "simple" or "rcm"
"simple" — preserves relative order, just makes IDs
contiguous. Fast, no optimisation.
``"rcm"`` — Reverse Cuthill-McKee bandwidth minimisation.
Reorders nodes so that the assembled stiffness matrix has
minimal bandwidth. Recommended for direct solvers.
int
Starting ID (default 1 = Fortran/OpenSees convention; use 0 for C/Python convention).
bool
If True (default), only include nodes that appear in at least one element (skip orphan nodes). Set False to include all nodes from the mesh.
Returns¶
NumberedMesh
Source code in src/apeGmsh/mesh/_numberer.py
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 | |
apeGmsh.mesh._numberer.NumberedMesh
dataclass
¶
NumberedMesh(node_ids: ndarray, node_coords: ndarray, elem_ids: ndarray, connectivity: ndarray, n_nodes: int = 0, n_elems: int = 0, bandwidth: int = 0, method: str = 'simple', gmsh_to_solver_node: dict[int, int] = dict(), solver_to_gmsh_node: dict[int, int] = dict(), gmsh_to_solver_elem: dict[int, int] = dict(), solver_to_gmsh_elem: dict[int, int] = dict())
Solver-ready mesh with contiguous IDs and bidirectional maps.
All IDs are 1-based (the standard in structural FEM solvers
like OpenSees, Abaqus, SAP2000). Set base=0 in
:meth:Numberer.renumber for 0-based if your solver needs it.
Attributes¶
node_ids : ndarray(N,)
New contiguous node IDs.
node_coords : ndarray(N, 3)
Nodal coordinates, same order as node_ids.
elem_ids : ndarray(E,)
New contiguous element IDs.
connectivity : ndarray(E, npe)
Element connectivity in terms of new node IDs.
n_nodes : int
n_elems : int
bandwidth : int
Semi-bandwidth of the resulting adjacency.
method : str
Numbering method used ("simple" or "rcm").
Maps ~~~~ gmsh_to_solver_node : dict[int, int] Gmsh node tag -> solver node ID. solver_to_gmsh_node : dict[int, int] Solver node ID -> Gmsh node tag. gmsh_to_solver_elem : dict[int, int] Gmsh element tag -> solver element ID. solver_to_gmsh_elem : dict[int, int] Solver element ID -> Gmsh element tag.