OpenSees Cloud
OpenSees AMI
Assertions of Failure
31 May 2026 - Michael H. Scott
In addition to confirming successful analysis outcomes, e.g., that a cantilever deflection is PL3/(3EI), assertions can also ensure an analysis that should fail actually does fail.
Previous posts showed failure of linear equation solvers and displacement control. In those posts I included a screenshot of the standard error messages output by OpenSees. The screenshots are useful for demonstration, but not for automated testing.
When automating tests, you do not want to inspect output manually. It’s better to have a failed assertion let you know that something did not go as expected.
When an analysis fails, e.g., due to either an ill-defined model or
invalid analysis options, ops.analyze() returns a negative value upon
which we can place an assertion.
ok = ops.analyze(1) # Or whatever
assert ok < 0
Consider a small example of a single element with no restrained nodes. This analysis will fail because the system of equations will form and attempt to solve a singular matrix.
import openseespy.opensees as ops
ops.wipe()
ops.model('basic','-ndm',1,'-ndf',1)
ops.node(1,0) # Node not restrained
ops.node(2,0)
ops.uniaxialMaterial('Elastic',1,100)
ops.element('zeroLength',1,1,2,'-mat',1,'-dir',1)
ops.timeSeries('Constant',1)
ops.pattern('Plain',1,1)
ops.load(2,1.0)
ops.analysis('Static','-noWarnings')
ok = ops.analyze(1)
assert ok < 0
Another example involves failure where the model is well-defined, but the analysis options are problematic. Here, we attempt displacement control on a fixed node.
import openseespy.opensees as ops
ops.wipe()
ops.model('basic','-ndm',1,'-ndf',1)
ops.node(1,0); ops.fix(1,1)
ops.node(2,0)
ops.uniaxialMaterial('Elastic',1,100)
ops.element('zeroLength',1,1,2,'-mat',1,'-dir',1)
ops.timeSeries('Linear',1)
ops.pattern('Plain',1,1)
ops.load(2,1.0) # Reference load applied at node 2
ops.integrator('DisplacementControl',1,1,0.1) # Controlling node 1 (fixed)
ops.analysis('Static','-noWarnings')
ok = ops.analyze(1)
assert ok < 0
The assertions pass because the analyses fail as expected.
While these examples are trivial, the approach can be used for regression tests of larger models with known failure modes. An analysis that is expected to fail but suddenly succeeds can reveal changes in the core of OpenSees, whether in the relevant analysis components, a change elsewhere in the codebase, or a change in the model itself. This makes assertions on expected failures just as valuable as assertions on successful analyses.