Evaluate footfall vibration¶
Check a floor or footbridge against walking-induced vibration — AISC Design Guide 11, 2nd edition, Chapter 7. Reach for this once you have a modal model (see Run a modal analysis) and want to know whether people walking on it will feel it.
The bay¶
One steel floor beam, simply supported, with the tributary floor mass spread along the span as distributed element mass — not lumped at one point — small enough to run in seconds, large enough to show a real pass/fail with a modal basis that actually covers the Guide's 20 Hz band.
Left (pin) Quarter Midspan Right (roller)
o───────────────────────o───────────────────o───────────────────o
|<---------- 6 m span (one bay) ------------------------------->|
Section: composite steel beam, Iz = 3.5e-4 m^4 (bare steel ~1.2e-4,
boosted for composite action with the slab — see below)
Mass: 500 kg/m distributed (the bay's tributary floor mass per unit
length: slab + ceiling + partitions + a share of live load) —
puts the first mode at ~16 Hz, a sensible occupied-floor
frequency, and the second at ~65 Hz, comfortably clear of the
20 Hz band the Guide's Eq 7-5 sum runs over.
from apeGmsh import apeGmsh
from apeGmsh.opensees import apeSees
from apeGmsh.results.user import UserFile
L, E, Iz, A = 6.0, 200e9, 3.5e-4, 0.0083 # SI: m, Pa, m^4, m^2
mass_per_len = 500.0 # distributed floor mass, kg/m
with apeGmsh(model_name="footfall-bay") as g:
p0 = g.model.geometry.add_point(0.0, 0.0, 0.0)
pq = g.model.geometry.add_point(L / 4, 0.0, 0.0)
pm = g.model.geometry.add_point(L / 2, 0.0, 0.0)
p1 = g.model.geometry.add_point(L, 0.0, 0.0)
l0 = g.model.geometry.add_line(p0, pq)
l1 = g.model.geometry.add_line(pq, pm)
l2 = g.model.geometry.add_line(pm, p1)
g.model.sync()
g.physical.add(1, [l0, l1, l2], name="Beam")
g.physical.add(0, [p0], name="Left")
g.physical.add(0, [p1], name="Right")
g.physical.add(0, [pq], name="Quarter")
g.physical.add(0, [pm], name="Midspan")
g.mesh.sizing.set_global_size(L / 12.0) # L/8 or finer — 12 here
g.mesh.generation.generate(1)
fem = g.mesh.queries.get_fem_data(dim=1)
ops = apeSees(fem)
ops.model(ndm=2, ndf=3)
transf = ops.geomTransf.Linear()
ops.element.elasticBeamColumn(
pg="Beam", transf=transf, A=A, E=E, Iz=Iz, mass=mass_per_len,
) # lumped element mass by default — do not pass c_mass=True (see below)
ops.fix(pg="Left", dofs=(1, 1, 0))
ops.fix(pg="Right", dofs=(0, 1, 0))
midspan = ops.nodes.get(pg="Midspan")
quarter = ops.nodes.get(pg="Quarter")
result = ops.footfall_walking(
num_modes=2, # highest extracted mode (~65 Hz) clears f_max=20 Hz
body_weight=747.0, # Q = 168 lb (the Guide's recommended walker weight)
g=9.81,
response_nodes=midspan,
dof=2, # vertical translation in this 2-D frame
occupancy="office",
damp=0.03, # must be > 0 — an undamped FRF has no finite
# resonant peak, and the driver refuses it
)
print(result.f_dom, result.a_p, result.regime, result.limit, result.ratio)
# -> [16.326] [0.012007] ['high'] [0.010204] [1.177]
ops.h5("footfall_bay.h5") # the model archive
result.to_results(fem, "footfall_bay.user.h5", model_h5="footfall_bay.h5")
UserFile("footfall_bay.user.h5").read_result("footfall")
That prints a dominant frequency of 16.33 Hz, a governing acceleration of 1.20 %g, and a ratio of 1.177 against the office limit — this bay fails, and by enough that stiffening the section or adding damping is worth considering. Here is what each part is doing.
Modelling the bay (§7.2)¶
The Guide asks for the floor's actual in-place mass (not a code live
load) and a composite-boosted stiffness — cracked-section bending
underestimates how stiff a slab-on-beam floor really is, so §7.2 has you
transform the slab into the beam at 1.35 Ec and use the resulting
composite I. Here that shows up as a single number: Iz = 3.5e-4 m^4
against a bare-steel 1.2e-4 m^4 — do the transformed-section calc for
your own beam and section.
num_modes and the 20 Hz warning¶
footfall_walking builds its own live domain and issues one eigen +
modalProperties pair for num_modes modes — it does not need a prior
ops.analyze() call. The high-frequency branch (Eq 7-4…7-6) sums over
every mode up to f_max (20 Hz by default), so a basis that stops
short warns. Drop the worked example above to num_modes=1 and the
highest (and only) extracted mode is 16.33 Hz, still under f_max=20.0:
UserWarning: apeSees.footfall_walking: the highest extracted mode is
16.326 Hz, below f_max=20.0 Hz — the Eq 7-5 impulse sum is missing modes
it should carry. Raise num_modes, or on the fork use eigen_feast(...) to
get the band exactly.
That basis is genuinely short: the Eq 7-5 sum needs every mode up to
20 Hz, and this beam's second mode (~65 Hz) sits well outside it — so the
sum evaluated with num_modes=1 is missing a real contribution, not a
spurious one. num_modes=2 (used above) clears the warning because its
highest extracted mode is already past f_max. On a real floor, raise
num_modes until the basis covers 20 Hz, or use the fork's band solve
(eigen_feast) to get it exactly.
footfall_walking defaults to solver="-genBandArpack"; leave it at the
default here. On this build -genBandArpack returns unit-modal-mass
eigenvectors under both lumped and consistent element mass, while
-fullGenLapack does not under consistent mass and is correctly refused
by the ADR 0109 D2 eigenvector-scale check.
body_weight and g¶
Both are required, in the model's own units — apeGmsh has no unit
system, and a silently wrong g is a factor of 386 in the answer. The
Guide's recommended walker weight is Q = 168 lb ≈ 747 N; this model is
SI, so body_weight=747.0, g=9.81. In kip-inch units you'd pass
body_weight=0.168, g=386.1 instead — same walker, different numbers.
excitation="self" vs "full"¶
"self" (the default) evaluates the diagonal: the walker stands exactly
where the occupant sits — the Guide's conservative default, both at
mid-bay. "full" checks every excitation/response pair and reports which
walker governs:
full = ops.footfall_walking(
num_modes=2, body_weight=747.0, g=9.81,
response_nodes=midspan, excitation="full",
excitation_nodes=(*midspan, *quarter),
dof=2, occupancy="office", damp=0.03,
)
full.exc_node # -> [3] — Midspan itself, not Quarter
Here the occupant's own position still governs even under "full",
because this bay's dominant mode shape peaks at midspan — the walker
standing anywhere else excites it less. On a floor where a different mode
dominates at a different response node, a different excitation node can
win, and exc_node tells you which.
Reading the result¶
Per response node, result.a_p is the governing acceleration (the larger
of a_p_lf, Eq 7-1, and a_espa_hf, Eq 7-4…7-6) as a fraction of g,
result.regime says which branch produced it ("low" / "high" /
"both"), and result.ratio = a_p / limit is the demand/capacity check —
below 1 is acceptable. result.limit is read at f_dom on the Fig 2-1
curve by default (limit="curve"), which is why it comes out at 1.02 %g
here rather than the flat 0.5 %g office value: the curve rises above 8 Hz,
and this bay's dominant frequency (16.33 Hz) sits well into that rise.
Saving the ratio map¶
to_results writes the evaluation into the model's user-results file,
<stem>.user.h5 (ADR 0131 D6). It is one state-free user result named
"footfall" on the nodes: it belongs to no stage, mode or combination,
like any design check (ADR 0130 D7). It holds three components, footfall_ap (fraction of g),
footfall_ratio and footfall_fdom (Hz), over every node in fem, with
NaN outside the response nodes:
ops.h5("footfall_bay.h5")
result.to_results(fem, "footfall_bay.user.h5", model_h5="footfall_bay.h5")
user = UserFile("footfall_bay.user.h5")
footfall = user.read_result("footfall")
footfall.components # ('footfall_ap', 'footfall_ratio', 'footfall_fdom')
footfall.data.shape # (1, 13, 3): one row, every node, three components
footfall.data[0, :, 1] # the ratio: 1.177 at Midspan, NaN elsewhere
footfall.ids # the node tags, in fem.nodes.ids order
model_h5 is required. It is the model archive of the same fem
(ops.h5(...) or fem.to_h5(...)), and its /meta/lineage pairs the
user file with that model; an archive of any other fem is refused. The
file name must end in .user.h5. If the file already exists, the
"footfall" entry is added or replaced and every other entry is kept,
so footfall sits beside the set's combinations and design checks.
/meta@writer records the driver and the OpenSees build the modal basis
ran on.
On a real floor with many response nodes, this file turns a table of
per-node ratios into a map: red where the floor fails, green where it
does not. apeGmshViewer draws it. Open the model; the Contour card lists
footfall under User Results, and picking it colours the mesh by one
of its three columns. Nodes outside the response set are drawn as no data
(grey). The map is a contour only: the Deformed card is refused while it
is shown. If the user file no longer pairs with the model (another
fem_hash), the contour is refused with that reason.
A still of the map comes from the app's --render, with
apeGmsh.agent_view.render_stills. A user result belongs to no stage, so
the shot names none:
from apeGmsh.agent_view import render_stills
render_stills({
"spec": "apegmsh-view/1",
"files": {"model": "footfall_bay.h5"},
"shots": [{"name": "footfall_ratio", "camera": "top", "chrome": "model",
"contour": {"field": "footfall", "component": "footfall_ratio",
"source": "user"}}],
}, "stills")
The worked two-bay slab
writes its footfall_ratio.png this way. It falls back to matplotlib only
when no viewer is installed.
Why the 2nd edition, not Robot¶
Robot's own Footfall case is built on the Design Guide's 1st
edition — resonant-only under its AISC option, with no equivalent to the
high-frequency effective-impulse branch this driver evaluates as
a_espa_hf; ADR 0109 has the full comparison.
See also¶
- Example: Modal analysis of a cantilever — mass,
eigen, and reading modes back, the ingredients this recipe builds on. - ADR:
architecture/decisions/0109-footfall-vibration-frf-method.md— the FRF method, the eigenvector-scale assertion, and why Robot isn't the oracle. - API:
apeGmsh.opensees.apeSees.footfall_walking,apeGmsh.opensees.analysis.footfall_result.FootfallResult.