Plaxis远程脚本教程四——一个全新的代理封装框架

博客的这个系列好久没有更新了，在沉寂的这些时候，断断续续地有又有通过这个教程与我结识。有的友友只有一面之缘，有的友友结下了深厚的友谊。我一直觉得人与人的相遇是一件很奇妙的事情，世界上有那么多人，正好在我认识的有限的人里面，你就是其中之一。今天在工作的时候，QQ 音乐悄悄地把我的背景音乐切换成了苏打绿的《你被写在我的歌里》：

走过的路 是一阵魔术

把所有的 好的坏的 变成我的

确实，人有悲欢离合，月有阴晴圆缺。其实经历了这么多，发现人与人的所有的矛盾都来自于不成熟，但是人不能踏入同一条河流，但是作为在成长道路上披星戴月的我们，不就是在历经千万磨练时，寻求外在与内心上的蜕变，追求前方的风与自由吗。现在看来，好与坏都不再那么重要，都是我们成长历程中的最为宝贵的小幸运。

这个 Plaxis 教程对于我来说意义非凡，是我众多支点中一个十分重要联结了许多友友的一个纽带，但是在 22 年由于各种原因暂停了更新，而且用法都是一致的，继续更新也没有很大大意义，看文档能解决大部分的问题。在近两年的科研中，我陆陆续续还在使用 Plaxis 软件作为仿真的工具，也积累了一些使用经验，因此我做了一个决定，把当前使用的一些经验设计成一个开源框架，以方便友友们能够通过这个框架降低使用 Plaxis 自动化门槛，把所有需要试错的问题，全部集成到框架中让同学们可以无痛调用，减少莫名其妙的错误。因此我设计了这个 plaxisproxy-excavation 这个框架。顾名思义，这是一个把 Plaxis 原有的需要边看文档边猜测的原生命令脚本封装成了一个代理工具包，所有对象的创建和调用都封装成了具体的类和方法，并且给出了__doc__文档。

这个代码框架开源了有些时候，原本由于近期相当忙，想过段时间再来解析和补充这个框架的用法，但是今晚听到的这首歌，把我拉回了以前那激情澎湃的思绪中。于是我决定先写一个总纲，向大家推介这套代码框架，便于有需要的同学可以快速入门。

这原本是一个系列的一部分，但也可以不作为一部分，但我将其整理到了一个分类中，链接地址：Plaxis 软件远程脚本教程

🧱 plaxisproxy-excavation

A Pythonic automation framework for Plaxis 3D excavation modeling and simulation
（一个面向 Plaxis 3D 软件的基坑工程建模与仿真自动化框架，注意是 3D，不是之前的 2D）。欢迎感兴趣的同学可以联系我，可以进一步开发 2D 软件的映射工具，以拓展当前的项目的使用范围。

不知道 Plaxis 远程脚本是啥的同学请看这里：Plaxis远程脚本教程一——总纲

当前项目实现了基本的土体材料（集成了摩尔库伦、修正剑桥和小应变硬化模型，其他模型暂未集成）、板、梁、锚杆、嵌固桩、降水井的材料和对象的定义，并进一步定义了施工阶段对象和施工阶段配置。在此基础上实现了这些实体对象到 Plaxis 软件的 mapper 模块，将我们编程的重心从原来的建模和调试 Plaxis 映射两大块工作，解放到只需要专注建模和结果提取上。本框架因为叫名字中有 excavation ，因此进一步在 builder 中实现了基坑工程的自动建模器，且在 examples 中给了一个完整的建模用例。如有其他工程类型需求的同学可以一起交流讨论，创建更多的工程项目自动建模器。

Github 项目地址：QiQiWan - plaxisproxy-excavation

🌍 项目简介 | Project Introduction

plaxisproxy-excavation 是一个面向 Plaxis 3D 的自动化仿真与建模封装框架，基于 Python 3.9.x 开发，适用于 教学、科研与实际工程模拟。

该项目通过对 Plaxis 的原生脚本接口（plxscripting）进行 面向对象 (OOP) 的再封装，构建了一个清晰、统一、可扩展的 API 层，实现了以下自动化流程：

  • 🧩 自动化建模：自动生成土层、支护、降水、开挖阶段等；
  • ⚙️ 自动化计算：自动执行 Plaxis 求解流程；
  • 📊 结果提取与导出：从 Plaxis Output 中提取关键结果（如位移、内力、应力）；
  • 🚀 可扩展框架：便于添加新的材料类型、结构、边界条件与后处理逻辑。

目标：以更清晰的 Python API 替代原生 plxscripting 的低层接口，
让 Plaxis 3D 的数值仿真变得可编程、可维护、可复现。

💡 设计初衷 | Motivation for Wrapping Plaxis API

🧱 原生 plxscripting 的痛点

Plaxis 官方提供的 plxscripting 库虽然能实现远程建模与控制计算，但存在明显问题：

问题类别 原因 影响
命令发现困难 许多对象的属性与方法只能通过 __dir__() 或实验调用才能得知 开发时缺乏补全与文档支持
属性调用不透明 参数命名、大小写与类型不一致 容易出错且调试困难
调用顺序依赖强 例如创建材料与结构的先后顺序必须符合内部逻辑 一旦顺序错，脚本即失败
参数验证缺失 无类型检查与参数验证机制 常见报错如 “unknown property”、“wrong argument type”
错误提示晦涩 返回通用异常信息 不利于教学与复用

💬 简言之，原生 API 是“能用但不友好”；它更像一个 远程命令行接口 而非真正的编程库。

之前很多同学在我的博客留言，咨询我各种 Plaxis 脚本不起作用的问题，通过后面的学习研究我发现这些问题主要是来源于属性的相互冲突和属性赋值的先后顺序不对导致，因此这个框架着重解决了这个问题，并且封装成了相应的对象和函数，以便调用。

另外在学习过程中仍有问题的同学，可以直接添加我的微信方便交流，我博客的留言板托管在第三方的云平台，由于是免费版本所以留言服务一直不稳定，原来部署了邮件通知的功能现在均已失效，只能我随缘看到大家的留言。

✅ 显式封装 API 的优势

在 plaxisproxy-excavation 中，所有 Plaxis 命令均被重新封装为显式 API：

项目 原生 plxscripting plaxisproxy-excavation 封装后
调用方式 模糊命令（需 __dir__() 探测） 显式类方法（IDE 可自动补全）
参数传递 不统一（类型/顺序依赖内部） 明确参数名与类型提示
错误控制 无校验，抛出模糊异常 自动检测并抛出详细错误
对象关系 全局命令式 面向对象（Wall、Soil、Well、Phase 等）
阶段管理 手动创建、关联复杂 自动管理 Phase 链接与激活逻辑
脚本结构 程序化但不可维护 高层抽象清晰、模块化、可扩展

⚙️ 显式 API 能解决的核心问题

  1. 🧩 清晰调用关系

    原来Plxscrpting框架中全部使用PlxFactory来衍生映射所有命令，这种衍生出来的对象中的属性和方法是隐式的，无法直接被 IDE 的代码自动补全读取。现在这个框架将常用的命令进行了显式化，不再需要靠 __dir__() 试探命令。每个 Plaxis 对象都有专属类（如 RetainingWall、SoilLayer、Well），其方法与属性在 IDE 中一目了然。

  2. 🧱 参数赋值与顺序控制
    创建材料或结构时，封装内部嵌入了相应的完整性检查算法，会自动确保正确的参数顺序与依赖关系。例如：

    • 材料属性自动检查单位与类型；
    • 结构依赖的材料对象会自动绑定；
    • 避免 “property not found” 与 “attribute missing” 错误。（试了无数的用例，编了无数的代码得到的经验哈哈哈哈😂）

  3. 🧠 逻辑防护与错误校验
    通过编写相应的算法，使得在基本的对象创建和映射功能之外，实现了每个 API 都内置参数校验与异常捕获。例如：

    • 创建钻孔时，内置算法可以提取所有的钻孔中的不同土层进行全局排序，后分发到各个钻孔中，确保输入的非均匀厚度、缺失土层（程序中作为 0 厚度处理）和侵入土层都能够被正常建模（局部序列抽取、邻接约束构图和拓扑排序算法）。
    • 若某墙体底部未闭合，将提示几何不封闭（几何检查算法）；
    • 若 excava_depth 超出最深墙底，则阻止生成坑底（归并排序】）；
    • 这些检查能防止仿真失败或非物理计算。

✨ 功能与优势 | Features & Benefits

🔍 功能概览

功能模块 描述
🏗️ 自动化建模 从几何、土层、结构到开挖阶段的全流程自动建模
⚙️ 自动化计算 自动触发网格生成与计算，支持阶段继承
📊 结果提取与导出 可提取 Ux、Uy、Uz、应力、内力等结果并导出 Excel
🧱 项目检查 自动检查墙体闭合、深度合理性、阶段连贯性
🧩 封装式 API 提供 OOP 风格的清晰接口，统一参数命名与结构层级
🔁 可扩展性 模块化设计，可自定义结构、材料、工况与导出器

✅ 封装带来的优势

  • [x] 提高建模效率：通过类方法批量创建模型要素；
  • [x] 降低重复劳动：支持多阶段、重复性模型的复用；
  • [x] 改进代码可维护性：清晰的模块与接口设计；
  • [x] 便于扩展与集成：可与优化算法、可视化工具协同；
  • [x] 提升教学体验：学生可快速理解数值建模逻辑；
  • [x] 增强鲁棒性：自动检测参数合法性与几何闭合；
  • [x] 统一接口风格：所有命令均采用 Python 风格命名；
  • [x] 支持批量仿真：可快速运行多工况对比分析。

⚙️ 安装与环境 | Installation & Environment

🧩 依赖环境

  • Python 3.9.x
  • Plaxis 3D 2023 或以上版本
  • 需启用 Plaxis Remote Scripting 服务

📦 Python 包依赖

安装本框架之前需要先安装依赖：

1
2
pip install shapely==2.0.7
pip install plxscripting==1.0.4

直接运行以下命令安装本框架：

1
pip install plaxisproxy-excavation

⚙️ 配置 Plaxis 远程服务

修改：

1
config/plaxis_config.py

设置：

1
2
3
HOST = "localhost"
PORT = 10000
PASSWORD = "your_plaxis_password"

确保 Plaxis 3D 已启动且 Remote scripting 服务处于开启状态。

🧩 项目结构 | Project Architecture

📁 目录树

想参与开发的同学可以通过项目的目录树结构快速了解我们的项目，整体核心代码一万六千行左右，代码结构主要分为 8 个模块：

  1. 根目录下geometry.py定义了整个项目的基本几何对象，包括点、线、面、体，所有的结构对象均需映射到基本几何对象上；
  2. borehole.py 定义了基本土层对象、钻孔对象和钻孔集对象，并集成了相应的配套算法，所有的岩土分析都需要使用钻孔来创建地质层，因此我将其放在了根目录；
  3. excavation.py 定义了一个完整的基坑工程中需要用到的所有部件，包括材料、结构、边界条件、施工阶段等，因为它不是单个组件，因此我也将其放在了根目录；
  4. core/ 定义了项目所有实体对象的基本对象，包括可序列化对象，使得项目中所有的对象都可以导出为规范化字典，并且从字典载入对象；定义了基础的 PlaxisObject 对象，使得所有实体对象都会获得 plx_id 属性，便于与 Plaxis 软件相互映射。后面开发的所有对象都应该继承 PlaxisObject 对象；
  5. materials/ 文件夹定义了 Plaxis 3D 软件中支持的除了土工格室外的所有材料模型，为啥不定义土工格室呢，因为我用不上哈哈哈哈；
  6. components/ 文件夹定义了所有非主体结构对象的实体，包括网格划分、曲线点、项目信息、水位边界条件、施工阶段和施工阶段配置；
  7. plaxishelper/ 定义了将所有所有建立的实体对象映射到 Plaxis 软件的工具类，单个实体映射工具类名称为 xxxmapper, 并且定义了统一的建模帮助类PlaxisRunner和结果提取类PlaxisOutput，将分散定义的结构映射代理封装到了一个位置，便于统一调用；
  8. builder/ 中定义了一键生成具体的工程对象的帮助类，能够实现在用例中通过简单调用，快速建立分析模型和提取结果，因为我是研究基坑的，因此目前仅集成了基坑对象的 builder

由以上可见，同学如果需要开发隧道、边坡、路基等其他类型的工程案例，仅需创建新的类似于excavation.py的工程类型对象，和类似于excavation_builder.py的一键建模和结果提取的帮助类即可，其他模块均可完全复用。

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
plaxisproxy-excavation/
├─ config/
│  └─ plaxis_config.py
├─ examples/
│  └─ testmapper.py
├─ src/
│  └─ plaxisproxy_excavation/
│     ├─ core/
│     │  ├─ __init__.py
│     │  └─ plaxisobject.py           # 基类/对象抽象：统一ID/会话/属性映射
│     │
│     ├─ components/
│     │  ├─ __init__.py
│     │  ├─ curvepoint.py             # 曲线/特征点抽象（供几何/工况使用）
│     │  ├─ mesh.py                   # 网格全局设置/细化策略
│     │  ├─ phase.py                  # Phase 实体：继承、激活清单、土体覆盖等
│     │  ├─ phasesettings.py          # 塑性阶段/加载类型/步长等计算参数
│     │  ├─ projectinformation.py     # 工程信息、单位体系
│     │  └─ watertable.py             # 水位点表/水位面定义
│     │
│     ├─ materials/
│     │  ├─ __init__.py
│     │  ├─ anchormaterial.py         # 锚杆/拉索类材料
│     │  ├─ basematerial.py           # 统一材料基类（公共属性、校验）
│     │  ├─ beammaterial.py           # 梁单元材料（支撑/立柱等）
│     │  ├─ pilematerial.py           # 桩/嵌入式桩材料
│     │  ├─ platematerial.py          # 板单元材料（如地连墙）
│     │  └─ soilmaterial.py           # 土体材料与工厂（SoilMaterialFactory, 枚举）
│     │
│     ├─ plaxishelper/
│     │  ├─ __init__.py
│     │  ├─ boreholemapper.py         # 钻孔/层序 → Plaxis 映射
│     │  ├─ geometrymapper.py         # Point/Line/Polygon/Surface 映射
│     │  ├─ loadmapper.py             # 荷载与工况映射
│     │  ├─ materialmapper.py         # 各类材料属性映射/赋值顺序控制
│     │  ├─ meshmapper.py             # 网格生成与细化策略下发
│     │  ├─ monitormapper.py          # 监测点/结果监测映射
│     │  ├─ phasemapper.py            # Phase 创建/继承/激活清单映射
│     │  ├─ plaxisoutput.py           # Output 会话与结果查询封装
│     │  ├─ plaxisrunner.py           # Input/Output 客户端、会话与错误处理
│     │  ├─ projectinfomapper.py      # 工程信息/单位映射
│     │  ├─ resulttypes.py            # 结果枚举（Plate.Ux 等）
│     │  └─ structuremapper.py        # 结构体（墙/梁/井/荷载等）映射
│     │     └─ watertablemapper.py    # （同级）水位相关映射
│     │
│     ├─ structures/
│     │  ├─ __init__.py
│     │  ├─ anchor.py                 # 锚杆/拉锚结构
│     │  ├─ basestructure.py          # 结构基类：通用属性、创建协议
│     │  ├─ beam.py                   # 梁/撑（水平撑、围檩等）
│     │  ├─ embeddedpile.py           # 嵌入式桩
│     │  ├─ load.py                   # 面/线/点荷载实体
│     │  ├─ retainingwall.py          # 围护墙（地连墙/截桩墙等）
│     │  ├─ soilblock.py              # 土体块（开挖块/保留块）
│     │  └─ well.py                   # 井点（抽水/回灌，参数：流量、井深等）
│     │
│     ├─ excavation.py                # FoundationPit 容器 + StructureType 枚举
│     ├─ geometry.py                  # 项目的基本几何对象，包括点、线、面、体
│     ├─ borehole.py                  # 项目的钻孔管理对象，定义了土层、钻孔和钻孔集
│     └─ builder/
│        └─ excavation_builder.py     # 构建器：建模/阶段/计算/结果提取的总控
│
├─ tests/
│  └─ ...
├─ requirements.txt
└─ README.md

其实一个完整的项目还应该包含完整的单元测试，由于笔者实在没有大量的空闲时间完成所有的单元测试，当前代码仓库仅编写了基本的材料、结构、几何、钻孔和施工阶段的测试，基坑工程的完整建模和 mapper 的测试尚未完整，感兴趣参与贡献交流学习的同学可以联系我从编写单元测试开始。

🧱 模块职责概览

模块 说明
excavation_builder.py 控制整个建模与计算流程的核心模块。负责模型验证、阶段创建、计算执行、结果导出。
excavation.py 定义基坑对象 FoundationPit，包含几何边界、结构列表、施工阶段等。
materials/ 封装不同类型的材料：土体、板、梁、锚杆等；提供属性映射与默认参数。
structures/ 定义支护、井点、墙体等结构元素类
geometry.py 几何操作辅助（如多边形生成、坐标变换、体积计算）。
borehole.py 土层与钻孔模型，支持按深度分层。
plaxishelper/ 对原生 plxscripting 进行轻封装，包括 Input、Output 的客户端管理。
resulttypes.py 统一结果枚举（如位移、内力、应力类型），用于结果提取函数。

🧭 架构逻辑图

1
2
3
4
5
PlaxisRunner  →  ExcavationBuilder  →  FoundationPit
                                   ↙
                        Structures / Materials / Phases
                                   ↘
                               Result Exporter
  • PlaxisRunner：负责连接和会话管理；
  • ExcavationBuilder：负责构建、计算、提取；
  • FoundationPit：数据容器；
  • Structures：结构与支护；
  • Exporter：导出 Excel。

💬 如何贡献 | How to Contribute

  1. Fork 仓库并创建新分支：

    1
    git checkout -b feature/new-module
  2. 在 src/plaxisproxy_excavation/ 下添加新类或模块；
  3. 编写单元测试（放入 /tests）；
  4. 提交 PR 并附带使用示例。

🧠 示例解析 | Example: examples/testmapper.py

下面是一个示例脚本（examples/testmapper.py）的简要介绍，展示如何通过封装的 API 自动化完成基坑建模、计算与结果导出。完整代码请参阅 github 的项目中 examples/testmapper.py，这里仅简单介绍关键代码。

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
# -*- coding: utf-8 -*-
"""
testmapper.py
Demonstration of automated pit assembly and calculation using Plaxis API wrapper.
"""

from src.plaxisproxy_excavation.excavation import FoundationPit
from src.plaxisproxy_excavation.excavation_builder import ExcavationBuilder
from src.plaxisproxy_excavation.plaxishelper.runner import PlaxisRunner
from src.plaxisproxy_excavation.materials import SoilMaterialFactory
from src.plaxisproxy_excavation.structures import RetainingWall, Well
from shapely.geometry import Polygon
import math

def rect_wall_x(y0=0, y1=50, x=0, z0=0, z1=-25):
    """Create rectangular wall geometry along x-axis."""
    return [[x, y0, z0], [x, y1, z0], [x, y1, z1], [x, y0, z1]]

def wells_on_polygon_edges(polygon: Polygon, spacing: float = 5.0):
    """Generate well points along polygon edges at given spacing."""
    coords = list(polygon.exterior.coords)
    wells = []
    for i in range(len(coords)-1):
        p1, p2 = coords[i], coords[i+1]
        length = math.hypot(p2[0]-p1[0], p2[1]-p1[1])
        n = int(length // spacing)
        for j in range(n+1):
            x = p1[0] + (p2[0]-p1[0]) * j / n
            y = p1[1] + (p2[1]-p1[1]) * j / n
            wells.append((x, y))
    return wells

def assemble_pit():
    """Create a demo excavation pit with walls, soil, and wells."""
    runner = PlaxisRunner("localhost", 10000, "password")
    pit = FoundationPit("TeachingDemoPit")

    # Define soil
    soil = SoilMaterialFactory.create_default()
    pit.add_soil(soil)

    # Define walls
    wall1 = RetainingWall(points=rect_wall_x(y0=0, y1=40, x=0))
    wall2 = RetainingWall(points=rect_wall_x(y0=0, y1=40, x=40))
    pit.add_structure(wall1)
    pit.add_structure(wall2)

    # Define wells
    polygon = Polygon([(0,0), (40,0), (40,40), (0,40)])
    wells = wells_on_polygon_edges(polygon)
    for w in wells:
        pit.add_structure(Well(x=w[0], y=w[1], depth=25))

    builder = ExcavationBuilder(runner, pit)
    builder.build()
    builder.calculate()

    # Export displacement results
    from src.plaxisproxy_excavation.utils.exporter import export_walls_horizontal_displacement_excel_2
    export_walls_horizontal_displacement_excel_2(builder, "results.xlsx")

if __name__ == "__main__":
    assemble_pit()

📖 逐行解析与对应模块

行号范围 内容 说明
1–11 模块导入 引入核心构建类与封装的几何、结构模块；替代了原生 g_i.* 命令。
13–18 rect_wall_x 用于生成矩形墙体的几何点序列；返回四点封闭多边形。对应封装在 geometry.py。
20–32 wells_on_polygon_edges 利用 shapely 生成井点坐标；按边长度与间距自动布井。
34–65 assemble_pit() 主函数 主体逻辑：连接 Plaxis → 定义土体 → 墙体 → 井点 → 构建与计算。
37 PlaxisRunner 建立与 Plaxis 3D Input 服务的通信连接（底层基于 plxscripting）。
38–39 FoundationPit 创建基坑对象，作为统一的模型容器。
42 SoilMaterialFactory 自动生成默认土体材料（带物理参数），封装自 materials 模块。
44–47 RetainingWall 定义墙体结构并加入基坑；自动建立墙面几何与材料关联。
49–55 Well 沿边布置井点降水系统，体现典型基坑降水布置。
57–61 ExcavationBuilder 调用构建器自动生成几何、材料、结构与阶段。
63–64 export_walls_horizontal_displacement_excel_2 结果导出函数，提取每面墙在各阶段的位移结果到 Excel。
66–67 主函数调用 直接运行后完成整个建模、计算与导出流程。

🔁 自动化工作流说明

  1. 连接阶段：PlaxisRunner 自动打开 Input 会话；
  2. 建模阶段：ExcavationBuilder.build() 调用内部 _create_materials()、_create_structures()；
  3. 计算阶段：builder.calculate() 调用 Plaxis API 执行所有 Phase；
  4. 结果阶段：自动连接 Output，提取所需结果；
  5. 导出阶段：封装导出器输出 Excel 报表，一面墙一个 Sheet。

🤝 贡献与许可证 | Contributing & License

  • 本项目遵循 Apache-2.0；
  • 欢迎提交 Issue 或 Pull Request；

  • 建议附带：

    • 示例脚本；
    • 单元测试；
    • 文档更新。

🏁 总结 | Summary

plaxisproxy-excavation 通过面向对象封装，将 Plaxis 的复杂命令行式接口转化为清晰、统一、自动化的 Python API，使得：

  • 模型构建更快、更稳、更可控；
  • 代码结构更清晰、易维护；
  • 仿真流程更自动化、可重复。

无论是教学演示、科研实验，还是

工程项目的标准化分析流程，它都能极大提升 Plaxis 的使用体验。

✅ *Repository:QiQiWan/plaxisproxy-excavation

📚 Language: Python 3.9

🧩 Dependencies: shapely==2.0.7, plxscripting==1.0.4

🏗️ Application: Plaxis 3D Excavation Automation Framework

后续我将陆续发布每个模块的单独用法详解，帮助大家快速上手本框架，要是有入门比较快的同学可以加入我一起写教程。材料、结构、实体对象映射的独立测试代码可以参考 examples/testmapper.ipynb。

交流与讨论

欢迎关注我的微信公众号：EatRicer的智能建造之旅，想交流讨论或参与贡献的同学可以添加我微信，参与的同学多了后我会拉一个交流群。

微信公众号二维码

EatRicer的智能建造之旅

添加我的微信一起讨论与优化

我的微信

#学习 #Plaxis软件 #Python有限元分析
Plaxis远程脚本教程四——一个全新的代理封装框架
https://www.eatrice.cn/post/PlaxisFrameworkOne/
作者
吃白饭-EatRice
发布于
2025年11月1日
许可协议