PyPile

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

功能

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

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

安装

需要 Python 3.9 或更新版本。

python -m pip install --upgrade pypile

也可以下载 GitHub Releases 中的 wheel 安装：

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

开发安装：

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

快速使用

下载 混合桩示例 mixed.dat，保存到当前工作目录。

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 平移，不代表已求得轴向桩身压缩曲线。图题会标明这一显示约定。

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。

虚拟桩

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

负 KSCTR 对应六个对角刚度：

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

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

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

内力包络与精度

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、动力阻抗、桩土连续体相互作用和结构承载力需要相应的专用模型。

模型公式和基准算例见 数值验证。版本功能见 版本记录。

来源与许可

算法参考同济大学桥梁工程系 CAD 研究组的 BCAD_PILE，Python 项目由 Lingyun Gou 维护。采用 GPL-3.0 许可证。