Metadata-Version: 2.4
Name: structural-dynamic-tools
Version: 1.0.0
Summary: A Python library for structural dynamics analysis
Author: Xiaopenggu
License: MIT
Project-URL: Homepage, https://gitee.com/richardogu/structural-dynamic-tools
Project-URL: Repository, https://gitee.com/richardogu/structural-dynamic-tools.git
Keywords: structural dynamics,seismic analysis,earthquake engineering,dynamic analysis,finite element,modal analysis,nonlinear analysis,hysteresis,numerical integration,civil engineering,structural engineering
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.17.1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# structural-dynamic-tools

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

[![PyPI](https://img.shields.io/pypi/v/structural-dynamic-tools?label=PyPI)](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-β 法，结合非线性本构模型
- **MDOF 线性分析**：中心差分法、Newmark-β 法、Wilson-θ 法，支持多自由度系统
- **MDOF 非线性分析**：中心差分法和 Newmark-β 法，用于非线性多自由度系统
- **本构模型**：Elastic（线弹性）、Bilinear（双线性）、Bouc-Wen、Clough、Ramberg-Osgood、PeakOriented（峰值指向）共 6 种滞回模型
- **模态分析**：Jacobi 迭代、子空间迭代、Lanczos 法、Rayleigh-Ritz 法、矩阵迭代法等
- **建模工具**：层剪切模型、Rayleigh/Caughey 阻尼、非比例阻尼
- **I/O 工具**：支持 PEER、KIK 等标准地震动格式的读写

## 安装

```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-β 法
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 种逐步积分方法，涵盖卷积类方法和递推类方法。

> 📖 [逐步积分方法原理详解](docs/principle/integration_methods.md)

### 显式与隐式方法对比

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

> 📖 [显式与隐式方法对比](docs/principle/explicit_vs_implicit.md)

### 非线性本构模型

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

> 📖 [非线性本构模型原理详解](docs/principle/constitutive.md)

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

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

> 📖 [非线性本构与逐步积分结合原理](docs/principle/nonlinear_mdof.md)

### 模态分析

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

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

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

> 📖 [模态分析原理详解](docs/principle/modal.md)

## API 参考

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

> 📖 完整 API 文档入口：[API 索引](docs/api/index.md)

### 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 文档](docs/api/io.md)

### modeling — 结构建模

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

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

> 📖 [modeling 模块 API 文档](docs/api/modeling.md)

### 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 文档](docs/api/modal.md)

### response — 时程响应分析

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

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

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

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

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

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

> 📖 [response 模块 API 文档](docs/api/response.md)

### utils — 工具函数

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

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

> 📖 [utils 模块 API 文档](docs/api/utils.md)

## 依赖

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

## 许可证

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