Metadata-Version: 2.5
Name: pypile
Version: 1.1.1
Summary: Spatial pile foundation stiffness, simulated springs and 3D visualization
Project-URL: Repository, https://github.com/GLY2024/pypile
Project-URL: Issues, https://github.com/GLY2024/pypile/issues
Project-URL: Documentation, https://github.com/GLY2024/pypile#readme
Author: Lingyun Gou
License-Expression: GPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: art>=6.4
Requires-Dist: loguru>=0.7.3
Requires-Dist: numpy>1.24.4
Requires-Dist: plotly<8,>=5.18
Requires-Dist: pydantic>=2.10.6
Requires-Dist: tabulate>=0.9.0
Description-Content-Type: text/markdown

# PyPile

桥梁桩基础空间静力分析：实体桩与虚拟弹簧的6自由度刚度、承台位移、桩身内力，以及离线交互式3D可视化。

## 功能

- 计算承台中心的6×6整体刚度、单桩刚度及六自由度位移。
- 支持圆形和方形截面、斜桩、地上自由段、分层土和变截面桩。
- 支持实体桩、虚拟弹簧及二者的混合布置。
- 输出桩身位移、剪力、轴力、弯矩、土压力及内力分量包络。
- 提供 Python API、命令行工具、文本报告和可离线使用的3D HTML。

横向分析采用双精度 Euler–Bernoulli/Winkler 梁有限元，土反力按线性 m 法计算；轴向分析采用分段柔度与桩端弹簧模型。

## 安装

需要 Python 3.9 或更新版本。

```bash
python -m pip install --upgrade pypile
```

也可以下载 [GitHub Releases](https://github.com/GLY2024/pypile/releases) 中的 wheel 安装：

```bash
python -m pip install /path/to/pypile.whl
```

开发安装：

```bash
git clone https://github.com/GLY2024/pypile.git
cd pypile
pip install -e . pytest build
python -m pytest
```

## 快速使用

下载 [混合桩示例 mixed.dat](https://raw.githubusercontent.com/GLY2024/pypile/main/examples/mixed.dat)，保存到当前工作目录。

```python
from pathlib import Path
import numpy as np
from pypile import PileManager

pile = PileManager(welcome=False)
pile.read_dat(Path("mixed.dat"))

print(pile.K)            # 承台中心整体6×6刚度
print(pile.K_pile(1))    # 桩号从1开始；实体桩为局部轴，虚拟桩为整体轴
print(pile.disp_cap())   # 使用DAT荷载
results = pile.eforce()  # 实体桩结果字典，键从0开始
print(pile.simu_reactions())  # 虚拟桩反力，整体轴，键接续实体桩编号

force = np.array([1000, 500, 10000, 2000, -3000, 100.0])
results = pile.eforce(force)
# 可以在同一个对象连续计算工况，新荷载会更新全部结果。
results2 = pile.eforce(2 * force)

pile.pile_group_report(output_file="group.out")
pile.plot_piles(output_file="piles.html", deformed_scale=100, color_by="NZ")
```

`plot_piles()` 返回 Plotly Figure，默认不打开浏览器。HTML 包含绘图库，可离线旋转、缩放、查看悬停数据。未提供荷载时可以只查看几何；`deformed_scale` 是显示放大倍数，不改变计算结果。

变形图同时保留灰色原形参考线。横向位移来自各桩身节点；轴向显示仅采用桩顶 UZ 平移，不代表已求得轴向桩身压缩曲线。图题会标明这一显示约定。

```bash
pypile -f mixed.dat -p --plot piles.html --deformed-scale 100
pypile -f mixed.dat --plot --color-by MY
pypile -f mixed.dat --force 1000 0 10000 0 0 0 --mode replace
pypile --help
```

CLI 写入同名 `.out`；计算内力时写入 `.pos`。两者均为可读文本报告。`--plot [文件名]` 导出 HTML，省略文件名则与 DAT 同名。`--mesh-size` 调整横向计算的最大单元长度，默认0.25 m；很硬的土层会进一步细分。建议用更细网格复核高刚度反差工况。

## 输入与单位

按一致单位输入。示例采用 m、kN、kN·m，弹性模量为 kN/m²。自由度顺序为 `[UX, UY, UZ, SX, SY, SZ]`，相应荷载为 `[FX, FY, FZ, MX, MY, MZ]`。全局 Z 和桩的局部深度向下，方向余弦应构成向下的单位向量。

DAT 有四个块，以 `end` 或 `end;` 结束：

- `[contral]` / `[control]`：JCTR=1（位移与内力）、2（整体刚度）、3（指定单桩刚度，随后输入1基桩号）。
- `[arrange]`：实体桩数 PNUM、虚拟桩数 SNUM；先依次输入实体桩坐标，再输入虚拟桩坐标。
- `[no_simu]`：KCTR 和实体桩定义。正编号为完整定义；负编号从 `<0>` 继承并按 `HBL=` 等字段覆盖。
- `[simu_pe]` / `[simu_pile]`：KSCTR 和虚拟桩的刚度矩阵。

支持 `.8`、`-.8`、`3e7`、`3D7` 等数值，支持 `%` 和 `!` 行尾注释。输入校验会检查数值格式、有限性、整数计数、字段完整性和物理参数范围。

实体桩一类的内容为：截面类型 KSH（0圆、1方）、桩端类型 KSU、三个方向余弦；地上段数及各段的长度/直径/输出分段数；地下段数及各段的长度/直径/m/摩擦角/输出分段数；最后 PMB、PEH、PKE。PKE 是弯曲刚度折减系数。KSU=1/2使用轴向摩擦桩简化模型，3为非嵌固端承，4为固定桩端。完整输入见 [mixed.dat](https://github.com/GLY2024/pypile/blob/main/examples/mixed.dat)。

## 虚拟桩

虚拟桩表示作用在指定承台平面坐标的等效弹簧，以六个对角刚度或完整6×6刚度矩阵定义。矩阵在全局坐标轴下定义，程序负责从其位置转换并组装到承台中心。

负 KSCTR 对应六个对角刚度：

```text
[simu_pe]
-1
<-1>
100000 100000 200000 1000000 1000000 1000000
end;
```

正 KSCTR 对应按行给出的完整6×6对称矩阵。允许单个弹簧矩阵半正定，整体模型必须约束全部6个自由度才能求位移。虚拟桩按布置顺序组装，可重复引用类型；可以与实体桩混用，也可以 PNUM=0 只使用虚拟桩。参见 [纯虚拟桩示例](https://github.com/GLY2024/pypile/blob/main/examples/simulated_only.dat)。

`eforce()` 只返回有桩身的实体桩；`simu_reactions()` 返回虚拟弹簧处的六分量反力。可视化使用不同标记显示它们。

## 内力包络与精度

```python
envelopes = pile.get_worst_pile_force()
print(envelopes["axial"])   # 最大绝对轴力所在桩及其带符号值
# 综合排序必须提供明确的力/弯矩参考尺度，顺序为NZ,NX,NY,MX,MY,MZ。
ranked = pile.get_worst_pile_force(scales=[1e4, 1e3, 1e3, 1e4, 1e4, 1e3])
```

内力分量包络分别查找各分量的最大绝对值，并记录桩号与带符号内力。综合排序使用各分量除以参考尺度后的无量纲范数；参考尺度需由使用者给定。截面承载力验算需要结合材料、配筋和相应设计准则。

横向计算网格与 NSF/NSG 输出分段独立。桩端边界由有限元约束施加，计算覆盖全部桩长。节点位移由形函数插值，剪力与弯矩按一致土反力积分保持平衡；截面交界节点采用上侧直径。局部2×2刚度、全局平衡、荷载线性、编号置换和变截面边界均有回归测试。

模型适用范围：线性 m 法 Winkler 土弹簧；经验群桩影响系数；分段轴向刚度与轴力衰减模型；`0.1*(Krxrx+Kryry)` 的扭转近似。该模型用于线性静力分析。非线性 p-y、动力阻抗、桩土连续体相互作用和结构承载力需要相应的专用模型。

模型公式和基准算例见 [数值验证](https://github.com/GLY2024/pypile/blob/main/docs/validation.md)。版本功能见 [版本记录](https://github.com/GLY2024/pypile/blob/main/CHANGELOG.md)。

## 来源与许可

算法参考同济大学桥梁工程系 CAD 研究组的 BCAD_PILE，Python 项目由 Lingyun Gou 维护。采用 [GPL-3.0](https://github.com/GLY2024/pypile/blob/main/LICENSE) 许可证。
