structural-dynamic-tools 1.0.0

A Python library for structural dynamics analysis

structural-dynamic-tools

English | 中文

一个专注于结构动力学分析的开源 Python 工具集，提供高效、准确的仿真与分析功能，适用于工程设计与科研。

特性

• SDOF 线性分析：Duhamel 积分（解析/数值）、分段解析法、中心差分法、Newmark-β 法
• SDOF 非线性分析：中心差分法和 Newmark-β 法，结合非线性本构模型
• MDOF 线性分析：中心差分法、Newmark-β 法、Wilson-θ 法，支持多自由度系统
• MDOF 非线性分析：中心差分法和 Newmark-β 法，用于非线性多自由度系统
• 本构模型：Elastic（线弹性）、Bilinear（双线性）、Bouc-Wen、Clough、Ramberg-Osgood、PeakOriented（峰值指向）共 6 种滞回模型
• 模态分析：Jacobi 迭代、子空间迭代、Lanczos 法、Rayleigh-Ritz 法、矩阵迭代法等
• 建模工具：层剪切模型、Rayleigh/Caughey 阻尼、非比例阻尼
• I/O 工具：支持 PEER、KIK 等标准地震动格式的读写

安装

pip install structural-dynamic-tools

快速开始

import numpy as np
from structural_dynamic_tools import (
    sdof_linear_newmark_beta,
    load_example_seismic_wave,
)

# 加载示例地震波
time, acc = load_example_seismic_wave("elcentro")

# SDOF 线性分析 — Newmark-β 法
period = 1.0          # 自振周期 (s)
damping_ratio = 0.05  # 阻尼比

disp, vel, abs_acc = sdof_linear_newmark_beta(time, acc, period, damping_ratio)

print(f"最大位移: {np.max(np.abs(disp)):.4f} m")

原理解释

本库的核心算法基于结构动力学经典理论。以下为各原理文档的概要及链接。

逐步积分方法

结构动力学中，单自由度系统的运动方程为：

$$ m \ddot{u}(t) + c \dot{u}(t) + k u(t) = p(t) $$

除简谐荷载等少数情况外，大多数实际荷载（如地震波）需通过逐步积分法在时域内递推求解。本库实现了 5 种逐步积分方法，涵盖卷积类方法和递推类方法。

📖 逐步积分方法原理详解

显式与隐式方法对比

逐步积分法分为显式方法（如中心差分法）和隐式方法（如 Newmark-β 法）。核心区别在于：显式方法在 $t_i$ 时刻满足运动方程，而隐式方法在 $t_{i+1}$ 时刻满足。两种方法在稳定性、精度和计算量方面有本质差异。

📖 显式与隐式方法对比

非线性本构模型

本构模型描述构件在循环加载下的力-变形关系。强震下构件进入非线性阶段，恢复力与变形呈现复杂的滞回关系。本库实现了 6 种经典滞回模型：线弹性、双线性、Bouc-Wen、Clough、Ramberg-Osgood 和峰值指向模型。所有模型继承自 ConstitutiveModel 抽象基类，提供统一的 update() / reset() 接口。

📖 非线性本构模型原理详解

非线性本构与逐步积分结合

非线性 MDOF 系统运动方程的核心挑战在于：恢复力依赖于变形历史，无法用恒定刚度矩阵处理。本模块采用每自由度独立的滞回模型 + 切线刚度对角阵近似的方式，将非线性本构与逐步积分框架深度结合。

📖 非线性本构与逐步积分结合原理

模态分析

模态分析的核心是求解广义特征值问题：

$$ \mathbf{K} \boldsymbol{\phi} = \omega^2 \mathbf{M} \boldsymbol{\phi} $$

本库实现了多种经典模态分析方法，从简单的 Rayleigh 商法到高精度的 Jacobi 迭代和 Lanczos 法，适用于不同规模和精度需求。

📖 模态分析原理详解

API 参考

本库由 5 个模块组成，提供了从地震波读写、结构建模、模态分析到时程响应计算的完整工具链。

📖 完整 API 文档入口：API 索引

io — 地震波读写

支持单列/双列文本文件读写，以及 PEER、KIK 等标准地震动格式的解析。内置 El Centro 示例波数据，可快速上手。

主要函数	说明
read_wave_from_1line_file	从单列文本文件读取地震波
write_wave_to_1line_file	将地震波写入单列文本文件
read_wave_from_2line_file	从双列（时间+值）文本文件读取
write_wave_to_2line_file	将数据写入双列文本文件
read_from_kik	读取 KIK 格式地震动数据
read_from_peer	读取 PEER 格式地震动数据
load_example_seismic_wave	加载内置示例地震波

📖 io 模块 API 文档

modeling — 结构建模

提供层剪切模型（剪切型多自由度建筑/糖葫芦模型）的构造，以及 Rayleigh、Caughey、非比例阻尼矩阵的生成。

主要函数/类	说明
LayerShear	层剪切模型类（含 P-Delta 刚度）
build_stiffness	由层刚度构建剪切型刚度矩阵
extract_story_stiffness	从刚度矩阵反算层刚度
rayleigh	Rayleigh 阻尼矩阵
caughey	Caughey 阻尼矩阵
damping_nonclassical	非比例（非经典）阻尼矩阵

📖 modeling 模块 API 文档

modal — 模态分析

提供多种频率与振型的计算方法，涵盖 Rayleigh 商法、Rayleigh-Ritz 法、矩阵迭代法（矢量迭代）、子空间迭代法、Lanczos 法和 Jacobi 法等。

主要函数	说明
normalize	质量矩阵归一化向量
rayleigh_psi	Rayleigh 商法求基频
rayleigh_ritz	Rayleigh-Ritz 法
load_depended_ritz_vector	荷载依赖的 Ritz 向量
mat_iterate_base	矩阵迭代法求基频/基本振型
mat_iterate_high	矩阵迭代法求高阶频率/振型
mat_iterate_highest	矩阵迭代法求最高阶频率/振型
subspace_iteration	子空间迭代法
lanczos	Lanczos 法
dunkerley	Dunkerley 公式估计基频
jacobi	Jacobi 迭代法

📖 modal 模块 API 文档

response — 时程响应分析

涵盖线性和非线性、单自由度和多自由度系统的时域积分方法，以及非线性本构模型。所有积分器均支持非均匀时间步和批量计算。

SDOF 线性积分：Duhamel 积分（解析/数值/并行）、分段解析法、中心差分法、Newmark-β 法

SDOF 非线性积分：中心差分法、Newmark-β 法（含 Newton-Raphson 迭代）

MDOF 线性积分：中心差分法、Newmark-β 法、Wilson-θ 法

MDOF 非线性积分：中心差分法、Newmark-β 法（含 Newton-Raphson 迭代）

本构模型：Elastic、Bilinear、BoucWen、Clough、RambergOsgood、PeakOriented

📖 response 模块 API 文档

utils — 工具函数

提供数组截断/补零和幅值缩放等通用工具函数。

函数	说明
adjust_length	沿指定轴截断或零填充数组
adjust_amplitude	将数据缩放到目标峰值幅值

📖 utils 模块 API 文档

依赖

• Python >= 3.12
• NumPy >= 1.26
• SciPy >= 1.17.1

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。