Before a simulated building meets an earthquake, it usually has another job: stand under gravity. The next calculation must inherit that loaded structure while introducing motion, inertia and a different solution procedure. OpenSees makes this handoff possible by keeping the structural model separate from the objects that advance its state. That separation is the organizing idea behind its architecture.[2][5]

Developed within the Pacific Earthquake Engineering Research Center, OpenSees is an open-source framework for simulating structures and surrounding soil.[1] Its usefulness becomes clearer when we follow one model through a change of analysis, then examine what the software actually means by success.

The model has a home

OpenSees calls that home the Domain. It contains the nodes, elements, load patterns and constraints that describe the finite-element model. Nodes provide the points at which movements are represented; elements connect those points through mechanical relationships. The model's current state belongs here.[2]

The Analysis calculates how that state changes. In their 2010 architecture paper, Frank McKenna, Michael H. Scott and Gregory L. Fenves describe an analysis assembled from interchangeable objects. These let numerical methods change without rebuilding the representation of the structure.[2]

For a software developer, this is a concrete use of separation of concerns. For the person running the model, it becomes a practical question: which part of the calculation needs to change?

Six jobs behind a solution step

The analysis commands expose that division of labor directly.[3]

That distinction between system and algorithm matters. Solving a linear system is one operation inside a nonlinear solution procedure. Selecting the linear solver does not, by itself, specify how the calculation approaches nonlinear equilibrium.[3]

The integrator also does more than choose a step size. It defines the predictive step, the matrix and residual to solve, and the corrections to the response. In a static analysis that response involves displacement; in a transient analysis it also involves velocity and acceleration.[4] Changing integrators therefore changes how the next state is constructed.

These components are specified before creating the analysis object. The analysis Static and analysis Transient commands assemble different kinds of analysis; analyze then asks the assembled machinery to run.[7][8]

Keep gravity when the earthquake begins

Consider an illustrative model whose gravity analysis has completed successfully. Its members already carry load. Starting the earthquake calculation should preserve that condition.

The command wipeAnalysis removes the analysis objects while retaining the model's state. The documentation explicitly identifies the transition from gravity loading to earthquake response as a reason to use it. Crucially, it also retains the domain's time and leaves existing loads active.[5]

There are therefore two distinct housekeeping tasks. Replacing the analysis machinery handles the numerical procedure. Freezing the established gravity loads handles what those loads do next.

For the latter, loadConst -time 0.0 holds the load patterns already in the domain constant and resets domain time to zero. Load patterns added afterward are not frozen by that earlier call.[6] In this sequence, gravity is established first, its loads are held constant, and the earthquake loading is introduced afterward.

The distinction is easy to miss in a long script. Removing an analysis does not freeze loads; resetting the clock does not reconstruct an unloaded structure. The commands operate on different parts of the simulation, so their order carries physical meaning.[5][6]

What a successful return value says

The analyze command returns zero for success and a negative value for failure.[8] A surrounding script can use that result to decide whether to continue. But interpreting the zero requires knowing the configured acceptance rule.

Take test NormDispIncr. It examines the norm of the solution vector from the linear equation system. That vector usually corresponds to a displacement correction, although its meaning depends on the integrator and constraint handler. The command also specifies a tolerance and a maximum number of iterations.[9]

This is a numerical stopping criterion. It does not inspect whether the material assumptions describe the specimen or whether the selected response agrees with a measurement.

There is an especially revealing option: the test's pFlag value of 5 prints a failure message when convergence is not achieved within the iteration limit but returns a successful test result.[9] A script that treats every successful status as evidence that the tolerance was satisfied can therefore misread its own configuration.

The architectural lesson is that success has a definition supplied by the analysis. To interpret it, keep the test settings alongside the result.

The measurement still has the final say

An independent study gives this distinction practical substance. In a 2021 PCI Journal paper, Shane Oh and colleagues assessed their OpenSees modeling approach against published shake-table measurements of precast concrete frames, and also compared it with models in DRAIN-2DX.[10]

Agreement depended on what they measured. Peak story drift and floor displacement matched the experimental results well; discrepancies in peak absolute velocity and acceleration were generally larger. The authors judged the models adequate for their study's purpose, which emphasized drift and displacement.[10]

That is a useful way to read a validation claim: identify the response being checked, the evidence used and the intended purpose. Agreement for one output does not automatically establish equal accuracy for every other output.

OpenSees makes the numerical choices visible and replaceable. The gravity-to-earthquake handoff shows why that flexibility matters: a loaded structure can persist while the calculation changes. The experimental comparison supplies the next question—whether the resulting model reproduces the behavior the investigation needs to understand.

Sources

1. Research UC Berkeley, “Pacific Earthquake Engineering Research Center” — OpenSees' purpose and institutional context.
2. Frank McKenna, Michael H. Scott and Gregory L. Fenves, “Nonlinear Finite-Element Analysis Software Architecture Using Object Composition,” Journal of Computing in Civil Engineering 24(1), 2010, pp. 95–107 — Domain, Analysis and interchangeable numerical components.
3. OpenSees documentation, “Analysis Commands” — responsibilities of the six analysis components; consulted November 1, 2026.
4. OpenSees documentation, “integrator Command” — prediction, equation formation and response correction.
5. OpenSees documentation, “wipeAnalysis Command” — removing analysis objects while retaining model state, time and active loads.
6. OpenSees documentation, “loadConst Command” — freezing existing load patterns and optionally resetting domain time.
7. OpenSees documentation, “analysis Command” — constructing static and transient analyses and sequencing their components.
8. OpenSees documentation, “analyze Command” — running analysis steps and interpreting return values.
9. OpenSees documentation, “Norm Displacement Increment” — tolerance, iteration limit, solution-vector meaning and the pFlag 5 exception.
10. Shane Oh, Yahya C. Kurama, Jon Mohle and Brandt W. Saxey, “Seismic design and analysis of precast concrete buckling-restrained braced frames,” PCI Journal, September–October 2021 — independent assessment against earlier experimental evidence; “Nonlinear model validation,” pp. 69–71.
11. PEER, “50th Anniversary of UC Berkeley Shaking Table,” July 20, 2022 — source of the photograph of the three-story REPEAT frame at the June 24 demonstration.