Skip to content

Latest commit

 

History

History
1889 lines (1475 loc) · 75.9 KB

pushover_analysis.md

File metadata and controls

1889 lines (1475 loc) · 75.9 KB
title Pushover (Non-linear Static) Analysis
description Pushover analysis: fiber sections, lumped hinges, brace buckling approaches, ADRS conversion, and CSM.
status complete
tags
analysis-type
pushover
nonlinear
fiber
hinges
brace
csm
category
analysis-types
related
modal_analysis.md
tcl_export.md
stiffness_factors.md
element_properties_config.md
storey_response.md

Pushover (Non‑linear Static) Analysis

Status at a glance — RC frame modelling

Layer Status Notes
RC sections ✅ mostly complete RectangularSection / CircularSection with to_fiber_patches(), rebar auto-placement, Mander confinement (fiber_confinement()). ⚠️ Channel / Angle / Tee / SD / Encased shapes are placeholders (P6)
Pipeline ✅ Preprocessor → AnalysisBuilder → fiber rebuild (forceBeamColumn + Lobatto, PDelta); static / modal / response-spectrum / pushover
Concrete law ✅ (opt-in) concrete_material="Concrete02" — strain-softening + tension stiffening; core_residual_factor (crushing-residual lever); both default-off
Bond-slip ✅ (opt-in) bond_slip=True — zero-length Bond_SP01 end springs on fiber members; default-off
Shear ✅ (opt-in) simplified-MCFT capacity reporter + nonlinear trilinear shear backbone (aggregate_shear="nonlinear")
Column limit states ✅ (opt-in) Elwood zero-length springs (limit_state_columns)
Lumped hinges ✅ (opt-in) hinge_model="lumped" (Hysteretic backbones)
Validation ⚠️ Vecchio & Emara 1992: peak 1.07×, secant 1.03× in band — post-peak descent not reproduced (documented). Duong 2007: shear-critical failure reproduced (≈ 1.03× peak, ≥ 15 % post-peak drop)

See also vecchio_emara_benchmark.md, shear_failure_modelling.md and _pending_work.md.

Overview

Pushover analysis is a non‑linear static procedure used to evaluate the seismic performance of structures. A monotonically increasing lateral load (or displacement) is applied to the structure while gravity loads are held constant. The result is a capacity curve — base shear vs. control node displacement — that shows how the structure stiffens, yields, and degrades under increasing lateral demand.

Requirement — fiber-capable model. Pushover is nonlinear and requires a fiber-capable model (make_nonlinear_sample_model(), or sections implementing to_fiber_patches()). A model with only elastic Section properties cannot yield, so the runner raises ValueError rather than silently degrading to a linear "pushover". (Lumped plastic hinges — hinge_model='lumped' — are exempt, since the hinges supply the nonlinearity.)

The fea_toolkit implementation follows the standard OpenSees two‑stage approach used in well‑known examples (e.g. the PEER RC Frame pushover and the included docs/references/RCFramePushOver_v2.py):

Stage 1:  Apply gravity loads (load‑controlled)
Stage 2:  Lock gravity (loadConst), apply lateral loads, push
          (displacement‑controlled)

How it works

Stage 1 — Gravity

  1. The model is (re-)built with the configured element type and sections. If all frame sections support fiber patches (to_fiber_patches() returns patches rather than raising NotImplementedError), the builder automatically uses:

    • forceBeamColumn elements with Lobatto beam integration
    • Fiber sections (Steel01 / Concrete01 uniaxial materials)
    • This enables non‑linear material behaviour (yielding, plastic hinge formation)

    Otherwise it falls back to elasticBeamColumn with elastic sections (linear pushover).

  2. All load patterns listed in gravity_patterns are created and their loads applied (joint loads, frame self‑weight, area self‑weight, area gravity loads, frame gravity loads, frame distributed loads).

  3. A load‑controlled static analysis is run using LoadControl(1.0) — either as a single step (non‑LayeredShell baseline):

    ops.integrator('LoadControl', 1.0)
    ops.analysis('Static')
    ops.analyze(1)

    or — for LayeredShell RC models — ramped over gravity_num_substeps increments so the shells activate gradually without a stiffness shock:

    NUM_SUB = 10  # AnalysisBuilder.LAYERED_SHELL_GRAVITY_SUBSTEPS
    load_step = 1.0 / NUM_SUB
    for i in range(1, NUM_SUB + 1):
        ops.integrator("LoadControl", load_step)
        ops.analysis("Static")
        ok = ops.analyze(1)
        if ok != 0:
            break

    The substep count is auto‑detected from mesh_model.layered_shell_sections (an explicit gravity_num_substeps config value always wins).

    The structure deforms under gravity alone.

Gravity convergence (LayeredShell RC models)

RC models with LayeredShell walls (e.g. the cropped Project B model) can fail the gravity stage with NormUnbalance errors. Two distinct failure modes were observed in practice:

Symptom Root cause Fix
Norm ≈ 1.000e-4 vs tol 1e-4 — repeated "analyze failed" Near-miss tolerance: the residual sits just above solver_test_tol Relax solver_test_tol to 2e-4
Norm = NaN during the gravity step Sudden LayeredShell stiffness shock when shells activate in a single LoadControl step Ramp gravity with gravity_num_substeps: 10
Norm = NaN during the gravity step (Elwood limit-state columns) Inflated P_g collapses the shear limit surface to a zero LimitState backbone, or the LimitState material's known fragility Check _derive_gravity_axial_loads() / supply column_gravity_loads; use the CenterCol recipe (solver_constraints: "Penalty", solver_system: "ProfileSPD", gravity_num_substeps: 5) — see docs/shear_failure_modelling.md Phase 3
Norm = NaN at push step 1 on a large model (> ~5,000 equations, e.g. the uncropped Project B) solver_system: "BandGen" (the default) banded LAPACK factorisation breaks down: wide RCM bandwidth makes it slow and numerically fragile, Newton stalls a hair above the tolerance then emits NaN at load factor nan Set solver_system: "UmfPack" (sparse direct solver) — identical model, 42/100 steps to 0.126 m in ~100 s with zero failures. The AnalysisBuilder now auto-selects UmfPack above 600 nodes unless solver_system is set explicitly. See Portwood Digital, "Stop Cargo Culting BandGeneral and Plain Numberer" (Feb 2026)
numeric analysis returns 1 / Integrator failed (-2) at random steps on a large model with LayeredShell smeared-crack walls The ConcreteS/J2PlateFibre smeared-crack tangent becomes exactly singular at crack-formation states (perfectly plastic J2PlateFibre with Hiso=Hkin=0 has a zero eigenvalue after yield), so UmfPack's strict pivot check bails — run-to-run variability on the uncropped Project B Two levers: (1) give the wall rebar a small kinematic hardening (Hkin ≈ 1 % E, physically real for HRB400); (2) if the run is still marginal, model the walls elastically (keep the nonlinear fibre frames) — reliable (3/3 complete) but overestimates wall strength. The pushover facade skips a direction gracefully if its gravity stage fails, and the push loop stops cleanly on a -2 integrator failure instead of crashing

Both settings are configured through the builder config dict:

config = {
    # ... pushover / section / shell settings ...
    "solver_test_tol": 2e-4,        # documented pushover default is 1e-6; 2e-4 is an RC+LayeredShell relaxation
    "solver_test_max_iter": 1000,   # sufficient for the fiber/LayeredShell chain
    "solver_algorithm": "Newton",   # falls back to ModifiedNewton only during the lateral pushover loop; gravity handles failures by adapting the load increment, not switching algorithms
    "gravity_num_substeps": 10,     # ramp gravity in 10 LoadControl increments
}
Config key Default Notes
solver_test_tol 1e-6 (general and pushover) The documented 1e-4 (pushover) intent was rejected by the 2026-08-24 empirical pass — it was never effective (the general defaults pre-fill the config) and is not universally safe (breaks the Duong flexure-only forceBeamColumn pushover). Relax to 2e-4 explicitly for RC + LayeredShell models. The 2e-4 value is specific to the documented kN-m unit system — for other force/length unit systems it should be scaled from model.units (e.g. via the model's characteristic weight total_mass × g_from_units(units) × 1e-6, as the builder's automatic fallback does) or derived from the typical residual magnitude in those units.
solver_test_max_iter 10 (general and pushover), 1000 (automatic fallback) The pushover path auto-falls back to ModifiedNewton with 1000 iterations — only during the lateral pushover loop
solver_algorithm "Newton" Falls back to ModifiedNewton automatically only during the lateral pushover loop; the gravity stage adapts the load increment (halving/quartering) rather than switching algorithms
gravity_num_substeps 1 (10 auto when the model has LayeredShell sections) Use 5–10 for LayeredShell RC models

Auto-detection of LayeredShell models

Since fea_toolkit v0.x, the AnalysisBuilder automatically ramps gravity over 10 substeps whenever the MeshModel contains at least one LayeredShellSection (i.e. the model uses the Preprocessor's shell_layers config). This removes the need to remember the gravity_num_substeps: 10 manual override for RC wall models:

  • Detection: mesh_model.layered_shell_sections is non-empty.
  • Override: an explicit gravity_num_substeps in the config dict always wins — auto-detection is skipped when the user sets it.
  • Constant: the auto value is stored in AnalysisBuilder.LAYERED_SHELL_GRAVITY_SUBSTEPS = 10.

So the recommended config for a new LayeredShell RC model is simply:

config = {
    # ... pushover / section / shell settings ...
    "solver_test_tol": 2e-4,        # still recommended — near-miss tolerance
    "solver_test_max_iter": 1000,
    "solver_algorithm": "Newton",   # falls back to ModifiedNewton only in the lateral pushover loop
}

and the builder handles gravity substepping automatically.

Verification — after the run, the log should show zero failures:

grep -c "analyze failed" output/v8_run.log   # → 0

This eliminated all 18 gravity convergence failures seen in the Project B Building v7 run (which used solver_test_tol: 1e-4 and a single gravity step). Use the venv_opensees Python environment when running these models — the stock interpreter produced NaN results in the LayeredShell gravity stage.

Stage 2 — Lateral push

  1. ops.loadConst('-time', 0.0) is called. This is the critical command that separates the two stages:

    • All existing load patterns (gravity) are locked at their current load factor (1.0). They will remain active at that level for all subsequent analysis steps.
    • The domain time is reset to 0.0. Any new patterns created after this point start from time 0.0 and are free to vary.

    Without loadConst, a new lateral pattern would be mixed with the gravity patterns and scaled uniformly by the integrator, producing incorrect results (e.g. gravity loads appearing as lateral reaction).

  2. A new lateral reference pattern is created. The shape of the lateral load is determined by the lateral_load_type parameter:

    • 'uniform' — nodal loads proportional to mass ($F_i \propto m_i$) generated by _compute_uniform_lateral_loads().
    • 'triangular' — nodal loads proportional to mass × height$^k$ ($F_i \propto m_i h_i^k$) generated by _compute_triangular_lateral_loads().
    • 'mode1' — nodal loads proportional to mass × mode shape ($F_i \propto m_i \phi_i$) generated by _compute_mode_shape_lateral_loads().
    • 'pattern' — distributed loads read from an existing SAP2000 load pattern (the original approach).

    For the first three types, loads are applied as concentrated nodal loads (ops.load). A dedicated time series and pattern tag are created for the lateral load (no tag collision with gravity patterns).

  3. The integrator is switched to DisplacementControl:

    ops.integrator('DisplacementControl', control_node, dof, disp_inc)
    ops.analysis('Static')

    This drives the control node in the specified DOF by disp_inc at each step, finding the load factor on the lateral pattern that produces the target displacement.

  4. The push proceeds in a loop:

    for step in range(num_steps):
        ok = ops.analyze(1)
        # Record control node displacement and base shear

    At each step the control displacement and base shear (sum of reactions at restrained nodes in the push direction) are recorded, producing the capacity curve.


Key commands explained

Command Purpose
ops.loadConst('-time', 0.0) Lock gravity loads; reset time so new patterns start from zero
ops.integrator('LoadControl', 1.0) Ramp all loads to full value in one step (gravity stage)
ops.integrator('DisplacementControl', node, dof, inc) Drive a node's displacement; scale lateral load to achieve it
ops.timeSeries('Linear', tag), ops.pattern('Plain', tag, tag) Create a dedicated time series + lateral load pattern (separate from gravity pattern tags)
ops.load(tag, fx, fy, fz, ...) Concentrated nodal load (used for uniform, triangular, mode1)
ops.eleLoad('-ele', tag, '-type', '-beamUniform', ...) Element‑span load (used for pattern type)
Steel01(matTag, Fy, E, b) Steel material with kinematic hardening (used for fiber sections)

Lateral load types — what they are and why to use them

Both ASCE 41-17 §7.2 and ATC-40 §2.2 require at least two distinct lateral load patterns to bracket the possible inertial force distribution as the structure yields and degrades. The four options in run_pushover_analysis() are:

# Type Shape Requires Code status
1 'uniform' $F_i \propto m_i$ Seismic masses ✅ ASCE 41 / ATC‑40 required
2 'triangular' $F_i \propto m_i h_i^k$ Masses + optional $T_1$ ✅ ASCE 41 / ATC‑40 required
3 'mode1' $F_i \propto m_i \phi_{i1}$ Masses + mode shapes ✅ Allowed alternative
4 'pattern' From SAP2000 eleLoad A named load pattern ❌ Not code‑compliant

1. Uniform (mass‑proportional) — 'uniform'

Shape: $F_i \propto m_i$

Every node with mass receives a lateral force proportional to its mass. This is equivalent to applying a uniform ground acceleration to the structure — every mass particle feels the same acceleration.

When to use: Required by both ASCE 41 and ATC-40 as one of the two minimum patterns. The uniform pattern places more demand on lower storeys compared to the triangular pattern, because upper-storey masses (the smallest contributor to the triangular pattern's $m_i h_i^k$ factor at small $h$) still receive full lateral force. It often produces larger base shear and can reveal strength or ductility weaknesses at lower levels that a triangular pattern might underestimate.

Typical result: Higher base shear, lower roof displacement compared to triangular for the same structure.

2. Triangular (ELF / code pattern) — `'triangular''

Shape: $F_i \propto m_i h_i^k$

Lateral force increases with both mass and height above the base, following the same distribution as the ASCE 7 Equivalent Lateral Force (ELF) procedure. The exponent $k$ accounts for higher-mode effects in taller structures:

  • $k = 1.0$ for $T \le 0.5$ s (low‑rise, stiff structures)
  • $k = 2.0$ for $T \ge 2.5$ s (tall, flexible structures)
  • Linear interpolation for $0.5 < T < 2.5$ s

When to use: Required as the second minimum pattern in both ASCE 41 and ATC-40. The triangular pattern approximates the fundamental‑mode inertial force distribution and tends to produce larger roof displacements than the uniform pattern, making it more demanding on upper‑storey drift-sensitive components.

Typical result: Lower base shear, larger roof displacement compared to uniform.

3. Mode‑shape pattern — 'mode1'

Shape: $F_i \propto m_i \phi_{i1}$

Lateral force is proportional to the product of nodal mass and the fundamental mode eigenvector component in the push direction. This is the most accurate representation of the elastic inertial force distribution.

When to use: Allowed as an alternative to the triangular pattern in ASCE 41. Particularly useful when:

  • The fundamental mode shape is not well‑approximated by a triangle (e.g., structures with set‑backs, transfer storeys, or non‑uniform mass distribution).
  • You want to compare results against a response‑spectrum analysis that uses the same mode shape.

Requires: A prior call to run_modal_analysis() followed by extract_mode_shapes().

4. Pattern-based (SAP2000) — 'pattern'

Shape: Taken directly from an existing SAP2000 load pattern's frame distributed loads (eleLoad commands).

When to use: Kept for backward compatibility and for specialised cases where the user wants complete control over the load distribution (e.g., a custom user‑defined pattern, or a pattern exported from another source). Not recommended for code‑compliant seismic assessment.

Comparing the patterns

Lateral force distribution (qualitative)
                                              ▲
                    uniform                   │
                 mass-proportional            │
                                              │   ●  ●  ●  ●  ●  ●
                                              │
                    triangular                │    height
                 (ELF, k=1..2)                │      ●
                                              │        ●
                                              │          ●
                                              │            ●
                                              │              ●
                                              └──────────────────► force

Recommendation: Run at least two pushover analyses — one 'uniform' and one 'triangular' — and use the envelope of both capacity curves for performance assessment, as required by ASCE 41-17.


Using the k exponent (triangular pattern)

The $k$ exponent in the triangular pattern follows ASCE 7-16 §12.8.3:

k = 1.0                     if  T₁ ≤ 0.5 s
k = 2.0                     if  T₁ ≥ 2.5 s
k = 1.0 + (T₁ - 0.5) / 2.0  if  0.5 < T₁ < 2.5 s

Where $T_1$ is the fundamental period from modal analysis. If fundamental_period is not provided (left as None), $k = 1.0$ is used (a conservative choice for most low‑ to mid‑rise structures).


Usage

Basic — mass‑proportional (uniform) pattern

from fea_toolkit.opensees.preprocessor import preprocess_model
from fea_toolkit.opensees.analysis_builder import AnalysisBuilder
from fea_toolkit.plotting import plot_pushover_curve

mm = preprocess_model(model_data)
builder = AnalysisBuilder(mm, config)
builder.build_domain()
builder.compute_seismic_masses()
modal = builder.run_modal_analysis(num_modes=3)

results = builder.run_pushover_analysis(
    gravity_patterns={'DEAD': 1.0, 'DEAD SDL': 1.0, 'LL': 1.0},
    lateral_load_type='uniform',
    lateral_direction='X',
    max_disp=0.5,
    num_steps=50,
)

fig = plot_pushover_curve(results)
fig.savefig('pushover_curve.png')

Triangular (ELF) pattern

Uses the ASCE 7 equivalent lateral force distribution $F_i \propto m_i h_i^k$:

results = builder.run_pushover_analysis(
    gravity_patterns={'DEAD': 1.0, 'DEAD SDL': 1.0, 'LL': 1.0},
    lateral_load_type='triangular',
    lateral_direction='X',
    fundamental_period=modal['periods'][0],  # T₁ from modal analysis
    max_disp=0.5,
    num_steps=50,
)

Mode‑shape pattern

Uses the fundamental mode eigenvector: $F_i \propto m_i \phi_{i1}$:

shapes = builder.extract_mode_shapes(modal['num_modes'])

results = builder.run_pushover_analysis(
    gravity_patterns={'DEAD': 1.0, 'DEAD SDL': 1.0, 'LL': 1.0},
    lateral_load_type='mode1',
    lateral_direction='X',
    mode_shapes=shapes,
    mode_index=0,
    max_disp=0.5,
    num_steps=50,
)

Pattern‑based (SAP2000 load pattern)

Uses an existing SAP2000 load pattern's distributed loads as the lateral load shape (kept for backward compatibility):

results = builder.run_pushover_analysis(
    gravity_patterns={'DEAD': 1.0, 'DEAD SDL': 1.0, 'LL': 1.0},
    lateral_load_type='pattern',
    lateral_pattern_name='Wind +X',
    lateral_direction='X',
    max_disp=0.5,
    num_steps=50,
)

With fiber sections (non‑linear)

If your model's frame sections support to_fiber_patches() (ISection, PipeSection, BoxSection, RectangularSection, CircularSection), the builder automatically uses forceBeamColumn with fiber sections. No additional configuration is needed — the fallback to elastic is automatic.

Controlling the lateral load shape

For 'uniform', 'triangular', and 'mode1' types, the lateral loads are generated from the model's mass distribution and applied as concentrated nodal loads (ops.load). DisplacementControl then scales the entire pattern uniformly to achieve the target displacement. For 'pattern' type, the loads come from the specified SAP2000 load pattern's frame distributed loads.


Beam integration: Lobatto vs HingeRadau

The builder's beam_integration config option controls how plasticity is distributed along forceBeamColumn elements:

Option Behaviour Best for
'Lobatto' (default) Distributed plasticity — integration points spread across the full element length. Yielding can occur anywhere. General use, conservative.
'HingeRadau' Concentrated plasticity — hinges form only at element ends within a plastic hinge length Lp. Interior remains elastic. Moment frames where hinges are expected at beam/column ends.

HingeRadau uses :func:fea_toolkit.model.checks.compute_hinge_length to estimate Lp from section geometry:

  • I‑sections: :math:L_p = 0.5 \\cdot d (section depth)
  • Pipe sections: :math:L_p = 0.5 \\cdot OD
  • Other: :math:L_p = 0.1 \\cdot L (10 % of element length)
from fea_toolkit.opensees.preprocessor import preprocess_model
from fea_toolkit.opensees.analysis_builder import AnalysisBuilder

mm = preprocess_model(model_data)
builder = AnalysisBuilder(mm, {
    'element_type': 'forceBeamColumn',
    'beam_integration': 'HingeRadau',
    'create_fiber_sections': True,
})
builder.build_domain()

Brace modelling

Standard fiber‑section pushover cannot capture brace buckling because:

  1. A single joint‑to‑joint element has no initial imperfection.
  2. Without imperfection, the brace just shortens axially under compression.
  3. Linear and PDelta transforms don't develop lateral bowing.

Three approaches are available, in order of increasing fidelity:

Approach A — Subdivided element with imperfection (implemented)

Each brace is split into N sub‑elements (default 4) with a small sinusoidal lateral offset at internal nodes (default L/500 per ASCE 41). Used with geom_transf_type='Corotational', the imperfection triggers buckling under compression.

How to use:

from fea_toolkit.model.selection import Selection

# Identify braces by section type
sel = Selection.from_brace_sections(model)
brace_ids = set(sel.get_frame_ids(model))

# Or manually
brace_ids = {'10', '11', '12'}

# Preprocess model with brace subdivision already configured
from fea_toolkit.opensees.preprocessor import preprocess_model
from fea_toolkit.opensees.analysis_builder import AnalysisBuilder

mm = preprocess_model(model_data, config={
    'brace_ids': brace_ids,
    'brace_n_segments': 4,
    'brace_imperfection_ratio': 1/500,
})

builder = AnalysisBuilder(mm, {
    'element_type': 'dispBeamColumn',
    'create_fiber_sections': True,
    'geom_transf_type': 'Corotational',  # required for buckling
    'split_elements': True,
})
# set_brace_selection retained only for downstream buckling checks
builder.set_brace_selection(brace_ids)

# Check Euler buckling before running pushover (analytical, no Ops needed)
builder.check_brace_buckling(K=1.0)

Parameters:

Config key Default Description
brace_n_segments 4 Number of sub‑elements per brace
brace_imperfection_ratio 1/500 Lateral offset as fraction of length

Approach B — Phenomenological truss (future)

Replace forceBeamColumn with a Truss element using a custom uniaxial material that exhibits softening in compression while remaining elastic‑plastic in tension. Simpler but no moment interaction at gusset plates.

Implementation sketch:

# Buckling material via Hysteretic or custom
ops.uniaxialMaterial('Hysteretic', matTag, ...
                     pinchX, pinchY, damage1, damage2, beta)
# Truss element (no bending stiffness)
ops.element('Truss', eleTag, *nodes, A, matTag)

Approach C — Hybrid (future)

Subdivided brace with fibre hinges at ends (HingeRadau) and an elastic Corotational interior with imperfection. Highest fidelity:

[hinge]───[elastic subdivided with imperfection]───[hinge]

Gusset plates and joint offsets (implemented)

In steel braced frames, the brace physical end is offset from the beam‑column working point by the gusset plate. This is handled by rigid offset segments (Approach 2):

                  ║  column
      working ───╫─── point
      point  │  ║
             │←d→║
   ──────────┘   ║  ← rigid link (elasticBeamColumn, high stiffness)
        brace    ║
   ──────────┐   ║
             │   ║
      working ───╫─── point
                  ║

When end_offset > 0, :func:subdivide_elements:

  1. Creates offset nodes at distance d from each working point along the brace axis.
  2. Subdivides the brace (with imperfection) between the offset nodes.
  3. Returns rigid_links — tuples describing the link segments.
  4. The builder creates elasticBeamColumn elements with very high stiffness for each rigid link.

How to use:

mm = preprocess_model(md, config={
    "brace_ids": brace_ids,
    "brace_end_offset": 0.15,
    "brace_n_segments": 4,
    "brace_imperfection_ratio": 1.0 / 500.0,
})
b = AnalysisBuilder(mm, config)
b.config['geom_transf_type'] = 'Corotational'
b.build_domain()

The offset is automatically clamped to 45 % of the brace length to prevent the brace from vanishing. Typical values for steel gusset plates are 0.1–0.3 m.

This is a steel‑specific feature — concrete brace-to-frame connections (cast-in-place, embedded) use different detailing and are not addressed here.

Alternative approaches (not yet implemented)


For shell edge constraints (connecting discontinuous slab meshes), see the shell support documentation.


Validation: eigenvalue buckling benchmark

The subdivided brace method (Approach A) is validated by an independent eigenvalue buckling analysis using SciPy linear algebra — no OpenSees involvement.

How it works

The benchmark assembles the global stiffness matrix K and geometric stiffness matrix K_g for the subdivided column using standard Euler-Bernoulli beam finite elements, then solves the generalised eigenvalue problem:

$$(K - \lambda K_g)\phi = 0$$

via scipy.linalg.eig. The smallest positive eigenvalue $\lambda$ is the buckling load $P_{cr}$.

For a 10 m pin‑pin pipe column (100 × 5) subdivided into 6 segments:

Source $P_{cr}$ Difference
Analytical Euler formula 33 557 N —
SciPy eigenvalue FEA 33 560 N +0.01 %

The 0.01 % difference is numerical round-off — the FEA discretisation converges to the exact Euler solution as the number of segments increases.

Why this matters

This benchmark independently proves that the discretised subdivided column has the correct buckling load. Without it, we would only have:

  • The analytical check_brace_buckling() formula (which is just algebra)
  • The OpenSees nonlinear pushover (which proved too sensitive for an automated test — elastic elements carry load past $P_{cr}$ without softening)

The SciPy eigenvalue analysis sits between these two: it confirms that the discretisation (segments, element formulation, DOF connectivity) is correct, using a fast, deterministic, and rock-solid linear algebra solver.

What it does NOT validate:

  • The nonlinear post-buckling response (load redistribution after the brace buckles) — this depends on material nonlinearity and solver settings, and must be verified on a case-by-case basis.
  • The interaction between multiple braces in a frame.
  • Cyclic / seismic buckling behaviour.

Running the benchmark

pytest tests/test_buckling.py -k "TestEulerBucklingBenchmark"

Requires scipy (not a core dependency — the test skips gracefully if missing).


Euler buckling check

:meth:AnalysisBuilder.check_brace_buckling computes the Euler buckling load :math:P_{cr} = \\pi^2 E I_{22} / (K L)^2 for selected braces.

When to call it

Call it after build_domain(), before create_loads() or any analysis run. The method reads section properties and materials from the constructed domain — it does not require an OpenSees analysis, but the elements must exist so the frame tag map and section data are available.

Example::

builder = AnalysisBuilder(mm, config)
builder.build_domain()
brace_selection = Selection(frame_type="Brace")
builder.check_brace_buckling(brace_selection)
builder.create_loads(...)
results = builder.run_pushover_analysis(...)

Basic usage

from fea_toolkit.model.selection import Selection

# Identify braces by section type
sel = Selection.from_brace_sections(model)
brace_ids = set(sel.get_frame_ids(model))

# Build the model
builder.set_brace_selection(brace_ids)
builder.build_domain()

# Check buckling — before pushover
builder.check_brace_buckling(K=1.0)

Output interpretation

── Euler buckling check (K=1.0) ──
         ID              Section    L (m)        λ   P_cr (kN)
  ──────────────────────────────────────────────────────────────
        B1                  PIP4    8.485    112.3       45.2
       B12                  PIP4    6.200     82.1       84.7
Column What it tells you
λ Slenderness ratio :math:KL/r. Above 100 → Euler buckling governs. Below 30 → yielding governs.
P_cr Euler critical load. Compare against expected brace force from gravity + lateral loads.

Frame Member Types

The builder treats all frame elements uniformly through the configured section and material types. The behaviour depends on the element type, section type, and material properties, not on any explicit "beam" / "column" / "brace" flag.

Steel Members

Steel members are the primary target and are fully supported.

Section types:

Shape OpenSees section Notes
I/Wide Flange Elastic or Fiber (Steel01) Beam-columns, girders
Box/Tube Elastic or Fiber (Steel01) Columns, braces
Pipe (CHS) Elastic or Fiber (Steel01) Braces, columns
Channel Elastic or Fiber (Steel01) Purlins, girts
Angle / Double Angle Elastic or Fiber (Steel01) Braces, bracing
Tee Elastic or Fiber (Steel01) Secondary members
Rectangular / Plate Elastic only Stiffeners, plates

Behaviour with fiber sections:

  • create_fiber_sections=True — creates Steel01 uniaxial material with $F_y$ from Material.Fy, $E$ from Material.E_mod, and 1 % strain hardening. Fibre patches are generated via Section.to_fiber_patches().
  • Yielding spreads through the cross-section (I‑section: flanges yield first, then web).
  • HingeRadau integration concentrates plasticity at element ends.

Buckling (braces):

  • Steel braces can be modelled with Approach A (subdivided + imperfection) or Approach B (truss + Hysteretic material with compression degradation).
  • See the Brace Modelling section above.

Concrete Members (Reinforced) — status

Historical status table. The canonical, up-to-date status summary for RC frame modelling is the "Status at a glance — RC frame modelling" table at the top of this document. The table below is retained as the historical record: it predates the 2026-08 rebar auto-placement, Mander confinement wiring, and opt-in shear-modelling work, so its "not implemented" entries are stale.

Current status:

Capability Status Notes
Concrete materials (Concrete01) ✅ Implemented Material.type == "Concrete" triggers Concrete01 material in fiber sections
RC section shapes (Rect, Circle) ✅ Implemented RectangularSection, CircularSection with to_fiber_patches()
Rebar auto-placement ✅ Implemented The S2K parser promotes RectangularSection → ConcreteRectangularSection with a bar count estimate (A × 1% / bar_area, min 4)
Mander confined concrete ✅ Wired sec.fiber_confinement() (with tie_fy resolved RebarMatT → RebarMatL → framework defaults) feeds the confined-core Concrete01; the no-tie-data fallback uses RC_NO_TIE_CONFINEMENT_FACTOR (1.25×)
Nonlinear beam-column behaviour ✅ Implemented Via fiber sections with forceBeamColumn + Lobatto integration
Shear failure modelling ✅ (opt-in) simplified-MCFT capacity reporter + nonlinear trilinear shear backbone (aggregate_shear="nonlinear"); Elwood zero-length column limit states (limit_state_columns)
Bond-slip ✅ Implemented (opt-in) config["bond_slip"] = True inserts zero-length Bond_SP01 slip springs at fibre member ends (P5 Phase B; OpenSeesPy registers the material as Bond_SP01 — the Tcl name bond_sp01 is not exported)

How RC sections work today:

from fea_toolkit.model.sap_data import RectangularSection

# An RC section from SAP2000
section = RectangularSection(
    name="C400x400",
    shape="Concrete Rectangular",
    material="C30/37",
    A=0.16, I33=2.13e-3, I22=2.13e-3,
    depth=0.4, bf=0.4,
)

When create_fiber_sections=True, the builder creates:

  • A Concrete01 uniaxial material (if Material.type == "Concrete") with Fc and epsc0 from Material.Fc and Material.eFc.
  • A Steel01 material for longitudinal rebar — auto-placed as fibres by ConcreteRectangularSection.to_fiber_patches() for promoted RC sections.

Roadmap (remaining / completed):

  1. Rebar layer placement — automatic generation of rebar fibres within rectangular and circular sections, with configurable cover and bar diameter ✅ Implemented.
  2. Confined concrete — Mander or Chang-Mander model for core concrete, with unconfined cover concrete ✅ Implemented — Mander via fiber_confinement(), wired in _create_single_section().
  3. PM interaction — axial‑flexural interaction checks using the fiber section's P‑M diagram — open.
  4. Shear springs — zero‑length shear spring elements at member ends with degrading backbone (ASCE 41) ✅ Implemented — the aggregate_shear="nonlinear" trilinear shear backbone and Elwood limit_state_columns springs.

Contributions welcome — see the model/sap_data.py section hierarchy for the extension points.

With demand data — the full picture

Run a quick linear static analysis first to get axial forces, then re-run the check with demand:

# Linear static to get axial demands
results = builder.run_static_analysis(
    pattern_scales={'DEAD': 1.0, 'WIND': 1.0}
)
results = builder.run_static_analysis(
    pattern_scales={'DEAD': 1.0, 'WIND': 1.0}
)

# Build axial demand dict keyed by SAP2000 element ID (string),
# matching what check_brace_buckling() expects.
# Use the builder's element tag → SAP ID mapping.
axial = {}
for eid, elem in builder.model.frame_elements.items():
    tag = builder.frame_tag_map.get(eid)
    if tag is not None:
        fz = results['element_force'].get(tag, {}).get('Fz', 0.0)
        axial[eid] = abs(fz)

# Buckling check with D/C ratios
builder.check_brace_buckling(K=1.0, axial_demand=axial)

This adds two columns to the output:

   P_cr (kN)   P_dem (kN)    Ratio
   ────────────────────────────────
       45.2         38.1      0.843  ⚠ demand > 50% of P_cr
       84.7         12.3      0.145  ✅

Choosing K (effective length factor)

Connection type K Notes
Pinned-pinned (ideal) 1.0 Default
Gusset plates (steel) 0.85 Some rotational restraint from the gusset
Fixed-fixed (ideal) 0.5 Rare in braced frames
Per AISC 360 1.0 Conservative pinned assumption

When to worry

  • Ratio > 1.0 — brace will buckle before reaching the design load. Reconsider the section or framing arrangement.
  • Ratio > 0.5 — brace is approaching :math:P_{cr} under service loads. The pushover will show significant softening in this brace. Verify that the imperfection amplitude (brace_imperfection_ratio) is adequate.
  • Ratio < 0.3 — brace is stocky; buckling is unlikely. Yielding or connection failure will govern instead.

Common pitfalls

  1. No mass source — does not matter; the check uses section geometry, not mass data.
  2. End offsets — end_offset shortens the effective brace length, which increases :math:P_{cr}. The check uses the original node-to-node length (conservative — true P_cr with offsets will be higher).
  3. Subdivided elements — the check works on original element IDs, not subdivided segments. Call it before build() for element lookup.
  4. K is for the brace alone** — if the model has semi-rigid connections (gusset plates), use K=0.85 to account for partial fixity even without explicit rigid offsets.

Capacity Spectrum Method (CSM)

Once a pushover curve has been computed, the Capacity Spectrum Method (ATC‑40 / GB 50011) converts the force–displacement relationship into ADRS (Acceleration‑Displacement Response Spectrum) format and intersects it with the demand response spectrum to find the performance point — the expected inelastic displacement demand under the design earthquake.

1. ADRS conversion — pushover_to_adrs()

adrs = builder.pushover_to_adrs(
    pushover_results,
    modal_results,
    mode_shapes,
    direction='X',
)

The method:

  1. Identifies the dominant mode in the push direction (the mode with the highest participating mass ratio).

  2. Computes the participation factor :math:\Gamma = \sqrt{M_{\text{eff}}}, consistent with mass‑normalised eigenvectors (which :meth:extract_mode_shapes returns).

  3. Converts each pushover step:

    .. math::

    S_d = \frac{D_{\text{control}}}{|\Gamma| \cdot |\phi_{\text{control}}|}
    \qquad
    S_a = \frac{V_{\text{base}}}{|M_{\text{eff}}|}
    

Returns a dict with keys S_a, S_d, Gamma, M_eff, phi_control, and best_mode.

2. Performance point — compute_performance_point()

pp = builder.compute_performance_point(
    pushover_results,
    modal_results,
    mode_shapes,
    spectrum_periods,        # [0.0, 0.1, 0.35, 0.5, …]
    spectrum_accels,         # [0.71, 1.57, 1.57, 1.57, …]  (m/s²)
    direction='X',
    damping_ratio=0.05,
    max_iter=50,
    tol=0.01,
)

The algorithm:

  1. Bilinearises the capacity spectrum using equal‑energy (area under the bilinear curve = area under the actual curve).
  2. Secant iteration — for each trial displacement :math:S_d:
    • Reads :math:S_a from the capacity curve.
    • Computes equivalent period :math:T_{\text{eq}} = 2\pi\sqrt{S_d/S_a}.
    • Computes ductility :math:\mu = S_d/S_{dy} and equivalent viscous damping :math:\beta_{\text{eq}} (ATC‑40 Equation 5‑19).
    • Reduces the elastic demand spectrum by a damping factor :math:B.
    • Reads :math:S_a^{\text{demand}} from the reduced spectrum at :math:T_{\text{eq}} and converts back to :math:S_d^{\text{demand}}.
    • Checks convergence: :math:|S_d^{\text{demand}} - S_d| / S_d < tol.
  3. Elastic fallback — if the trial point drops below the first data point of the capacity curve, the algorithm computes the elastic spectral response from the dominant mode's natural period and the demand spectrum. This handles stiff structures that remain elastic under the design earthquake.

Returns a dict with:

Key Description
S_dp Performance point spectral displacement (m)
S_ap Performance point spectral acceleration (m/s²)
V_base Corresponding base shear (N)
D_roof Corresponding roof displacement (m)
T_eq Equivalent period at the performance point (s)
mu Ductility demand
converged Whether the secant iteration converged
S_dy, S_ay Bilinear yield point (ADRS coordinates)
capacity_adrs Full ADRS curve as {'S_a': …, 'S_d': …}

3. Visualisation — plot_capacity_spectrum()

from fea_toolkit.plotting.viz import plot_capacity_spectrum

fig = plot_capacity_spectrum(
    adrs,             # from pushover_to_adrs()
    spectrum_periods,
    spectrum_accels,
    performance_point=pp,   # optional, from compute_performance_point()
    title='CSM – ADRS Format',
)
fig.savefig('capacity_spectrum.png', dpi=300)

The plot shows:

  • The capacity spectrum (blue line with markers).
  • The elastic demand spectrum (red dashed line) in ADRS coordinates.
  • Constant‑period rays (grey dotted lines labelled T=0.1s, T=0.2s, etc.) for reference.
  • The bilinear yield point (orange square) and the initial / post‑yield slopes.
  • The performance point (green diamond) with dashed projection lines.

4. End‑to‑end example

from fea_toolkit.opensees.preprocessor import preprocess_model
from fea_toolkit.opensees.analysis_builder import AnalysisBuilder
from fea_toolkit.plotting.viz import plot_capacity_spectrum

# Build, run modal, run pushover (see §Usage above)
mm = preprocess_model(model_data)
b = AnalysisBuilder(mm, config)
b.build_domain()
b.compute_seismic_masses()
modal = b.run_modal_analysis(num_modes=5)
shapes = b.extract_mode_shapes(5)
push = b.run_pushover_analysis(
    gravity_patterns={'DEAD': 1.0},
    lateral_load_type='uniform',
    lateral_direction='X',
    control_node_tag=top_tag,
    max_disp=0.3, num_steps=30,
)

# Define elastic design spectrum (e.g. GB 50011, Site Class II)
# g = 9.80665 m/s² — the toolkit's shared SI constant (DEFAULT_GRAVITY_MS2);
# for a model in non-SI length units use g = g_from_units(md.units) instead.
g = 9.80665
T = [0.0, 0.1, 0.35, 0.5, 1.0, 2.0, 4.0, 6.0]
Sa = [0.16*g*0.45, 0.16*g, 0.16*g, 0.16*g,
      0.16*g*0.35, 0.16*g*0.35/2,
      0.16*g*0.35/4, 0.16*g*0.35/6]

# ADRS conversion + performance point
adrs = b.pushover_to_adrs(push, modal, shapes, direction='X')
pp = b.compute_performance_point(push, modal, shapes, T, Sa, direction='X')

print(f"Performance point: S_dp = {pp['S_dp']:.4f} m  "
      f"S_ap = {pp['S_ap']:.2f} m/s²")
print(f"Ductility μ = {pp['mu']:.2f}  "
      f"T_eq = {pp['T_eq']:.3f} s")

# Plot
fig = plot_capacity_spectrum(adrs, T, Sa, performance_point=pp)
fig.savefig('capacity_spectrum.png', dpi=300)

5. Limitations and caveats

The CSM implementation in compute_performance_point() follows the ATC‑40 secant‑period procedure. Users should be aware of the following limitations and how modern codes (particularly ASCE 41) address them.

Convergence and robustness

  • The secant iteration can fail to converge when the capacity curve is very steep (stiff, elastic structures) or when the demand spectrum is low. The implementation includes an elastic fallback for this case, but the transition can be abrupt.
  • Initial period mismatch — the period implied by the initial slope of the pushover curve (particularly with uniform or triangular patterns) may differ from the true first‑mode period. This is because the pushover displacement profile is not the same as the first mode shape. The mode1 load pattern minimises this discrepancy.
  • Bilinearisation sensitivity — the equal‑energy yield point :math:(S_{dy}, S_{ay}) depends on which peak is chosen on the capacity curve. Systems that do not have a sharp yield point (e.g. gradual stiffness degradation) can produce different ductility estimates depending on the bilinearisation algorithm.

The single‑mode assumption

The ADRS conversion (Section 1) assumes the structure responds predominantly in the first mode. This is reasonable for low‑to‑mid‑rise shear‑wall and moment‑frame buildings, but can be unconservative for:

  • Tall buildings (higher‑mode contributions to base shear and drift).
  • Vertically irregular structures (setbacks, soft storeys).
  • Structures where higher modes contribute significantly to the acceleration response (e.g. base‑isolated buildings).

Equivalent viscous damping (ATC‑40 Eqn 5‑19)

The damping reduction factor :math:B is computed from the hysteretic energy dissipation using an empirical formula developed for bilinear elasto‑plastic systems with stable, full hysteresis loops. It is less reliable for:

  • Systems with pinched hysteresis (e.g. poorly detailed RC frames).
  • Systems with degrading stiffness or strength.
  • Systems where higher modes influence the damping demand.

What ASCE 41 does differently (the Coefficient Method)

ASCE 41 (Chapter 7) specifies the Nonlinear Static Procedure (NSP), commonly known as the Coefficient Method, which differs from CSM in several important ways:

Aspect ATC‑40 CSM (this implementation) ASCE 41 Coefficient Method
Target displacement Found by intersecting the capacity and demand spectra in ADRS space (secant iteration). Computed directly as :math:\delta_t = C_0 C_1 C_2 C_3 \, S_a(T_e) \, \frac{T_e^2}{4\pi^2} \, g, where :math:T_e is the effective fundamental period at the yield level.
Period Secant period :math:T_{\text{eq}} varies with each iteration. Effective period :math:T_e = T_i \sqrt{\mu / (1 + \alpha\mu - \alpha)} where :math:\mu is ductility and :math:\alpha is post‑yield stiffness ratio.
Damping Reduces the demand spectrum by :math:B(\beta_{\text{eq}}) (equivalent viscous damping). Uses modification factors:
:math:C_0 — spectral displacement → roof displacement (modal participation).
:math:C_1 — ratio of max inelastic to elastic displacement (function of :math:T_e and :math:\mu).
:math:C_2 — effect of pinched hysteresis / stiffness degradation.
:math:C_3 — P‑Delta induced second‑order effects.
Convergence Requires iterative secant search. Direct computation — no iteration needed after bilinearisation.
Code base ATC‑40 (later superseded by ASCE 41). Commonly referenced in GB 50011 (China), TCECS‑1782, and some European guidelines. ASCE 41‑17 / ASCE 41‑23 (US), referenced in most modern US‑based seismic retrofit guidelines.

Key advantages of the Coefficient Method over CSM:

  1. No iteration — the target displacement is computed directly, which is more robust.
  2. C₁ factor — based on statistical analysis of thousands of nonlinear time‑history analyses. It accounts for the fact that, for short‑period structures, the inelastic displacement can be larger than the elastic displacement (:math:C_1 > 1 for :math:T_e < T_0), whereas CSM with equivalent damping can underestimate this effect.
  3. C₂ and C₃ factors — explicitly address pinched hysteresis and P‑Delta, which the ATC‑40 damping formula handles only implicitly and often unconservatively.
  4. Effective period — uses the secant stiffness at the yield level rather than iterating on the secant period.

When CSM is still useful

Despite its limitations, CSM is widely used in practice because:

  • GB 50011 and TCECS‑1782 specify CSM as the primary pushover evaluation method.
  • The ADRS plot provides intuitive visual insight into the relationship between capacity and demand — the constant‑period rays make it easy to see how changes in stiffness or strength affect the performance point.
  • It is suitable for first‑mode‑dominated structures (most regular buildings up to 10–15 storeys).
  • It can be used with any response spectrum (design code spectrum, uniform hazard spectrum, site‑specific), while the ASCE 41 coefficient method is designed for the ASCE 7 design spectrum format.

Recommendation: For structures governed by GB 50011 or TCECS‑1782, CSM is the appropriate method. For US‑based projects following ASCE 41, consider implementing the Coefficient Method as a separate endpoint or supplementing the CSM result with the ASCE 41 factors for comparison.

Key Description
step Step numbers (0 = after gravity)
control_disp Control node displacement relative to gravity state
base_shear Total base shear in the push direction at each step
status Analysis return code (0 = success)
gravity_displacements Nodal displacements after gravity only
control_node The control node tag used
dof The push DOF (1=X, 2=Y, 3=Z)
lateral_load_type The load pattern type used ('uniform', 'triangular', 'mode1', or 'pattern')

Brace buckling modelling

The builder supports two approaches for modelling brace buckling in pushover analysis, controlled by the brace_type parameter.

Recommendation: Use brace_type="truss" (Approach B) for all practical work. It is numerically robust, captures directional asymmetry correctly, and is the only approach that is fully tested and working. Approach A remains experimental — Corotational geometry with imperfect subdivided braces fails to converge under gravity loads, which is a known OpenSees limitation. See the Approach A docstring and geometry.py for details.

Brace identification

Braces are identified automatically by their section shape type. Any frame element assigned a section of one of the following types is treated as a brace:

  • PipeSection (CHS)
  • AngleSection
  • DoubleAngleSection
  • TeeSection
  • ChannelSection

This logic mirrors Selection.from_brace_sections(). To override which sections are treated as braces, use the brace_sections config option (see below).

Approach A — Subdivided beam-column elements (experimental)

Set brace_type="beam".

.. warning:: Approach A is experimental and not yet production-ready. Known issues:

  1. ✅ Missing set_brace_selection() — Fixed. Subdivision now actually triggers.
  2. ✅ Double subdivision on rebuild — Fixed. subdivide_elements() now skips already-inactive elements.
  3. ✅ split_elements conflict — Fixed. Approach A uses split_elements=False to avoid creating split children that overlap with subdivided elements.
  4. ✅ forceBeamColumn element-level failure — Fixed by switching to dispBeamColumn (displacement-based formulation has no element-level Newton iteration).
  5. ✅ Node creation during rebuild — Fixed. _create_nodes() now tracks created tags; subdivision-only nodes are created separately.
  6. ✅ Rigid-link section E/A swap — Fixed. ops.section('Elastic', ...) parameter order corrected.
  7. ❌ PDelta / Corotational gravity convergence — Still open. Even with dispBeamColumn, no imperfection, NormUnbalance test, KrylovNewton algorithm, and 100 gravity sub-steps, the model cannot converge under ~7.5 MN of gravity load. The subdivided elements sharing nodes with existing frame elements appears to create an ill-conditioned system matrix when PDelta or Corotational geometric stiffness is added.

Braces are subdivided into brace_n_segments sub-elements with a sinusoidal initial imperfection (amplitude = brace_imperfection_ratio × L). Uses forceBeamColumn elements with fiber sections (Steel01 material) and Corotational geometric transformation. Gusset plates can be modelled via brace_end_offset (creates rigid link elements at brace ends).

Solver settings (configurable via builder config).

The following are the project-wide defaults and are the recommended settings for all analyses. They were chosen because they are more robust than the alternatives — see the notes below for when an alternative might be considered.

Key Default Description
solver_constraints 'Transformation' Constraint handler ('Transformation', 'Plain', 'Penalty', 'Lagrange', 'MP'). 'Transformation' is recommended for most models; 'Plain' can produce singular stiffness matrices with subdivided elements or complex connectivity.
solver_system 'BandGen' Linear system solver ('BandGen', 'BandGeneral', 'ProfileSPD', 'SparseGeneral', 'UmfPack', 'Mumps'). 'BandGen' is robust for most models. Switch to 'UmfPack' or 'Mumps' for large models.
solver_test_tol 1e-5 Convergence tolerance for NormDispIncr test
solver_test_max_iter 50 Maximum iterations per load step
solver_algorithm 'ModifiedNewton' Algorithm ('Newton', 'ModifiedNewton', 'NewtonLineSearch', 'KrylovNewton')
gravity_num_substeps 5 Number of sub-steps for gravity application

Note on solver_constraints: 'Transformation' (the default) uses the transformation method to enforce constraints by reducing the system of equations. It is more robust than 'Plain' when elements share intermediate nodes (e.g., subdivided braces). The 'Plain' handler can produce a singular stiffness matrix in such cases. 'Penalty' uses a penalty approach and may be suitable for very large models where transformation becomes expensive, but requires careful selection of the penalty value.

Note on solver_system: 'BandGen' (the default) is a direct solver suitable for most models. 'BandGeneral' is an alternative banded solver. 'ProfileSPD' is optimized for symmetric positive-definite systems. 'UmfPack' and 'Mumps' are sparse direct solvers that handle larger models more efficiently. Choose 'UmfPack' or 'Mumps' when the model has many degrees of freedom or the banded solvers run out of memory.

Important (large models): 'BandGen' is not just slow on big shell-meshed buildings — it can fail outright. The banded LAPACK factorisation degrades numerically as the RCM bandwidth grows, so Newton iterations stall a hair above the convergence tolerance and then emit Norm: nan at every pushover step (load factor nan). The sparse UmfPack solver converges the identical model. The AnalysisBuilder now defaults to UmfPack whenever the mesh has 600+ nodes and solver_system was not set explicitly — you should still set it explicitly in your config for large models so the intent is documented.

Approach B — Truss elements with Hysteretic material

Set brace_type="truss".

  • Brace elements are replaced by Truss elements (axial-only, no bending stiffness).
  • Each brace uses a Hysteretic uniaxial material with asymmetric tension/compression to capture buckling phenomenologically.
  • Beams and columns remain as elasticBeamColumn elements.

Hysteretic material parameters

The material is auto-generated from the section and material properties:

Parameter Tension Compression
Elastic modulus $E$ (from material) $E$ (from material)
Yield / buckling stress $F_y$ (yield) $\sigma_{cr} = P_{cr} / A$ (Euler buckling)
Post-yield / post-buckling $1.01,F_y$ at 1% strain $0.2,\sigma_{cr}$ at 1% post-buckling strain
Ultimate $1.02,F_y$ at 5% strain $0.1,\sigma_{cr}$ at 5% post-buckling strain

Where $P_{cr} = \pi^2 E I_{22} / L^2$ is the Euler buckling load for the longest brace of that section, and $A$ is the cross-sectional area.

Advantages

  • Numerically robust — no convergence issues from subdivision or corotational geometry.
  • Captures directional asymmetry — braces that buckle in compression show much lower resistance than those in tension, revealing the true structural behaviour under reversed loading.
  • Fast — truss elements are computationally cheap.

Limitations

  • No bending stiffness at connections (pinned ends). Gusset plate rotational restraint is not captured.
  • Phenomenological buckling — the post-buckling behaviour is defined by the material stress-strain envelope, not by geometric P-δ interaction.
  • Not suitable for cyclic/pseudodynamic analysis without calibrating the Hysteretic pinching and damage parameters.

Fatigue wrapper for cyclic/dynamic analysis

Set brace_fatigue=True to wrap the Hysteretic material with an OpenSees Fatigue material for low-cycle fatigue degradation:

.. code:: python

config = {
    "brace_truss": True,
    "brace_fatigue": True,
    "brace_fatigue_E0": 0.095,    # Coffin-Manson strain amplitude at fracture
    "brace_fatigue_m": -0.3,      # Coffin-Manson exponent
}

This wraps the Hysteretic backbone (which provides the asymmetric tension/compression buckling) with a Fatigue material that tracks cumulative damage and fractures the element when the Coffin-Manson criterion is met. This is the recommended approach for nonlinear dynamic (time-history) analysis, matching the OpenSees Day CBF examples (Workshops/OpenSeesDays/Steel2dModels/) which use Steel02 + Fatigue with subdivided beam-column elements. For the truss approach, Hysteretic replaces Steel02 to capture the asymmetric buckling that would otherwise emerge from fiber-section P-M interaction.

The Fatigue material is available in OpenSeesPy (tested and verified).

Comparison and recommendation

Criterion Approach A (beam + subdivision) Approach B (truss + Hysteretic)
Status ⚠️ Experimental — element-level convergence issues ✅ Recommended — fully working
Element type forceBeamColumn (fiber sections) Truss (uniaxial material)
Geometry Corotational Linear (buckling is material-defined)
Buckling mechanism Geometric (P-δ via imperfection + corotational) Phenomenological (Hysteretic compression degradation)
Bending stiffness ✅ Yes (beam-column) ❌ No (axial only, pinned ends)
Directional asymmetry ✅ Captured if subdivision works ✅ Captured (tension vs. compression envelope)
Numerical robustness ❌ ForceBeamColumn3d::update fails with fibre sections ✅ Very robust
Computational cost Moderate Low
Gusset plate modelling ✅ Rigid end offsets available ❌ Not applicable
Post-buckling path ⚠️ Sensitive to solver settings ✅ Directly controlled via material params

Bottom line: Use brace_type="truss" (Approach B) for all practical pushover analyses. It is numerically robust, produces clear directional asymmetry, and is fully tested. Approach A (subdivided beam-column) is not yet functional — the Corotational geometry required for buckling causes gravity-stage convergence failure with imperfect subdivided braces. PDelta geometry converges but does not trigger local brace buckling. A two-stage approach (Linear gravity → Corotational push) would require a model rebuild between stages, which is not currently implemented. See the test output at tests/test_buckling.py for the current status of Approach A.

Selecting specific brace sections

By default, braces are identified automatically by their section shape (Pipe, Angle, Double Angle, Tee, or Channel). To override this and explicitly list which sections should be treated as braces, use the brace_sections config option:

CONFIG = {
    "pushover": {
        "brace_type": "truss",
        "brace_sections": ["Diagonal Barcing- CHS 193.7x8"],
    },
}

When brace_sections is set to a list of section names, only those sections are replaced by truss elements. Sections with brace-type shapes that are not in the list are treated as ordinary beam-column elements. This is useful when a structure has CHS members that are not braces (e.g., CHS columns or chords).

When brace_sections is None (the default), the auto-detection by shape type is used.

Config keys for the two-stage pipeline

In the two-stage Preprocessor → AnalysisBuilder workflow (used by project_a_report_v2.py), brace modelling is controlled by two config keys passed to AnalysisBuilder via the builder config dict:

brace_truss (bool, default False) When True, sections identified as braces (by shape type or brace_sections list) are created as 2-node Truss elements with Hysteretic material instead of beam-column elements.

Each brace gets a **per-element** ``Hysteretic`` backbone computed
from its actual length and section properties:

- Tension envelope: yield at ``Fy``, plateau at ``1.01 Fy``, ultimate
  at ``1.02 Fy``.
- Compression envelope: buckle at ``Pcr = π²EI / L²``, post-buckling
  residual at ``0.2 Pcr``, ultimate at ``0.1 Pcr``.

``Truss`` elements have only axial DOF — they don't accept a
``geomTransf``, so the ``PDelta`` / ``Corotational`` transformation
settings are irrelevant for braces under this mode.

Set via ``brace_type="truss"`` in the pushover config.

subdivide_braces (bool, default False) When True, each brace is subdivided into brace_n_segments (default 4) dispBeamColumn sub-elements with a sinusoidal initial geometric imperfection (amplitude = brace_imperfection_ratio × L, default L/500). Each sub-element uses fiber sections (Steel01 material) — buckling emerges naturally from P-M interaction when axial compression acts on the imperfect geometry.

These **are** beam-column elements with rotational DOFs, so they
use the ``geomTransf`` set in the config (``Linear`` by default).
``PDelta`` could theoretically apply but is not wired up (see the
note in ``rebuild_with_fiber_sections``).

Set via ``brace_type="beam"`` in the pushover config.  This path is
**experimental** and not recommended for production use.

Both keys are mutually exclusive — the brace_type parameter in run_pushover_4dir picks which one is set in the builder config.

Usage in the report module

The :func:run_pushover_4dir function in project_a_report.py accepts a brace_type parameter:

from project_a_report import run_pushover_4dir

# Approach B (truss elements with Hysteretic material) — recommended
results = run_pushover_4dir(md, modal, shapes, brace_type="truss")

# Approach A (subdivided beam-column elements) — experimental
results = run_pushover_4dir(md, modal, shapes, brace_type="beam")

The config-driven workflow uses the same key (defaults to "truss"):

CONFIG = {
    "pushover": {
        "patterns": ["mode1"],
        "directions": ["+X", "-X", "+Y", "-Y"],
        "max_disp": 0.30,
        "num_steps": 50,
        "brace_type": "truss",   # <-- default, "beam" is experimental
    },
}

Creating a seismic evaluation report with Quarto

The project_a_report.qmd file in the local/ directory is a complete working example of a pushover-based seismic evaluation report using Quarto with a Jupyter kernel. Below is a guide to setting up your own report.

1. Quarto document header

Start with YAML front matter that declares the output formats and enables the Jupyter kernel:

---
title: "My Building — Seismic Evaluation Report"
format:
  html:
    embed-resources: true
    toc: true
    code-fold: true
  pdf:
    toc: true
  docx:
    toc: true
execute:
  echo: false
  warning: false
jupyter: venv_opensees       # or your kernel name
---

code-fold: true collapses code cells in the HTML output — the reader sees only tables and figures unless they expand the code.

2. Setup cell

Import libraries and configure the analysis. The run_all() function handles the full pipeline: parse the model, run modal analysis, linear cases, pushover, and CSM.

import sys
from pathlib import Path

_REPO = Path().resolve().parent
sys.path.insert(0, str(_REPO / "src"))
sys.path.insert(0, str(_REPO / "local"))

import pandas as pd
import numpy as np
from project_a_report import (
    run_all, bounding_box, modal_table_enhanced,
    format_linear_table, brace_buckling_check,
)

S2K_PATH = "/path/to/your/model.s2k"
CONFIG = {
    "model": {"path": S2K_PATH},
    "spectrum": {
        "code": "GB50011",
        "intensity": 7,
        "acceleration": 0.10,
        "site_class": "I1",
        "design_group": 1,
        "level": "rare",
        "damping": 0.05,
    },
    "loads": {"auto_detect": True},
    "pushover": {
        "patterns": ["mode1"],
        "directions": ["+X", "-X", "+Y", "-Y"],
        "max_disp": 0.30,
        "num_steps": 50,
        "brace_type": "truss",           # "truss" (recommended) or "beam" (experimental)
        "brace_sections": None,          # or ["Section Name"]
    },
    "general": {
        "n_modes": 12,
        "out_dir": None,
        "verbose": False,
        "force_recompute": False,
    },
}

Key config options:

Key Purpose
spectrum.damping Elastic damping ratio for the GB 50011 spectrum (default 0.05)
pushover.brace_type "truss" (recommended) — Approach B (Hysteretic material) or "beam" (experimental) — Approach A (subdivided beam-column)
pushover.brace_sections Optional list of section names to treat as braces (None = auto-detect by shape)
general.force_recompute True to ignore cached results and re-run all analyses

3. Run the analysis

#| label: run-all
#| cache: true
#| output: false
results = run_all(CONFIG)
md = results["md"]
modal = results["modal"]
bb = bounding_box(md)

The #| cache: true directive caches the notebook cell so subsequent renders skip re-computation (as long as the code hasn't changed).

4. Display results

Model overview

Bounding box: `{python} f"{bb['x_span']:.1f} m (X) x {bb['y_span']:.1f} m (Y) x {bb['z_span']:.1f} m (Z)"`

Tables

Use IPython.display.display with HTML and to_html(index=False) to hide the pandas row index:

from IPython.display import display, HTML

# Load totals
from project_a_report import load_pattern_totals
display(HTML(load_pattern_totals(md).to_html(index=False)))

# Materials (with bold <strong> tags via escape=False)
display(HTML(results["df_materials"].to_html(index=False, escape=False)))

# Sections
display(HTML(results["df_sections"].to_html(index=False)))

Pushover curves

#| label: fig-pushover-overlay
_po = results["all_out"]["mode1"]
fig2, ax2 = plt.subplots(figsize=(9, 6))
clr = {"+X":"#1f77b4", "-X":"#ff7f0e", "+Y":"#2ca02c", "-Y":"#d62728"}
for lb in ["+X", "-X", "+Y", "-Y"]:
    r = _po[lb]["results"]
    ax2.plot(r["control_disp"], r["base_shear"],
             label=lb, color=clr[lb], lw=1.5)
    pp = _po[lb]["pp"]
    if pp["converged"] and pp["D_roof"] != 0:
        ax2.plot(pp["D_roof"], pp["V_base"], "D", color=clr[lb], ms=10)
ax2.set_xlabel("Control node displacement (m)")
ax2.set_ylabel("Base shear (kN)")
ax2.set_title("Pushover Curves (4 directions)")
ax2.grid(True, alpha=0.3)
ax2.legend()
fig2

Note the signed values — with brace_type="truss", -Y shows much lower shear than +Y because all braces buckle in compression, while +Y engages braces in tension.

Brace buckling check

from project_a_report import brace_buckling_check
df_buckling = brace_buckling_check(md, n_longest=2, K=1.0)
display(HTML(df_buckling.to_html(index=False)))

CSM 4-panel ADRS plot

#| label: fig-csm
results["fig_csm"]

Comparison table

from project_a_report import pushover_comparison_table
df_compare = pushover_comparison_table(
    results["all_out"]["mode1"], results["df_linear"])
display(HTML(df_compare.to_html(index=False)))

5. Caching and re-computation

Results are cached in two places:

  1. Jupyter cell cache — controlled by the #| cache: true cell directive. Clear it by deleting the .ipynb file in the output directory, or by changing the cell code.
  2. Pickle cache — run_all() saves results to local/output/results.pkl. Set "force_recompute": True in CONFIG to bypass it, or delete the file manually.

When switching between brace_type="beam" and brace_type="truss", always set "force_recompute": True (or clear both caches) to ensure fresh results.

6. Rendering

From the terminal (with the virtual environment activated):

cd local/
quarto render project_a_report.qmd --to html

For all formats (HTML, PDF, DOCX):

quarto render project_a_report.qmd --to all

3D Visualisation (PyVista)

The toolkit provides interactive 3D plots of analysis results using PyVista (install with pip install pyvista).

Moment diagrams

:func:~fea_toolkit.plotting.force_diagram.plot_force_diagram draws a 3D force/moment diagram on the structure, with two display modes:

  • mode='flag' — planar quadrilaterals extruded perpendicular to each member on the tension side of the bending moment. Flag height is proportional to the magnitude. Red = positive, blue = negative.
  • mode='tube' — colour‑coded tubes along each element (red = +ve, blue = −ve).

All forces are transformed to local coordinates before plotting (using the element's local axes), so the moment sign and direction are correct regardless of member orientation:

  • 'Mz' — major‑axis bending (flags extend in local y direction)
  • 'My' — minor‑axis bending (flags extend in local z direction)

The unified function accepts an AnalysisBuilder, a model builder, or an NPZ data dict as its source parameter.

from fea_toolkit.plotting import plot_force_diagram

forces = builder.extract_static_element_forces()

# Interactive flag diagram — opens a PyVista window
plot_force_diagram(builder, forces, quantity="Mz",
                   dimension="3d", mode="flag", show_original=True)

# With reaction arrows and title
results = builder.run_static_analysis(extract_reactions=True)
plot_force_diagram(builder, forces, quantity="Mz",
                   dimension="3d", mode="flag", show_original=True,
                   show_reactions=True, static_results=results,
                   title="My Model — Mz (Wind +X)")

# Off‑screen screenshot (for batch scripts)
plotter = plot_force_diagram(builder, forces, quantity="Mz",
                             dimension="3d", mode="flag", show_original=True,
                             off_screen=True)
if plotter is not None:
    plotter.screenshot("moment_diagram.png")

Reaction arrows

When show_reactions=True and the static_results dict from run_static_analysis(extract_reactions=True) is provided, reaction forces at restrained nodes are drawn as arrows:

  • Red arrows = horizontal resultant (fx, fy)
  • Green arrows = vertical (fz)

Arrow length is auto‑scaled to 8 % of the model height for the largest force.

2D force diagrams (Matplotlib)

:func:~fea_toolkit.plotting.force_diagram.plot_force_diagram produces a 2D line plot of any end-force quantity against elevation:

from fea_toolkit.plotting import plot_force_diagram

# Local Mz (major-axis bending) — default use_local=True
fig = plot_force_diagram("results.npz", quantity="Mz",
                         dimension="2d",
                         title="Major-axis moment vs elevation")
fig.savefig("moment.png")

The quantity parameter refers to local coordinates by default (use_local=True), so the physical meaning is consistent regardless of member orientation:

Quantity Local meaning
'Fx' Axial force (+ = tension)
'Fy' Shear in local y
'Fz' Shear in local z
'Mx' Torsion
'My' Bending about local y (minor)
'Mz' Bending about local z (major)

Pass use_local=False to plot raw global forces instead.


See also

  • :class:AnalysisBuilder API documentation
  • :meth:AnalysisBuilder.run_pushover_analysis
  • :meth:AnalysisBuilder.export_results

Exporting Results to NPZ

After a static or pushover analysis, results can be exported to a compressed NumPy .npz file for visualisation in Rhino or other tools. See docs/rhino_export.md for the Rhino visualisation workflow.

Basic usage

# After run_static_analysis():
results = builder.run_static_analysis()
builder.export_results_to_npz("static_results.npz", results)

# After run_pushover_analysis():
push_results = builder.run_pushover_analysis(...)
builder.export_results_to_npz("pushover_results.npz", push_results)

Including section and fiber data

For models using fiber sections, pass section_responses:

builder.export_results_to_npz("results_fiber.npz", results,
    section_responses={
        "section_forces": True,   # N, Mz, My, Vz, Vy, T per integration point
        "fiber_stress": True,     # max/min fiber stress per IP
        "fiber_strain": True,     # max/min fiber strain per IP
    })

What gets saved

Data Arrays Source
End forces sub_fx_i … sub_mz_j ops.eleResponse(tag, 'forces')
Section forces sec_N, sec_Mz, … ops.eleResponse(tag, 'section', ip, 'force')
Fiber extremes sec_sig_max, sec_eps_max, … ops.eleResponse(tag, 'section', ip, 'fiberData')
Displacements node_dx, node_dy, node_dz ops.nodeDisp(tag)
Split map sub_sap_ids, sub_t_start, sub_t_end self.split_elements parent/child tracking

Loading in Rhino

import numpy as np

data = np.load("results.npz", allow_pickle=True)

# Element forces: find sub-elements for a given SAP FrameID
mask = data["sub_sap_ids"] == "42"
mz_j = data["sub_mz_j"][mask]  # major-axis moment at J-end

# Nodal displacements: find a specific node
idx = list(data["node_sap_ids"]).index("5")
dx, dy, dz = data["node_dx"][idx], data["node_dy"][idx], data["node_dz"][idx]

Notes

  • Forces are in global coordinates (end forces) or local coordinates (section forces — OpenSees order: N, Mz, My, Vz, Vy, T).
  • The .npz is a compressed ZIP file. Use allow_pickle=True when loading because string arrays are stored as Python objects.
  • NumPy ships with Rhino 8 CPython — no additional packages required.
  • For pushover, export the final step results. To export every step, modify the loop in run_pushover_analysis() to call export_results_to_npz() with the results from each step.