Plaxis远程脚本教程——一个全新的代理封装框架
博客的这个系列好久没有更新了，在沉寂的这些时候，断断续续地有又有通过这个教程与我结识。有的友友只有一面之缘，有的友友结下了深厚的友谊。我一直觉得人与人的相遇是一件很奇妙的事情，世界上有那么多人，正好在我认识的有限的人里面，你就是其中之一。今天在工作的时候，QQ 音乐悄悄地把我的背景音乐切换成了苏打绿的《你被写在我的歌里》：
走过的路 是一阵魔术
把所有的 好的坏的 变成我的
确实，人有悲欢离合，月有阴晴圆缺。其实经历了这么多，发现人与人的所有的矛盾都来自于不成熟，但是人不能踏入同一条河流，但是作为在成长道路上披星戴月的我们，不就是在历经千万磨练时，寻求外在与内心上的蜕变，追求前方的风与自由吗。现在看来，好与坏都不再那么重要，都是我们成长历程中的最为宝贵的小幸运。
这个 Plaxis 教程对于我来说意义非凡，是我众多支点中一个十分重要联结了许多友友的一个纽带，但是在 22 年由于各种原因暂停了更新，而且用法都是一致的，继续更新也没有很大大意义，看文档能解决大部分的问题。在近两年的科研中，我陆陆续续还在使用 Plaxis 软件作为仿真的工具，也积累了一些使用经验。
因此我做了一个决定，把当前使用的一些经验设计成一个开源框架，以方便友友们能够通过这个框架降低使用 Plaxis 自动化门槛，把所有需要试错的问题，全部集成到框架中让同学们可以无痛调用，减少莫名其妙的错误。因此我设计了这个 plaxisproxy-excavation 这个框架。顾名思义，这是一个把 Plaxis 原有的需要边看文档边猜测的原生命令脚本封装成了一个代理工具包，所有对象的创建和调用都封装成了具体的类和方法，并且给出了__doc__文档。
当前的代码开源了有些时候，原本由于近期相当忙，想过段时间再来解析和补充这个框架的用法，但是今晚听到的这首歌，把我拉回了以前那激 情澎湃的思绪中。于是我决定先写一个总纲，向大家推介这套代码框架，便于有需要的同学可以快速入门。
🧱 plaxisproxy-excavation
A Pythonic automation framework for Plaxis 3D excavation modeling and simulation（一个面向 Plaxis 3D 软件的基坑工程建模与仿真自动化框架，注意是 3D，不是之前的 2D）。欢迎感兴趣的同学可以联系我，可以进一步开发 2D 软件的映射工具，以拓展当前的项目的使用范围。
不知道 Plaxis 远程脚本是啥的同学请看这里：Plaxis远程脚本教程一——总纲：https://www.eatrice.cn/post/Plaxis2DPythonAPIOne/
当前项目实现了基本的土体材料（集成了摩尔库伦、修正剑桥和小应变硬化模型，其他模型暂未集成）、板、梁、锚杆、嵌固桩、降水井的材料和对象的定义，并进一步定义了施工阶段对象和施工阶段配置。在此基础上实现了这些实体对象到 Plaxis 软件的 mapper 模块，将我们编程的重心从原来的建模和调试 Plaxis 映射两大块工作，解放到只需要专注建模和结果提取上。本框架因为叫名字中有 excavation ，因此进一步在 builder 中实现了基坑工程的自动建模器，且在 examples 中给了一个完整的建模用例。如有其他工程类型需求的同学可以一起交流讨论，创建更多的工程项目自动建模器。
Github 项目地址：https://github.com/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__() 或实验调用才能得知 | |
| 属性调用不透明 | ||
| 调用顺序依赖强 | ||
| 参数验证缺失 | ||
| 错误提示晦涩 |
💬 简言之，原生 API 是“能用但不友好”；它更像一个 远程命令行接口 而非真正的编程库。
之前很多同学在我的博客留言，咨询我各种 Plaxis 脚本不起作用的问题，通过后面的学习研究我发现这些问题主要是来源于属性的相互冲突和属性赋值的先后顺序不对导致，因此这个框架着重解决了这个问题，并且封装成了相应的对象和函数，以便调用。
另外在学习过程中仍有问题的同学，可以直接添加我的微 信方便交流，我博客的留言板托管在第三方的云平台，由于是免费版本所以留言服务一直不稳定，原来部署了邮件通知的功能现在均已失效，只能我随缘看到大家的留言。
✅ 显式封装 API 的优势
在 plaxisproxy-excavation 中，所有 Plaxis 命令均被重新封装为显式 API：
| 调用方式 | __dir__() 探测） | |
| 参数传递 | ||
| 错误控制 | ||
| 对象关系 | ||
| 阶段管理 | ||
| 脚本结构 |
⚙️ 显式 API 能解决的核心问题
🧩 清晰调用关系
原来
Plxscrpting框架中全部使用PlxFactory来衍生映射所有命令，这种衍生出来的对象中的属性和方法是隐式的，无法直接被 IDE 的代码自动补全读取。现在这个框架将常用的命令进行了显式化，不再需要靠__dir__()试探命令。每个 Plaxis 对象都有专属类（如RetainingWall、SoilLayer、Well），其方法与属性在 IDE 中一目了然。🧱 参数赋值与顺序控制创建材料或结构时，封装内部嵌入了相应的完整性检查算法，会自动确保正确的参数顺序与依赖关系。例如：
材料属性自动检查单位与类型； 结构依赖的材料对象会自动绑定； 避免 “property not found” 与 “attribute missing” 错误。（试了无数的用例，编了无数的代码得到的经验哈哈哈哈😂） 🧠 逻辑防护与错误校验通过编写相应的算法，使得在基本的对象创建和映射功能之外，实现了每个 API 都内置参数校验与异常捕获。例如：
创建钻孔时，内置算法可以提取所有的钻孔中的不同土层进行全局排序，后分发到各个钻孔中，确保输入的非均匀厚度、缺失土层（程序中作为 0 厚度处理）和侵入土层都能够被正常建模（局部序列抽取、邻接约束构图和拓扑排序算法）。 若某墙体底部未闭合，将提示几何不封闭（几何检查算法）； 若 excava_depth超出最深墙底，则阻止生成坑底（归并排序】）；这些检查能防止仿真失败或非物理计算。
✨ 功能与优势 | Features & Benefits
🔍 功能概览
✅ 封装带来的优势
[x] 提高建模效率：通过类方法批量创建模型要素； [x] 降低重复劳动：支持多阶段、重复性模型的复用； [x] 改进代码可维护性：清晰的模块与接口设计； [x] 便于扩展与集成：可与优化算法、可视化工具协同； [x] 提升教学体验：学生可快速理解数值建模逻辑； [x] 增强鲁棒性：自动检测参数合法性与几何闭合； [x] 统一接口风格：所有命令均采用 Python 风格命名； [x] 支持批量仿真：可快速运行多工况对比分析。
⚙️ 安装与环境 | Installation & Environment
🧩 依赖环境
Python 3.9.x Plaxis 3D 2023 或以上版本 需启用 Plaxis Remote Scripting 服务
📦 Python 包依赖
安装本框架之前需要先安装依赖：
1 | |
直接运行以下命令安装本框架：
1 | |
⚙️ 配置 Plaxis 远程服务
修改：
1 | |
设置：
1 | |
🧩 项目结构 | Project Architecture
📁 目录树
想参与开发的同学可以通过项目的目录树结构快速了解我们的项目，整体核心代码一万六千行左右，代码结构主要分为 8 个模块：
根目录下 geometry.py定义了整个项目的基本几何对象，包括点、线、面、体，所有的结构对象均需映射到基本几何对象上；borehole.py定义了基本土层对象、钻孔对象和钻孔集对象，并集成了相应的配套算法，所有的岩土分析都需要使用钻孔来创建地质层，因此我将其放在了根目录； excavation.py定义了一个完整的基坑工程中需要用到的所有部件，包括材料、结构、边界条件、施工阶段等，因为它不是单个组件，因此我也将其放在了根目录； core/定义了项目所有实体对象的基本对象，包括可序列化对象，使得项目中所有的对象都可以导出为规范化字典，并且从字典载入对象；定义了基础的 PlaxisObject对象，使得所有实体对象都会获得plx_id属性，便于与Plaxis软件相互映射。后面开发的所有对象都应该继承PlaxisObject对象；materials/文件夹定义了 Plaxis 3D 软件中支持的除了土工格室外的所有材料模型，为啥不定义土工格室呢，因为我用不上哈哈哈哈； components/文件夹定义了所有非主体结构对象的实体，包括网格划分、曲线点、项目信息、水位边界条件、施工阶段和施工阶段配置； plaxishelper/定义了将所有所有建立的实体对象映射到 Plaxis 软件的工具类，单个实体映射工具类名称为 xxxmapper, 并且定义了统一的建模帮助类PlaxisRunner和结果提取类PlaxisOutput，将分散定义的结构映射代理封装到了一个位置，便于统一调用；builder/中定义了一键生成具体的工程对象的帮助类，能够实现在用例中通过简单调用，快速建立分析模型和提取结果，因为我是研究基坑的，因此目前仅集成了基坑对象的 builder
由以上可见，同学如果需要开发隧道、边坡、路基等其他类型的工程案例，仅需创建新的类似于excavation.py的工程类型对象，和类似于excavation_builder.py的一键建模和结果提取的帮助类即可，其他模块均可完全复用。
其实一个完整的项目还应该包含完整的单元测试，由于笔者实在没有大量的空闲时间完成所有的单元测试，当前代码仓库仅编写了基本的材料、结构、几何、钻孔和施工阶段的测试，基坑工程的完整建模和 mapper 的测试尚未完整，感兴趣参与贡献交流学习的同学可以联系我从编写单元测试开始。
🧱 模块职责概览
| excavation_builder.py | |
| excavation.py | FoundationPit，包含几何边界、结构列表、施工阶段等。 |
| materials/ | |
| structures/ | |
| geometry.py | |
| borehole.py | |
| plaxishelper/ | plxscripting 进行轻封装，包括 Input、Output 的客户端管理。 |
| resulttypes.py |
🧭 架构逻辑图
1 | |
PlaxisRunner
：负责连接和会话管理； ExcavationBuilder
：负责构建、计算、提取； FoundationPit
：数据容器； Structures
：结构与支护； Exporter
：导出 Excel。
💬 如何贡献 | How to Contribute
Fork 仓库并创建新分支：
1git checkout -b feature/new-module在 src/plaxisproxy_excavation/下添加新类或模块；编写单元测试（放入 /tests）；提交 PR 并附带使用示例。
🧠 示例解析 | Example: examples/testmapper.py
下面是一个示例脚本（examples/testmapper.py）的简要介绍，展示如何通过封装的 API 自动化完成基坑建模、计算与结果导出。完整代码请参阅 github 的项目中 examples/testmapper.py，这里仅简单介绍关键代码。
"""
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
defrect_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]]
defwells_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
defassemble_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() | |
| 37 | PlaxisRunner | |
| 38–39 | FoundationPit | |
| 42 | SoilMaterialFactory | |
| 44–47 | RetainingWall | |
| 49–55 | Well | |
| 57–61 | ExcavationBuilder | |
| 63–64 | export_walls_horizontal_displacement_excel_2 | |
| 66–67 |
🔁 自动化工作流说明
连接阶段：
PlaxisRunner自动打开 Input 会话；建模阶段：
ExcavationBuilder.build()调用内部_create_materials()、_create_structures()；计算阶段：
builder.calculate()调用 Plaxis API 执行所有 Phase；结果阶段：
自动连接 Output，提取所需结果； 导出阶段：
封装导出器输出 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。
