# structural-dynamic-tools

**Repository Path**: richardogu/structural-dynamic-tools

## Basic Information

- **Project Name**: structural-dynamic-tools
- **Description**: 一个专注于结构动力学分析的开源工具集，提供高效、准确的仿真和测试功能，适用于工程设计与研究。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# structural-dynamic-tools

[English](README.en.md) | 中文

[![PyPI Version](https://img.shields.io/pypi/v/structural-dynamic-tools)](https://pypi.org/project/structural-dynamic-tools/)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
[![NumPy](https://img.shields.io/badge/numpy-%3E%3D1.26-013243.svg)](https://numpy.org/)
[![SciPy](https://img.shields.io/badge/scipy-%3E%3D1.17.1-8CAAE6.svg)](https://scipy.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

## 特性

- **SDOF 线性分析**：Duhamel 积分（解析/数值/并行）、分段解析法、中心差分法、Newmark-β 法
- **SDOF 非线性分析**：中心差分法、Newmark-β 法、HHT-α 法，结合非线性本构模型及 Newton-Raphson 迭代
- **SDOF 自适应积分**：自适应 RK45（Dormand-Prince 5(4)）、含子步进的自适应 Newmark-β
- **MDOF 线性分析**：中心差分法、Newmark-β 法、Wilson-θ 法，支持多自由度系统
- **MDOF 非线性分析**：中心差分法、Newmark-β 法、HHT-α 法，含 Newton-Raphson 迭代
- **MDOF 自适应积分**：自适应 RK45、含子步进的自适应 Newmark-β
- **本构模型**：Elastic、Bilinear、BoucWen、Clough、RambergOsgood、PeakOriented、BoucWenBaberNoori、Pinching4、EnhancedClough、LRB、FPS、ViscousDamper、Steel02、Concrete01、Concrete02 共 15 种模型
- **模态分析**：Jacobi 迭代、子空间迭代、Lanczos 法、Rayleigh-Ritz 法、矩阵迭代法、Dunkerley 法等
- **反应谱分析**：反应谱计算、GB 50011 / ASCE 7-22 / EC8 / 日本规范设计谱、振型分解反应谱分析、地震动缩放与兼容性检查
- **振型叠加**：Fourier 变换法、振型叠加法、复模态分析法（非比例阻尼）
- **频域分析**：FFT 功率谱密度（PSD）、频响函数（FRF）、传递函数、相干性分析
- **随机振动**：虚拟激励法（PEM）求解多点地震激励与风振随机振动问题，支持白噪声/空间相干激励生成
- **OMA 运行模态分析**：SSI-COV（协方差驱动）、SSI-DATA（数据驱动），含稳定图生成
- **建模工具**：层剪切模型（含 P-Delta）、Rayleigh/Caughey 阻尼、非比例阻尼
- **I/O 工具**：支持 PEER、KIK 等标准地震动格式的读写，内置 El Centro 示例波
- **地震动强度指标**：21 种常用 IM（PGA/PGV/PGD、Arias、CAV、ASI、HI、SA/SV/SD 等），支持批量计算与等比缩放
- **地震动信号处理**：基线校正（多项式/Butterworth 高通）、滤波（低通/高通/带通/带阻）、数值积分与微分（加速度↔速度↔位移）、零线调整
- **静力非线性分析 (Pushover)**：能力谱法 (ATC-40)、N2 方法 (Eurocode 8)、位移系数法 (FEMA 440)，推覆曲线 → 性能点求解 — 基于性能抗震设计的核心工具

## 安装

```bash
pip install structural-dynamic-tools
```

## 快速开始

```python
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-β 法
mass = 1.0                   # 质量
omega_n = 2 * np.pi / 1.0    # 固有圆频率 (周期=1.0s)
stiffness = mass * omega_n**2
damping_ratio = 0.05         # 阻尼比

disp, vel, abs_acc = sdof_linear_newmark_beta(
    mass, stiffness, acc, time, damping_ratio=damping_ratio
)

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

## 原理说明

本库的核心算法基于经典结构动力学理论，各原理文档入口：

> 📖 [原理文档索引](docs/principle/index.md)

## API 参考

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

> 📖 [API 文档索引](docs/api/index.md)

## 依赖

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

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。