kbf-damage-sim

Parametric OpenSeesPy finite-element model of a 10-story knee-braced frame (KBF) for structural damage simulation. This is the data-generation component of an AI-powered structural damage detection project: it produces modal features that distinguish healthy and damaged structural states.

The model represents every KBF connection as a zero-length rotational spring, and a damage scenario as a binary list marking which of the 20 springs have been degraded. The same model is rebuilt for any damage configuration, so healthy and damaged states are directly comparable.

Features

• Parametric 2D steel-frame model (10 stories, 4 bays) with a knee-braced central bay
• 20 zero-length elements as discrete damage locations (two per story)
• Deterministic node/element tag scheme for reproducible healthy-vs-damaged comparisons
• Consistent lumped-mass distribution with element geometry
• Modal analysis: eigen extraction, flexibility matrix by modal superposition, and a convergence study
• delta-MAC (Modal Assurance Criterion) signature quantifying the modal deviation between healthy and damaged states
• Damage-scenario sampling strategies for downstream dataset generation

Project structure

src/kbf_damage_sim/
    config.py           project-wide parameters (geometry, materials, damage model)
    model_builder.py    OpenSeesPy model assembly
    modal_analysis.py   eigen, flexibility matrix, convergence analysis
    delta_mac.py        MAC and delta-MAC damage signature
    damage_utils.py     damage-scenario sampling strategies
    visualization.py    model geometry plot
    utils.py            section-property I/O
examples/
    run_healthy_vs_damaged.py   end-to-end example (mode extraction + delta-MAC)
data/
    section_properties.json     European steel section properties

Quick start

Requires Python >= 3.12 and uv.

uv sync
uv run python examples/run_healthy_vs_damaged.py

The script builds a healthy and a damaged model, extracts 20 modes from each, and writes the delta-MAC figure to outputs/mac_deviation.png. Add --convergence to also save the flexibility-matrix convergence figure.

How damage is modeled

Each story of the knee-braced bay carries two zero-length rotational springs — a vertical one at the column and a horizontal one at the beam. An intact spring is Steel01; a damaged spring is an elastic material with near-zero stiffness, i.e. a released connection. The damage_config list passed to build_structure marks damaged springs:

from kbf_damage_sim.config import SECTION_PROPERTIES_FILE
from kbf_damage_sim.model_builder import build_structure
from kbf_damage_sim.utils import load_section_properties

sections = load_section_properties(SECTION_PROPERTIES_FILE)
dofs, zle_tags = build_structure(sections, damage_config=[0, 1, 0, 0, ...])

The ZLE tags (zle_tags) and the mode-shape DOF ordering (dofs) are returned so results can be matched back to specific connections.

Modal features

• get_first_n_modes returns squared natural frequencies and the mode-shape matrix for a fixed, deterministic set of DOFs.
• calculate_flexibility_matrix assembles the flexibility matrix by modal superposition: F = sum(phi phi^T / omega_i^2).
• analyze_flexibility_convergence shows how many modes are needed for a stable flexibility matrix.
• plot_mac_deviation produces the reference / damaged / delta-MAC panels used as the damage signature.

Scope

This repository covers model-based data generation for ML-based structural damage detection; it does not include model training.