A toolkit for importing, analysing, and visualising structural
engineering models. Parses SAP2000 .s2k, ETABS .e2k / .$et and
CSi SAFE .f2k / .$sf text models, builds OpenSees models for
structural analysis, and exports to Rhino 3-D for visualisation and
Grasshopper workflows.
The goal is to create a Python package fea_toolkit that:
- Parses SAP2000
.s2k, ETABS.e2k/.$et, and CSi SAFE.f2k/.$sffiles into a common intermediate data model (SAPModelData). - Enriches section properties using a manufacturer database.
- Splits frame elements at joints (and optionally at frame intersections) with parent‑child tracking.
- Splits distributed loads (uniform, linear, trapezoidal) to match the sub‑elements.
- Builds OpenSees models with configurable element types
(
elasticBeamColumn,forceBeamColumn, etc.), applies loads, and runs linear static, modal, response spectrum, pushover and nonlinear dynamic (time-history) analysis. - 3D-only analysis engine — all analysis runs in the OpenSees 3D
domain (
ndm=3,ndf=6); planar ("2D") frames are modelled as planar 3D models with out-of-plane restraints. 2D OpenSees analyses are used only in tests, never in the main workflow. - Exports to Rhino 8 for 3-D visualisation with lightweight extrusion solids, section-based layers, and FEA metadata for Grasshopper.
This section is designed for language model (LLM) assistants working with this codebase. For a full reference, see docs/llm_guide.md — including its section on helping an engineer interpret a model, its analyses and its results.
from fea_toolkit import SAP2000Parser, preprocess_model, AnalysisBuilder
md = SAP2000Parser("model.s2k").parse().get_model_data()
mesh = preprocess_model(md, {"element_type": "elasticBeamColumn"})
builder = AnalysisBuilder(mesh, {}).build_domain()import fea_toolkit
# Inspect: fea_toolkit.__all__, fea_toolkit.io.__all__, fea_toolkit.opensees.__all__, etc.| Goal | Call |
|---|---|
| Parse a model | SAP2000Parser(path).parse().get_model_data() |
| Review a model | python -m fea_toolkit.model.review model.s2k |
| Filter elements | Selection(element_types=['Frame'], groups=['Lateral']) |
| Plot 3D model | plot_mesh(builder) |
| Plot deformed shape | plot_deformed_displacement_3d(builder, results, scale=100) |
| Plot force diagram | plot_force_diagram(builder, results, quantity='Mz') |
| Export to NPZ | from fea_toolkit.io import write_results_npz |
| Export to Tcl | from fea_toolkit.opensees import export_mesh_model_to_tcl |
- Never hardcode
9.81— useg_from_units(units)fromfea_toolkit.utils. - Never use 8-arg trapezoidal
eleLoad— broken in OpenSeesPy 3.8.0.0. CorotationalgeomTransf +eleLoaddoes not work in 3D.- Preprocessor mutates topology. AnalysisBuilder reads the
MeshModelone-way (topology + modelling specs) and emits the OpenSees domain. Panel zones are preprocessed; lumped hinges, member releases, brace subdivision and limit-state columns remain build-time instrumentation (mutate-and-restore) — known debt, seedocs/dev_notes.md.
the "Package tree (abbreviated)" section below for the full subpackage list
~/Projects/fea_toolkit/
├── data/ # (private) section_dict.pkl
├── examples/ # [`examples/README.md`](examples/README.md)
├── src/fea_toolkit/
│ ├── __init__.py
│ ├── io/
│ │ ├── s2k_parser.py # SAP2000Parser with string IDs, numeric tags
│ │ ├── npz_writer.py # Analysis results → NPZ archives
│ │ ├── npz_reader.py # NPZ / HDF5 readers (unified, auto-detect)
│ │ ├── unified_writer.py # Combined NPZ/HDF5 writer
│ │ ├── model_codec.py # Lossless dataclass ⟷ JSON codec (round-trip)
│ │ ├── stage_writer.py # Self-describing model-stage file (SAP + mesh)
│ │ ├── stage_reader.py # read_model_stages() lossless round-trip
│ │ ├── results_schema.py # NPZ key layout + SCHEMA_VERSION
│ │ ├── report.py # pandas summary tables
│ │ └── helper.py # File‑chooser utilities (tkinter/macOS)
│ ├── model/
│ │ ├── sap_data.py # Dataclasses: Node, FrameElement, LoadPattern, JointLoad, FrameDistributedLoad, SAPModelData, and others
│ │ ├── sections.py # SectionLibrary with unit conversion (mm/in)
│ │ ├── mesh_model.py # Frozen post-preprocessor topology
│ │ ├── source_resolver.py # SAPModelData / MeshModel / AnalysisBuilder / stage-file → ResolvedSource
│ │ └── geometry.py # SpatialGrid, point_on_segment, trapezoidal_force_split, split_elements (joint splitting + load redistribution)
│ ├── opensees/
│ │ ├── preprocessor.py # Preprocessor: topology mutations → MeshModel
│ │ ├── analysis_builder.py # AnalysisBuilder: OpenSees domain + analysis execution
│ │ └── builder.py # Tcl export functions (export_model_to_tcl, etc.)
│ └── rhino/
│ ├── __init__.py # Public API (RhinoImporter)
│ ├── colors.py # SAP2000 colour conversion
│ ├── groups.py # Rhino group creation
│ ├── importer.py # Main RhinoImporter orchestrator
│ ├── layers.py # Section-based layer hierarchy
│ └── geometry.py # Centreline + extrusion geometry
├── tests/ # pytest suite — [`tests/README.md`](tests/README.md)
├── pyproject.toml
└── README.md
| Component | Status | Notes |
|---|---|---|
Selection |
✅ Complete | Flexible element filter: select by type (Frame/Area/Node), section, material, group membership, or ID. AND across criteria, OR within lists. Used to control which area loads are converted to edge loads in the builder. |
SAP2000Parser |
✅ Complete | Parses .s2k into raw tables; converts to SAPModelData with string IDs; assigns numeric tags; extracts materials, sections, frame connectivity, restraints, load patterns, joint loads, distributed loads, auto‑mesh settings. |
SAPModelData |
✅ Complete | Contains all model data with mutable defaults via field(default_factory=...); includes units dict with default {'F':'N','L':'m','T':'C'}. |
SectionLibrary |
✅ Complete | Loads section catalogue pickle; converts units to match model (mm or in); enriches Section objects with Z33, Z22, dimensions, etc. |
geometry.split_elements |
✅ Complete | Splits elements at joints when AtJoints=True; marks parent as inactive; creates child elements with new numeric tags; redistributes distributed loads using trapezoidal_force_split; stores relative positions (rdist_a, rdist_b) in child loads. |
Preprocessor |
✅ Complete | Topology-only mutations: element splitting, auto-meshing, end offsets, edge constraints — produces a frozen MeshModel. |
AnalysisBuilder |
✅ Complete | Reads the frozen MeshModel, builds the OpenSees domain (nodes, restraints, elastic/nonlinear sections, elements, loads) and runs static/modal/RS/pushover analyses. |
| Modal Analysis | ✅ Complete | run_modal_analysis() — eigenvalue extraction (ops.eigen), modal properties table with frequencies, periods, participating masses & ratios. |
| Response Spectrum | ✅ Complete | run_response_spectrum_analysis() — mode‑by‑mode RS analysis with a spectrum from GB 50011 (from_gb50011), Eurocode 8 (from_eurocode8 / from_eurocode8_displacement), IEC 62271-207 (from_iec62271) or any user‑supplied table (from_arrays); CQC/SRSS combination, base shear + moment. |
| Element‑Level RS Forces | ✅ Complete | extract_element_rs_forces() — CQC‑combined moments/shears per element, sorted by elevation. |
| Missing Mass Correction | ✅ Complete | Rigid / missing-mass response is computed by spectrum.cqc_base_shear(..., total_mass=...) (keys base_shear_missing_mass, residual_mass) and wired into AnalysisBuilder.run_response_spectrum_analysis() behind the opt-in config["missing_mass"] gate. |
| Seismic Masses | ✅ Complete | compute_seismic_masses() — lumps element self‑weight and load‑based masses per MASS SOURCE (Elements/Masses/Loads flags). Load patterns contribute only their global‑Z component (SAP2000's rule: Gravity/Projected are downward‑positive, Z is sign‑flipped, horizontal X/Y excluded). Per‑source totals are exposed via builder.mass_components and the review's mass_source["components"]. |
| Rhino Export | ✅ Complete | Centreline + lightweight Extrusion geometry with section profiles, section-based layers, UserString metadata, groups. See docs/rhino_export.md. |
| Frame Member Types (Steel) | ✅ Complete | All steel section shapes (I, Box, Pipe, Channel, Angle, etc.) with Steel01 fiber sections or elastic sections. |
| Frame Member Types (RC) | Concrete materials and section shapes supported; rebar auto-placement implemented; confined concrete (Mander) wired via fiber_confinement(). See docs/pushover_analysis.md. |
|
| Code-Specific Capacity Modules | ✅ Complete | fea_toolkit.capacity — GB 50010-2010 flexure/axial/shear/wall checks and ASCE 41-17 plastic hinge length, unit-aware (strengths authored in SI Pa, scaled to model units exactly once). See docs/capacity.md. |
| Storey Identification | ✅ Complete | identify_stories() — 5 strategies: ETABS story table (SAPModelData.stories) → S2K STORY DATA (legacy) → diaphragm constraints → horizontal area elements → node Z clustering. Returns sorted StoryLevel list with confidence ratings. See docs/storey_response.md. |
| Storey Response Analysis | ✅ Complete | storey_displacements() (rigid-body fit with outlier rejection), storey_drifts() (inter-storey drift ratios), storey_shears() (summed element-end forces), modal_storey_drifts() (CQC-combined modal drifts). |
| Rigid Diaphragms | ✅ Complete | ops.rigidDiaphragm() per group — S2K Z‑axis constraints, forced storey detection, or explicit named groups; slab‑derived levels are detected but applied only when explicitly requested (rigid_diaphragms: True/Z‑list), and False always disables. See docs/shell_support.md. |
| Connectivity Diagnostics | ✅ Complete | check_model_connectivity() (orphan nodes, shell-only base), check_split_connectivity() (zero-length elements), check_mesh_connectivity() (unrestrained mesh), diagnose_singularity() (tree-plot distribution). |
| Self-Weight Consistency | ✅ Complete | check_self_weight_consistency() — compares analytical self-weight (element volumes × material unit weight) against applied load-pattern multipliers. |
| Model Export to Tcl | ✅ Complete | export_model_to_tcl() — direct SAPModelData → Tcl script for standalone OpenSees execution; RecordingOpenSees proxy captures all ops.* calls as Python/Tcl; xara_build() classmethod for Xara/OpenSeesRT workflow. |
| Mesh Quality Checks | ✅ Complete | mesh/checks.py — aspect ratios, skew, flatness diagnostics for quad shell elements. |
| Constrained Remeshing | ✅ Complete | mesh/remesh.py — Gmsh-based constrained quadrilateral remeshing with line constraints from frame edges. |
| Shell Openings (Exact Cut-Out) | cut_cell trims structured shell meshes around openings (conforming hole, boundary-node reuse) only for host areas with an enabled mesh assignment (auto_mesh=True, positive max_size); CSI Type → thin/thick shell family selection (ShellDKGQ/ShellDKGT, ASDShellQ4/ASDShellT3); openings filtered from the viewer's filled shells. See docs/shell_openings.md. |
|
| NDMaterial / LayeredShell | ✅ Complete | Data model for nonlinear shear walls: NDMaterial (uniaxial/multiaxial), LayeredShellSection, ShellFiberLayer — parsed from SAP2000 area sections. |
| Backend-Agnostic Viewer | ✅ Complete | ModelViewer + RenderBackend abstraction — renders via PyVista or exports to standalone HTML. plot_interactive_viewer() adds radio buttons, sliders, click-to-inspect. |
| NPZ/H5 Rhino Colouring | ✅ Complete | apply_results(), colour_from_npz(), colour_shells_from_results(), create_deformed_geometry() — colour frames/shells and overlay deformed shapes from .npz/.h5 results or stage files. colour_members=False keeps the Mesh geometry in its section/layer colours; scale_mode="stepped" colours by discrete bands; clip_pct clips the scale to the inner percentiles so outliers don't wash the bulk out. |
| Brace Buckling (Approach A) | ✅ Implemented | Subdivided element with imperfection + Corotational. |
| Brace Buckling (Approach B) | ✅ Implemented | Truss + Hysteretic material — robust for pushover. |
| Brace Fatigue | ✅ Implemented | Fatigue material wrapper for cyclic degradation. |
| Load Handling | ✅ Complete | Supports uniform and linear/trapezoidal distributed loads in global (gravity, X, Y, Z) and member-local (LocalX/LocalY/LocalZ) directions; projects global directions onto local axes using get_SAP_vecxz; handles split loads. |
| Parent‑Child Tracking | ✅ Complete | Each split element stores parent_id, child_ids, t_locations; inactive flag prevents building of parent. |
| Unit Conversion | ✅ Complete | SectionLibrary converts lengths, areas, inertias between in and mm based on catalogue metadata. |
| Rhino 3-D Export | ✅ Complete | Full Rhino 8 module (fea_toolkit.rhino): centreline geometry (points/lines/Breps) and lightweight Extrusion solids (I/Box/Pipe/Channel/Rect/Circular) with section-based layers, FEA metadata (UserStrings), SAP group → Rhino group mapping, and joint colour-coding by restraint. See docs/rhino_export.md. |
| Brace Buckling (Approach A) | ✅ Implemented | Subdivided element with sinusoidal imperfection + Corotational geometry. Converges for pushover with HingeRadau integration. |
| Brace Buckling (Approach B) | ✅ Implemented | Truss element with Hysteretic material (asymmetric tension/compression) — numerically robust. |
| Brace Fatigue | ✅ Implemented | Optional Fatigue material wrapper for cyclic degradation. |
| Pytest Suite | ✅ Passing | 211 tests: dataclass construction, geometry utilities, section enrichment, modal/RS/pushover analysis, CSM, brace buckling (Euler + eigenvalue FEA benchmark), parser, Rhino colour + layer utilities. |
| Load Cases (SAP2000) | ✅ Complete | get_load_cases() parses LOAD CASE DEFINITIONS, CASE - RESPONSE SPECTRUM (general + load assignments), CASE - MODAL, CASE - STATIC into LoadCase.case_data. |
| Auto Load Data | ✅ Complete | AUTO SEISMIC and AUTO WIND tables are parsed and attached to LoadPattern.auto_data. |
| Material Damping | ✅ Complete | Damping parameters from MATERIAL PROPERTIES 06 are captured in Material.extra. |
| Area Element Mass | ✅ Complete | compute_seismic_masses() now includes area element self-weight, area gravity loads (MultiplierZ), and area uniform loads. |
| Brace Fatigue | ✅ Complete | Optional Fatigue material wrapper for cyclic degradation (brace_fatigue config). |
- String IDs – Node and frame IDs are kept as strings (SAP2000 labels), with numeric
tagfields for OpenSees. - Relative Load Positions –
FrameDistributedLoadstoresrdist_aandrdist_b(0..1) for child elements, matching OpenSeesaOverL/bOverL. - Spatial Grid – Efficient nearest‑neighbour search for splitting.
- Trapezoidal Splitting – Exact redistribution of varying loads using
trapezoidal_force_split. - Configurable Builder – Element type, integration points, splitting, verbosity can be set via
configdict. - MASS SOURCE – The
MASS SOURCEtable is parsed by_get_mass_sources()which groups rows by MassSource name, accumulates multipliers when the same LoadPat appears on multiple rows, and stores the result inSAPModelData.mass_sources. The builder'scompute_seismic_masses()then uses this to derive nodal masses (self‑weight fromElements=True, load‑based fromLoads=True+LoadPat/Multiplierpairs). - Modal & RS Analysis –
run_modal_analysis()usesops.eigen('-fullGenLapack', …).run_response_spectrum_analysis()andextract_element_rs_forces()callops.responseSpectrumAnalysis()mode‑by‑mode and extract element forces viaops.eleResponse(eid, 'forces')(global system). CQC follows Der Kiureghian's formula.spectrum.cqc_base_shear(..., T_rigid=..., total_mass=...)computes the rigid cut-off and missing-mass response from residual mass at short‑period spectral acceleration. - Brace buckling — two approaches – The builder supports two buckling modelling strategies. Approach A (experimental) subdivides braces into segments with a sinusoidal imperfection and uses
Corotationalgeometric transformation — has element-level convergence issues. Approach B (recommended) replaces braces withTrusselements using aHystereticmaterial with asymmetric tension/compression. Approach B is numerically robust and captures directional asymmetry correctly. Controlled viabrace_type="truss"(default) /brace_type="beam"(experimental). - Configurable solver settings – The builder's
run_static_analysis()andrun_pushover_analysis()read solver parameters from config:solver_test_tol,solver_test_max_iter,solver_algorithm('Newton','ModifiedNewton','NewtonLineSearch','KrylovNewton'), andgravity_num_substepsfor gravity load ramping. - Per-type stiffness factors (ACI 318 cracked sections) – The
stiffness_factorsconfig option maps structural types to E_mod reduction factors for elastic analysis. Keys:'beam','column','brace','wall','slab'. Typical RC values per ACI 318-19 Table 6.6.3.1.1(a): beams=0.35, columns=0.70, walls=0.70, slabs=0.25. Set toNone(default) for gross/uncracked stiffness. Classification: columns have |Δz| > 4× Δh; braces are diagonal; areas with all corner nodes at the same Z are slabs. Separate OpenSees section tags are created per (section_name, type) pair so the same SAP2000 section used for both beams and columns gets different modifiers. - Brace fatigue – Optional
Fatiguematerial wrapper for cyclic degradation, controlled viabrace_fatigue,brace_fatigue_E0,brace_fatigue_mconfig options. - Pushover spectrum override – The pushover/CSM analysis can use a different spectrum from the response spectrum analysis via
pushover.spectrumin the CONFIG. Falls back to the top-levelspectrumif not specified. - Linear case auto-detection –
run_linear_cases()now reads LinStatic load cases from the SAP2000 model automatically. Users can override vialinear.casesin the CONFIG. - Mass computation includes area elements –
compute_seismic_masses()now includes area element self-weight, area gravity loads (MultiplierZ), and area uniform loads. Previously only frame elements were included. - Spectrum damping fix – The GB50011 spectrum now applies the damping reduction factor
η₂to the ascending branch (T ≤ 0.1s) as well as the plateau and descending branch, matching the referenceGB_spectrum()function. - SAP2000 data extraction – The parser now extracts: load case definitions, response spectrum case data (general + load assignments), modal case data, AUTO seismic/wind table data, and material damping parameters.
A typical analysis flows through five stages. Each stage produces or consumes a well-defined data structure, making it easy to pick up at any point (e.g. load a cached NPZ and jump straight to visualisation).
SAP2000 .s2k / ETABS .e2k / SAFE .f2k / .json
│
▼ ┌──────────────────────┐
│ │ load_model_data() │ Stage 1 — Data Ingestion
│ │ → SAPModelData │
│ └──────────────────────┘
│
▼ ┌──────────────────────┐
│ │ Preprocessor │ Stage 2 — Preprocess
│ │ → MeshModel │ (frozen topology)
│ └──────────────────────┘
│
▼ ┌──────────────────────┐
│ │ AnalysisBuilder │ Stage 3 — Analysis
│ │ → static results │
│ │ → modal results │
│ │ → RS results │
│ │ → pushover results │
│ └──────────────────────┘
│
▼ ┌──────────────────────┐
│ │ write_results_npz() │ Stage 4 — Storage
│ │ → results.npz │ (unified NPZ schema)
│ └──────────────────────┘
│
├──┬──────────────────────┐
│ │ read_results_npz() │ Stage 5 — Visualisation
│ │ → npz_to_pyvista_* │ (PyVista 3D plots)
│ │ → npz_to_rhino_* │ (Rhino colouring)
│ │ → plot_force_diagram │ (force diagrams, moments)
│ └──────────────────────┘
│
└──┬──────────────────────┐
│ local/ │ Real‑world scripts
│ project_b_linear.py │ Full pipeline: parse → analyse
│ project_b_report.py │ → NPZ → plots → reports
└──────────────────────┘
Key data structures across the pipeline:
| Stage | Data structure | Location |
|---|---|---|
| 1 — Parsed model | SAPModelData (dataclass tree) |
fea_toolkit.model.sap_data |
| 2 — Preprocessed topology | MeshModel (frozen) |
fea_toolkit.model.mesh_model |
| 3 — Analysis output | dict with nodal_displacements, periods, etc. |
Returned by AnalysisBuilder methods |
| 4 — NPZ archive | Dict[str, np.ndarray] (keyed by schema) |
fea_toolkit.io.results_schema |
| 5 — Visualisation | pyvista.Plotter / Rhino objects |
fea_toolkit.plotting / fea_toolkit.rhino |
The unified NPZ schema (Stage 4) is the canonical exchange format — it is what the visualisers consume. You can save it once and reuse for PyVista animations, Rhino colouring, and report plots without re-running the analysis.
# Minimal end-to-end pipeline
from fea_toolkit.io.s2k_parser import SAP2000Parser
from fea_toolkit.opensees.preprocessor import preprocess_model
from fea_toolkit.opensees.analysis_builder import AnalysisBuilder
from fea_toolkit.io.npz_writer import write_results_npz
from fea_toolkit.io.npz_reader import read_results_npz, npz_to_pyvista_frame_mesh
from fea_toolkit.plotting import plot_deformed_displacement_3d, plot_force_diagram
# 1. Parse
md = SAP2000Parser("model.s2k").parse().get_model_data()
# 2. Preprocess — frozen MeshModel topology
mm = preprocess_model(md, {"element_type": "elasticBeamColumn"})
# 3. Analyse — run each static case separately
b = AnalysisBuilder(mm, {})
b.build_domain()
static_dead = b.run_static_analysis(pattern_scales={"DEAD": 1.0})
b.build_domain()
static_wind = b.run_static_analysis(pattern_scales={"WIND": 1.0})
# 4. Save to NPZ as case-keyed mapping
cases = {"DEAD": static_dead, "WIND": static_wind}
write_results_npz("results.npz", md, static_results=cases)
# 5. Visualise from NPZ
data = read_results_npz("results.npz")
plot_force_diagram(data, quantity="Fx", combo="DEAD") # axial force diagramSee also:
local/project_b_linear.py— full end‑to‑end workflow (parse → mesh → split → static → modal → RS → plots → animate)src/fea_toolkit/io/README.md— NPZ schema reference (also indexed fromdocs/documentation_index.md)
The toolkit exposes a set of workflows covering the full pipeline from model parsing through analysis to visualisation and reporting.
| Workflow | Entry point | What it does |
|---|---|---|
Parse SAP2000 .s2k |
SAP2000Parser.parse() → get_model_data() |
Read SAP2000 text export into structured model data |
Parse ETABS .e2k |
ETABSParser.parse() → get_model_data() |
Read ETABS text export into structured model data |
Parse SAFE .f2k / .$sf |
SAFEF2KParser.parse() / SAFEDBParser.parse() → get_model_data() |
Read SAFE tabular / native-database export into structured model data |
| Save/load JSON cache | .to_json() / .from_json() |
Serialise raw parsed tables for reuse without re-parsing |
| Enrich from catalogue | SectionLibrary.enrich_section() |
Populate section dimensions from a manufacturer database |
| Workflow | Entry point | What it does |
|---|---|---|
| Build OpenSees model | preprocess_model() → AnalysisBuilder(mm, cfg).build_domain() |
Preprocess topology into a frozen MeshModel, then construct nodes, restraints, materials, sections, elements, loads |
| Build with shells | preprocess_model(create_shells=True) → AnalysisBuilder(mm, cfg).build_domain() |
Preprocessor creates ShellMITC4 for area elements (with optional loads-only selection); builder then constructs the domain |
| Split elements at joints | preprocess_model(split_elements=True) → AnalysisBuilder(mm, cfg).build_domain() |
Preprocessor subdivides frame elements at intermediate nodes (SAP2000 auto-mesh); builder then constructs the domain |
| Apply frame end offsets | preprocess_model(frame_end_offsets=...) → AnalysisBuilder(mm, cfg).build_domain() |
Preprocessor creates rigid zones at joints via stiff link elements; builder then constructs the domain |
| Mesh area elements | preprocess_model(create_shells=True) → AnalysisBuilder(mm, cfg).build_domain() |
Preprocessor performs bilinear subdivision of quad areas per SAP2000 auto-mesh settings; builder then constructs the domain |
| Apply edge constraints | apply_edge_constraints() |
Tie fine-mesh nodes to coarse edges via equationConstraint |
| Detect unconnected edges | detect_unconnected_edges() |
Diagnostic: find shell nodes on coarse edges not yet connected |
| Record as script | RecordingOpenSees proxy |
Capture all ops.* calls as standalone Python or Tcl script |
| Detect storeys | identify_stories() |
5 strategies to find storey elevations (ETABS story table → diaphragm → area elements → node clustering) |
| Model connectivity check | check_model_connectivity() |
Pre-build scan for orphan nodes, shell-only base fixity, duplicate coordinates |
| Split connectivity check | check_split_connectivity() |
After splitting: zero-length elements, duplicate nodes |
| Mesh connectivity check | check_mesh_connectivity() |
After meshing: unrestrained base mesh, low-connectivity nodes |
| Singularity diagnosis | diagnose_singularity() |
After build: scan OpenSees node DOF, tree-plot distribution |
| Self-weight consistency | check_self_weight_consistency() |
Compare analytical vs applied weight, grouped by section and by material |
| Export to Tcl | export_model_to_tcl() |
Direct SAPModelData → standalone OpenSees Tcl script |
| Workflow | Entry point | What it does |
|---|---|---|
| Linear static | run_static_analysis() |
Nodal displacements, reactions, element forces |
| Modal (eigenvalue) | run_modal_analysis() |
Periods, frequencies, mass participation, mode shapes |
| Response spectrum (CQC) | run_response_spectrum_analysis() |
CQC-combined base shear, moment, element RS forces |
| Pushover (non-linear) | run_pushover_analysis() |
Gravity → displacement-controlled lateral push with fiber sections |
| CSM performance point | compute_performance_point() |
ATC-40 capacity spectrum method |
| Storey displacement | storey_displacements() |
Rigid-body fit (Ux, Uy, Rz) per storey with outlier rejection |
| Storey drifts | storey_drifts() |
Inter-storey drift ratios from rigid-body displacements |
| Modal storey drifts (CQC) | modal_storey_drifts() |
CQC-combined modal drifts using spectral displacement scaling |
| Storey shears/moments | storey_shears() |
Summed element-end forces per storey level |
| Workflow | Entry point | What it does |
|---|---|---|
| Brace buckling check | check_brace_buckling() |
Euler |
| Set brace subdivision | set_brace_selection() |
Mark braces for imperfection + offset (Approach A) |
| ADRS conversion | pushover_to_adrs() |
Convert capacity curve to acceleration-displacement format |
| Capacity spectrum plot | plot_capacity_spectrum() |
ADRS plot with bilinear yield and performance point |
| Workflow | Entry point | What it does |
|---|---|---|
| Export to NPZ | export_results_to_npz() |
Compressed NumPy archive for Rhino/post-processing |
| 3D model (PyVista) | plot_mesh() |
Interactive structural model view |
| Deformed shape (PyVista) | plot_deformed_displacement_3d() |
Displaced shape with colour-mapped displacements |
| Mode shape (PyVista) | plot_mode_animation() |
Animate eigenvector displacements per mode |
| Moment/force flags (PyVista) | plot_force_diagram() |
Flag or tube diagrams in 3D |
| Pushover curve | plot_pushover_curve() |
Pushover capacity curve (base shear vs control displacement) |
| CSM 4-panel | plot_csm_4panel() |
2×2 ADRS plots per push direction |
| Rhino import (centreline) | RhinoImporter.run(create_centreline=True) |
Joint points, frame lines, shell Breps with SAP metadata |
| Rhino import (extrusion) | RhinoImporterV2.run() |
Lightweight Extrusion solids (I/Box/Pipe/Channel/Rect/Circular) |
| Rhino colour from results | apply_results() / colour_from_npz() |
Colour frames/shells and overlay deformed shapes from .npz/.h5/stage files |
| Rhino result flags | create_result_flags() |
3D flag annotations for peak response values |
| Interactive 3D viewer | plot_interactive_viewer() |
Radio buttons, sliders, click-to-inspect in browser |
| Backend-agnostic HTML export | ModelViewer.export_html() |
Self-contained HTML with 3D scene |
| Workflow | Entry point | What it does |
|---|---|---|
| GB 50011 design spectrum | plot_seismic_spectrum(), ResponseSpectrum.from_gb50011() |
GB 50011 elastic spectrum from intensity, site class, level (returns periods, accelerations, and a Matplotlib figure) |
| GB 50011 3-level plot | plot_seismic_spectrum() |
Frequent / fortification / rare spectra overlay |
| Eurocode 8 (EN 1998-1) spectrum | ResponseSpectrum.from_eurocode8() |
EC8 acceleration spectrum from ground type and a_g (= γ_I · a_gR), Type 1 or 2: the design spectrum (§3.2.2.5, with the behaviour factor q) by default, or the elastic spectrum (§3.2.2.2/3) with elastic=True; damping correction η and the vertical component included |
| Eurocode 8 displacement spectrum | ResponseSpectrum.from_eurocode8_displacement() |
EC8 elastic displacement spectrum S_De(T) = S_e(T)·(T/2π)² (§3.2.2.4, Eq. 3.6); q does not enter |
| Workflow | Entry point | What it does |
|---|---|---|
| Model summaries |
report.py functions |
Bounding box, materials, sections, masses, load totals |
| Modal table (6-DOF) | modal_table_enhanced() |
Periods + rotational mass participation |
| Brace buckling table | brace_buckling_check() |
|
| Storey force plots | plot_storey_forces() |
Shear/moment profiles with analytical trapezoidal curves |
| Storey displacement plots | plot_storey_displacements() |
Storey displacement & drift side-by-side |
| Modal participation plot | plot_modal_participation() |
Bar chart of mass participation ratios |
| RS modal analysis plot | plot_rs_modal_analysis() |
Periods, base shear, storey forces combined |
| CSM 4-panel plot | plot_csm_4panel() |
2×2 ADRS plots per push direction |
| Seismic spectrum plot | plot_seismic_spectrum() |
GB 50011 elastic spectrum (1- or 3-level) |
| Storey story plot (3D) | plot_stories() |
PyVista render with semi-transparent storey planes |
| Script | Purpose |
|---|---|
examples/basic_usage.py |
File chooser → parse → enrich → build → static analysis |
examples/static_analysis.py |
Parse → build → static → 2D/3D force diagrams |
examples/modal_rs_analysis.py |
Parse → build → masses → modal → GB 50011 RS → element RS forces |
examples/pushover_analysis.py |
Parse → fiber build → pushover → deformed shape plots |
Project-specific drivers (e.g. the CSM pipeline and edge detection) live in the
private, gitignored local/ directory and are not part of the distribution.
generate_report() (in report.py, re-exported from fea_toolkit) runs the
full two-stage pipeline — preprocess → modal → response spectrum → pushover →
combination reduction → storey response → CSM — and returns the canonical result
dict. It is driven by a nested Python dict config (config=…, deep-merged
over the defaults, with **overrides using __ as a nesting separator) —
not a YAML file. Figures are written to ./output (or out_dir); with
config={"export": {"enabled": True}} it additionally writes a single
self-contained .h5 / .npz archive (default .h5) bundling the model
stages and results.
The self-contained HTML/PDF report-rendering stage is still designed but not yet
implemented — see docs/report_generation.md (draft). The pipeline's analysis
stages are also scheduled to become workflow verbs so generate_report and the
recipe layer compose the same registry (workflow Phase E, docs/workflow_authoring.md).
Two optional subpackages provide mesh quality diagnostics and Gmsh-based constrained quadrilateral remeshing. Neither is imported by the core workflow — they must be explicitly imported after a build.
Report orchestration and the pandas summary/figure helpers are also
optional: pip install -e ".[report]" (from the cloned source — the toolkit
is not on PyPI; see Licence and Disclaimer). The
rest of the toolkit imports cleanly without pandas (the report modules raise a
clear RuntimeError only when a pandas-dependent helper is actually
called).
The test suite, by contrast, runs with the extra installed — CI does
pip install -e ".[report,mesh-remesh]" — so a test module that exercises
pandas-backed helpers imports pandas at module level; a test that must
also collect on a minimal pip install -e . uses
pytest.importorskip("pandas") at the point of use. Never
__import__("pandas") or an unguarded function-local import pandas in a
test body. See docs/dev_notes.md → Optional dependencies in tests — the
pandas policy.
# Mesh quality checks (NumPy only — no extra install needed)
from fea_toolkit.mesh import checks as mesh_check
# After building with shells:
quality = mesh_check.report(builder.model.area_elements, builder.model.nodes)
if not quality["passed"]:
for w in quality["warnings"]:
print(w)# Constrained remeshing via Gmsh: pip install fea_toolkit[mesh-remesh]
from fea_toolkit.mesh import remesh
# Build line constraints from frame elements that connect to area edges
constraints = {}
for fid, fe in model.frame_elements.items():
for aid, ae in model.area_elements.items():
if fe.node_i in ae.node_ids and fe.node_j in ae.node_ids:
remesh.constrain_line(aid, fid, fe.node_i, fe.node_j, model.nodes, constraints)
# Remesh via Gmsh (replaces built-in structured subdivision)
areas, assign, nodes, ntag = remesh.remesh_areas(...)| Function | What it measures | Warning threshold |
|---|---|---|
aspect_ratios() |
Longest / shortest edge per quad | > 4.0 |
skew() |
Max deviation from 90° interior angles | > 30° |
flatness() |
True non-planarity (tet height / avg edge) | > 0.02 |
report() |
Combined report with warnings | Configurable |
All functions work with the same {area_id: AreaElement} / {node_id: Node}
dicts used throughout the builder. No external dependencies (pure NumPy).
| Function | Purpose |
|---|---|
remesh_areas() |
Replace structured subdivision with Gmsh-generated quads |
constrain_line() |
Register a frame edge as a mesh constraint |
Line constraints ensure that frame-element edges crossing an area
boundary are preserved in the Gmsh mesh — the mesh conforms to those
lines automatically, eliminating the need for post-process
equationConstraint. Powered by the Gmsh Python API (GPL v2+).
Constrained curves are embedded in the OCC model before mesh generation so the mesher respects them natively.
Relation to built-in meshing:
| Aspect | Built-in mesh_area_elements |
remesh_areas() |
|---|---|---|
| Mesh type | Structured (grid) | Unstructured (Gmsh) |
| Element size | Uniform max_size |
Graded via characteristic length |
| Edge constraints | Post-process equationConstraint |
Native via embedded curves |
| Dependencies | None (pure NumPy) | gmsh (GPL v2+) |
| Recommended for | Simple rectangular areas | Warped quads, complex boundaries |
The builder supports two hinge modelling strategies for non-linear pushover
analysis, controlled by the hinge_model config option.
Uses forceBeamColumn elements with fiber sections. Each cross-section
is discretised into fibres (concrete patches + steel rebar layers for RC,
flange/web rectangles for steel). P-M-M interaction is captured implicitly
as individual fibres yield.
Fiber is required for pushover. Because pushover is nonlinear, the distributed-plasticity path requires every frame section to implement
to_fiber_patches(). A model with only elasticSectionproperties cannot yield, so the runner raisesValueErrorinstead of silently degrading to a linear "pushover". Usemake_nonlinear_sample_model()(or typed sections), or opt into lumped plasticity (§10.2) for the hinge-based alternative.
Steel sections — the existing to_fiber_patches() on ISection,
PipeSection, BoxSection, etc. generates rectangular patch definitions.
RC sections — two new section types support concrete fibre modelling:
| Section class | SAP2000 shape | Concrete layering |
|---|---|---|
ConcreteRectangularSection |
Concrete Rectangular |
Confined core + unconfined cover + steel rebar layers |
ConcreteCircularSection |
Concrete Circular |
Confined core ring + unconfined cover ring + rebar ring |
Material tags are allocated per fiber role (see
Section.fiber_roles()), each role fixing its OpenSees uniaxial law::
"steel" → structural steel (Steel01)
"concrete" → unconfined concrete cover/fill (Concrete01)
"core" → confined concrete core (Concrete01, Mander enhanced)
"rebar" → steel rebar (Steel02)
to_fiber_patches(materials, nfy, nfz) takes a role → tag mapping rather
than a single mat_tag plus +1/+2 offsets, so composite sections
(encased steel, concrete-filled tube) can carry steel + concrete + rebar in
one section.
Uses zeroLength elements at member ends with an elastic interior.
This path directly replicates SAP2000's ASCE 41 hinge assignment::
structural_node_i → hinge_i → elastic_mid → hinge_j → structural_node_j
Key implementation details:
-
Coincident nodes are created at each element end with the same coordinates.
-
zeroLength+-mat/-dircarries all six DOFs with noequalDOF: rigidElasticmaterials retain the retained DOFs (P, Vy, Vz, T), while the two rotational DOFs are carried by the hinge backbone materials.hinge_backboneselects the rotational law:hinge_backboneRotational law "asce41"(default)Hystereticmatched to ASCE 41 rotation limits"bilinear"Steel01(yieldMy = Z·fy,hardening_ratio)"trilinear"Hysteretic(Ohtorimat_tblEI1/EI2/EI3 + d1/d2)"imk"IMKBilin(Lignos-Krawinkler, collapse-level) -
ASCE 41-17 §10.8 hinge length:
fea_toolkit.capacity.asce41.hinge_lengthimplements Eq 10-1 / 10-2 / ACI formulas for steel, brace, and RC members.
Configure with::
config = {
'hinge_model': 'lumped', # default: 'fiber'
# ... other builder options ...
}
A separate concentrated-plasticity element, hinge_model: 'beam_with_hinges',
replaces the zero-length hinge assembly with an elastic interior plus a
trilinear moment-curvature Uniaxial (strong-axis Mz) hinge section at
each end — no "nearly rigid" spring, so the elastic stiffness is the exact
6EI1/L. The plastic hinge length hinge_length_fraction (default
1/6) converts curvature to member-end rotation (θ = φ·L/6). Supported
hinge_backbone values are "trilinear" (Hysteretic),
"trilinear_steel02" (two Steel02 springs in parallel) and
"trilinear_clough" (Hysteretic with Clough/Takeda unloading-stiffness
degradation, β = 0.5). See docs/modeling_guidance.md
for guidance on choosing a hinge formulation.
fea_toolkit.capacity.asce41.hinge_length(md, sec_name, elem_length)
(legacy alias: model.checks.compute_asce41_hinge_length) returns the
plastic hinge length per ASCE 41-17:
| Member type | Formula (Lp) | Reference |
|---|---|---|
| Steel moment frame | 0.08L + 0.022 · db · fy | ASCE 41 Eq 10-1 |
| Steel brace | 0.08L + 0.015 · db · fy | ASCE 41 Eq 10-2 |
| RC beam/column | 0.05L + 0.1 · db · fy / √fc | ACI 318 |
| Fallback (no data) | max(0.05, 0.1L) | — |
All formulas are capped at 0.33L per ASCE 41.
Fiber pushover (steel)::
mm = preprocess_model(md, {'split_elements': True})
builder = AnalysisBuilder(mm, {
'create_fiber_sections': True,
'element_type': 'forceBeamColumn',
'hinge_model': 'fiber',
})
builder.build_domain()
builder.compute_seismic_masses()
modal = builder.run_modal_analysis(num_modes=3)
shapes = builder.extract_mode_shapes(3)
results = builder.run_pushover_analysis(
gravity_patterns={'DEAD': 1.0},
lateral_load_type='uniform',
)
Lumped plasticity pushover (steel or RC)::
mm = preprocess_model(md, {'split_elements': True})
builder = AnalysisBuilder(mm, {
'use_elastic_sections': True,
'hinge_model': 'lumped',
})
# ... same analysis pipeline ...
RC fiber pushover: parser automatically creates
ConcreteRectangularSection or ConcreteCircularSection for
Concrete Rectangular / Concrete Circular SAP2000 shapes::
mm = preprocess_model(md, {'split_elements': True})
builder = AnalysisBuilder(mm, {
'create_fiber_sections': True,
'element_type': 'forceBeamColumn',
})
builder.build_domain() # confined/unconfined/steel materials created automatically
Not all OpenSees element types support the same eleLoad -type -beamUniform argument forms. The builder handles this automatically:
| Element type | 3-arg uniform (wy, wz, wx) |
5-arg partial (wy, wz, wx, aL, bL) |
Trapezoidal / linear varying |
|---|---|---|---|
elasticBeamColumn |
✅ Native | ✅ Native | ❌ Decomposed to equivalent uniform |
forceBeamColumn |
✅ Native | ✅ Native | ❌ Decomposed to equivalent uniform |
dispBeamColumn |
✅ Native | ✅ Native | ❌ Decomposed to equivalent uniform |
nonlinearBeamColumn |
✅ Native | ✅ Native | ❌ Decomposed to equivalent uniform |
Notes:
- The 8‑argument trapezoidal form
(wy1, wz1, wx1, aL, bL, wy2, wz2, wx2)is broken in OpenSeesPy 3.8.0.0 — the end values (wy2etc.) are silently ignored. The builder therefore decomposes non‑uniform loads into 4 partial‑ span uniform segments (using the working 5‑argument form), which preserves both the total force and the moment distribution. Corotationalgeometric transformation does not supporteleLoadin 3D (per the OpenSees documentation). If you use'geom_transf_type': 'Corotational', the builder will emit a warning. Use :func:beam_load_to_nodal_loadsfromfea_toolkit.model.geometryto convert distributed loads into equivalent nodal loads as a workaround.
SAP2000/ETABS models use a variety of cross‑section shapes. The Section dataclass in sap_data.py has been refactored into a polymorphic hierarchy so that each shape stores only its relevant geometric parameters:
| Class | SAP2000 shape names | Shape‑specific fields | Fiber patches |
|---|---|---|---|
Section (base) |
(generic / unknown) | — | ❌ NotImplementedError |
ISection |
I/Wide Flange, WIDE FLANGE, Steel I/Wide Flange |
depth, bf, tf, tw |
✅ 3 rect patches (bot flange → web → top flange) |
ChannelSection |
Channel, Steel Channel, Concrete Channel |
depth, bf, tf, tw |
✅ 3 rect patches (web + 2 flanges, centroid-shifted) |
AngleSection |
Angle, Steel Angle, Concrete Angle |
depth, bf, tf, tw |
✅ 2 rect patches (2 legs, centroid-shifted) |
DoubleAngleSection |
Double Angle, Steel Double Angle |
depth, bf, tf, tw, dis |
✅ 4 rect patches (2 back-to-back angles, centroid-shifted) |
TeeSection |
Tee |
depth, bf, tf, tw |
✅ 2 rect patches (flange + stem, centroid-shifted) |
PipeSection |
Pipe, Steel Pipe, Concrete Pipe, Filled Steel Pipe |
od, t |
✅ 1 annular circ patch |
BoxSection |
Box/Tube, Steel Tube, Concrete Tube, Filled Steel Tube |
depth, bf, tf, tw |
✅ 4 rect patches (flanges + webs) |
RectangularSection |
Rectangular, Rectangle, Steel Plate, Concrete Rectangular |
depth, bf |
✅ 1 rect patch |
CircularSection |
Circle, Steel Rod, Concrete Circle |
diameter |
✅ 1 solid circ patch |
GeneralSection |
General, NA |
— | ❌ Requires a known shape |
SDSection |
SD Section |
polygons (multi‑material) |
A/I33/I22/J from the polygon (shoelace); fiber meshing deferred |
EncasedSection |
Concrete Encasement Rectangle/Circle |
embedded_section, encasement_depth/bf |
|
ConcreteFilledTubeSection |
(programmatic only — parsers map Filled Steel Tube to BoxSection) |
depth, bf, tf, tw, fill_material |
|
ConcreteFilledPipeSection |
(programmatic only — parsers map Filled Steel Pipe to PipeSection) |
od, t, fill_material |
|
ShellSection |
Shell |
thickness |
❌ Not applicable |
All section classes inherit the common derived properties (A, I33, I22, J) directly from the SAP2000 text file, which includes pre‑computed values. The to_fiber_patches() method on each class generates OpenSees patch('rect', …) definitions for nonlinear fiber‑section analysis.
When the parser encounters a FRAME SECTION PROPERTIES 01 - GENERAL table, it dispatches to the correct subclass based on the Shape field, extracting SAP2000 dimension keys (t3 → depth / OD, t2 → width, tw, tf) into the appropriate fields.
The :class:Selection class (src/fea_toolkit/model/selection.py) provides a
flexible, composable way to pick subsets of model elements for targeted
operations. It is used, for example, to control which area uniform loads
get converted to equivalent frame edge loads during model building.
Logic rules
- AND across criteria — every non-
Nonefield narrows the selection. An element must satisfy all of them to be included. - OR within a list — multiple values in the same field are alternatives; an element matching any of them passes that criterion.
Available criteria
| Field | Scope | Description |
|---|---|---|
element_types |
All | 'Frame', 'Area', 'Node' (or a list) |
sections |
Frame, Area | Section/property name(s) — checked via assignment maps |
materials |
Frame, Area | Material name(s) — resolved through the assigned section |
groups |
All | Group name(s) — matched against Group.objects (e.g. "Frame:123") |
element_ids |
All | Specific ID(s) for exact targeting |
Key methods
| Method | Returns | Purpose |
|---|---|---|
get_frame_ids(model) / get_area_ids(model) / get_node_ids(model) |
List[str] |
Get matching element IDs |
filter_frames(model) / filter_areas(model) / filter_nodes(model) |
Dict[str, Element] |
Get matching element objects |
filter_area_uniform_loads(model) |
List[AreaUniformLoad] |
Uniform loads on selected areas |
filter_area_gravity_loads(model) |
List[AreaGravityLoad] |
Gravity loads on selected areas |
Example — convert only slab area loads
from fea_toolkit.model.selection import Selection
sel = Selection(
element_types=["Area"],
sections=["Slab 200mm", "Roof 150mm"],
)
builder.build(selection=sel)Only area loads on the two slab sections are converted to frame edge loads; all other area loads are ignored.
To exclude instead of include, prefix a key with NOT —
Selection.from_string("NOT section=Slab 200mm") selects everything except
that section.
The canonical, priority-ordered backlog lives in
docs/_pending_work.md. Items below are reconciled with that register; P-item cross-references are in brackets.
-
Frame‑Frame Intersection Splitting ✅
-
AtFrames=Truesplitting at frame-frame intersections is implemented (model/geometry_frames.pysplit_elements()), parser-wired (FRAME AUTO MESH ASSIGNMENTS→SAPModelData.frame_auto_mesh), and unit-tested (TestSplitElementsAtFrames+ parser round-trip tests).
-
-
ETABS
.E2K/.$ETinput⚠️ Partial-
ETABSParser(io/e2k_parser.py) reads geometry, sections, materials, restraints, loads, load cases/patterns, mass sources and combinations from an ETABS text export into the sameSAPModelData, and is wired throughload_model_data(), the review CLI, the GUI file dialog and the examples. - Open gaps: object auto-meshing (M6),
AUTOSECTIONauto-select lists, multi-tower elevations, and real-export section-name gaps (storeys- FOR EACH TOWER, splitSLAB/DECK/WALLproperties) that leave geometry empty on real exports. Seedocs/e2k_import_plan.md.
-
-
CSi SAFE
.f2k/.$sfinput⚠️ Partial-
SAFEF2KParser/SAFEDBParser(io/f2k_parser.py,io/safe_db_parser.py) read SAFE tabular and native-database exports into the sameSAPModelData— points, slab/wall/beam/column objects, section assignments, point/line/area springs, tendons, design strips, punching-shear overwrites, loads, cases/combos, groups and mass source — and are wired throughload_model_data(). - Floor meshing (
mesh/floors.py, gmsh) turns SAFE'sn-gon slab objects (with openings, drop panels and stiff zones) into buildable shell elements. - Soil/foundation springs resolve to node-level
zeroLengthsupports (compression-only viaENTwhensoil_spring_compression_onlyis set). - Parse-only (not yet analysis-modelled): tendons (prestress), design strips
and punching-shear overwrites. See
docs/safe_import.md.
-
-
Load Combinations and Analysis Types
-
✅ Parsed byMassSource_get_mass_sources()and stored inSAPModelData.mass_sources. -
✅ Parsed byLoadCaseget_load_cases()—LOAD CASE DEFINITIONS,CASE - RESPONSE SPECTRUM(general + load assignments),CASE - MODAL,CASE - STATIC(see the "Key Components Implemented" table above). \ -
✅ Parsed byLoadCombination_get_load_combinations()from theCOMBINATION DEFINITIONStable and stored inSAPModelData.load_combinations— combo type, design overrides, and a lossless, order- and duplicate-preservingentrieslist ofLoadCombinationEntry(name, factor,kind= case/combo/unknown, optional modalMode). -
Load-combination trees & composite results✅model.load_combinationsmaterialises the reference graph (build_combo_tree), aggregates linear factors (expand_linear_combination) and generates composite load cases (generate_combination_results): a response-spectrum or SRSS term mixed with gravity forks into+/−composites, andEnvelopeyields a max/min pair or one composite per branch.generate_composite_results()turns them into NPZ-ready result sets, so a combination can be visualised exactly like a load case. Seedocs/load_combinations.md(⚠️ Absolute AddandRange Addnot yet implemented). \ -
Combination results export✅analysis.combinations.build_combination_results()expands the model's combinations against the run load-case payloads, andAnalysisBuilder.export_results(..., model=md, expand_combinations=True)writes the composites into the NPZ asstatic/{composite}/...cases — ready for the force-diagram and viewer tools (tracked as P12 indocs/_pending_work.md).
-
-
Advanced Analyses
-
Modal Analysis✅run_modal_analysis()implemented — eigenvalue extraction with modal properties table. -
Response Spectrum✅run_response_spectrum_analysis()+extract_element_rs_forces(); the rigid / missing-mass correction (spectrum.cqc_base_shear(...)) is wired intoAnalysisBuilder.run_response_spectrum_analysis()behind the opt-inconfig["missing_mass"]gate. -
Nonlinear Static Pushover✅run_pushover_analysis()implemented — seedocs/pushover_analysis.md. -
HingeRadau integration✅beam_integrationconfig option ('Lobatto'/'HingeRadau'). -
Brace subdivision (Approach A)✅subdivide_elements()ingeometry.py,set_brace_selection()/check_brace_buckling()in builder. -
Brace buckling (Approach B — truss + Hysteretic)✅brace_trussconfig option,Hystereticmaterial with asymmetric tension/compression. Seedocs/pushover_analysis.md. -
Configurable solver settings✅solver_test_tol,solver_test_max_iter,solver_algorithm,gravity_num_substepsbuilder config options. -
Brace detection✅Selection.from_brace_sections(). -
Buckling eigenvalue benchmark✅ SciPy-based independent validation — subdivided column buckling matches Euler within 0.01 %. -
Capacity Spectrum Method✅pushover_to_adrs()+compute_performance_point()+plot_capacity_spectrum()— seedocs/pushover_analysis.md. -
Nonlinear Time History (Tcl/Xara ground-motion path)✅run_nonlinear_dynamic_analysis()implemented — ground-motion input + transient analysis via Tcl export and Xara/OpenSeesRT, with Rayleigh damping from a preceding modal analysis (seedocs/nonlinear_dynamic_analysis.md). - Nonlinear Time History (additional integration schemes) – Python-native integration schemes (e.g. direct OpenSeesPy transient analysis) remain planned.
-
-
Joint Modeling (for concrete frames)
- Level 1 (rigid joint end zones) ✅ —
rigid_end_zonesauto-generates offsets (0.5 x intersecting depth) withrigid_link_mpcMPC links. - Extend parser to recognise joint elements (if present in SAP2000) — tracked as P13 in
docs/_pending_work.md. - Implement
Joint2DandbeamColumnJointelements inAnalysisBuilder(Level 3) — P13.
- Level 1 (rigid joint end zones) ✅ —
-
Brace gusset plates / joint offsets
- ✅ Rigid offset segments between working point and brace physical end (
brace_end_offset/subdivide_elements(end_offset=...)). - Open: gusset plate flexibility as rotational springs at brace ends.
- See
docs/pushover_analysis.mdfor discussion of approaches.
- ✅ Rigid offset segments between working point and brace physical end (
-
Rhino Importer Refactoring ✅ —
rhino/importer.py(RhinoImporter) readsSAPModelDatadirectly and creates lightweight Extrusions;rhino/layers.py+rhino/colors.pyhandle section-based layers and FEA metadata.
See examples/README.md for quick-start examples.
All feature‑specific documentation (analysis types, model features, export,
visualisation, tool‑specific workflows) is indexed in
docs/documentation_index.md — grouped by category with a tag‑based
cross‑reference section.
-
Improved Load Handling
- Point loads on frames (
FRAME LOADS - POINT) — parsed intoframe_point_loadsand visualised (⚠️ OpenSeeseleLoadpropagation still open, P14 indocs/_pending_work.md). - Area uniform loads — visualised as a grid of arrows or a one-sided extrusion flag over the shell face, with an optional pressure colour-fill that recolours the shells themselves and per-element load values in the GUI Inspector. Applied-load glyphs draw only on the elements they act on, so hiding a beam/slab/node hides its loads.
- Temperature loads — only if needed (no current demand; P14).
- Option to convert linear loads to uniform (simplification) via config flag.
- Point loads on frames (
-
Result Extraction
- Extend the analysis runners to return reactions, internal forces, and mode shapes where not already returned.
- Deeper
opstoolintegration — closed as no current demand (seedocs/report_generation.md; NPZ ↔ opstool ODB converter deferred).
-
Documentation
- Write full API docs (Google style already in code).
- Create a user guide (examples, how to run different analyses).
-
Testing
✅ Populated — CSM/bilinearization (test_model.pyis yet to be populatedtest_csm.py), Euler buckling benchmark (test_buckling.py), load dataclasses (test_sap_data.py), Mander confinement wiring (test_confinement.py,test_analysis_csm.py), mesh edge-restraint propagation.Add unit tests for✅ Covered inSectionLibrary,SAPModelDatadataclasses, and geometry utilitiestest_sections_selection.py,test_sap_data.py,test_geometry_core_frames.py,test_mesh_units.py,test_confinement.py.Add integration tests for the two-stage pipeline✅ Covered intest_workflows.py,test_rc_pushover.py,test_layered_shell.py,test_wall_pushover.py.Add tests for✅split_elementsTestParserModelIntegration::test_split_elements{,_tracking}andTestBuildWorkflow::test_build_with_split_elements; trapezoidal-load decomposition remains an open sub-item.De-duplicate repeated visualisation-test boilerplate✅ Centralised intests/conftest.py: the matplotlib Agg backend (autouse, module-scoped) and the suite-wide PyVista probe +OFF_SCREEN; per-file_has_pyvista/_skip_if_no_pyvista/_needs_pyvistaguards and duplicate notebook-warning filters were replaced by the@pytest.mark.needs_pyvistamarker (registered inpyproject.toml). See.clinerules§5.5.
- Parallel Processing – Not planned (large-model splitting/analysis parallelisation).
- Graphical User Interface – 🚧 In progress: native Qt (PySide6)
desktop app, shipped as an optional
[gui]extra. Seedocs/gui_roadmap.mdand P22 indocs/_pending_work.md. - Other FEA Formats – Abaqus
.inp, Ansys.cdb– not planned.
The SAP2000 → OpenSees pipeline is now largely functional. You can parse a model, split elements and loads (including frame-frame intersections), build an OpenSees model, and run linear static, modal, response-spectrum, pushover and nonlinear dynamic (time-history) analyses. The code is modular and well‑structured; the priority-ordered backlog lives in docs/_pending_work.md.
The project is well on track to meet your original goals. Let me know which of the remaining tasks you would like to tackle next, and I will provide the necessary code and guidance.
openseespy.opensees and opstool are C extensions (compiled .so files). Pylance cannot statically inspect C extensions, so it flags every ops.xxx() call as "xxx" is not a known attribute — even though the calls work fine at runtime.
The fix is to provide type stubs that tell Pylance these modules are dynamically typed.
The project ships with detailed type stubs covering every OpenSees and opstool function used in the source code:
typings/openseespy/opensees/__init__.pyi — 22 functions with named parameters and docstrings:
| Category | Functions |
|---|---|
| Domain/model | wipe(), model(), node(), fix(), nodeCoord(), nodeDisp() |
| Section | section() |
| Geometry | geomTransf() |
| Elements | element(), beamIntegration(), eleNodes(), eleResponse() |
| Loads | timeSeries(), pattern(), load(), eleLoad() |
| Analysis | constraints(), numberer(), system(), test(), algorithm(), integrator(), analyze() |
| Recorder | recorder() |
| Material | uniaxialMaterial() |
Plus a __getattr__ fallback for any undocumented functions.
typings/opstool/__init__.pyi + typings/opstool/post/__init__.pyi — CreateODB(), save_model_data(), get_model_data() with typed parameters.
In .vscode/settings.json (already created):
{
"python.analysis.stubPath": "typings"
}Run Developer: Reload Window in VS Code so Pylance picks up the changes.
Status note (2026-08-23):
run_nonlinear_dynamic_analysis()is now implemented via the Tcl export + Xara/OpenSeesRT path (seedocs/nonlinear_dynamic_analysis.md). The outstanding item is a Python-native transient integration (no Tcl/Xara dependency); the building blocks below describe that native path.
A run_time_history_analysis() method is needed. Below are the building blocks required, along with recommendations based on published OpenSees practice.
| Item | Detail | Priority |
|---|---|---|
| Transient integrator |
Newmark (constant acceleration, HHT ( |
High |
| Damping | Rayleigh damping (ops.rayleigh) from mass‑ and stiffness‑proportional coefficients ( |
High |
| Ground motion input |
ops.timeSeries('Path', …) + ops.pattern('UniformExcitation', …) for uniform base excitation. Multi‑support excitation requires ImposedMotion. |
High |
| Dynamic recorders |
ops.recorder('Node', …) for displacement/velocity/acceleration at control nodes; ops.recorder('Element', …) for brace axial forces. |
High |
| Material improvements | The Hysteretic material in Approach B lacks cyclic degradation. OpenSees offers better alternatives for braces under cyclic loading (see below). |
Medium |
| Convergence under dynamics | Transient analysis may require KrylovNewton or NewtonLineSearch for brace buckling cycles. Test tolerance should be |
Medium |
Based on the OpenSees workshop examples (Workshops/OpenSeesDays/Steel2dModels/) and published research:
| Material | Use case | Cyclic degradation? | Fatigue? | Notes |
|---|---|---|---|---|
Hysteretic (current) |
Static pushover only | ❌ No | ❌ No | Simple backbone, no cycle‑to‑cycle change. Adequate for monotonic pushover only. |
Hysteretic + Fatigue |
Cyclic dynamic | ❌ No (Hysteretic) | ✅ Yes (Coffin‑Manson) | Implemented. Wrap Hysteretic with Fatigue via brace_fatigue=True. Asymmetric buckling + low-cycle fracture. Recommended for dynamic analysis. |
Steel02 + Fatigue |
Cyclic dynamic | ✅ Yes (Bauschinger) | ✅ Yes (Coffin‑Manson) | Preferred for subdivided beam-column elements (fiber section buckling). Used in OpenSees Day CBF examples (CBFbase.tcl). Not suitable for truss approach (Steel02 is symmetric). |
BraceMaterial |
Cyclic dynamic | ✅ Yes (damage) | ✅ Yes (energy‑based) | Specialised uniaxial brace model with pinching + damage. Not available in OpenSeesPy (tested). |
Pinching4 |
Cyclic dynamic | ✅ Yes (degradation) | ❌ No | Not available in OpenSeesPy with this version. |
Recommendation: For nonlinear dynamic analysis with the truss approach, use Hysteretic + Fatigue (brace_fatigue=True). For subdivided beam-column elements (if the convergence issue is resolved), use Steel02 + Fatigue.
- Use
Transformationconstraints (already the default) —Plainis unreliable for large 3D models. - Use
BandGensystem (already the default) —ProfileSPDorSparseSYMare alternatives for larger models but slower. - Consider a two‑stage analysis:
Transient(ground motion) →Static(residual gravity check). OpenSeesloadConst('-time', 0.0)separates stages naturally. - For gravity + earthquake, apply gravity first with
LoadControl, thenloadConst('-time', 0.0)before starting the transient analysis.
These approaches are documented in the OpenSees literature but have not been implemented in fea_toolkit:
| Approach | Element type | Material | Geometry | Works for static? | Works for dynamic? | Notes |
|---|---|---|---|---|---|---|
| A — Subdivided beam‑column | dispBeamColumn |
Fiber (Steel01) | PDelta / Corotational | ❌ Gravity convergence fails | ❌ Not tested | The subdivided elements + PDelta create an ill‑conditioned stiffness matrix. No imperfection also fails. See docs/pushover_analysis.md. |
| B — Truss + Hysteretic (current) | Truss |
Hysteretic |
None (axial only) | ✅ Works | Recommended for static. For dynamic, enable brace_fatigue=True to wrap with Fatigue for low-cycle fracture. |
|
C — beamWithHinges |
beamWithHinges |
Fiber (Steel01) | Corotational | ❓ Not tested | ❓ Not tested | Plastic hinge ends + elastic interior. More stable than full‑length fiber subdivision. Used in some OpenSees examples. |
D — corotTruss |
corotTruss |
Hysteretic / Steel02 |
Built‑in corotational | ❓ Not tested | ❓ Not tested | Truss element with corotational formulation. Captures large‑displacement axial response. |
E — Pinching4 truss |
Truss |
Pinching4 |
None (axial only) | ✅ Should work | ✅ Should work | Good for braces with pinched hysteresis and cyclic degradation. |
| F — Steel02+Fatigue truss | Truss |
Steel02 + Fatigue |
None (axial only) | ✅ Should work | ❌ Not suitable | Steel02 is symmetric — cannot capture asymmetric tension/compression buckling. Use Hysteretic + Fatigue (Approach B) instead. |
Overall recommendation for brace modelling:
| Analysis type | Recommended approach |
|---|---|
| Static pushover (current) | Approach B (Truss + Hysteretic) — already working |
| Nonlinear dynamic (future) | Approach B (Truss + Hysteretic + Fatigue) — already implemented (brace_fatigue=True) |
The subdivided element approach (subdivided dispBeamColumn + fiber sections + PDelta/Corotational) fails at the gravity stage even after fixing:
- ✅ Missing
set_brace_selection()call - ✅
split_elementsconflict (split_elements=Falsenow used) - ✅ Double subdivision on rebuild (inactive‑element check)
- ✅
forceBeamColumn→dispBeamColumnelement‑level fix - ✅ Node creation during rebuild (tracked via
_created_node_tags) - ✅ Rigid‑link section parameter order (E/A swapped)
- ❌ Gravity convergence still fails — subdivided
dispBeamColumnelements with PDelta geometry cannot converge under ~7.5 MN of gravity load, even with 100 sub‑steps, no imperfection, NormUnbalance, and KrylovNewton.
The root cause appears to be the shared‑node connectivity between subdivided braces and existing frame elements — the PDelta geometric stiffness contributions from multiple subdivided elements at the same node create an ill‑conditioned system matrix.
The following items are the highest-impact improvements identified during a codebase-wide review:
-
Create
fea_toolkit/spectrum.py— ✅ Done:_gb50011_spectrum(),_build_spectrum(),_interp_sa(), andplot_seismic_spectrum()live insrc/fea_toolkit/spectrum.py;AnalysisBuilderconsumes them for RS and CSM. -
Create
fea_toolkit/io/report.py— ✅ Done: the generic SAP2000→pandas summary functions live insrc/fea_toolkit/io/report.py. -
Create
fea_toolkit/utils.py— ✅ Done:deep_merge(),infer_loads(),build_gravity_patterns(),pick_wind(),g_from_units()etc. live insrc/fea_toolkit/utils.py. The Euler buckling check was consolidated intomodel/checks.py(check_brace_buckling()+ DataFrame variantbrace_buckling_check()), importable without an OpenSees builder. -
Create
fea_toolkit/plotting/report.py— ✅ Done: matplotlib report figures live insrc/fea_toolkit/plotting/report.py. -
Split
builder.py— ✅ Done: replaced by the two-stage pipeline. Topology mutation lives inopensees/preprocessor.py(produces a frozenMeshModel); OpenSees domain construction + analysis execution live inopensees/analysis_builder.py;opensees/builder.pynow only exports standalone Tcl-export functions. -
Add unit tests — ✅ Largely done:
tests/mirrorssrc/with 1,600+ tests covering the pipeline, pushover, CSM, capacity, storey response, meshing, and the extracted modules. Shared visualisation-test infrastructure (matplotlibAgg, the suite-wide PyVista probe and theneeds_pyvistamarker) lives intests/conftest.py— see.clinerules§5.5.
The priority-ordered pending-work register lives in
docs/_pending_work.md ("PENDING — active"), with
detailed designs in docs/force_diagram_unification.md and the deprecation
plan. In summary:
- Phase B — force-diagram unification — the four legacy entry points
(
plot_rs_force_diagram(),plot_force_diagram_3d(),plot_npz_force_diagram(),plot_npz_moment_3d()) are now a single unit-awareplot_force_diagram()dispatcher (detailed design →docs/force_diagram_unification.md); the legacy wrappers were removed 2026-08-24. - Module splits (done 2026-08-27) —
opensees/analysis_builder.py(previously ~7.4k lines) is now a 563-line facade over domain/runner mixins;plotting/viz.pyandmodel/geometry.pyare pure re-export facades over the split implementation modules;utils.pyis a re-export facade over_unit_scaling.py,_loads_infer.py,_flags.pyand_cqc.py;plot_seismic_spectrummoved toplotting/seismic_spectrum.py; the IO writers shareio/_serial.py;tests/test_model.py(6.1k lines) was split into four mirror files (test_sap_data.py,test_sections_selection.py,test_geometry_core_frames.py,test_analysis_csm.py), and thetest_extracted.pygrab-bag was later dissolved into its mirror files (test_spectrum.py,test_loads_infer.py,test_flags.py,test_csm.py,test_buckling.py) with parser/geometry/confinement classes returned to their owners. - Pushover solver tuning (empirical pass) ✅ P3 and CSM Gap-4
benchmark validation ✅ P4 landed 2026-08-24. The follow-on
shear-failure / post-peak modelling P5 closed 2026-08-25 as
"documented, not reproduced" (documented-partial fallback — the V&E
descent is flexure-softening, not shear; the P4 re-check and the V&B
(1990) variant are deferred). See
docs/deprecation_plan.md§5–6 and the Tier-2 record indocs/_pending_work.md. - Section fiber patches — ✅ P6a done 2026-08-25 for
Channel/Angle/DoubleAngle/Tee; 🚧 P6b pending forSDSection(polygon meshing).EncasedSectionand the CFT sections (ConcreteFilledTubeSection/ConcreteFilledPipeSection) are implemented via the role-based fiber contract; the CFT concrete-fill confinement model is deferred (seedocs/cft_confinement_plan.md). - Python-native nonlinear dynamic integration 🚧 P7 pending — the
Tcl/Xara ground-motion path is complete; a native OpenSeesPy transient
runner remains planned. See the Tier-3 items in
docs/_pending_work.md.
- ✅ Deleted stale files:
src/fea_toolkit/opensees/builder_ss.pyandsrc/fea_toolkit/model/geometry_ss.py— old versions, never imported anywhere.
- OpenSeesPy Examples
- Tutorial
- AmirHosseinNamadchi - OpenSeesPy-Examples
- Brainery Examples (Silvia Mazzoni)
fea_toolkit is free software, licensed under the GNU General Public
License, version 3 or later (SPDX: GPL-3.0-or-later). The full licence
text is in
LICENSE; a
complete breakdown of the terms, the third-party dependency licences and the
distribution position is in docs/licence.md.
No warranty. This software is distributed in the hope that it will be useful, but without any warranty, express or implied, including without limitation the implied warranties of merchantability, fitness for a particular purpose and non-infringement. The entire risk as to the quality and performance of the software is with you (GPL-3.0 §§15–16).
Engineering judgement is required. The toolkit performs finite-element analysis and design checks. Every result must be independently verified by a suitably qualified engineer before it is relied upon for design, construction or assessment. Nothing produced by this software is a substitute for engineering judgement or for the applicable design code.
fea_toolkit is currently distributed as source, by git clone only:
git clone https://github.com/boustrephon/fea_toolkit.git
cd fea_toolkit
pip install -e ".[report]" # add [mesh-remesh] for Gmsh remeshing| Extra | Adds | Python |
|---|---|---|
[report] |
pandas / imageio / tabulate -- report tables and figures | >= 3.9 |
[mesh-remesh] |
gmsh -- constrained quadrilateral remeshing | >= 3.9 |
[gui] |
PySide6 + pyvistaqt + qtpy -- the desktop GUI (plus pyobjc on macOS, for the Application-menu item titles) | >= 3.10 |
[docs] |
the mkdocs toolchain | >= 3.9 |
The Qt desktop GUI is an opt-in extra -- a plain pip install -e . does
not install it. User guide: docs/gui.md; design and
milestones: docs/gui_roadmap.md.
pip install -e ".[gui]" # PySide6 + pyvistaqt + qtpy
fea-gui # launch with a built-in demo frame
fea-gui path/to/model.s2k # or open a SAP2000 model- Selecting. Click a row in the Model Tree to highlight that entity in the
3-D view; left-click an element in the viewport to select it in the tree
(the group is expanded and scrolled to, and a click on empty space clears the
selection). A left-drag orbits as it always did — a press that travels more
than a few pixels is never treated as a click. Both directions share one
Qt-free identity index (
gui/controllers/selection.py), so they cannot drift apart. - Mouse habits are configurable. If you would rather select with the right
button (or tune the click distance, the picking region, or node-versus-member
priority), write
~/.config/fea_toolkit/gui.json— e.g.{"preset": "right_click"}or{"pick_tolerance": 0.004}. Anything unrecognised is reported in the message log. Seedocs/dev_notes.md→ Mouse interaction: one policy, many mouse habits. - The window is titled FEA Toolkit (
gui/app.py→APP_NAME, applied throughconfigure_application()before theQApplicationexists), and on macOS the Application menu'sAbout/Hide/Quititems are retitled away from Qt's bundle-derived… Pythonnames at launch — AppKit throughpyobjc-framework-Cocoa, which the[gui]extra installs on macOS (cosmetic, a quiet no-op elsewhere). - The bold menu-bar / Dock name stays
Pythonand cannot be changed. macOS paints it from the interpreter's framework bundle, not from Qt: verified against Qt's names, AppKit retitles,NSProcessInfo.processName, and a generated.appbundle both with a script launcher and with the interpreter inside it. Only a py2app/PyInstaller-style build (compiled launcher embeddinglibpython) changes that — and such a self-contained bundle is compatible with the OpenSeesPy licence provided it ships no OpenSees code and drives a separately-installed OpenSees instead: the future option sketched indocs/gui_roadmap.md§5 (P22). Probes:docs/dev_notes.md. - Workflows are authored, not implied. The Recipe dock at the bottom
shows the operations a model is put through as an ordered list of steps —
each a verb (
scale_sections,mesh,run_static,combine) applied to a selection, with its parameters.Recipe ▸ Run reciperuns them on a worker and registers what they produce as views; a recipe saves to JSON and exports as a runnable Python script.Model ▸ Split elements/Mesh areasare presets over that recipe — each writes its step and runs it, so the work performed stays visible and editable. Seedocs/workflow_authoring.mdand the user guide. - Two ways to make masonry non-structural, both available and independent:
scale_sectionskeeps the wall elements and reduces their stiffness (their weight stays with them), while ameshstep whose selection matches the walls leaves them out of the OpenSees model entirely and reassigns their loads to the supporting frames. - Requires Python 3.10 or newer.
pyvistaqt(the Qt viewport bridge) declaresrequires-python >= 3.10. The core toolkit stays on Python 3.9 -- the Rhino 8 embedded-interpreter floor -- and never imports theguisubpackage, so the extra and the newer interpreter are needed only to run the GUI. - On Python 3.9,
pip install -e ".[gui]"fails to resolvepyvistaqt; that is expected and affects nothing else -- every other workflow (parse, preprocess, analyse, report, Rhino) runs on 3.9. PySide6is a large download (hundreds of MB); anyone who only parses or analyses models never pays for it.
It is not published on PyPI — pip install fea_toolkit will not find it,
and there is no released wheel to install. Because distribution is
source-only, GPL-3.0 obligations arise only if you redistribute the source or
a modified copy: keep the copyright notice and licence text, mark modified
versions as changed, make the corresponding source available, and state the
absence of warranty.
fea_toolkit drives OpenSees models but does not bundle or redistribute
OpenSeesPy, which carries its own licence:
OpenSeesPy is free for research, education, and internal use. Commercial redistribution of OpenSeesPy, such as, but not limited to, an application or cloud-based service that uses
import openseespy, requires a license similar to that required for commercial redistribution of OpenSees.exe. Contact Dr. Minjie Zhu (zhum@oregonstate.edu) for commercial licensing details.
In short: internal use is free, but shipping an application — or running a
cloud-based service — that imports openseespy requires a commercial
licence from Oregon State University. That obligation is independent of, and
additional to, fea_toolkit's GPL-3.0 terms.
fea_toolkit reads .s2k (SAP2000), .e2k / .$et (ETABS) and .f2k /
.$sf (SAFE) text files exported from CSi products. SAP2000® and
CSi® are registered trademarks of Computers and Structures, Inc. This
project is an independent interoperability tool and is not affiliated with,
authorised by, sponsored by or endorsed by CSI; no CSI branding is used.
Imported data is converted as-is — unrecognised tables and records may be
silently skipped and units default silently — so always cross-check the
converted model against the source. Parsing is entirely local: there is no
network access and no telemetry, and you are responsible for having the right
to process the files you supply. Never commit client or proprietary model
data. Full details: docs/licence.md.