Plaxis代理封装框架——完整的基坑仿真解析(一)

写在前面

为了更好地介绍这个代理框架，以降低使用同学的操作门槛。

由于这个框架是原来笔者的科研过程中流式代码转换过来的，且在完整的框架开发时由于对Plaxis机理和机制理解有限，因此难免存在疏漏和错误，还请各位同学及时提出，辅助修正。当前笔者的相关工作也已经从之前的流式代码切换到当前框架，优化的频率较高，因此代码库更新的速度较快，同学们使用这个框架时，应当首先运行以下命令检查当前的代码库是否有更新，然后再运行业务代码。

1
2
3
4
5
# 检查并安装最新的代码库
pip install plaxisproxy_excavation -U

# 其他可选安装的模块：pandas（数据分析）、openpyxl（Excel读写处理提速）、scipy（KD树实现空间最近邻算法，提升结果提取的效率）
pip install pandas openpyxl scipy

下面将详细解析Examples/testmapper.ipynb和Examples/testmapper.py这两个文件的具体结构和功能。

testmapper.ipynb结构解析

什么是 .ipynb 文件？

简单理解：

  • .ipynb 是 Jupyter Notebook 的工作文件；
  • 里面可以同时包含：
    • 可以运行的代码（通常是 Python）
    • 文字说明（Markdown）
    • 图表、公式、输出结果等

你可以把它看成一个“可以运行的文档”：
一边写说明，一边写代码，一边看到运行结果，非常适合教学、实验和记录笔记。

下面给初学者简单介绍一下如何运行这类文件。

方案 A：用 Anaconda（傻瓜式、体积大、但省心）

  1. 前往 Anaconda 官网下载：
    https://www.anaconda.com/download
  2. 选择对应系统（Windows / macOS），一路下一步安装；
  3. 安装完成后，系统会多出一个叫 Anaconda Prompt 的终端。

方案 B：已有 Python，用 pip 安装 Jupyter

如果你已经装了 Python，可以直接在命令行输入：

1
2
3
4
5
# Install Jupyter Notebook
pip install jupyter

# 或者安装 JupyterLab（界面更现代）
pip install jupyterlab

终端打开方式：

  • Windows：Win + R → 输入 cmd → 回车
  • macOS：打开 Terminal（终端）

而后使用终端用cd命令，进入你的ipynb所在的文件目录，运行jupyter notebook即可。

运行效果如下：

终端运行notebook效果示意图

Notebook在浏览器中的效果如图所示：

浏览器打开Notebook效果（博客目录）

什么是testmapper.ipynb

testmapper.ipynb是一个全面的测试文件，系统地验证了Plaxis代理框架中各个核心组件的功能。文件按照模块化结构组织，从基础材料到复杂结构，再到完整的工程流程，层层递进地展示了框架的能力。由于testmapper.ipynb是在本框架的源码上测试得到的，因此在引入相关代码模块时存在src等文件目录字样，同时import时直接对具体代码文件中的对象或函数进行引用，与当前直接通过pip安装得到的模块包引用的方式存在一定的区别，这里仅对当前的测试文件进行介绍，实际本框架内各个模块怎么导入和使用建议阅读源码和第二部分的真实示例介绍。

代码中主要包括两类实例，一类是Material、Structure等之类的直接表示具体的材料、结构或施工阶段相关的对象实例，这类实例直接用来储存对象的基本信息；另一类是Mapper之类的映射器实例，该实例将对象实例中的内容发送到Plaxis软件实现在软件内的自动控制。

基于Notebook中的映射测试源代码，我将详细介绍每一部分的测试内容和实现原理：

1. 材料映射测试

土体材料测试

1
2
3
4
5
6
7
8
9
# ######## Soil Materials ########
mc = MCMaterial("MC", SoilMaterialsType.MC, "", 22, 5e3, 0.3, 25, 0.4)
soil_mat_mc = SoilMaterialMapper.create_material(g_i, mc)

mcc = MCCMaterial("MCC", SoilMaterialsType.MCC, "", 22, 5e3, 0.3, 25, 0.4)
soil_mat_mcc = SoilMaterialMapper.create_material(g_i, mcc)

hss = HSSMaterial("HSS", SoilMaterialsType.HSS, "", 22, 5e3, 0.3, 25, 0.4)
soil_mat_hss = SoilMaterialMapper.create_material(g_i, hss)

代码作用：创建三种不同本构模型的土体材料，包括基本的Mohr-Coulomb模型、修正剑桥模型和考虑小应变硬化的HSS模型，测试土体材料映射器的基本功能。

映射原理：

  • 创建三种不同本构模型的土体材料对象
  • 通过SoilMaterialMapper.create_material()将领域对象映射到Plaxis材料
  • 每个材料对象会自动获得plx_id属性，存储Plaxis句柄

板材料测试

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 各向同性弹性板
ep = ElasticPlate(
    name="Slab_EL_ISO", type=PlateType.Elastic,
    comment="isotropic elastic plate", gamma=24.0,
    E=30e6, d=1.0, nu=0.2, preventpunch=True, isotropic=True
)
plx_plate_1 = PlateMaterialMapper.create_material(g_i, ep)

# 各向异性弹性板
ep_aniso = ElasticPlate(
    name="Slab_EL_ANISO", type=PlateType.Elastic,
    comment="orthotropic elastic plate", gamma=24.0,
    E=30e6, nu=0.2, d=1.0, preventpunch=True, isotropic=False,
    E2=20e6, G12=12e6, G13=10e6, G23=9e6  # 各向异性参数
)
plx_plate_2 = PlateMaterialMapper.create_material(g_i, ep_aniso)

代码作用：测试板材料的创建，包括各向同性和各向异性弹性板，验证材料参数的正确传递和各向异性参数的处理能力。

映射特点：

  • 支持各向同性和各向异性材料定义
  • 自动处理材料参数的完整性和有效性
  • 通过PlateMaterialMapper统一接口创建

梁材料测试

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 圆形截面弹性梁
beam_el_cyl = ElasticBeam(
    name="Beam_EL_Cylinder", type=BeamType.Elastic,
    comment="Elastic beam - solid circular section", gamma=25.0,
    E=30e6, nu=0.20, cross_section=CrossSectionType.PreDefine,
    predefined_section=PreDefineSection.Cylinder, diameter=0.60
)
plx_beam_el_cyl = BeamMaterialMapper.create_material(g_i, beam_el_cyl)

# 自定义截面弹塑性梁
beam_ep_custom = ElastoplasticBeam(
    name="Beam_EP_Custom", type=BeamType.Elastoplastic,
    comment="Elasto-plastic beam - custom section with yield",
    gamma=24.0, E=31e6, nu=0.20,
    cross_section=CrossSectionType.Custom, predefined_section=None,
    A=0.42, Iy=0.018, Iz=0.014, W=0.028,  # 自定义截面参数
    sigma_y=300e3, yield_dir=2
)
plx_beam_ep_custom = BeamMaterialMapper.create_material(g_i, beam_ep_custom)

代码作用：测试梁材料的各种截面类型，包括预定义截面（圆形、矩形、管状）和自定义截面，验证弹性梁和弹塑性梁的材料映射。

截面类型支持：

  • 预定义截面：圆形、矩形、管状等
  • 自定义截面：直接定义A、Iy、Iz等参数
  • 自动计算截面特性

2. 几何映射测试

点线面创建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
def make_rectangle(z: float = 0.0, width: float = 10.0, height: float = 6.0, 
                   x0: float = 0.0, y0: float = 0.0):
    """返回闭合矩形：Point 列表、PointSet、Line3D、Polygon3D（外环）"""
    pts: List[Point] = [
        Point(x0, y0, z), Point(x0 + width, y0, z),
        Point(x0 + width, y0 + height, z), Point(x0, y0 + height, z),
        Point(x0, y0, z)  # 闭合
    ]
    ps = PointSet(pts)
    line = Line3D(ps)
    poly = Polygon3D.from_points(ps)  # 仅外环
    return pts, ps, line, poly

# 1) 点：批量创建
pts, ps, line, poly = make_rectangle(z=0.0, width=12.0, height=5.0, x0=2.0, y0=3.0)
handles = GeometryMapper.create_points(g_i, ps)

# 2) 线：由 Line3D 创建
line_created = GeometryMapper.create_line(g_i, line, name="DemoRectEdge")

# 3) 面：由 Polygon3D 创建
surf_id = GeometryMapper.create_surface(g_i, poly, name="DemoRectSurface")

代码作用：测试几何对象的创建流程，从基础的点开始，逐步构建线、面，验证几何映射器的层次化创建能力和几何依赖关系处理。

几何映射流程：

  1. 创建领域几何对象（Point→PointSet→Line3D→Polygon3D）
  2. 通过GeometryMapper批量创建Plaxis几何
  3. 自动设置plx_id建立双向映射

删除验证

1
2
3
4
5
6
7
8
9
10
# 4) 删除测试（并验证 plx_id 清空）
# 先删面
ok_surf = GeometryMapper.delete_surface(g_i, poly)
assert ok_surf, "Surface deletion failed"
assert_plx_id_cleared(poly, "Polygon3D")

# 再删线
ok_line = GeometryMapper.delete_line(g_i, line)
if ok_line:
    assert_plx_id_cleared(line, "Line3D")

代码作用：测试几何对象的删除功能，验证映射器能够正确清理Plaxis资源和本地引用，确保资源管理的完整性。

生命周期管理：

  • 创建时自动设置plx_id
  • 删除时自动清理plx_id
  • 支持断言验证映射状态

3. 结构映射测试

结构创建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 为每个结构准备独立的几何实例
line_beam   = make_line(pA_ref, pB_ref)  # 仅用于 Beam
line_pile   = make_line(pA_ref, pB_ref)  # 仅用于 EmbeddedPile
line_anchor = make_line(pA_ref, pB_ref)  # 仅用于 Anchor

# 结构对象创建
beam1   = Beam(name="B1", line=line_beam, beam_type=beam_mat)
pile1   = EmbeddedPile(name="P1", line=line_pile, pile_type=pile_mat)
anchor1 = Anchor(name="A1", line=line_anchor, anchor_type=anchor_mat)

# 通过Mapper创建结构
BeamMapper.create(g_i, beam1)
EmbeddedPileMapper.create(g_i, pile1)
AnchorMapper.create(g_i, anchor1)

代码作用：测试各种结构类型（梁、桩、锚杆等）的创建，验证结构映射器能够正确处理几何依赖关系和材料关联。

结构映射特点：

  • 每个结构使用独立的几何实例，避免句柄冲突
  • Mapper自动处理几何依赖关系
  • 支持复杂的结构类型组合

4. 钻孔映射测试

钻孔数据构建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
def build_borehole_set(fill_mat, sand_mat, clay_mat, gravel_mat):
    # 全局土层定义
    sl_fill = SoilLayer(name="Fill", material=fill_mat)
    sl_sand = SoilLayer(name="Sand", material=sand_mat)
    
    # 钻孔1的土层序列
    bh1_layers = [
        BoreholeLayer(name="Fill@BH1", top_z=0.0, bottom_z=-1.5, soil_layer=sl_fill),
        BoreholeLayer(name="Sand@BH1", top_z=-1.5, bottom_z=-8.0, soil_layer=sl_sand),
    ]
    bh1 = Borehole(name="BH_1", location=Point(0, 0, 0), ground_level=0.0, 
                   layers=bh1_layers, water_head=-2.0)
    
    return BoreholeSet(name="Site BH", boreholes=[bh1, ...], comment="Full demo set")

# 一次性导入钻孔集
summary = BoreholeSetMapper.create(g_i, bhset, normalize=True)

代码作用：测试复杂钻孔数据的创建和导入，包括多层土体剖面、不同钻孔间的土层变化，验证钻孔映射器的土层归一化能力。

钻孔映射特性：

  • 支持多层土体剖面定义
  • 自动处理土层归一化（补全缺失层）
  • 生成土层分布汇总信息

5. 荷载映射测试

静态荷载创建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 点荷载
pl_static = PointLoad(
    name="PL_static", comment="static point load", point=P3,
    Fx=0.0, Fy=0.0, Fz=-100.0, Mx=0.0, My=0.0, Mz=0.0
)
LoadMapper.create(g_i, pl_static)

# 线荷载（线性分布）
ll_static_linear = LineLoad(
    name="LL_static_linear", comment="static linear line load", line=L13,
    distribution=DistributionType.LINEAR, 
    qx=0.0, qy=0.0, qz=-5.0, qx_end=0.0, qy_end=0.0, qz_end=-12.0
)
LoadMapper.create(g_i, ll_static_linear)

代码作用：测试各种静态荷载类型的创建，包括点荷载、线荷载（均匀分布和线性分布）、面荷载，验证荷载映射器的几何关联和分布模式处理能力。

动态荷载与乘子

1
2
3
4
5
6
7
8
9
10
11
12
13
# 荷载乘子定义
mul_h_5Hz = LoadMultiplier(
    name="Mul_H_5Hz", comment="harmonic 5 Hz", signal_type=SignalType.HARMONIC,
    amplitude=1.0, phase=0.0, frequency=5.0
)
LoadMultiplierMapper.create(g_i, mul_h_5Hz)

# 基于静态荷载创建动态荷载
pl_dyn = pl_static.create_dyn(
    name="PL_dyn", comment="dynamic point (from PL_static)",
    multiplier={LoadMultiplierKey.Fz: mul_h_5Hz}
)
LoadMapper.create(g_i, pl_dyn)  # 在相同句柄上附加乘子

代码作用：测试动态荷载系统的创建，包括荷载乘子的定义和动态荷载的生成，验证荷载映射器对静态-动态荷载关联关系的处理。

荷载映射机制：

  • 静态荷载直接创建Plaxis荷载对象
  • 动态荷载通过乘子附加到静态荷载基座上
  • 支持谐波、表格等多种荷载类型

6. 阶段映射测试

阶段定义与继承

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 阶段设置
st_init = PlasticStageSettings(
    load_type=LoadType.StageConstruction,
    max_steps=100, time_interval=0.5, 
    over_relaxation_factor=1.05, ΣM_weight=1.0
)

# 阶段对象（必须继承自基础阶段）
phase0 = Phase(
    name="Phase0_InitialSupports",
    comment="Activate base supports the anchor depends on.",
    settings=st_init,
    activate=[wall1, waler, plate1, pile1],  # 激活结构
    deactivate=[],  # 冻结结构
    inherits=initial_phase  # 必须指定继承关系
)

# 创建阶段并应用
h = PhaseMapper.create(g_i, ph)  # 继承自ph.inherits

代码作用：测试施工阶段的创建和管理，包括阶段设置、结构激活/冻结、阶段继承关系，验证阶段映射器对复杂施工序列的处理能力。

阶段映射特点：

  • 强制阶段继承关系，确保计算连续性
  • 支持结构激活/冻结状态管理
  • 可配置土体材料行为覆盖

7. 完整建模流程测试

基坑模型组装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def assemble_pit(runner=None) -> FoundationPit:
    # 1. 工程信息
    proj = ProjectInformation(
        title="Rectangular Pit – DWall + Braces + Wells",
        company="Demo", model="3D", element="10-noded",
        length_unit=Units.Length.M, force_unit=Units.Force.KN
    )
    pit = FoundationPit(project_information=proj)
    
    # 2. 材料定义
    fill = SoilMaterialFactory.create(SoilMaterialsType.MC, name="Fill", ...)
    pit.add_material("soil_materials", fill)
    
    # 3. 钻孔数据
    pit.borehole_set = build_borehole_set(...)
    
    # 4. 结构系统
    walls = [RetainingWall(name=..., surface=..., plate_type=...)]
    for w in walls:
        pit.add_structure(StructureType.RETAINING_WALLS.value, w)
    
    # 5. 降水井系统
    wells_unique, stats = layout_wells_with_limit(...)
    for w in wells_unique:
        pit.add_structure(StructureType.WELLS.value, w)
    
    # 6. 施工阶段
    for p in (ph0, ph1, ph2, ph3):
        pit.add_phase(p)
    
    return pit

代码作用：测试完整的基坑工程建模流程，集成所有组件（材料、几何、结构、荷载、阶段），验证框架在复杂工程场景下的综合应用能力。

构建器执行

1
2
3
4
5
6
7
8
9
runner = PlaxisRunner(HOST, PORT, PASSWORD)
pit = assemble_pit(runner=runner)
builder = ExcavationBuilder(runner, pit)

print("[BUILD] start …")
builder.build()  # 执行完整构建流程
print("[BUILD] done.")

builder.calculate()  # 开始计算

代码作用：测试构建器的执行流程，从模型定义到实际构建和计算，验证整个框架的端到端功能完整性。

完整流程映射：

  • 通过FoundationPit容器组织所有工程组件
  • ExcavationBuilder负责执行映射构建
  • 支持从模型定义到计算的全自动化流程

测试小结

通过深入分析testmapper.ipynb中的映射测试源代码，我们可以看到这个测试文件实际上构建了一个完整的Plaxis代理框架验证体系。它不仅测试了各个独立组件的功能，更重要的是验证了组件之间的协同工作和整个建模流程的完整性。

测试文件从最基础的材料映射开始，逐步构建起复杂的工程模型。在材料测试部分，我们看到框架支持从简单的弹性材料到复杂的各向异性材料和弹塑性材料。每种材料类型都有对应的映射器负责将领域对象转换为Plaxis内部表示，这个过程不仅仅是简单的参数传递，还包含了类型检查、参数验证和默认值处理等复杂逻辑。特别值得注意的是，材料映射器会自动为每个创建的对象分配plx_id，这个标识符成为连接领域模型和Plaxis实体的桥梁，为后续的引用和管理奠定了基础。

几何映射测试展现了框架在处理空间关系方面的能力。从简单的点开始，到线、面的构建，测试代码演示了一个完整的几何创建链条。这里体现了一个重要的设计理念：几何对象之间存在严格的依赖关系，框架必须确保这种关系在映射过程中得到保持。删除测试则验证了资源管理的正确性，确保在对象生命周期结束时能够正确释放Plaxis资源，避免内存泄漏和句柄混乱。这种严格的生命周期管理对于长期运行的岩土工程分析至关重要。

结构映射测试将材料和几何结合起来，创建出具有工程意义的实体。测试中特别强调了每个结构使用独立几何实例的重要性，这避免了在复杂模型中可能出现的句柄冲突问题。结构映射器不仅要处理自身的创建逻辑，还要协调材料引用和几何依赖，这种多层级的关联管理体现了框架设计的复杂性。

钻孔数据测试展示了框架处理地质信息的能力。在实际工程中，钻孔数据往往存在土层缺失、厚度变化等不一致情况，测试中的归一化功能正是为了解决这一问题。通过自动补全缺失土层和调整层序，框架确保了地质模型的一致性，这为后续的稳定性分析提供了可靠的基础。

荷载系统测试涵盖了从静态到动态的完整荷载类型。特别值得注意的是动态荷载的实现方式：它不是创建新的荷载实体，而是在静态荷载的基础上附加乘子。这种设计既符合Plaxis的内部机制，又提供了清晰的荷载管理逻辑。测试中的荷载防护机制确保同一几何体上不会创建多个静态荷载，这避免了荷载叠加导致的数值计算问题。

阶段映射测试验证了施工序列的管理能力。岩土工程的核心就是模拟施工过程，阶段管理系统必须确保每个阶段的继承关系和状态转换的正确性。测试中展示的阶段继承机制、结构激活/冻结功能以及土体行为覆盖能力，构成了一个完整的施工过程模拟框架。

最终的完整建模流程测试将所有这些组件整合在一起，构建了一个真实的基坑工程模型。从工程信息配置到材料定义，从钻孔数据导入到结构系统布置，从降水井设计到施工阶段划分，测试代码演示了一个端到端的工程建模过程。这种集成测试不仅验证了各个组件的功能，更重要的是检验了组件之间的协同工作和数据流传递。

#学习 #Plaxis软件 #Python有限元分析
Plaxis代理封装框架——完整的基坑仿真解析(一)
https://www.eatrice.cn/post/PlaxisFrameworkTwo/
作者
吃白饭-EatRice
发布于
2025年11月21日
许可协议