E9 — Compose modules¶
Up to now every model was built in a single session: open apeGmsh,
draw the geometry, mesh, solve. That's the right shape for one structure.
But real buildings repeat — the same bay, the same column, the same
prefabricated unit, stamped out many times. You don't want to re-draw and
re-mesh it on every copy. You want to build the piece once, save it,
and place copies of it into a larger model.
That's compose. You save a meshed module, with its elements, to a
model.h5, then an Assembly places it as many times as you like —
tag-offset and namespaced, no re-meshing. In this example we build the
portal frame from E1 as a module, place it as two
bays, push each bay with the same 60 kN lateral load, and check that
each bay drifts exactly the E1 amount, 8.39 mm — because the assembly
leaves the bays independent. That self-consistency is the whole proof: a
placed copy behaves identically to the standalone original.
The problem¶
bay 1 ("bay1." prefix) bay 2 ("bay2." prefix)
P ──►●═══════════● P ──►●═══════════●
║ ║ ║ ║
║ columns ║ beam ║ ║ H = 5 m
║ ║ ║ ║
██╨██ ██╨██ ██╨██ ██╨██
Fixed Fixed Fixed Fixed
└──── 5 m ────┘ ← 10 m gap → └──── 5 m ────┘
Module: the E1 portal — columns 0.22×0.22, beam 0.20×0.50, steel E = 200 GPa
Each bay: lateral P = 60 kN + gravity W = 300 kN at the roof joints
Bays are 10 m apart and NOT tied → mechanically independent
What we expect, stated up front:
Per-bay drift. Each bay is the E1 portal, loaded exactly as in E1. So each bay's roof should drift the same 8.39 mm E1 produced — and the two bays should agree with each other to round-off. If composing changed the physics, this is where it would show.
Per-bay base shear. Each bay's two column bases must between them react
that bay's 60 kN lateral load — −60 000 N, exactly. Two separate static
equilibrium checks, one per bay, both to the last digit.
Units
Consistent SI throughout — metres, newtons, pascals. Drift comes out in metres; we print millimetres.
The whole script¶
Read it once top to bottom, then we'll walk the three new moves: save a module, place it twice, and address each copy by its prefixed name.
import tempfile, os
from apeGmsh import apeGmsh
from apeGmsh.assembly import Assembly
from apeGmsh.opensees import apeSees
from apeGmsh.opensees.emitter.live import get_ops
from apeGmsh.results.spec import ResolvedRecorderRecord, ResolvedRecorderSpec
# --- Problem data (consistent SI: m, N, Pa) — the E1 portal ---
H, B, E = 5.0, 5.0, 200e9
bc, hc = 0.22, 0.22; Ac = bc * hc; Ic = bc * hc**3 / 12.0 # columns
bb, hb = 0.20, 0.50; Ab = bb * hb; Ib = bb * hb**3 / 12.0 # beam
P, W = 60_000.0, 300_000.0 # lateral + gravity
work = tempfile.mkdtemp()
module = os.path.join(work, "portal_module.h5") # the reusable part
assembly = os.path.join(work, "two_bay.h5") # the assembled model
run_path = os.path.join(work, "run") # the run (the route sets the suffix)
# --- 1. Build the portal MODULE once: mesh, groups and elements ---
with apeGmsh(model_name="portal_module") as g:
bl = g.model.geometry.add_point(0.0, 0.0, 0.0)
br = g.model.geometry.add_point(B, 0.0, 0.0)
tl = g.model.geometry.add_point(0.0, H, 0.0)
tr = g.model.geometry.add_point(B, H, 0.0)
col_l = g.model.geometry.add_line(bl, tl)
col_r = g.model.geometry.add_line(br, tr)
beam = g.model.geometry.add_line(tl, tr)
g.model.sync()
g.physical.add(1, [col_l, col_r], name="Columns")
g.physical.add(1, [beam], name="Beam")
g.physical.add(0, [bl, br], name="Base")
g.physical.add(0, [tl], name="RoofL")
g.physical.add(0, [tr], name="RoofR")
g.mesh.sizing.set_global_size(H / 6.0)
g.mesh.generation.generate(1)
fem = g.mesh.queries.get_fem_data(dim=None)
portal = apeSees(fem)
portal.model(ndm=2, ndf=3)
transf = portal.geomTransf.Linear()
portal.element.elasticBeamColumn(pg="Columns", transf=transf, A=Ac, E=E, Iz=Ic)
portal.element.elasticBeamColumn(pg="Beam", transf=transf, A=Ab, E=E, Iz=Ib)
portal.h5(module) # the module: one reusable file
# --- 2. Place the module twice: bay 2 sits 10 m to the right ---
asm = Assembly("two_bay")
asm.instance("bay1", module)
asm.instance("bay2", module, translate=(10.0, 0.0, 0.0))
ops = asm.bridge(ndm=2, ndf=3) # the elements arrive with each instance
# --- 3. Supports, loads and the analysis, on the bridge ---
for bay in ("bay1", "bay2"):
ops.fix(pg=f"{bay}.Base", dofs=(1, 1, 1))
ts = ops.timeSeries.Linear()
with ops.pattern.Plain(series=ts) as pat:
for bay in ("bay1", "bay2"):
pat.load(pg=f"{bay}.RoofL", forces=(P / 2.0, -W / 2.0, 0.0))
pat.load(pg=f"{bay}.RoofR", forces=(P / 2.0, -W / 2.0, 0.0))
ops.constraints.Plain()
ops.numberer.Plain()
ops.system.BandGeneral()
ops.test.NormDispIncr(tol=1e-10, max_iter=10)
ops.algorithm.Linear()
ops.integrator.LoadControl(dlam=1.0)
ops.analysis.Static()
asm.h5(assembly) # the assembled model.h5 + /assembly
# --- 4. Solve, recording each bay's roof drift AND base reactions ---
fem = ops.fem # the assembled snapshot: both bays, prefixed names
roofs = [f"{bay}.{pg}" for bay in ("bay1", "bay2") for pg in ("RoofL", "RoofR")]
bases = ["bay1.Base", "bay2.Base"]
spec = ResolvedRecorderSpec(
fem_snapshot_id=fem.snapshot_id,
records=(
ResolvedRecorderRecord(
category="nodes", name="roofs",
components=("displacement_x", "displacement_y"),
dt=None, n_steps=None, node_ids=fem.nodes.select(pg=roofs).ids,
),
ResolvedRecorderRecord(
category="nodes", name="bases",
components=("reaction_force_x", "reaction_force_y"),
dt=None, n_steps=None, node_ids=fem.nodes.select(pg=bases).ids,
),
),
)
ops.run()
opspy = get_ops()
with spec.emit_default(run_path, model_h5=assembly) as run:
opspy.analyze(1)
# --- 5. Read each bay's drift back, by name ---
results = run.results()
def drift(bay):
l = results.nodes.get(pg=f"{bay}.RoofL", component="displacement_x")
r = results.nodes.get(pg=f"{bay}.RoofR", component="displacement_x")
return 0.5 * (float(l.values[-1, 0]) + float(r.values[-1, 0]))
drift_bay1 = drift("bay1")
drift_bay2 = drift("bay2")
bx1 = results.nodes.get(pg="bay1.Base", component="reaction_force_x")
bx2 = results.nodes.get(pg="bay2.Base", component="reaction_force_x")
print(f"bay 1 drift = {drift_bay1*1e3:.4f} mm")
print(f"bay 2 drift = {drift_bay2*1e3:.4f} mm")
print(f"E1 standalone = 8.3883 mm")
print(f"bay1 vs bay2 = {abs(drift_bay1-drift_bay2)*1e3:.2e} mm")
print(f"bay 1 base shear = {float(bx1.values[-1, :].sum()):.1f} N")
print(f"bay 2 base shear = {float(bx2.values[-1, :].sum()):.1f} N")
Run it. You should see:
bay 1 drift = 8.3883 mm
bay 2 drift = 8.3883 mm
E1 standalone = 8.3883 mm
bay1 vs bay2 = 6.83e-12 mm
bay 1 base shear = -60000.0 N
bay 2 base shear = -60000.0 N
Both bays drift 8.3883 mm — the exact E1 number — and agree with each
other to 1e-11 mm. Each base shear is −60 000 N to the last digit. The
placed copies are mechanically indistinguishable from the standalone
portal. That's compose doing its job: it relocates and renames a module
without perturbing a single stiffness term.
Step 1 — Save a module with ops.h5¶
portal = apeSees(fem)
portal.model(ndm=2, ndf=3)
transf = portal.geomTransf.Linear()
portal.element.elasticBeamColumn(pg="Columns", transf=transf, A=Ac, E=E, Iz=Ic)
portal.element.elasticBeamColumn(pg="Beam", transf=transf, A=Ab, E=E, Iz=Ib)
portal.h5(module)
The geometry and mesh are E1's. What's new is where the session ends: the
meshed model goes to a bridge, the bridge gets the dimensions and the
elements, and portal.h5(module) writes it all — nodes, elements,
physical groups, the transform and the element specs — to a native
model.h5. That file is the module: a self-contained, reusable part you
can place any number of times, in this script or a different one next week.
Two things make a file a module. It must carry its model dimensions —
ops.model(ndm=2, ndf=3) — because the assembly checks them; a plain
g.save() file has none, and placing it is refused. And whatever it
declares on its groups travels with every copy: the columns and the beam
are declared once, here, and both bays get them. That's the "build
once" story all the way down to the element properties.
Every PG name you'll want to address later — "Columns", "Base",
"RoofL" — gets named here, exactly as in E1.
Step 2 — Place the module twice¶
asm = Assembly("two_bay")
asm.instance("bay1", module)
asm.instance("bay2", module, translate=(10.0, 0.0, 0.0))
ops = asm.bridge(ndm=2, ndf=3)
Three new calls.
Assembly("two_bay") starts an empty assembly. It draws nothing and
meshes nothing; it only records where each file goes.
asm.instance(label, module, ...) places one copy of the file. The
label is the copy's namespace prefix: every physical group the module
carries comes in renamed "{label}.{pg}" — so the first bay's columns are
"bay1.Columns", the second bay's base is "bay2.Base", and so on. Every
instance is namespaced the same way; there is no privileged first copy
with bare names. translate= rigidly shifts the copy; there's also
rotate=((ax, ay, az), theta), applied before the shift, and anchor=,
which places a copy at a port of an earlier instance.
asm.bridge(ndm=2, ndf=3) merges the instances into one model and
hands back an ordinary apeSees bridge, with each module's elements
already declared on its prefixed groups. From here on it is the bridge
you've used since E1.
If you want to see what's inside a module before placing it,
apeGmsh.from_h5(module).compose_inspect(module)["pg_inventory"] returns its
physical-group names without merging anything — here
('Base', 'Beam', 'Columns', 'RoofL', 'RoofR').
Compose does not weld coincident nodes
Placing an instance is a graft, not a merge. If two instances happen
to share a coordinate at an interface, they keep two separate
nodes — the copies stay mechanically independent unless you
explicitly tie them. In this example that independence is exactly what
we want (the bays are 10 m apart and uncoupled). To actually connect
adjacent copies — share a column line, bolt a bay to its neighbour — you
declare the join on the assembly before bridging, e.g.
asm.tie("bay1.face", "bay2.face") or
asm.equal_dof("bay1.joint", "bay2.joint", dofs=[1, 2, 3]). That's a
separate move; instance never couples anything.
Step 3 — Address each copy by its namespaced name¶
for bay in ("bay1", "bay2"):
ops.fix(pg=f"{bay}.Base", dofs=(1, 1, 1))
...
pat.load(pg=f"{bay}.RoofL", forces=(P / 2.0, -W / 2.0, 0.0))
This is the payoff of the namespacing. The two bays are the same module,
so they'd have name-collided if the assembly hadn't prefixed them. Because
every copy is prefixed, every selector stays unambiguous: pg="bay1.Base"
is bay 1's base, pg="bay2.Base" is bay 2's. You declare each bay's
fixities and loads with the same names you'd use for a standalone
portal, just with the instance label in front — which is why a loop over
the labels does it all.
Supports, loads and the analysis are declared here, on the bridge, not
in the module. A module carries its model — mesh, groups, elements; the
assembly decides how the whole thing is held and pushed. (The bridge
auto-emits MP constraints, while g.loads cases are opt-in — import each
into a Plain pattern with p.from_model("<case>"); fixities are declared
explicitly here.)
asm.h5(assembly) then writes the assembled model: the same model.h5
the bridge's own ops.h5 writes, plus an /assembly zone that lists the
instances. apeGmsh.from_h5(assembly).compose_list() reads it back —
one record per bay, with its source file and its translate.
Step 4 — Read each bay back, by name¶
def drift(bay):
l = results.nodes.get(pg=f"{bay}.RoofL", component="displacement_x")
r = results.nodes.get(pg=f"{bay}.RoofR", component="displacement_x")
return 0.5 * (float(l.values[-1, 0]) + float(r.values[-1, 0]))
drift_bay1 = drift("bay1")
drift_bay2 = drift("bay2")
The read side is the same results.nodes.get(pg=..., component=...) you've
used since E1: run.results() opens the run, paired with the assembled
model.h5 that asm.h5(assembly) wrote, which is why the record and the
read can both name "bay1.RoofL". The only difference is which name you
ask for: the instance label in front of the group. One helper, two labels,
two bays.
See it¶
The deformed shape makes the independence obvious. We render it headless (matplotlib, no GPU) and look straight down the out-of-plane axis:
ax = results.plot.deformed(step=-1, scale=200)
ax.view_init(elev=90, azim=-90) # look down +z -> 2-D elevation
ax.figure.savefig("compose-two-bay.png", dpi=130, bbox_inches="tight")

Two portals, 10 m apart, each leaning right by the same amount — the E1 sway mode, stamped twice. Nothing crosses the gap: the bays deform as if the other weren't there, which is precisely why each drift lands on 8.39 mm.
For an interactive 3-D view in a notebook, reach for
results.show_web() — the kernel-safe web viewer. (Never call
results.viewer() in a notebook; its blocking VTK+Qt loop crashes the
kernel.) The composed viewer can even colour by source module
(set_mode('Module')) so each bay gets its own hue.
What you just learned¶
- Build once, save, reuse. A bridge with
ops.model(ndm=..., ndf=...)and its element specs, written withops.h5(path), is a reusable module. A plaing.save()file is not: it has no model dimensions. Assembly+instance+bridge. Place each copy withasm.instance(label, module, translate=...), thenasm.bridge(...)merges them, tag-offset and renamed, with their elements. No re-meshing.- Every instance is label-prefixed. Each copy's groups are
"{label}.{pg}"("bay1.Columns","bay2.Columns"). Address every part by that name from there on. - Compose grafts, it doesn't weld. Coincident nodes of different
instances stay separate — copies are independent until you join them on
the assembly (
tie/equal_dof/rigid_link/embedded). - The model travels, the analysis doesn't. Elements come with each instance; supports, loads and the analysis are declared on the bridge.
- Proof, not promise. Each bay drifts the exact E1 8.3883 mm and reacts its full 60 kN base shear — a placed copy is mechanically identical to the standalone original, to round-off.
Where next¶
- Portal frame — the E1 module this page stamps twice, if you want the walkthrough behind the 8.39 mm.
- Assemble saved models — the
full
Assemblyrecipe: rotation, ties, couplings, reference nodes and one MPI rank per instance. - Multi-part assembly — the in-session way to
reuse a member: build a column as a
Partand stamp it withg.parts.add(one gmsh kernel), versus the assembly's cross-sessionmodel.h5placing. - Tie non-matching meshes — when modules should connect: the interface constraint that the assembly deliberately leaves to you.
Next: E10 — Pushover of a steel moment frame (fiber sections).