> For the complete documentation index, see [llms.txt](https://docs.openbrim.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbrim.org/templates/openbrimfea/loads-fea/dynamic-loads-fea/time-history-cases-fea.md). # Time History Cases \[FEA] A Time History Case integrates the equation of motion step by step and produces the structure's response as a function of time, rather than a single enveloped peak. Use it when the *timing* of the response matters: when peaks in different members occur at different instants, when damping or nonlinear links dissipate energy over the record, or when a response-spectrum analysis is not accepted because modal combination rules discard phase. The case reads mass from the model (self-weight plus Nodal Mass objects pointed at it), reads the excitation from a Time History Function, and marches forward in time. ## Solution **Solution Method:** Selects the integration strategy. This is the parameter that determines which of the other fields matter, so set it first. | Method | Integrator | Damping input | Nonlinear links | | ---------- | ------------------------------------------------------------------ | ---------------- | ---------------- | | **Modal** | Nigam–Jennings piecewise-exact recurrence on decoupled modal SDOFs | Damping Ratio | no — linear only | | **Direct** | average-acceleration Newmark (γ=½, β=¼), full system | Rayleigh α and β | no | | **FNA** | modal basis with iterated link forces | Damping Ratio | **yes** | *Engineering influence.* **Modal** is the cheapest and, for a linear structure whose response is captured by a manageable number of modes, it is exact for a piecewise-linear excitation — accuracy is limited by how many modes you retain, not by the time step. **Direct** integrates the full system and therefore captures all modes without truncation, at much greater cost, and its accuracy *is* governed by the step size. **FNA** is the method to choose when the model contains nonlinear links (gaps, hooks, isolators): Modal and Direct treat those links with their linear stiffness and will not reproduce gapping or yielding at all. Choosing Modal for a model with nonlinear links does not raise an error — it silently analyses a linearized structure. This is the most consequential setting on the object. {% hint style="danger" %} **FNA corrects nonlinear `FESpring` links only.** Nonlinear behaviour authored directly on an **FENode support** — a gap, hook or nonlinear curve on the node's own DOF — is assembled at its linearized stiffness and stays permanently linear even under FNA. A node gap will not open or close. Model any support that must behave nonlinearly as a **zero-length FESpring** between two coincident nodes instead. The solver detects this and reports it, so read the case messages rather than assuming. Two further FNA limitations are reported the same way: nonlinear links combined with a **rigid diaphragm** or other DOF transform can produce incomplete link residuals, and running FNA under consistent mass makes the modal mass and participation approximate. In both cases benchmark before relying on the result. {% endhint %} ## Modal **# of Modes (Modal):** The number of modes extracted and superposed. Used by **Modal** and **FNA**; ignored by **Direct**. *Engineering influence.* Too few modes truncates the response: high-frequency content, and the stiff-direction response in particular, is simply absent, which typically **understates** member forces near supports. The usual acceptance criterion is that the retained modes capture at least about 90% of the participating mass in each direction of interest — check the modal participating mass ratios rather than guessing a number. Increasing the count costs eigen-solution time and always improves (or leaves unchanged) the fidelity of the superposition; it never makes the answer worse. A value of 0 means no modes, and a Modal or FNA case cannot solve — the case is skipped. ## Excitation **Gravity:** The gravitational constant, in the model's length unit per second squared, used to convert nodal **weights** into masses. Leaving it blank or zero is safe — it falls back to standard gravity in the project's length unit (386.09 in/s² for an inch model). An explicitly wrong value rescales the entire mass matrix, shifting every period and invalidating the whole analysis. It does not scale the excitation record; that is the function's own **Scale**. **Ground Motion:** The Time History Function supplying the excitation. This is a **connectivity / selection** parameter — without it the case has nothing to integrate and the solve is skipped. Define together with Direction and the function's Scale. Changing the record changes everything about the result; the structure's periods are unaffected. **Direction:** The global direction (X, Y or Z) the ground motion is applied in. The excitation is applied as a uniform base acceleration in that direction, so the load on each mass is proportional to that mass. Choose the direction that governs — for most bridges the transverse direction controls substructure demand — and run each direction as its own case rather than expecting one case to cover all. A record applied in a direction with little participating mass produces a small, misleading response. Both parameters describe a **uniform** base motion — every support moving identically and in phase. For a bridge long enough that the seismic wave reaches one pier appreciably later than another, or whose supports sit on different soils, that assumption removes the differential-support demand entirely: moving every support together is rigid-body translation and generates no member force. To model spatially varying ground motion instead, leave Ground Motion **empty** and attach [Support Motions](https://github.com/openbrim/platform/tree/master/docs/documentation/templates/openbrimfea/loads-fea/dynamic-loads-fea/support-motions-fea.md) — one prescribed displacement record per (joint, DOF), with an optional per-support time shift for wave passage. The two are mutually exclusive and the analysis enforces it: uniform base excitation reports displacements *relative* to the moving ground while support motions report *absolute* displacements, so a case carrying both is rejected rather than summing two different reference frames. Multi-support also requires Solution Method = **Direct** — Modal and FNA carry one participation factor per mode per direction, which cannot represent more than one uniform base motion, nor the pseudo-static response to differential movement at all. Direction is ignored on a multi-support case, since each Support Motion names its own DOF. **Output Step (s):** How often results are **saved** — the sampling interval of the stored response history and of the peak search. *Engineering influence.* A coarse output step can miss the true peak between saved samples, so reported maxima are slightly unconservative; it also loses the visual detail of the response history. A fine output step multiplies stored data volume, which on a large model is the practical limit. For Modal and FNA this is also the marching interval. Choose it small enough to resolve the shortest period of interest — a common rule is at least ten points per period of the highest mode that matters. **Integration Sub-Steps (Direct):** Whole number of Newmark steps taken per saved output step; **Direct only**, capped at 1000. This separates accuracy from storage. The march advances by `Output Step / N` while results are still saved every Output Step, so `N = 4` integrates four times more finely at no extra storage cost. Increase it when the Direct solution looks unstable or period-elongated but you do not want to store more data. A value of 1 (the default) integrates at the output step. It has no effect on Modal or FNA. **Duration (s):** How long to analyse. **0 means use the record's own length**, which is usually what you want. Setting a duration shorter than the record truncates the excitation and may cut off the peak entirely; setting it longer continues the analysis past the end of the record, which is a legitimate way to observe free-vibration decay and confirm the damping is behaving. **Save Response History (Direct):** Retains the full per-step response for the viewer. Turning it off keeps peak results while discarding the history, which is the pragmatic choice on large models where the stored history dominates project size. It does not change the computed answer — only what is kept. ## Damping **Damping Ratio (Modal):** A single modal damping ratio applied to **all** modes. Used by **Modal** and **FNA**; ignored by Direct. *Engineering influence.* Damping controls how quickly the response decays and strongly governs the peak in near-resonant conditions. Increasing it reduces peak response — sharply near resonance, only mildly away from it. A value of 0 means undamped: the response grows without bound at resonance and free vibration never decays, which is almost never realistic and is usually a data-entry slip. The default 0.05 (5%) is a common assumption for a bridge at moderate response levels; concrete at high strain, or a structure with energy-dissipating devices, warrants a different value, and codes often prescribe it. Because one ratio applies to every mode, this cannot represent a structure whose damping genuinely varies with frequency. **Rayleigh α (Direct, mass):** Mass-proportional damping coefficient in `C = αM + βK`. **Direct only.** **Rayleigh β (Direct, stiffness):** Stiffness-proportional damping coefficient in `C = αM + βK`. **Direct only.** *Engineering influence, both.* Rayleigh damping gives a damping ratio that varies with frequency: the α term damps **low** frequencies, the β term damps **high** frequencies, and the combination is exactly at the target ratio at only two frequencies, over-damping everything outside that band. Pick the two frequencies to bracket the modes that carry the response, then compute α and β from them — choosing round numbers without that calculation is the usual source of a Direct analysis that is inexplicably over- or under-damped compared with an equivalent Modal run. Both default to 0, which means an **undamped** Direct analysis. That is rarely intended and, unlike a missing modal damping ratio, it is easy to overlook because the fields sit on a different tab from the solution method. ## Mass Source **Mass Case 1 / Mass Case 2 / Mass Case 3:** Up to three load cases whose applied vertical load is converted into additional mass for this analysis. *Engineering influence.* The structure's own self-weight is always available as mass, but a seismic or vibration assessment usually has to include mass that is applied as *load* rather than modelled as structure — superimposed dead load, a code-required fraction of live load, ballast, or equipment represented as a surface load rather than as elements. Naming a case here converts its load into mass at the corresponding joints, so the same superimposed dead load can act as both a gravity load in the static cases and a mass contribution here without being modelled twice. Adding mass lengthens periods and, for a spectrum whose ordinates fall with period, can either raise or lower the force demand — the effect depends on where the structure sits on the spectrum, so it is not conservative in a single direction. Leaving all three empty means the only mass is the structure's self-weight plus any Nodal Mass objects assigned to the case. For most bridges that **understates** the seismic mass, because it omits the superimposed dead load entirely. Take care not to double-count: a load already represented by modelled elements with density should not also be named here. ## Settings **Structure Group:** The part of the structure active for this case, for staged or partial models. Leave empty to analyse the whole structure. **Is Active:** Whether the case runs. Inactive cases are skipped without error, which is convenient for keeping a suite of records in one project and running them selectively — and is also a common reason a case appears to produce no results. ## Verification * Run a modal analysis first and confirm the periods are sensible before trusting any time-history output. A time history built on a wrong mass or stiffness model is wrong everywhere. * Check modal participating mass against the retained mode count. * Compare the Modal and Direct solutions of the same linear model. They should agree closely; a significant difference usually means too few modes (Modal) or too coarse a step (Direct). * Compare the peak response against a response-spectrum analysis using a spectrum for the same record — same order of magnitude is expected. * Extend Duration past the record and confirm free vibration decays at the rate the damping implies. * Halve the Output Step, or raise Integration Sub-Steps, and confirm the peaks are stable. If they move materially, the step was too coarse. * For a nonlinear case, confirm link forces show the expected gapping or yielding rather than a linear response. ## Common mistakes * **Using Modal or Direct on a model with nonlinear links**, silently analysing a linearized structure. Use FNA. * **Expecting FNA to handle a nonlinear FENode support.** It corrects `FESpring` links only — model the support as a zero-length spring. The solver warns; read the case messages. * **Leaving Rayleigh α and β at zero in a Direct case**, producing an undamped analysis whose peaks are far above the Modal result — then "reconciling" the two by adjusting the wrong parameter. * **Retaining too few modes** and under-predicting force demands, particularly near supports. * **Setting Duration shorter than the record** and truncating before the strongest pulse. * **Assuming the case runs** when Is Active is off, or when no Ground Motion is assigned. * **Applying the record in one direction only** and treating that as a complete assessment. * **Confusing the function's Scale with the case's Gravity** — one scales the excitation, the other converts weights to mass. Getting either wrong rescales the answer without any warning. * **Reading peaks from a coarse Output Step** and reporting them as the true maxima. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.openbrim.org/templates/openbrimfea/loads-fea/dynamic-loads-fea/time-history-cases-fea.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.