What the model calculates

Frame Explorer is a transparent teaching and research prototype for comparing planar reinforced concrete frames under a common ground acceleration. It is intended to make assumptions, member forces, modal behaviour and the limits of a simplified nonlinear model inspectable.

Start with a controlled comparison

1. Choose a recorded earthquake and keep Original × factor = 1 to preserve its published ordinates.
2. Edit frame A and frame B independently. The initial example compares 3 and 8 storeys, each with two 5 m bays and 120 t tributary mass per floor.
3. Run the comparison. Both frames receive the same samples, scaling, time origin and free-response tail. The animation uses the same geometric scale and deformation magnification.
4. Click a column or beam to open Member details, or use that tab and its member list. The longitudinal view and cross-section show the selected reinforcement. Move section A–A along the member to inspect local N, M and V; use the member time slider or Go to peak |M| to inspect the saved history. Edit the open section fields and apply to the selected element or all members of its kind in that frame.
5. Open Frequencies & resonance. Compare the initial modes with the Fourier content and elastic oscillator response spectra.
6. For a single-frequency experiment, select Harmonic and Tune to A/B · f₁. For recorded motion, examine a frequency band and Sa at the modal periods instead of assuming one earthquake frequency.
7. Switch to nonlinear analysis only after reviewing the illustrative hinge and shear parameters. A run ends at its first defined strength or deformation limit.

Changing the storey count changes the height, total mass and number of structural members together. To isolate one influence, adjust the other parameters explicitly. “Shorter” does not automatically mean a smaller response to every record.

The longitudinal cage is a projection of the two bending-face bar rows; the cross-section shows their actual bar counts. Extra stirrup legs are drawn schematically. Cover is measured to the outside of the stirrup. Ties use the entered spacing along the member; anchorage, laps and joint reinforcement are not specified. Changing reinforcement updates the nominal N–M envelope; initial stiffness uses the separately entered effective EI factor. The peak-member button searches saved samples and includes the beam interior stationary moment; its time can differ slightly from an internal-step envelope maximum.

1. Planar frame and gravity state

Each floor has one horizontal translation shared by its joints. Each above-ground joint also has its own vertical translation and rotation. The latter degrees of freedom have zero assigned inertia and satisfy equilibrium at each time step. All bases are fixed. Members are Euler–Bernoulli elements with elastic axial response; beam flexibility and joint rotations participate in the frame solution.

Supported geometry: 1–12 storeys, 1–3 equal bays, 2–12 m spans and 2–6 m storey heights. Storey masses and heights can be overridden separately. Column and beam sections can be overridden member by member. This is one planar frame, so enter its tributary floor mass, not an unrelated whole-building mass.

Gravity load on each floor is m × g × gravity factor, distributed uniformly across the beams. Its consistent end loads are included in a linear gravity analysis. Subsequent N–M–V values include this gravity state. Member self-weight is not added separately; include it in the floor masses/loading assumption. The nonlinear analysis rejects a gravity state already outside the assumed initial elastic/yield range.

The model does not include slab shell action, diaphragm flexibility in its plane, torsion, foundations, soil–structure interaction, vertical ground excitation, three-dimensional load paths, panel-zone deformation or shear deformation of the member itself.

2. Member sections and nominal N–M envelopes

Rectangular sections contain two reinforcement rows. The cover value is measured to the outer stirrup. Bar centrelines are at cover + stirrup diameter + longitudinal diameter / 2. The geometry check screens basic row fit; it is not a complete reinforcement detailing check.

These are nominal material envelopes: no code partial factors, national annex, confinement model, cyclic concrete crushing, bond-slip, bar buckling or fracture check is implied. Increasing stirrups does not automatically increase the entered shear resistance or the hinge rotation limit. Ec and the effective EI factor are explicit inputs; changing reinforcement does not silently replace them with a cracked-section stiffness calculation.

The strain-compatible section approach is illustrated in OpenSees section examples. LAB uses its own small browser implementation and the assumptions above; it does not run OpenSees or claim code-equivalent RC design.

3. Nonlinear member ends

The bending element has two coupled basic end rotations relative to its chord. Its elastic basic stiffness is (EI/L) [[4, 2], [2, 4]]. Plastic end rotations are integrated with an associative return map and kinematic hardening. The axial response remains elastic.

The user-defined My / envelope M ratio sets the initial hinge yield moment from the nominal section envelope at the current axial force. It is a calibration parameter, not an automatically calculated first-yield curvature. The default ratio is 0.75. The hardening parameter a defines Hᵢ = a/(1−a) × Kᵢᵢ,initial; it is not the post-yield stiffness ratio of the entire building.

The accumulated absolute plastic rotations κᵢ and κⱼ define D = min[1, (κᵢ + κⱼ)/(2 θplastic,limit)]. Optional strength and stiffness reductions are My × (1 − dstrength D) and EI × (1 − dstiffness D). Degradation is held at its last committed value during a trial and advances only after global equilibrium converges. Zero degradation is the default.

Moment–rotation loops, residual motions and redistribution are computed by this constitutive model. Its default yield, hardening, degradation and rotation-limit parameters are illustrative and uncalibrated. A physical application needs member-specific experimental or otherwise justified parameters. The implementation does not include pinching. More elaborate cyclic model features are described in the primary OpenSees hysteretic-material documentation; that model is not being reproduced here.

4. Gravity P–Δ and stability

The P–Δ option adds the sway geometric stiffness of each gravity-loaded column using its constant initial gravity axial force: −P/L × [[1,−1], [−1,1]] in the end horizontal translations, with P positive in compression. It changes the initial eigenperiods and the subsequent incremental restoring force.

This is a small-displacement sway approximation about the gravity reference state. Dynamic axial-force changes affect section-envelope screening and hinge yield thresholds, but are not used to update geometric stiffness. Local P–δ, corotational large rotations, contact after loss of support and a falling-building animation are outside the model. See the OpenSees P–Δ transformation documentation for the general second-order modelling concept.

An initially non-positive lateral eigenvalue prevents the run. After plasticity starts, condensed tangent stiffness is checked at approximately 0.1 s intervals. A non-positive or singular tangent is reported as a warning; a temporarily negative tangent is not by itself proof of dynamic collapse.

5. Equations, damping and integration

M ü + C u̇ + r(u, plastic history) = −M 1 ag(t)
Kcondensed φr = ωr² M φr
Tr = 2π/ωr; fr = ωr/(2π)
C = M Φ diag(2 ζ ωr) Φᵀ M, with Φᵀ M Φ = I

Initial modal damping is assembled on the horizontal floor coordinates and remains fixed during nonlinear response. All horizontal floor modes are retained. The initial frequencies shown in the spectrum view include selected P–Δ effects, but are not updated damaged-state frequencies. Initial vertical/rotational degrees of freedom are statically condensed for eigenanalysis.

Time response uses Newmark average acceleration, γ = 1/2 and β = 1/4. The internal step is no larger than the selected maximum, the native input interval or the shortest initial eigenperiod / 240. The output interval is 0.02 s; a limit reached between output samples retains its exact final integration time.

Initial displacement and velocity are zero relative to the gravity equilibrium, and the initial acceleration satisfies dynamic equilibrium, including a nonzero first ground sample. Nonlinear trials are recomputed from committed plastic states. The Newton residual tolerance is max(0.5 N, 10⁻⁸ × total mass × g), with at most 22 iterations. Axial-envelope dependence is updated during iterations; the tangent neglects its cross-derivative, so this is a quasi-Newton treatment of that coupling. There is no automatic step retry after nonconvergence; rerun at a smaller selected step to investigate it.

6. Interpreting member results and events

Local x runs from the bottom to the top of a column and left to right along a beam. N is positive in compression. For end nodal resisting moments qi, qj and a downward beam load w:

M(x) = −qi + (qi + qj)x/L + w x(L−x)/2
V(x) = (qi + qj)/L + w(L/2−x)
M(0) = −qi; M(L) = qj; dM/dx = V

The inspector displays both end moments, end-i shear and the axial force. Envelopes include the possible beam interior moment extremum and both shear ends. N, M and V diagrams each use their own labelled automatic amplitude scale. Viscous damping forces are not assigned to member resistance.

Peaks and event detection use internal integration steps; curves and CSV use output samples. Event times have internal-step resolution and are not exact physical failure times. End roof displacement is not automatically a settled residual displacement: extend the free-response tail and examine the remaining motion. Low damping and very flexible frames can require much longer tails.

7. Section stress reconstruction at A–A

The Member details page reconstructs a section stress state from the selected cut's current axial force N, bending moment M and shear V. N and M are passed to a separate plane-sections solver, with ε(z) = ε₀ + κz, and the two section resultants are iterated until they match the frame resultants. Compression is positive. The stress map, depth profiles and neutral-axis marker all use this recovered state.

Stress histories use the saved frame output samples at the selected A–A position. A sample is left blank when the RC state is outside the nominal N–M envelope, does not converge, or exceeds the nominal strain limits. The values are reconstructed snapshots; the postprocessor does not carry cyclic fibre memory or reconstruct unloading, residual strains, bond-slip, confinement, bar buckling, diagonal cracking or stirrup stresses. It also does not replace a distributed-plasticity or code section analysis.

8. Recorded motion, spectra and resonance

The five catalogue records are complete numeric files from a pinned OpenSees example repository revision. Their original AT2 files, hashes, station/component metadata and processing notes are bundled. See record provenance and source-specific reuse notes. These public examples are not a hazard-consistent or code-selected design suite.

Native accelerations are linearly interpolated for integration. There is no hidden baseline correction, detrending, filtering or spectrum matching. Original × factor = 1 preserves published values. Target PGA is an explicit alternative. The same applied record is passed to A and B; its amplitude never depends on either frame's parameters.

For the Fourier diagnostic only, the mean is removed and a Hann window is applied, with window-gain normalization and a one-sided amplitude spectrum. These operations do not modify the input used for structural response. Zero padding makes the display denser but does not improve the physical frequency resolution, approximately 1 / record duration. The largest Fourier peak is shown as a descriptive quantity, not “the frequency of the earthquake”.

The ±10% band statistic is the fraction of Fourier squared amplitude near f₁. It is not Arias intensity, a design resonance limit or a safety criterion. A broad or time-varying input can interact with several modes, and damping, participation and duration matter.

Elastic response spectra solve SDOF oscillators at the damping of A and B over periods from 0.05 to 10 s, plus the frame modal periods up to 30 s. Pseudo-acceleration is Sa = ω² max|uSDOF| / g. The oscillator step is at most min(0.01 s, record dt, T/80). The plotted Sa values are not the absolute roof acceleration of the multi-mode frame.

For a harmonic experiment, the steady-state SDOF relative-displacement amplification is D = 1 / √[(1−r²)² + (2ζr)²], with r = fforcing/fnatural. LAB's actual response also contains startup, tapering and multiple modes; an undamped ideal steady-state formula at r = 1 has no finite bound, whereas a finite-duration run has a finite response.

9. Imports, reproducibility and reports

Import a g-unit AT2 record with its NPTS and DT header, or a uniformly spaced CSV/TXT with one acceleration column or two columns (time in seconds, acceleration). Explicit CSV acceleration units are g, m/s² or cm/s². One-column files require a supplied dt. Limits are 120,000 samples and 180 s. No samples are sent to a server by the calculator.

Save model includes both frames, overrides, input choice, scaling and an uploaded record when selected. Copy scenario link supports catalogue and synthetic scenarios; for large models or uploaded samples, share the model file. Report / PDF opens the last completed calculation, its input model, record source, plots, events, member envelopes and the selected member drawings at the current time, ready for the browser's Print → Save as PDF. Later unapplied edits are marked. CSV exports include end times and run status.

10. Verification and practical limits

The reproducible core checks cover section endpoint capacities, frame equilibrium and symmetry, mass/stiffness scaling, modal mass, P–Δ trends, an analytical undamped SDOF response, force-diagram equilibrium, a cyclic plasticity return map, the elastic limit of nonlinear analysis, limit-event timing, harmonic spectra and file parsing. These are numerical checks, not experimental validation of the chosen hinge parameters.

A separate Python reference assembles conventional 6×6 frame elements, enforces the diaphragm constraints, and integrates the response with SciPy DOP853. Its measured comparison is in the verification results. Downloadable benchmark scripts and instructions are also included. An optional OpenSees comparison script is supplied with the source; an MPI initialization failure in this execution environment prevented running that optional reference, so no agreement with OpenSees is claimed.

DOM interaction checks exercise frame selection, member overrides, spectra, harmonic tuning, nonlinear stopping, model sharing and the record suite. They do not constitute live-browser layout or end-to-end testing. Before using the model for a physical structure, review its idealisation, calibrate strengths and deformations, verify time-step sensitivity and compare against an appropriate independent analysis.