《pyFEM帮助文档（完整版）》

# pyFEM 帮助文档（完整版）

说明

• 本文件由《pyFEM帮助文档正文（第一批）》到《pyFEM帮助文档正文（第六批）》合并整理而成。
• 文档内容严格基于 project_code_bundle.txt 中可确认的实现与测试行为编写，保持保守口径，不把占位能力、预留入口或未接入正式主线的对象写成已支持功能。
• 当前版本的重点是形成一份连续可读、章节统一、术语一致的完整帮助文档，便于后续继续润色、补图或转换为发布格式。

目录

1. 第 1 章 软件概览
2. 第 2 章 安装与启动
3. 第 3 章 快速开始
4. 第 4 章 定义层与编译层
5. 第 5 章 输入文件参考
6. 第 6 章 GUI 工作台
7. 第 7 章 Python API / Facade / Probe
8. 第 8 章 建模对象说明
9. 第 9 章 Procedures 层
10. 第 10 章 Kernel 层
11. 第 11 章 Solver 层
12. 第 12 章 结果层
13. 第 13 章 作业、快照与派生算例
14. 第 14 章 插件与扩展说明
15. 第 15 章 常见错误与排查
16. 第 16 章 开发与维护说明
17. 第 17 章 术语表

第 1 章 软件概览

本章是整套帮助文档的总入口。它首先回答的不是“某个对象有哪些字段”，而是“pyFEM 当前采用什么正式分层、每一层为什么存在、层与层之间怎么衔接”。

当前文档不再继续沿用“定义层 / 编译层 / 运行时层 / 结果层 / GUI 消费层”这一过于压缩的五层简写。原因很简单：源码中的 kernel、procedures、solver 已经具有独立职责，如果仍然把它们合并成“运行时层”大桶，就会同时看不清对象边界、执行边界和产品壳层边界。

1. 功能概述

当前版本能够由源码直接确认的正式主线如下：

1. 通过 INP、GUI 或 Python API 形成定义层对象。
2. 通过 Compiler 将定义层编译为 CompiledModel。
3. 在 CompiledModel 中装配 kernel runtime 与 ProcedureRuntime。
4. 由 procedures 层驱动分析步执行，并通过 solver 层完成离散系统求解。
5. 将结果写入正式结果对象层级，再由 facade、probe、VTK 或 GUI 消费。

这条主线里的关键变化是：kernel、procedures、solver 从本章开始被视为三个不同的正式层，而不是同一个“运行时层”的内部子项。

2. 适用范围

当前版本已经确认的正式支持范围如下。

当前版本不应写成正式支持的内容包括：

• 显式动力学、热分析、屈曲分析、接触分析。
• 壳单元、高阶单元、三角形或四面体单元。
• follower_pressure、traction、nlgeom=True 下的 distributed load 主线。
• 完整接触/耦合/tie 工作流、网格生成、优化流程、截图导出、正式 Python 控制台接入。

3. 正式分层

3.1 为什么需要新的分层口径

新的分层口径不是为了增加术语，而是为了稳定回答以下问题：

1. “定义对象”与“运行时对象”到底在哪里切开。
2. CompiledModel 到底是编译产物，还是求解器对象。
3. kernel 为什么不等于 procedures。
4. solver 为什么不应再被 API、GUI、job 壳层直接叙述。

下表先给出当前帮助文档采用的正式层次地图。

需要特别记住两点：

1. CompiledModel 归属于编译层，它持有运行时对象图，但本身不是 kernel、procedures 或 solver 的具体实现类。
2. ResultsFacade 归属于结果消费侧，它是结果浏览入口，不是结果数据库本体。

3.2 最容易混淆的边界

下表用于澄清最容易被混写的对象或层边界。

4. 全局主线

4.1 从定义到结果的正式主线

当前版本应按下面的顺序理解正式主线，而不是跳过 kernel 或 solver：

INP / GUI / Python API
    -> ModelDB
    -> CompilationScope / Compiler / DofManager
    -> CompiledModel
    -> kernel runtimes
    -> ProcedureRuntime
    -> Assembler / DiscreteProblem / RuntimeState
    -> ResultsWriter / ResultsDatabase
    -> ResultsFacade / Query / Probe / VTK / GUI

这条链路分别回答的是：

1. 模型如何被定义。
2. 定义对象如何被解析为 canonical scope 与编译结果。
3. 编译后保存了哪些正式运行时对象。
4. 局部材料、截面、单元、约束由谁表示。
5. 分析步由谁组织和推进。
6. 全局离散系统由谁形成和求解。
7. 结果由谁保存、由谁消费。

4.2 一条最小对象链

如果只沿对象主线看一次最小流程，可以压缩为：

SectionDef / BoundaryDef / StepDef
    -> Compiler.compile(ModelDB)
    -> CompiledModel
    -> ProcedureRuntime.run(...)
    -> ResultsDatabase
    -> ResultsFacade

这条对象链的重点不是“每一步有哪些字段”，而是明确：定义对象、编译对象、runtime 对象、solver 对象、结果对象和消费对象处在不同层。

5. 使用方式

当前最主要的三种使用方式如下。

6. 结果与输出

当前版本的正式结果主文件通常是 .results.json。其中会保存：

• ResultsSession 级元数据。
• ResultStep 级步骤信息。
• ResultFrame 与 ResultField。
• ResultHistorySeries。
• ResultSummary。

如果启用 VTK 导出，还会得到 .vtk 文件，适合做几何和结果场可视化。

7. 限制与注意事项

1. 当前代码中产品命名尚未完全统一，文档统一使用“pyFEM”作总称。
2. pyproject.toml 未完整声明核心运行依赖，不能把“读到的依赖文件”直接等同于“官方安装说明”。
3. 当前没有统一的单位制约定，文档不能擅自固定为 SI 或 N-mm-MPa。
4. GUI 中有大量可见但未完成的预留入口，不能把这些入口写成已经形成正式工作流的功能。
5. 多步结果结构已经存在，但标准一键作业入口一次主要执行一个解析步骤；两者不能混为一谈。

8. 常见错误与排查

9. 本章主线图

定义层
    -> 编译层
    -> kernel 层
    -> procedures 层
    -> solver 层
    -> 结果层
    -> 产品壳层 / 消费层

10. 相关主题

• 第 2 章 安装与启动
• 第 3 章 快速开始
• 第 4 章 定义层与编译层
• 第 12 章 结果层

第 2 章 安装与启动

本章位于“概览之后、正式求解之前”的位置，用于说明当前版本需要什么运行环境、有哪些入口、怎样完成最小启动验证。

1. 功能概述

本章只回答三个实际问题：

1. 运行 pyFEM 需要准备什么环境。
2. 当前有哪些正式入口可以启动。
3. 如何在不依赖正文后续章节的情况下先验证环境可用。

2. 适用范围

本章当前只覆盖“源码目录直接运行”的启动方式。

不在本章正式范围内的内容包括：

• 未确认的 pip install 发布流程。
• 未确认的二进制安装包或独立桌面发行方式。
• 未确认的平台支持矩阵。

3. 环境要求

3.1 Python 版本

当前 pyproject.toml 明确要求 Python >=3.11。

3.2 代码中可确认的运行依赖

说明：

• 当前 pyproject.toml 只明确列出了 GUI 可选依赖。
• 由于求解主线代码直接导入 numpy 与 scipy，实际运行前应确认这两个数值库已经存在。

4. 启动入口

4.1 GUI 启动

当前项目中可以确认两种 GUI 入口形式，但对“源码目录直接运行”来说，应优先使用 run_gui.py：

python run_gui.py

pyfem-gui 也已经在 pyproject.toml 中声明为脚本入口，但它是否可以在当前环境中直接调用，取决于实际安装方式是否已完成。因此，本章不把它当作默认必然可用的启动命令。

4.2 INP 求解脚本启动

最直接的脚本入口是：

python run_case.py

run_case.py 支持通过环境变量覆盖输入、结果与导出路径，不必修改脚本主体。

4.3 Python API 启动

如果采用 Python API，可直接使用 PyFEMSession：

from pyfem.api import PyFEMSession

session = PyFEMSession()
report = session.run_input_file("beam.inp")
results = session.open_results(report.results_path)
print(report.step_name)
print(results.list_steps())

说明：

• 这条路径适合脚本集成或二次开发。
• 如果不是从项目源码根目录运行，需要先保证 pyfem 包可被 Python 正常导入。

5. run_case.py 的常用环境变量

6. 使用方法

6.1 源码目录直接运行

当前版本最稳妥的做法是从项目根目录直接运行脚本入口。run_gui.py 与 run_case.py 都会在启动时把 src 目录加入导入路径，因此源码目录直接运行是当前最明确的一条主线。

如果只需要验证 GUI 是否能启动，可先执行：

python run_gui.py

如果只需要验证求解主线是否可运行，可先准备一个 .inp 文件，再执行：

python run_case.py

6.2 默认输出路径

脚本和 GUI 都沿用同一套默认命名思路：

• 输入文件 beam.inp 的默认结果路径是 beam.results.json。
• 如果启用 VTK 导出，默认导出路径是 beam.vtk。
• GUI 运行当前模型时，会先写出一个运行快照，再对该快照执行正式求解。

7. 输入示例或代码示例

下面是一个仅用环境变量覆盖路径的最小脚本启动示例：

$env:PYFEM_INP_PATH = "D:\work\beam.inp"
$env:PYFEM_RESULTS_PATH = "D:\work\beam.results.json"
$env:PYFEM_VTK_PATH = "D:\work\beam.vtk"
$env:PYFEM_WRITE_VTK = "1"
python run_case.py

8. 输出或结果说明

run_case.py 运行成功后，终端至少会输出以下信息中的主要项：

• model = ...
• step = ...
• results = ...
• frame_count = ...
• history_count = ...
• vtk = ...（仅在启用导出时）
• report = ...（仅在设置 PYFEM_REPORT_PATH 时）

9. 限制与注意事项

1. 当前不能把“源码可运行”直接等同于“已经形成正式安装包流程”。
2. 如果直接调用 Python API，而运行环境又不在项目根目录，需要先解决导入路径问题。
3. GUI 3D 预览依赖 PySide6 + pyvista + pyvistaqt 的实际可用性；缺失时可能退回 placeholder。
4. 多步骤模型在脚本或 API 中可能需要显式给出 step_name。

10. 常见错误与排查

11. 相关主题

• 第 1 章 软件概览
• 第 3 章 快速开始
• 后续章节中的“作业、快照与派生算例”
• 后续章节中的“Python API / Facade / Probe”

第 3 章 快速开始

本章位于“环境已经可启动、需要第一次跑通”的位置。目标不是穷举功能，而是用一个最小算例把“输入文件 -> 求解 -> 结果文件 -> 结果查看”这条链路走通。

1. 本教程目标

完成以下最小闭环：

1. 准备一个两节点梁单元静力算例。
2. 通过 run_case.py 运行该算例。
3. 得到 .results.json 与 .vtk 文件。
4. 确认结果文件已生成，并知道下一步可以去哪里查看结果。

2. 前置条件

开始前应满足以下条件：

1. 已准备 Python >=3.11 环境。
2. 已确认数值依赖可用。
3. 已位于 pyFEM 项目源码根目录，或至少可以正常运行 run_case.py。

3. 本例模型或任务说明

本例采用当前代码包中的验证性 B21 梁单元静力样例。模型含义如下：

• 一根长度为 2.0 的二维梁单元。
• 根部全约束。
• 梁端在 UY 方向施加向下集中力。
• 步骤类型为静力线性。

这个样例的意义在于：

• 输入短。
• 支持路径稳定。
• 能同时产出位移、反力、应力相关结果与全局历史量。

4. 详细步骤

4.1 准备输入文件

新建 beam.inp，写入以下内容：

*Heading
Task 08 run_case script example
*Node
1, 0.0, 0.0
2, 2.0, 0.0
*Element, type=B21, elset=BEAM_SET
1, 1, 2
*Nset, nset=ROOT
1
*Nset, nset=TIP
2
*Material, name=STEEL
*Elastic
1000000.0, 0.3
*Density
4.0
*Beam Section, elset=BEAM_SET, material=STEEL
0.03, 0.0002
*Step, name=LOAD_STEP
*Static
*Boundary
ROOT, 1, 2, 0.0
ROOT, 6, 6, 0.0
*Cload
TIP, 2, -12.0
*End Step

说明：

• 该示例没有显式写 *Output。
• 当前 importer 在这种情况下会按步骤类型自动补上默认输出请求。
• 对于静力步骤，默认输出中包含节点位移/反力、单元中心结果、积分点结果、恢复结果、平均结果和时间历史。

4.2 运行脚本

推荐通过环境变量覆盖路径，不直接修改 run_case.py 顶部常量。

$env:PYFEM_INP_PATH = "D:\work\beam.inp"
$env:PYFEM_RESULTS_PATH = "D:\work\beam.results.json"
$env:PYFEM_VTK_PATH = "D:\work\beam.vtk"
$env:PYFEM_WRITE_VTK = "1"
python run_case.py

如果只想使用默认命名，也可以把输入文件命名为 Job-1.inp 并放在项目根目录，然后直接执行：

python run_case.py

4.3 检查终端输出

运行成功后，应能在终端看到与下面同类的信息：

model = ...
step = LOAD_STEP
results = ...beam.results.json
frame_count = 1
history_count = ...
vtk = ...beam.vtk

4.4 检查结果文件

确认以下文件已经生成：

1. beam.results.json
2. beam.vtk
3. 可选的运行报告 JSON（仅在设置 PYFEM_REPORT_PATH 时生成）

4.5 可选：打开结果

如果 GUI 环境可用，可以启动 GUI 后打开结果文件，继续查看步骤、帧、字段、历史量和 probe。

5. 每一步的预期结果

参考说明：

• 该验证样例在代码测试中对应的梁端 UY 位移参考值约为 -0.16。
• 这条数值可作为当前版本快速自检时的参考，不应替代更完整的工程验证流程。

6. 常见出错点

1. 输入文件路径写对了，但运行目录不对，导致脚本实际没有读到目标文件。
2. 模型中如果自行改成多个步骤，却没有显式指定 step_name，会触发步骤解析错误。
3. 将 GUI 中可见的预留按钮误当作本教程必需步骤。当前快速开始不依赖这些入口。
4. 误以为没有显式 *Output 就不会产生结果。当前 importer 会按步骤类型补默认输出请求。

7. 最终结果说明

完成本教程后，你已经走通了当前版本最稳定的一条正式主线：

beam.inp
    -> run_case.py
    -> beam.results.json
    -> beam.vtk

如果后续需要继续深入，可以沿两条方向扩展：

1. 保持 INP 主线，继续学习步骤、材料、输出请求和结果字段。
2. 进入 GUI 或 Python API 主线，学习模型浏览、作业提交和结果消费。

8. 本例涉及到的核心对象总结

9. 可继续尝试的扩展练习

1. 在保持单步模型的前提下，显式添加 *Output Request，观察结果字段是否变化。
2. 将同一条梁样例改为 modal 或 implicit_dynamic，对比输出变量集合。
3. 用 GUI 打开该模型，再通过 GUI 提交 job，观察快照与结果路径的生成方式。
4. 使用 PyFEMSession 运行同一个输入文件，再用 open_results() 读取结果。

10. 相关主题

• 第 1 章 软件概览
• 第 2 章 安装与启动
• 后续章节中的“输入文件参考”
• 后续章节中的“Procedures 层”
• 后续章节中的“结果层”

第 4 章 定义层与编译层

本章只回答两个问题：定义层为什么存在，编译层为什么存在。

它不再继续承担 kernel、procedures、solver 的统一说明职责。换句话说，本章从现在开始只负责“定义对象如何组织”和“定义对象如何被编译为 CompiledModel”，至于局部 runtime、过程推进和全局离散求解，将在后续章节分别展开。

1. 这一层为什么存在

1.1 定义层为什么存在

定义层解决的是“要算什么”。它保存模型、网格、材料、截面、边界条件、载荷、输出请求、步骤和作业顺序等正式定义对象。

定义层的特点是：

1. 对象可被 INP 导入器、GUI 编辑器和 Python API 直接创建或修改。
2. 对象之间主要通过名称引用关联，而不是通过求解阶段的运行时句柄关联。
3. 定义层对象本身不直接承担求解执行职责。

1.2 编译层为什么存在

编译层解决的是“如何把定义翻译为可执行对象图”。在 pyFEM 当前主线里，这一层至少承担以下职责：

1. 建立 canonical CompilationScope。
2. 把部件、本地集合、实例 alias、刚体变换放进统一解析边界。
3. 为节点和其他自由度拥有者建立全局 DOF 编号。
4. 根据定义对象的类型键选择 provider，并生成正式 runtime 或 placeholder runtime。
5. 产出 CompiledModel，作为后续 procedures 层与 solver 层消费的编译结果。

这里要特别说明一点：DofManager 的源码物理位置位于 pyfem.kernel.dof_manager，但在本帮助文档的结构口径中，它承担的是编译桥接职责，因此归入编译层说明。

2. 定义对象家族

下表先给出本章涉及的定义对象家族地图。它只回答“有哪些对象家族以及各自承担什么职责”，不展开字段级细节。

2.1 定义对象结构表

下表只回答“这个家族里有哪些核心对象，以及各自承担什么职责”。字段级表格将在第 8 章继续展开。

2.2 ModelDB 顶层结构

ModelDB 是当前定义层的唯一正式入口。源码可直接确认的顶层字段如下。

需要额外记住两点：

1. ModelDB.constraints 只是 boundaries 的兼容属性，不是独立存储。
2. ModelDB.procedures 只是 steps 的兼容属性，不是独立存储。

3. 作用域与名称引用

3.1 为什么需要 CompilationScope

定义层的大多数对象通过名称关联，而名称只有在明确作用域后才有确定含义。CompilationScope 的存在，就是为了把“部件本地名”“实例名”“装配 alias”“几何变换后节点记录”组织到统一边界内。

源码可直接确认以下规则：

1. 有装配且存在实例时，一个实例形成一个 canonical scope，scope_name = instance.name。
2. 没有装配时，一个部件形成一个 canonical scope，scope_name = part.name。
3. 节点几何记录通过 CompilationScope.get_node_geometry_record() 在作用域内施加刚体变换。
4. 节点集、单元集和表面会优先命中实例级 alias，未命中时再回退到部件本地对象。

3.2 名称引用表

下表专门说明定义层里最关键的名称引用关系。

3.3 当前需要保守处理的边界

1. SectionDef.region_name 当前正式主线按部件本地 element_sets 解析，不应扩大写成任意装配级区域名。
2. ElementRecord.region_name 字段存在，但主编译路径并不直接依赖它完成正式截面绑定，因此本章不把它写成稳定绑定主线。
3. BoundaryDef.constraint_type 是对 boundary_type 的兼容属性；文档说明应优先使用定义层口径 boundary_type，但在编译层需要知道编译器会通过兼容属性查找 constraint provider。

4. 编译桥接对象家族

4.1 这一家族解决什么问题

编译桥接对象家族负责把定义对象翻译成后续层可消费的对象图。它不直接执行分析步骤，也不直接保存结果数据库，但它决定了：

1. 哪些 canonical scope 会被创建。
2. 哪些节点与自由度会获得全局编号。
3. 哪个定义对象命中哪个 provider。
4. 未命中 provider 时是否生成 placeholder runtime。
5. CompiledModel 中最终持有哪些 runtime 字典。

4.2 编译桥接对象结构表

4.3 编译映射表

下表只说明“对象如何从定义进入编译产物”，不展开 runtime 家族的具体接口。

5. 核心类说明

5.1 ModelDB

• 所属层：定义层
• 家族：定义对象家族
• 职责：作为问题定义唯一来源，统一持有部件、工况、步骤与作业定义，并在编译前执行一致性校验。
• 核心字段：parts、assembly、materials、sections、boundaries、nodal_loads、distributed_loads、interactions、output_requests、steps、job
• 上下游关系：上游为 INP 导入器、GUI 与 API；下游为 Compiler.compile()。
• 典型误解：它不是“已经可运行的模型”，必须先经过编译。

下表只列当前建议作为正式公开边界理解的方法。

5.2 CompilationScope

• 所属层：编译层
• 家族：编译桥接对象家族
• 职责：描述一个 canonical scope，并在该作用域下解析节点、单元、集合、表面、方向和几何变换结果。
• 核心字段：scope_name、part_name、part、transform、instance_name、node_sets、element_sets、surfaces
• 主要边界：它是桥接对象，不是结果对象，也不是 kernel runtime。
• 典型误解：它不等于 PartInstance，而是由部件和实例信息推导出的编译期作用域对象。

5.3 Compiler

• 所属层：编译层
• 家族：编译桥接对象家族
• 职责：总控编译流程，依次构建材料、截面、单元、约束、相互作用和步骤运行时，并在完成后冻结 DofManager。
• 核心字段：_registry
• 主要方法：当前正式公开方法很少，主入口是 compile()；其余 _build_*、_resolve_* 为内部编译流程。
• 典型误解：它不执行分析步骤，只负责生成 CompiledModel。

5.4 DofManager

• 所属层：文档口径归入编译层
• 家族：编译桥接对象家族
• 职责：为节点和其他自由度拥有者分配全局编号，并提供后续查询接口。
• 核心状态：_index_by_location、_locations_by_index、_dof_names_by_owner、_is_finalized
• 主要方法：当前以注册、查询、冻结为主。
• 典型误解：它不是 solver 的求解器对象，也不是结果对象。

5.5 CompiledModel

• 所属层：编译层
• 家族：编译桥接对象家族
• 职责：持有 ModelDB、DofManager、各类 runtime 字典，以及跨步骤继承所需的 step_state_snapshots。
• 核心字段：model、dof_manager、element_runtimes、material_runtimes、section_runtimes、constraint_runtimes、interaction_runtimes、step_runtimes、step_state_snapshots
• 上下游关系：上游为 Compiler；下游主要由 procedures 层消费。
• 典型误解：它不是 solver 的 DiscreteProblem，也不是结果数据库。

6. provider 与 placeholder runtime

这部分只解释编译层如何处理 provider 绑定，不代替后续的 runtime 家族章节。

6.1 provider 在编译层中的含义

在当前源码主线中，Compiler 会通过 RuntimeRegistry 查找以下 provider：

• material provider：按 MaterialDef.material_type
• section provider：按 SectionDef.section_type
• element provider：按 ElementRecord.type_key
• constraint provider：按 BoundaryDef.constraint_type，其值来自 boundary_type 的兼容属性
• interaction provider：按 InteractionDef.interaction_type
• procedure provider：按 StepDef.procedure_type

这里的 provider 绑定，回答的是“当前定义对象应该被编译成哪一种正式 runtime 实现”。

6.2 placeholder runtime 在编译层中的含义

如果某个类型键没有命中 provider，当前编译主线不会凭空虚构正式实现，而是生成对应的 placeholder runtime，例如：

• MaterialRuntimePlaceholder
• SectionRuntimePlaceholder
• ElementRuntimePlaceholder
• ConstraintRuntimePlaceholder
• InteractionRuntimePlaceholder
• StepRuntimePlaceholder

本帮助文档对 placeholder runtime 的口径保持保守：

1. 它们表示“编译结构上保留了该对象的位置”。
2. 它们不应被写成稳定、可推荐依赖的正式用户接口。
3. 只要源码和主线文档没有明确说明某类 placeholder 已形成完整能力，就必须把相关能力视为待确认或未纳入正式支持边界。

7. 对象创建、引用与消费示例

7.1 构造示例

下面的例子只演示定义对象如何进入 ModelDB，不展开求解。

mesh = Mesh()
mesh.add_node(NodeRecord(name="N1", coordinates=(0.0, 0.0)))
mesh.add_node(NodeRecord(name="N2", coordinates=(1.0, 0.0)))
mesh.add_element(
    ElementRecord(
        name="E1",
        type_key="B21",
        node_names=("N1", "N2"),
        section_name="BEAM_SEC",
    )
)
mesh.add_element_set("ALL", ("E1",))
mesh.add_node_set("FIXED", ("N1",))

part = Part(name="BeamPart", mesh=mesh)

model = ModelDB(name="beam-demo")
model.add_part(part)
model.add_material(
    MaterialDef(
        name="Steel",
        material_type="linear_elastic",
        parameters={"E": 210000.0, "nu": 0.3},
    )
)
model.add_section(
    SectionDef(
        name="BEAM_SEC",
        section_type="beam",
        material_name="Steel",
        region_name="ALL",
        scope_name="BeamPart",
    )
)

这个例子里，NodeRecord 先进入 Mesh，Mesh 再进入 Part，Part 再进入 ModelDB.parts；SectionDef 则通过 ModelDB.add_section() 进入定义层顶层字典。

7.2 引用示例

下面的例子只演示“名字如何命中对象”。

boundary = BoundaryDef(
    name="BC-FIX",
    target_name="FIXED",
    target_type="node_set",
    scope_name="BeamPart",
    dof_values={"UX": 0.0, "UY": 0.0, "RZ": 0.0},
)

step = StepDef(
    name="Step-1",
    procedure_type="static",
    boundary_names=("BC-FIX",),
)

这里有两条连续引用链：

1. ElementRecord.section_name = "BEAM_SEC" 会命中 ModelDB.sections["BEAM_SEC"]。
2. BoundaryDef.target_name = "FIXED" 需要与 target_type = "node_set" 和 scope_name = "BeamPart" 一起解释，最终在 CompilationScope.resolve_node_names() 中命中当前作用域下的节点集。

7.3 消费示例

下面的例子演示编译之后对象如何进入 CompiledModel。

compiled = Compiler().compile(model)

beam_section = compiled.section_runtimes["BEAM_SEC"]
step_runtime = compiled.get_step_runtime("Step-1")
dof_total = compiled.dof_manager.num_dofs()

这说明：

1. Compiler.compile() 的直接产物是 CompiledModel。
2. 定义层对象不会原样“执行”，而是先被编译为 runtime 字典。
3. procedures 层后续消费的入口不是 StepDef，而是 CompiledModel.step_runtimes 中的 ProcedureRuntime。

8. 本章边界对照

下表用于澄清本章最容易被混写的相邻对象。

9. 本章主线图

定义对象家族
    -> 名称引用与 canonical scope
    -> Compiler / DofManager
    -> CompiledModel
    -> kernel / procedures / solver 后续章节

第 5 章 输入文件参考

本章位于“已经理解对象关系、开始正式写输入文件”的位置，用于说明当前 importer/exporter 真正支持的 INP 子集。

1. 功能

当前 INP 主线负责两件事：

1. 把 INP 文本翻译为 ModelDB
2. 把正式支持子集的 ModelDB 导出为 INP

本章只描述当前 importer/exporter 能稳定识别和回写的关键字子集。

2. 所属类别

本章属于“输入格式参考页”，关注的是关键字、选项、数据行和默认行为，而不是数值理论本身。

3. 基本解析规则

当前解析器使用以下基本规则：

1. 以 * 开头的行为关键字行。
2. 空行与 ** 注释行会被忽略。
3. 关键字名称会在解析时转为大写。
4. 关键字选项按逗号分隔；带 = 的项会被解析为选项字典。

4. 当前支持的顶层关键字

除上述关键字外，当前顶层出现其他关键字时，导入器会按不支持处理。

5. PART 与 ASSEMBLY 子集

5.1 PART 块当前支持的内容

当前 PART 块内支持：

• *Node
• *System（仅空控制块）
• *Element
• *Nset
• *Elset
• *Surface
• *Orientation
• *Solid Section
• *Beam Section

当前 PART 块内不应写成正式支持的内容包括未在导入器中显式处理的其他 Abaqus 关键字。

5.2 ASSEMBLY 块当前支持的内容

当前 ASSEMBLY 块只支持：

• *Instance
• *Nset
• *Elset
• *Surface

其中：

• *Instance 当前表示部件实例与实例刚体变换。
• 装配级 NSET/ELSET/SURFACE 当前必须显式给出 instance=，用于建立实例级别名。

5.3 实例作用域规则

在有装配实例的模型里，目标对象不能再模糊地依赖部件名。

当前推荐写法是：

*Boundary
left.ROOT, 1, 2, 0.0

如果使用装配别名，也必须保证该别名在当前装配中只唯一对应一个实例；否则导入器无法安全推断作用域。

6. 截面、表面与方向关键字

6.1 *Solid Section

当前 *Solid Section 支持两种模式：

1. 显式通过 formulation 或 section_type 指定 solid、plane_stress 或 plane_strain
2. 在未显式指定时按区域内首个单元类型推断

当前默认推断规则为：

• C3D8 -> solid
• CPS4 -> plane_stress

如果是平面截面，当前会记录 thickness；未提供时默认按 1.0 处理。

6.2 *Beam Section

当前 *Beam Section 会读取：

• area
• moment_inertia_z
• 可选 shear_factor

6.3 *Surface

当前 *Surface 只支持 type=ELEMENT。表面数据行需要至少给出：

1. 区域名或单元名
2. 局部面标签

6.4 *Orientation

当前 *Orientation 只支持 rectangular 方向定义，且必须给出 axis_1 与 axis_2。

7. STEP 块当前支持的关键字

7.1 过程关键字

当前 STEP 块内正式支持以下过程关键字：

7.2 STEP 内对象关键字

当前 STEP 块内支持：

• *Boundary
• *Cload
• *Dsload
• *Boundary Ref
• *Cload Ref
• *Dsload Ref
• *Output Request
• *Output Request Ref
• *Restart
• *Output
• *Step Parameter
• *Raw Keyword

其中有三个特别重要的边界：

1. *Restart 当前只接受不带数据行的控制形式。
2. *Output 当前只接受 variable=PRESELECT 且不带数据行的控制形式。
3. 任何不在上表中的 STEP 子关键字，当前都不应写成正式支持。

7.3 STEP 内边界与载荷的两种写法

*Boundary、*Cload、*Dsload 当前都支持“定义对象”和“直接数据行”两种用法，但边界不同：

7.4 顶层定义与步骤引用的关系

当前导入规则里需要区分“定义对象”和“让步骤使用对象”：

• 顶层结构化 *Boundary / *Cload / *Dsload 主要用于定义可复用对象。
• STEP 中通过 *Boundary Ref / *Cload Ref / *Dsload Ref 才表示当前步骤要使用这些命名对象。
• 顶层传统写法生成的全局边界和全局节点载荷，会被作为继承对象带入后续步骤。

因此，不能把“对象已经在顶层定义”直接理解为“当前步骤一定会执行它”。

8. 输出请求与默认行为

8.1 *Output Request

当前正式输出请求关键字为：

*Output Request, name=..., request_mode=..., target_type=..., position=..., frequency=...

数据行写变量名列表，例如：

U, RF, U_MAG

可选项当前包括：

• name
• request_mode
• target_type
• target
• scope
• position
• frequency

8.2 *Output Request Ref

如果输出请求已经在顶层定义，当前可以在步骤中使用 *Output Request Ref 引用名称。

8.3 默认输出请求

如果某个步骤没有显式输出请求，当前 importer 会按步骤类型自动补默认输出请求。

默认规则如下：

• modal：默认补 MODE_SHAPE 与 FREQUENCY
• implicit_dynamic：默认补节点位移 U 与时间历史 TIME
• 其他当前正式过程：默认补节点位移/反力/位移模、单元中心、积分点、恢复、平均和时间历史

这也是为什么很多最小 INP 示例即使没有显式写 *Output 或 *Output Request，仍然会得到结果字段。

9. RAW KEYWORD 与 STEP PARAMETER

9.1 *Raw Keyword

当前 *Raw Keyword 会被翻译为受控的 RawKeywordBlockDef，而不是直接无约束地拼接任意原始文本。

其当前关键信息包括：

• name
• keyword
• placement
• step
• order
• description
• 以 raw_ 前缀给出的原始选项

9.2 *Step Parameter

*Step Parameter 用于保存未被过程关键字专门消费的步骤参数。当前支持：

• 文本
• JSON
• 数值
• 整数
• 布尔值

这类参数会进入 StepDef.parameters。

10. 正确示例

10.1 最小 legacy 示例

*Heading
beam example
*Node
1, 0.0, 0.0
2, 2.0, 0.0
*Element, type=B21, elset=BEAM_SET
1, 1, 2
*Nset, nset=ROOT
1
*Nset, nset=TIP
2
*Material, name=STEEL
*Elastic
1000000.0, 0.3
*Beam Section, elset=BEAM_SET, material=STEEL
0.03, 0.0002
*Step, name=LOAD_STEP
*Static
*Boundary
ROOT, 1, 2, 0.0
ROOT, 6, 6, 0.0
*Cload
TIP, 2, -12.0
*End Step

10.2 装配作用域示例

*Assembly, name=ASM
*Instance, name=left, part=BEAM
*End Instance
*Instance, name=right, part=BEAM
5.0, 0.0
*End Instance
*End Assembly
*Step, name=LOAD_STEP
*Static
*Boundary
left.ROOT, 1, 2, 0.0
*Cload
right.TIP, 2, -12.0
*End Step

11. 错误示例

11.1 在装配模型里把部件名当成实例名

*Boundary
BEAM.ROOT, 1, 2, 0.0

在有装配实例的模型中，这种写法当前不应视为正式支持。目标应优先写成实例作用域。

11.2 使用当前未纳入正式主线的 SYSTEM 坐标定义

*System
0.0, 0.0, 0.0, 1.0, 0.0, 0.0

当前 SYSTEM 仅允许空控制块。

11.3 在传统 *Dsload 中使用非压力代码

*Dsload
PRESSURE_FACE, TRVEC, -2.0

当前传统 *Dsload 短写只支持 P 压力代码。

12. 当前限制

1. 顶层未列入翻译器分支的关键字，当前都不应写成正式支持。
2. ASSEMBLY 块当前只支持 INSTANCE/NSET/ELSET/SURFACE。
3. SYSTEM 仅支持空控制关键字。
4. OUTPUT 当前仅支持 variable=PRESELECT 的控制形式。
5. DSLOAD 的传统短写格式只在 STEP 内支持，且仅支持压力代码 P。
6. SURFACE 当前仅支持 ELEMENT 类型。
7. ORIENTATION 当前仅支持一阶 rectangular 方向定义。

13. 相关主题

• 第 3 章 快速开始
• 第 4 章 定义层与编译层
• 第 6 章 GUI 工作台
• 后续章节中的“建模对象说明”
• 后续章节中的“Procedures 层”

第 6 章 GUI 工作台

本章位于“已经可以跑通输入文件，希望通过工作台组织建模与结果浏览”的位置，用于说明当前 GUI 骨架、正式主线和预留入口之间的边界。

1. 功能概述

当前 GUI 工作台负责把以下动作组织到统一窗口中：

1. 打开模型与查看模型摘要
2. 浏览材料、截面、载荷、边界、步骤和输出请求
3. 通过正式对话框编辑已纳入主线的对象
4. 通过快照主线提交 job
5. 打开结果、浏览步骤/帧/字段/历史/摘要
6. 进行 probe、设置图例、导出 VTK

2. 适用范围

本章只描述当前已经形成正式主线的 GUI 能力。

本章不把以下内容写成已完成工作流：

• 接触、约束、耦合、tie 创建
• 幅值管理
• 网格划分与生成
• 完整优化工作流
• 丰富结果字段选择器
• 截图或图形导出工作流
• 正式 Python 控制台集成

3. 工作台总体结构

当前主窗口由以下几块组成：

4. 模块分区

当前模块顺序固定为：

1. Part
2. Property
3. Assembly
4. Step
5. Interaction
6. Load
7. Mesh
8. Optimization
9. Job
10. Visualization

这十个模块并不表示每个模块都已形成同样完整的工作流。

当前应理解为：

• Property、Step、Load、Job、Visualization 是正式主线更清晰的区域。
• Interaction、Mesh、Optimization 中仍有较多预留入口。

5. 模型浏览主线

5.1 导航树

模型加载后，左侧导航树当前会按以下分类显示对象：

• Models
• Parts
• Materials
• Sections
• Assembly
• Steps
• Loads
• BCs
• Output Requests

这使得当前 GUI 的首要角色更接近“模型工作台 + 结果浏览器”，而不是完整的几何建模系统。

5.2 当前已纳入正式编辑主线的对象

GUI 当前明确纳入正式参数编辑主线的对象种类包括：

• material
• section
• boundary
• nodal_load
• distributed_load
• output_request
• step
• instance

对应的正式编辑对话框或管理器包括：

• MaterialEditDialog
• SectionEditDialog
• BoundaryEditDialog
• LoadEditDialog
• OutputRequestEditDialog
• StepEditDialog
• InstanceTransformDialog
• MaterialManagerDialog
• SectionManagerDialog
• LoadManagerDialog
• BoundaryManagerDialog
• StepManagerDialog

5.3 当前正式模型编辑主线

当前比较稳定的 GUI 建模路径是：

Open Model
    -> 检查导航树与模型摘要
    -> 编辑材料 / 截面 / 边界 / 载荷 / 步骤 / 输出请求
    -> 可选做实例变换与截面分配
    -> Write INP 或 Run Current Model

6. 作业与快照主线

6.1 当前运行方式

GUI 当前提交作业时，不是额外维护一条与脚本完全无关的私有求解通道，而是先写出正式 snapshot，再通过 snapshot 主线执行。

这条链路可以概括为：

当前活模型
    -> write snapshot
    -> run snapshot
    -> results.json / optional vtk
    -> ResultsFacade

6.2 Job 区当前主命令

当前 Job 模块中已形成主线的命令包括：

• Run Current Model
• Run Last Snapshot
• Open Snapshot Manifest
• Open Job Center
• Open Current Job Monitor
• Open Job Diagnostics
• Results / Output...

6.3 派生算例

Assembly / Optimization 区域当前还共享一条正式入口：

• Save As Derived Case

这条路径会把当前模型另存为新的来源文件，并切换 GUI 当前来源路径。

7. 结果主线

7.1 结果打开与结果树

当前 GUI 打开结果后，会基于 ResultsFacade 构建结果浏览上下文，并在导航树中组织：

• 步骤
• 帧
• 字段
• 历史
• 摘要

右侧 ResultsBrowser 会同步显示步骤、帧、字段、历史量和摘要，并提供详情区。

7.2 当前显示模式

当前工作台支持以下显示模式：

• Undeformed
• Deformed
• Contour on Deformed

如果当前已经选中结果字段，系统会优先将其作为等值图字段处理；否则视图区会保留网格或形状显示。

7.3 当前 probe 种类

当前 probe 对话框支持以下 probe 类型：

• Node
• Element
• Integration Point
• Averaged

probe 的可用字段不是任意组合，而是按当前字段族与结果位置做兼容性匹配。例如：

• 位移族主要对应节点 probe
• 应力族可对应单元、积分点或平均节点 probe
• 某些字段族在当前 probe 类型下不可用时，GUI 会按不兼容处理

7.4 当前结果导出

当前结果侧已形成正式主线的导出能力包括：

• Open Results
• Export VTK
• Probe
• Legend Settings
• 结果输出入口中的 report / manifest / results 路径浏览

8. 视图区与预览退化路径

8.1 正常情况

如果 PySide6、pyvista 与 pyvistaqt 都可用，且当前会话满足 3D 预览条件，视图区会创建 PyVista 预览控件，显示：

• 网格
• 变形形状
• 等值图
• 图例和颜色映射

8.2 退化情况

如果当前会话不满足预览条件，GUI 不会把这件事伪装成求解失败，而是保留 placeholder 模式。

当前可能进入 placeholder 的典型情况包括：

• PyVista / pyvistaqt 不可用
• Qt 绑定与 PySide6 不一致
• 当前运行环境属于 offscreen / minimal 等安全模式
• 本会话显式禁用 3D preview

因此，当前版本里“没有 3D 预览”并不等于“结果不可用”。结果树、结果浏览器、probe 和 VTK 导出仍然可能正常工作。

9. 当前限制与预留入口

9.1 明确仍为 placeholder 的入口

当前界面中可见但仍属于预留入口的典型功能包括：

• Create Contact
• Create Constraint
• Create Coupling
• Create Tie
• Amplitudes...
• Generate Mesh
• Parameter Variant
• Result Field Selector
• Screenshot/Export Figure

此外，Mesh、Optimization 等模块中的若干按钮当前也仍以 reserved entry 的形式存在。

9.2 GUI 显示层与正式结果字段的区别

GUI 结果显示层会把正式字段组织成“位移、应力、应变、等效应力、主应力”等族，并可能显示“常用”或变体别名。

但这不等于这些显示名都是正式结果字段名。

一个典型例子是：

• GUI 显示层包含 E_AVG 族别名
• 当前正式输出与后处理主线并未生成 E_AVG 作为正式字段

因此，编写用户帮助时必须区分：

1. GUI 展示层的显示标签
2. 结果系统真正存在的正式字段

10. 使用方法

下面给出当前 GUI 最小正式工作流：

1. 启动 run_gui.py
2. 打开模型文件
3. 在导航树确认材料、截面、边界、载荷、步骤和输出请求
4. 在正式编辑对话框中修改需要的对象
5. 通过 Run 或 Run Current Model 提交作业
6. 打开结果
7. 在 Visualization 中切换字段、显示模式和 probe
8. 如有需要，导出 VTK

11. 输入示例或操作示例

一个最小 GUI 操作顺序可以写成：

Open Model
    -> Property: Materials / Sections
    -> Load: Loads / Boundaries
    -> Step: Steps / Output Controls
    -> Job: Run
    -> Visualization: Open Results / Probe / Export VTK

12. 输出或结果说明

当前 GUI 成功运行后，常见可见结果包括：

• 模型摘要更新
• 最近一次 job 记录
• 快照 manifest
• .results.json 路径
• 可选 .vtk 路径
• 结果树中的步骤、帧、字段、历史和摘要

13. 限制与注意事项

1. 不能因为按钮可见，就默认该功能已经形成正式用户工作流。
2. Visualization 中显示的字段族标签，不应直接替代正式字段名。
3. 当前 GUI 运行主线依赖 snapshot；不要把它理解为完全脱离 INP / Results 主线的独立求解器。
4. 3D 预览可能退回 placeholder，但这不自动表示结果不可读。

14. 常见错误与排查

15. 相关主题

• 第 3 章 快速开始
• 第 4 章 定义层与编译层
• 第 5 章 输入文件参考
• 后续章节中的“结果层”
• 后续章节中的“作业、快照与派生算例”

第 7 章 Python API / Facade / Probe

本章只讲产品壳层与结果消费入口，不再代讲编译层、kernel、procedures 或 solver 内部对象。读者看完本章后，应能回答两个问题：普通脚本应该从哪里进入主线，结果浏览应停留在哪一层。

1. 这一章为什么存在

pyFEM 需要一层面向用户和脚本的稳定入口，用来屏蔽底层编译、过程执行和结果协议细节。这一层的正式职责是：

1. 把“读模、运行、打开结果、导出结果”收口为少量稳定 API。
2. 把 ResultsFacade / Query / Probe 收口为结果消费入口。
3. 让普通用户不必直接依赖 Compiler、ProcedureRuntime、Assembler 或 RuntimeState。

因此，本章属于产品壳层 / 消费层，不属于底层结构章。

2. 产品壳层对象家族地图

下表先给出本章涉及的对象家族地图。

这里要特别注意：JobManager 属于产品壳层，但它的统一执行流程放在第 13 章讲。本章只把它作为 PyFEMSession 背后的主线调度器提及，不重复展开。

3. PyFEMSession

• 所属层：产品壳层 / 消费层
• 家族：会话入口家族
• 职责：作为 Python API 的统一会话入口，收口读模、运行、打开结果和导出结果
• 核心字段：未显式传入依赖时，当前会准备 registry、plugin_discovery、job_manager
• 主要方法状态：属于典型服务类
• 上下游关系：上游面向用户脚本；下游调度 importer、JobManager、reader、exporter
• 典型误解：它不是 solver 对象，也不是 ResultsDatabase

下表只列当前建议写成正式公开边界的方法。

对普通脚本，最稳妥的推荐路径仍然是：

PyFEMSession
    -> run_input_file() / run_model()
    -> JobExecutionReport
    -> open_results()
    -> ResultsFacade

4. ResultsFacade

• 所属层：结果层消费侧
• 家族：结果门面家族
• 职责：把 reader-only 结果浏览收口成统一入口
• 核心字段：当前以 reader 引用和能力边界为主
• 主要方法状态：属于门面类
• 上下游关系：上游来自 open_results()；下游派生 query / probe
• 典型误解：它不是结果数据库对象

下表只列最常用的正式入口。

5. ResultsQueryService

• 所属层：结果层消费侧
• 家族：结果查询家族
• 职责：按步骤、帧、字段、历史量和摘要做筛选与概览
• 核心字段：当前以服务边界为主
• 主要方法状态：属于服务类
• 上下游关系：由 ResultsFacade.query() 创建
• 典型误解：它返回的是结果对象或概览，不是 probe 序列

当前公开方法至少包括：

• steps()、step()
• frames(...)
• field()、field_overview()、field_overviews()
• history()、histories(...)
• summary()、summaries(...)

如果用户要回答“有哪些步骤、有哪些帧、哪些字段满足条件”，应优先用 query，而不是直接手动遍历 ResultsDatabase。

6. ResultsProbeService

• 所属层：结果层消费侧
• 家族：结果探针家族
• 职责：把结果对象转成可直接消费的探针序列，并支持 CSV 导出
• 核心字段：当前以服务边界为主
• 主要方法状态：属于服务类
• 上下游关系：由 ResultsFacade.probe() 创建
• 典型误解：probe 不是 ResultField 的同义词

当前公开方法至少包括：

• history()、paired_history()
• field_component()
• node_component()
• element_component()
• integration_point_component()
• averaged_node_component()
• export_csv()

这里最重要的使用分工是：

• ResultsFacade.field() 读取字段对象本体。
• ResultsQueryService.field_overviews() 读取字段概览。
• ResultsProbeService.node_component() / field_component() 把字段投影成一条序列。

7. 对象创建、引用与消费短例

7.1 从输入文件直接运行

from pyfem import PyFEMSession

session = PyFEMSession()
report = session.run_input_file(
    "tests/data/beam/b21_cantilever.inp",
    step_name="step-1",
    results_backend="json",
)

这条链路说明：

1. 普通用户入口应优先停在 PyFEMSession。
2. run_input_file() 内部会继续调度 job、编译、过程执行和结果写出。
3. 返回值是 JobExecutionReport，不是 CompiledModel。

7.2 打开结果并读取字段

results = session.open_results(report.results_path)
u = results.field("step-1", 0, "U")

这条链路说明：

1. open_results() 打开的入口是 ResultsFacade。
2. field() 返回的是正式 ResultField。
3. 结果消费不需要直接接触 solver 内部状态。

7.3 下钻 probe 并导出 CSV

probe = results.probe()
series = probe.node_component("step-1", "part-1.n2", "UY")
probe.export_csv(series, "outputs/uy_probe.csv")

这条链路说明：

1. probe 服务消费的是结果对象，不是 RuntimeState。
2. node_component() 适合取节点量分量序列。
3. CSV 导出属于结果消费动作，不属于结果层本体定义。

8. 边界对照表

下表用于澄清本章最容易混淆的相邻对象。

9. 本章主线图

PyFEMSession
    -> run_input_file() / run_model()
    -> JobExecutionReport
    -> open_results()
    -> ResultsFacade
    -> ResultsQueryService / ResultsProbeService

第 8 章 建模对象说明

本章说明 pyFEM 当前定义层对象的职责、关键字段、引用关系与校验规则。这里讲的是“模型怎样被描述”，不是“求解器怎样实现”。

1. 功能概述

pyFEM 当前采用以 ModelDB 为中心的定义层模型。部件、装配、材料、截面、边界条件、载荷、输出请求、步骤和作业都在这一层组织。

编译之前，用户看到的是一组“定义对象”。 编译之后，求解器使用的是“运行时对象”。 本章只关注前者。

2. 顶层对象 ModelDB

2.1 对象职责

ModelDB 是问题定义的唯一汇总容器。当前可确认的主要字段包括：

• parts
• assembly
• materials
• sections
• boundaries
• nodal_loads
• distributed_loads
• interactions
• output_requests
• steps
• raw_keyword_blocks
• job

这意味着：

• 网格和几何组织在 parts 与 assembly
• 物理属性组织在 materials 与 sections
• 工况组织在 boundaries、nodal_loads、distributed_loads、output_requests
• 求解流程组织在 steps 与 job

2.2 编译作用域

ModelDB.iter_compilation_scopes() 会决定编译时实际遍历的作用域：

• 如果没有装配实例，作用域通常就是各个 Part
• 如果存在 Assembly 和 PartInstance，作用域就切换为各个实例

这条规则非常重要，因为后续很多名称解析、结果命名和目标查找都依赖“作用域”而不是只依赖“部件”。

2.3 ModelDB 的公开方法与调用时机

ModelDB 不是一个“把对象全塞进去的大字典”。它已经有明确的容器方法和校验入口。读者真正需要掌握的是：对象应通过哪些入口进入模型，以及这些入口何时会参与后续编译主线。

很多初学者会直接手改 model.parts[...] 或 model.steps[...]。源码虽然允许读这些字段，但帮助文档更推荐走 add_* / set_* 方法，因为这样更符合正式主线，也更容易和后续校验逻辑对齐。

2.4 最小构造示例：把定义对象装入 ModelDB

下面的例子只做一件事：让读者看到 ModelDB 里的对象不是平铺词条，而是一条连续定义链。

mesh = Mesh()
mesh.add_node(NodeRecord(name="n1", coordinates=(0.0, 0.0)))
mesh.add_node(NodeRecord(name="n2", coordinates=(2.0, 0.0)))
mesh.add_element(ElementRecord(name="beam-1", type_key="B21", node_names=("n1", "n2")))
mesh.add_node_set("root", ("n1",))
mesh.add_node_set("tip", ("n2",))
mesh.add_element_set("beam-set", ("beam-1",))

part = Part(name="beam-part", mesh=mesh)

model = ModelDB(name="beam-demo")
model.add_part(part)
model.add_material(
    MaterialDef(
        name="mat-steel",
        material_type="linear_elastic",
        parameters={"young_modulus": 2.1e11, "poisson_ratio": 0.3, "density": 7850.0},
    )
)
model.add_section(
    SectionDef(
        name="sec-beam",
        section_type="beam",
        material_name="mat-steel",
        region_name="beam-set",
        scope_name="beam-part",
        parameters={"area": 3.0e-4, "moment_inertia_z": 8.1e-9},
    )
)

这段代码完成了三层绑定：

1. NodeRecord 和 ElementRecord 先进入 Mesh。
2. Mesh 再进入 Part，部件成为模型的几何容器。
3. SectionDef 通过 region_name="beam-set" 和 scope_name="beam-part" 命中单元区域，把物理定义挂到部件作用域上。

3. 网格与装配对象

3.1 Part

Part 表示一个可复用的部件，内部持有 Mesh。

如果模型没有显式装配实例，部件通常既是几何容器，也是编译作用域。

3.2 Mesh

Mesh 当前可确认的主要字段包括：

• nodes
• elements
• node_sets
• element_sets
• surfaces
• orientations

其中：

• nodes 保存节点记录
• elements 保存单元记录
• node_sets 与 element_sets 提供命名集合
• surfaces 提供面载荷和表面目标
• orientations 保存局部方向定义

3.3 NodeRecord

NodeRecord 的核心字段是：

• name
• coordinates

当前校验规则要求同一网格内节点空间维数保持一致。

3.4 ElementRecord

ElementRecord 的核心字段包括：

• name
• type_key
• node_names
• section_name=None
• material_name=None
• region_name=None
• orientation_name=None
• properties={}

这里有几个容易混淆的点：

• type_key 指向单元类型，例如 C3D8、CPS4、B21
• section_name 和 material_name 可以直接挂在单元上
• region_name 则允许单元通过区域名称与截面、材料等定义建立间接关联
• orientation_name 用于引用局部方向定义

3.5 SurfaceFacet 与 Surface

Surface 由若干 SurfaceFacet 组成，用于表达“某个命名表面包含哪些单元面”。

这类对象是表面载荷和表面目标选择的基础。

3.6 Orientation

Orientation 当前可确认的主要字段包括：

• name
• system="rectangular"
• axis_1
• axis_2
• parameters

当前校验会检查：

• 轴向量长度必须大于零
• 维数必须与模型空间维数一致
• 两个轴向量必须线性无关

因此，Orientation 不是普通标记对象，而是带有严格几何约束的正式定义对象。

3.7 RigidTransform

RigidTransform 表示实例级刚体变换，当前会校验：

• 维数必须是 2D 或 3D
• 旋转矩阵应保持正交
• 旋转矩阵应保持右手系

这说明装配实例的空间变换已经进入正式数据模型范围，而不是只在 GUI 层做显示。

3.8 PartInstance

PartInstance 当前可确认字段包括：

• name
• part_name
• transform

一个实例总是引用一个现有部件，再通过实例名和刚体变换形成实际求解作用域。

3.9 Assembly

Assembly 当前不仅保存 instances，还保存实例级别的别名索引：

• instance_node_sets
• instance_element_sets
• instance_surfaces

这说明装配层并不是“只有实例列表”，而是已经承担实例级目标解析职责。

3.10 网格记录家族的数据长相

下表只说明网格记录对象的字段形态，不讨论编译去向。

对 ElementRecord，最容易出错的是把字段都当成“随便写个名字就行”。实际上：

• node_names 必须命中当前 Mesh.nodes。
• orientation_name 必须命中 Mesh.orientations。
• section_name / material_name / region_name 不是同义字段，它们对应不同的引用路径。

3.11 Part、Mesh、Assembly 的公开方法

定义层里最常被直接调用的不是 dataclass 构造，而是这些容器方法。

因此，Part 更像“带名字的部件容器”，Mesh 是“真正保存记录和集合的地方”，Assembly 则是“把部件放入实例作用域并给目标查找加一层名字空间”。

3.12 构造示例：NodeRecord -> Mesh -> Part

mesh = Mesh()
mesh.add_node(NodeRecord(name="n1", coordinates=(0.0, 0.0)))
mesh.add_node(NodeRecord(name="n2", coordinates=(1.0, 0.0)))
mesh.add_node(NodeRecord(name="n3", coordinates=(1.0, 1.0)))
mesh.add_node(NodeRecord(name="n4", coordinates=(0.0, 1.0)))
mesh.add_orientation(Orientation(name="ori-1", axis_1=(1.0, 0.0, 0.0), axis_2=(0.0, 1.0, 0.0)))
mesh.add_element(
    ElementRecord(
        name="plate-1",
        type_key="CPS4",
        node_names=("n1", "n2", "n3", "n4"),
        orientation_name="ori-1",
    )
)
mesh.add_node_set("left", ("n1", "n4"))
mesh.add_element_set("plate-set", ("plate-1",))

part = Part(name="part-1", mesh=mesh)

这段代码里有两个很实用的阅读方法：

1. 看 ElementRecord.node_names，就知道单元连接关系的数据长相。
2. 看 mesh.add_element_set("plate-set", ("plate-1",))，就知道后续 SectionDef.region_name 要命中的字符串是什么。

3.13 引用示例：ElementRecord 如何命中截面、材料和方向

下面两种写法都属于当前正式定义主线，但含义不同。

# 直接绑定
mesh.add_element(
    ElementRecord(
        name="beam-1",
        type_key="B21",
        node_names=("n1", "n2"),
        section_name="sec-beam",
        material_name="mat-steel",
    )
)

# 区域绑定
mesh.add_element(ElementRecord(name="beam-2", type_key="B21", node_names=("n2", "n3"), region_name="beam-set"))
model.add_section(
    SectionDef(
        name="sec-beam",
        section_type="beam",
        material_name="mat-steel",
        region_name="beam-set",
        scope_name="beam-part",
        parameters={"area": 3.0e-4, "moment_inertia_z": 8.1e-9},
    )
)

区别在于：

• 直接绑定时，ElementRecord 自己就写明截面名和材料名。
• 区域绑定时，ElementRecord 只声明自己属于哪个区域，真正的截面和材料由 SectionDef.region_name + scope_name 来命中。

如果再叠加局部方向，则 orientation_name 会去 Mesh.orientations 里找同名 Orientation。这条引用链在编译前就会由 validate() 检查。

3.14 装配示例：PartInstance 与 Assembly

assembly = Assembly(name="assembly-1")
assembly.add_instance(PartInstance(name="left", part_name="beam-part"))
assembly.add_instance(
    PartInstance(
        name="right",
        part_name="beam-part",
        transform=RigidTransform(translation=(3.0, 0.0)),
    )
)
assembly.add_instance_node_set("left", "root", ("n1",))
assembly.add_instance_node_set("right", "root", ("n1",))

model.set_assembly(assembly)

这时读者需要换一个思路：

• beam-part 还是定义层里的部件名。
• left 和 right 已经是后续编译、载荷命中和结果命名所使用的实例作用域名。
• 同名集合 root 可以在不同实例下重复存在，真正区分它们的是实例作用域。

4. 物理与工况定义对象

4.1 MaterialDef

MaterialDef 的核心字段是：

• name
• material_type
• parameters

当前正式主线可确认的材料类型包括：

• linear_elastic
• elastic_isotropic
• j2_plastic
• j2_plasticity

对内置线弹性材料，可以确认的参数别名包括：

• 杨氏模量：young_modulus、elastic_modulus、e
• 泊松比：poisson_ratio、nu
• 可选密度：density

对内置 J2 塑性材料，可以确认的参数包括：

• 线弹性参数同上
• 必需屈服应力：yield_stress
• 可选硬化模量：hardening_modulus
• 可选密度：density
• 可选切线模式：tangent_mode

4.2 SectionDef

SectionDef 的核心字段是：

• name
• section_type
• material_name=None
• region_name=None
• scope_name=None
• parameters

当前正式主线可确认的截面类型包括：

• solid
• plane_stress
• plane_strain
• beam

内置截面的主要参数约束如下：

• solid 不要求额外几何参数，重点是材料绑定
• plane_stress 和 plane_strain 可使用 thickness，默认值为 1.0
• beam 需要 area
• beam 需要 moment_inertia_z 或别名 iz
• beam 可选 shear_factor，默认值为 1.0

此外，单元类型与截面类型之间存在正式兼容关系：

• C3D8 要求实体类截面
• CPS4 要求平面类截面
• B21 要求梁截面

文档写作时应把这些兼容关系视为正式限制，而不是经验建议。

4.3 BoundaryDef

BoundaryDef 的核心字段包括：

• name
• target_name
• dof_values
• target_type="node_set"
• scope_name=None
• boundary_type="displacement"
• parameters

当前内置正式约束类型是 displacement。因此：

• 边界条件的正式主线是位移型约束
• dof_values 用于给出自由度值
• 目标默认按节点集解释

4.4 NodalLoadDef

NodalLoadDef 的核心字段包括：

• name
• target_name
• components
• target_type="node_set"
• scope_name=None
• parameters

当前正式主线中，节点载荷目标类型应理解为：

• node
• node_set

载荷分量既可以直接写自由度名，也可以写常见力学别名。当前代码中可确认的映射包括：

• FX、FY、FZ
• MX、MY、MZ

这些别名最终会映射到对应自由度方向。

如果 parameters 中给出了 scale，装配时会应用该缩放因子。

4.5 DistributedLoadDef

DistributedLoadDef 的核心字段包括：

• name
• target_name
• load_type
• components
• target_type="surface"
• scope_name=None
• parameters

从定义对象角度看，分布载荷已经是正式对象；但从求解主线角度看，它的实际支持范围比对象定义本身更窄。

当前可以确认：

• 装配器只接受 surface 目标
• parameters["scale"] 会作为缩放因子参与装配
• P 和 pressure 会归一化到 pressure
• follower、follower_pressure、follower-pressure 会归一化到 follower_pressure

但这并不等于所有载荷类型都已经有正式求解支持。对于当前帮助文档，应把“小变形主线下的表面压力载荷”作为最稳妥的正式说明口径，而不要把 GUI 中露出的所有选项都写成正式能力。

4.6 OutputRequest

OutputRequest 的核心字段包括：

• name
• variables
• target_type="model"
• target_name=None
• scope_name=None
• position="node"
• frequency=1
• parameters

它表示“这个步骤希望输出哪些变量、面向什么目标、以什么位置和频率输出”。

需要特别注意：

• variables 不能为空
• frequency 必须大于零
• 位置、目标类型和变量类型之间存在正式匹配关系

当前正式支持的位置可确认包括：

• NODE
• ELEMENT_CENTROID
• INTEGRATION_POINT
• ELEMENT_NODAL
• NODE_AVERAGED
• GLOBAL_HISTORY

目标类型的正式校验范围可确认包括：

• model
• node
• node_set
• element
• element_set
• surface

但并不是所有目标类型都能和所有输出位置自由组合，具体匹配规则见本章第 6 节和第 9 章。

4.7 StepDef

StepDef 的核心字段包括：

• name
• procedure_type
• boundary_names=()
• nodal_load_names=()
• distributed_load_names=()
• output_request_names=()
• parameters

它的职责是把“使用什么分析过程”与“调用哪些工况对象”绑定起来。

边界条件、载荷和输出请求本身不会自动生效。只有被步骤对象显式引用后，它们才进入该步骤的正式执行范围。

4.8 JobDef

JobDef 的核心字段包括：

• name
• step_names
• parameters

作业对象负责组织步骤顺序。它说明 pyFEM 当前已经把“多步骤执行顺序”纳入正式模型层，而不是单纯依赖外部脚本逐步调用。

4.9 关键定义对象的数据长相

下表把“物理定义对象”和“工况定义对象”的字段语义落到最小可用层面。

parameters 字段需要单独说明。它不是任意附加信息的容器，而是 provider 和 runtime 会继续读取的正式输入。例如：

• MaterialDef.parameters 会被材料 provider 解释为材料常数。
• SectionDef.parameters 会被截面 provider 解释为几何参数。
• StepDef.parameters 则会被 procedure provider 解释为模态数、时间步长、非线性控制参数等步骤参数。

4.10 最小工况示例：SectionDef、BoundaryDef、OutputRequest、StepDef

model.add_material(
    MaterialDef(
        name="mat-1",
        material_type="linear_elastic",
        parameters={"young_modulus": 1.0e6, "poisson_ratio": 0.3, "density": 4.0},
    )
)
model.add_section(
    SectionDef(
        name="sec-1",
        section_type="beam",
        material_name="mat-1",
        region_name="beam-set",
        scope_name="beam-part",
        parameters={"area": 0.03, "moment_inertia_z": 2.0e-4},
    )
)
model.add_boundary(BoundaryDef(name="bc-root", target_name="root", dof_values={"UX": 0.0, "UY": 0.0, "RZ": 0.0}))
model.add_nodal_load(NodalLoadDef(name="load-tip", target_name="tip", components={"FY": -12.0}))
model.add_output_request(OutputRequest(name="field-u", variables=("U", "RF"), target_type="model", position="NODE"))
model.add_step(
    StepDef(
        name="step-static",
        procedure_type="static_linear",
        boundary_names=("bc-root",),
        nodal_load_names=("load-tip",),
        output_request_names=("field-u",),
    )
)
model.set_job(JobDef(name="job-1", step_names=("step-static",)))

从这个例子里可以直接看出三条正式引用关系：

1. SectionDef.material_name="mat-1" 命中 MaterialDef.name。
2. StepDef.boundary_names / nodal_load_names / output_request_names 命中对应定义对象的 name。
3. JobDef.step_names 命中 StepDef.name，把步骤真正排成执行顺序。

5. 名称、引用与作用域规则

5.1 目标查找的正式类型

ModelDB 当前会把以下目标类型视为正式可查找对象：

• model
• node
• node_set
• element
• element_set
• surface

这套目标类型贯穿边界条件、载荷和输出请求校验。

5.2 作用域名称 scope_name

scope_name 的意义可以概括为：“这个定义属于哪个部件或哪个实例作用域”。

在无装配实例模型中，scope_name 往往对应部件名。 在有装配实例模型中，scope_name 更应理解为实例作用域名。

因此：

• 同名节点集如果分属不同实例，需要靠 scope_name 区分
• 截面、边界、载荷和输出请求是否能命中目标，都会受 scope_name 影响

5.3 直接绑定与区域绑定

单元与材料、截面的关系有两条主线：

• 直接在 ElementRecord 上通过 section_name、material_name 绑定
• 通过 region_name 与 SectionDef.region_name 等区域定义建立间接绑定

帮助文档中需要同时说明这两条能力，但要提醒读者保持命名一致，否则模型校验阶段就会失败。

5.4 名称引用表

下表专门说明字符串名字是如何在定义层命中正式对象的。

读者真正需要掌握的是：pyFEM 当前大量使用“名字引用”，但这些名字并不是全局无条件生效。只要目标涉及集合、表面或实例，就必须把 scope_name 一起看。

5.5 名称命中与运行时映射示例

下面这条链最适合作为阅读定义层的主线：

ElementRecord.region_name = "beam-set"
    -> SectionDef.region_name = "beam-set"
    -> SectionDef.material_name = "mat-1"
    -> MaterialDef.name = "mat-1"
    -> Compiler.compile()
    -> SectionRuntime + MaterialRuntime + ElementRuntime

工况对象的命中过程可写成：

BoundaryDef(target_name="root", target_type="node_set", scope_name="left")
    -> StepDef.boundary_names = ("bc-root",)
    -> ProcedureRuntime.run(...)
    -> Assembler.collect_constraints(...)

这类“名称如何命中正式对象并进入运行时映射”的过程，需要在帮助文档中明确写出。只列对象名而不说明名称解析规则，读者很难建立可复现的建模方法。

6. 输出请求的正式匹配规则

从输出请求规划器可以确认，输出位置、变量和目标类型存在明确匹配关系。

6.1 节点类输出

节点位置与节点平均位置常见变量包括：

• U
• U_MAG
• RF
• MODE_SHAPE
• S_AVG
• S_VM_AVG
• S_PRINCIPAL_AVG

这类输出的正式目标类型主要是：

• model
• node
• node_set

6.2 单元类输出

单元质心、积分点和单元节点位置常见变量包括：

• S
• E
• SECTION
• S_IP
• E_IP
• S_VM_IP
• S_PRINCIPAL_IP
• S_REC
• E_REC
• S_VM_REC
• S_PRINCIPAL_REC

这类输出的正式目标类型主要是：

• model
• element
• element_set

6.3 全局历史输出

当前可确认的全局历史变量包括：

• TIME
• FREQUENCY

这类输出只能面向：

• target_type="model"

并且不应再给出 target_name 或 scope_name。

6.4 关于默认输出

这里需要区分两层逻辑：

• 过程侧的输出规划器有自己的默认输出规则
• 导入器在读入输入文件时，也可能自动补入一组默认输出请求

二者不是同一个概念。

因此，帮助文档不应简单写成“pyFEM 总会默认输出某某变量”，而应写成：

• 如果使用特定导入器工作流，导入器可能自动补入默认请求
• 如果从 Python API 直接构造 ModelDB，则应主动检查步骤实际引用了哪些输出请求

6.5 最小输出请求示例

下面三个例子分别对应节点场、单元场和全局历史量，基本覆盖了当前最常见的正式输出请求写法。

# 节点位移与反力
OutputRequest(
    name="field-node",
    variables=("U", "RF"),
    target_type="model",
    position="NODE",
)

# 单元应力与应变
OutputRequest(
    name="field-element",
    variables=("S", "E"),
    target_type="element_set",
    target_name="plate-set",
    scope_name="part-1",
    position="ELEMENT_CENTROID",
)

# 全局时间历史
OutputRequest(
    name="history-time",
    variables=("TIME",),
    target_type="model",
    position="GLOBAL_HISTORY",
)

这三个例子各自回答了一个常见问题：

1. U、RF 这类节点量通常挂在 NODE。
2. S、E 这类单元量通常挂在 ELEMENT_CENTROID、INTEGRATION_POINT 或派生位置。
3. TIME、FREQUENCY 这类全局历史量不应再写 target_name。

7. 模型校验规则

ModelDB.validate() 当前会执行一组正式校验。帮助文档中至少应明确以下几类错误会在编译前被拦截：

• 模型至少要有一个部件
• 部件和网格本身必须有效
• 单元直接引用的截面和材料必须存在
• 装配实例引用的部件必须存在
• 实例变换维数必须匹配
• 截面引用的作用域、材料和区域必须存在
• 边界条件、节点载荷和分布载荷的目标必须存在
• 相互作用的作用域必须存在
• 输出请求如果不是面向 model，则必须给出有效目标
• 步骤必须给出 procedure_type
• 步骤引用的边界、载荷和输出请求名字必须存在
• 作业引用的步骤名字必须存在

8. 对象创建、引用与编译长例

下面的示例把“记录对象 -> 定义对象 -> 步骤引用 -> 编译产物”连成一个完整过程，可作为第 8 章的综合示例。

mesh = Mesh()
mesh.add_node(NodeRecord(name="n1", coordinates=(0.0, 0.0)))
mesh.add_node(NodeRecord(name="n2", coordinates=(2.0, 0.0)))
mesh.add_element(ElementRecord(name="beam-1", type_key="B21", node_names=("n1", "n2"), region_name="beam-set"))
mesh.add_node_set("root", ("n1",))
mesh.add_node_set("tip", ("n2",))
mesh.add_element_set("beam-set", ("beam-1",))

model = ModelDB(name="beam-demo")
model.add_part(Part(name="beam-part", mesh=mesh))
model.add_material(
    MaterialDef(
        name="mat-1",
        material_type="linear_elastic",
        parameters={"young_modulus": 1.0e6, "poisson_ratio": 0.3, "density": 4.0},
    )
)
model.add_section(
    SectionDef(
        name="sec-1",
        section_type="beam",
        material_name="mat-1",
        region_name="beam-set",
        scope_name="beam-part",
        parameters={"area": 0.03, "moment_inertia_z": 2.0e-4},
    )
)
model.add_boundary(BoundaryDef(name="bc-root", target_name="root", dof_values={"UX": 0.0, "UY": 0.0, "RZ": 0.0}))
model.add_nodal_load(NodalLoadDef(name="load-tip", target_name="tip", components={"FY": -12.0}))
model.add_output_request(OutputRequest(name="field-u", variables=("U",), target_type="model", position="NODE"))
model.add_step(
    StepDef(
        name="step-static",
        procedure_type="static_linear",
        boundary_names=("bc-root",),
        nodal_load_names=("load-tip",),
        output_request_names=("field-u",),
    )
)
model.set_job(JobDef(name="job-1", step_names=("step-static",)))

compiled = Compiler().compile(model)

把这段代码拆开看，会更容易理解每个对象什么时候出现：

1. NodeRecord、ElementRecord、节点集和单元集先进入 Mesh。
2. Part 把 Mesh 变成模型中的正式部件。
3. SectionDef 通过 region_name + scope_name 命中 beam-part 作用域中的 beam-set。
4. BoundaryDef 和 NodalLoadDef 只有在被 StepDef 引用后才会成为该步骤的正式输入。
5. Compiler.compile() 之后，这些定义对象不会直接交给 solver，而会被翻译成编译产物、kernel runtime 和 procedure runtime。

最常见的误解主要有四个：

• ElementRecord 不是单元运行时对象，它不会自己算刚度。
• BoundaryDef 不是一创建就自动生效，它必须被步骤引用。
• OutputRequest 不是“结果文件设置面板”，它本身就是正式定义对象。
• JobDef 不是可有可无的装饰；一旦存在多步，步骤顺序就应写在这里。

9. 建模建议

• 优先把对象命名统一成“作用域名.对象名”的稳定风格，便于多实例模型追踪。
• 对 OutputRequest，不要依赖默认行为，显式写出变量、位置和目标会更稳妥。
• 对 DistributedLoadDef，把正式文档口径控制在当前求解主线可证实的范围内。
• 对 Orientation 和 RigidTransform，应视为正式模型对象，不要把它们写成 GUI 附属元数据。
• 对多步骤模型，尽量在 JobDef.step_names 中明确步骤顺序，而不是依赖脚本外部约定。

第 9 章 Procedures 层

本章把 procedures 作为独立体系讲清楚。它负责把一个 StepDef 组织成可执行的过程对象，并在步骤边界上管理状态推进、结果写出和对 solver 的调用。

1. 这一层为什么存在

procedures 层解决的是“一个分析步骤怎样执行”。它不负责局部物理细节，也不负责全局线性代数求解，而是承担以下正式职责：

1. 把 StepDef 翻译成 ProcedureRuntime。
2. 按过程类型组织边界、载荷、输出和求解主线。
3. 调用 solver 层完成离散系统装配与求解。
4. 在步骤开始和结束处处理状态继承、结果帧、历史序列和摘要。

因此，procedures 不是 kernel 的一部分，也不是 solver 的别名。它处在两者之上，负责“步骤级编排”。

2. Procedures 家族地图

下表先给出本层对象家族地图，帮助读者先建立层内分工，再进入具体对象。

3. StepDef 与 ProcedureRuntime 的区别

下表用于澄清最容易混淆的相邻对象。

StepDef 的职责是“定义这个步骤要做什么”。ProcedureRuntime 的职责是“真正按这个步骤去执行什么”。这也是为什么第 9 章必须独立于第 4 章。

4. Procedure Provider 与步骤家族

StepDef.procedure_type 不会直接实例化 ProcedureRuntime。当前正式主线里，它会先命中 provider，再由 provider 构造具体过程对象。

下表只说明当前正式支持的过程键与 provider 绑定。

provider 的正式角色包括：

1. 读取 StepDef 与 CompiledModel。
2. 选择合适的 Assembler、DiscreteProblem 和 LinearAlgebraBackend。
3. 创建具体 ProcedureRuntime。
4. 在必要时执行 fail-fast 校验。

其中，StaticNonlinearProcedureProvider 还会对 nlgeom=True 的元素、材料和载荷支持子集进行额外校验。因此，几何非线性边界不应被写成所有过程共享的公共承诺。

5. 各过程家族的共性与差异

下表只回答“这些过程家族分别组织哪类主线”，不展开全部算法细节。

6. 核心对象

6.1 ProcedureRuntime

• 所属层：procedures 层
• 家族：抽象过程家族
• 职责：定义所有过程运行时对象的最小正式接口
• 核心字段：当前以抽象边界为主，具体字段由子类承担
• 主要方法状态：当前正式公开方法很少，属于“以最小抽象接口为主”的 runtime 类
• 相邻对象关系：由 provider 创建，并在执行中调用 solver 与结果写出接口
• 典型误解：不要把它看成 StepDef 的别名

下表只列当前建议写成正式公开边界的方法。

6.2 StepProcedureRuntime

• 所属层：procedures 层
• 家族：步骤过程家族
• 职责：为步骤型过程提供统一的状态起点、结果会话和结果组织能力
• 核心字段：definition、compiled_model、problem、backend
• 主要方法状态：公开方法比抽象基类更多，属于“有明确运行主线的 runtime 类”
• 相邻对象关系：读取 StepDef 与 CompiledModel，并组织 DiscreteProblem 的调用
• 典型误解：它不是 solver 对象，也不是 CompiledModel 的一部分

除上述字段外，初始化阶段还会组织 output_planner、raw_field_service、recovery_service、averaging_service、derived_field_service 等结果相关服务。它们服务于过程执行，但不改变本层与结果层的边界。

下表只列当前可确认为正式公开边界的方法。

6.3 当前正式过程实现分节展开

下面不再只列“有哪些实现类”，而是分别说明每一种正式过程在主线里怎么工作。

6.3.1 StaticLinearProcedure

StaticLinearProcedure 是当前正式小变形线性静力过程类。该类在 StepDef.procedure_type 为 static 或 static_linear 时，由 StaticLinearProcedureProvider 创建，并以 StepDef、CompiledModel、DiscreteProblem、SciPyBackend 为构造输入。

数据字段

definition
类型为 StepDef。
该字段保存当前步骤定义，其中直接使用的内容包括 boundary_names、nodal_load_names、distributed_load_names、output_request_names 和 parameters。

compiled_model
类型为 CompiledModel。
该字段保存编译产物，过程对象通过它间接访问已编译的单元、材料、截面、约束和结果规划信息。

problem
类型为 DiscreteProblem。
该字段是静力线性求解的离散问题入口，负责矩阵装配、约束施加和状态提交。

backend
类型为 LinearAlgebraBackend。
当前正式内置实现由 provider 固定为 SciPyBackend。

output_planner 及结果辅助服务字段
类型为内部服务对象。
这些字段在 StepProcedureRuntime.__post_init__() 中创建，包括输出规划器、原始字段构造、恢复、平均和派生字段服务。当前帮助文档不将这些内部字段扩展为稳定用户合同。

正式公开方法

get_name()
返回 str。
返回步骤名，当前实现直接取自 definition.name。

get_procedure_type()
返回 str。
返回步骤过程类型，当前实现直接取自 definition.procedure_type。

describe()
返回 Mapping[str, Any]。
返回过程摘要，其中包含步骤名、过程类型、边界条件名称、载荷名称、输出请求名称和步骤参数。

build_results_session()
返回 ResultsSession。
该方法根据模型名、作业名、步骤名、过程类型和步骤参数创建本步骤的结果会话对象。

run(results_writer)
返回 ProcedureReport。
这是当前类的正式执行入口。方法内部依次调用 problem.begin_trial()、problem.assemble_tangent()、problem.assemble_external_load()、problem.apply_constraints() 和 backend.solve_linear_system()，得到位移解后提交状态，并按输出请求写出 ResultFrame、ResultSummary 和可选的 TIME 历史量。

当前可直接确认的行为

run() 只求解一次线性方程组，不执行增量控制，不执行迭代收敛判定。

求解完成后，当前实现会将 trial_state.velocity 和 trial_state.acceleration 写成与位移向量同长度的零向量，并将 trial_state.time 设为 0.0。

结果写出时，当前正式字段主线至少包括节点位移 U 和节点反力 RF。摘要对象名称固定为 static_summary，当前至少包含 residual_norm、load_norm 和 displacement_norm 三个数值项。

当输出规划器请求 TIME 历史量时，当前实现会写出轴类型为 FRAME_ID、轴值为 (0,)、数据值为 (0.0,) 的单点历史序列。

当前边界

该类不执行非线性增量迭代，不应写成会自动切换到 StaticNonlinearProcedure。

该类会读取 distributed_load_names，但不同分布载荷是否能形成正式求解主线，仍受单元和求解实现的当前支持范围约束。

当前文档未将 describe() 返回映射的完整键集合冻结为稳定公开合同。

最小示例

step = StepDef(
    name="step-static",
    procedure_type="static_linear",
    boundary_names=("bc-root",),
    nodal_load_names=("load-tip",),
    output_request_names=("field-node", "history-time"),
)

6.3.2 ModalProcedure

ModalProcedure 是当前正式小变形线性模态过程类。该类在 StepDef.procedure_type 为 modal 时创建，用于计算约束条件下的广义特征值和振型。

数据字段

definition
类型为 StepDef。
该字段保存模态步定义，当前可直接确认会读取 boundary_names、output_request_names 和 parameters["num_modes"]。

compiled_model
类型为 CompiledModel。
该字段提供模态步所需的编译结果、自由度管理信息和结果规划上下文。

problem
类型为 DiscreteProblem。
该字段提供刚度矩阵、质量矩阵、约束缩减和向量扩展接口。

backend
类型为 LinearAlgebraBackend。
当前内置实现使用 SciPyBackend 求解广义特征值问题。

正式公开方法

get_name()
返回 str。
返回步骤名。

get_procedure_type()
返回 str。
返回过程类型键，当前值为 modal。

describe()
返回 Mapping[str, Any]。
返回步骤摘要，包含模态步使用的边界条件、输出请求和参数字典。

build_results_session()
返回 ResultsSession。
创建本步骤结果会话对象。

run(results_writer)
返回 ProcedureReport。
这是当前类的正式执行入口。当前实现先装配切线矩阵和质量矩阵，再对两者施加相同的边界约束，随后调用 backend.solve_generalized_eigenproblem() 求解特征对，并把缩减空间中的模态向量扩展回全局自由度。

当前可直接确认的行为

run() 会从 definition.parameters 中读取 num_modes，若未显式给出，则当前源码默认值为 6。

对每个模态，当前实现会生成一个 ResultFrame，其 frame_kind 为 MODE，axis_kind 为 MODE_INDEX，axis_value 为当前模态序号。字段名固定为 MODE_SHAPE。

模态向量扩展回全局自由度后，当前实现会按最大绝对值归一化。

当输出规划器请求历史量 FREQUENCY 时，当前实现会写出频率序列，并在 paired_values 中同步写出 eigenvalue。

当前边界

该类不推进时间，不写出静力位移平衡解，不应与 StaticLinearProcedure 混写。

当前文档未将模态向量归一化策略扩展为用户可配置合同。当前可确认行为是按最大绝对值归一化。

当前文档未进一步展开 ResultFrame.metadata 中模态相关元数据的完整键表；当前源码可确认至少包含模态序号、频率和特征值。

最小示例

step = StepDef(
    name="step-modal",
    procedure_type="modal",
    boundary_names=("bc-root", "bc-guide"),
    output_request_names=("field-modal", "history-modal"),
    parameters={"num_modes": 3},
)

6.3.3 ImplicitDynamicProcedure

ImplicitDynamicProcedure 是当前正式隐式动力过程类。该类由 ImplicitDynamicProcedureProvider 创建，当前实现采用 Newmark 参数格式组织时间离散。

数据字段

definition
类型为 StepDef。
当前可直接确认会读取 boundary_names、nodal_load_names、distributed_load_names、output_request_names 和时间积分参数。

compiled_model
类型为 CompiledModel。
该字段提供已编译的运行时对象集合和结果写出上下文。

problem
类型为 DiscreteProblem。
该字段负责质量矩阵、阻尼矩阵、切线矩阵、外载、规定值处理和状态提交。

backend
类型为 LinearAlgebraBackend。
当前 provider 使用 SciPyBackend 求解每个时间步中的线性系统。

正式公开方法

get_name()
返回 str。
返回步骤名。

get_procedure_type()
返回 str。
返回过程类型键，当前可为 implicit_dynamic 或其兼容入口 dynamic。

describe()
返回 Mapping[str, Any]。
返回步骤摘要。

build_results_session()
返回 ResultsSession。
创建隐式动力步骤的结果会话对象。

build_initial_state()
返回 RuntimeState。
根据 initial_displacement、initial_velocity、initial_acceleration 这组步骤参数构造零时刻状态。参数未给出时，相关向量保持为零向量。

run(results_writer)
返回 ProcedureReport。
这是当前类的正式执行入口。方法先解析积分参数，建立初始状态并施加约束对应的规定位移、速度和加速度；随后装配质量矩阵、阻尼矩阵、切线矩阵和初始外载，求解初始加速度；再按照时间步循环构造有效刚度与有效右端，逐步更新位移、速度、加速度和时间，并在满足输出规划时写出结果帧。

当前可直接确认的行为

当前实现会解析 time_step、num_steps 或 total_time、beta、gamma，并将其整理为统一的 Newmark 参数对象。

初始加速度由约束修正后的质量矩阵和右端项求解得到。右端项为 initial_load - damping @ velocity - tangent @ displacement。

每个时间步内，当前实现都会更新 displacement、velocity、acceleration 和 time，并把受约束自由度重新写回规定值。

结果写出方面，当前正式字段主线可直接确认至少包括节点位移 U。摘要对象名称固定为 dynamic_summary，当前至少包含 scheme、time_step、num_steps、times 和 displacement_norms。

当前边界

当前帮助文档未将速度场和加速度场写成稳定公开结果字段，不能直接扩写为当前正式输出。

当前帮助文档未进一步展开阻尼矩阵的完整来源合同。assemble_damping() 接口存在，但不同单元是否返回非零阻尼矩阵，应以当前源码实现为准。

当前文档未把完整时间积分参数集合冻结为稳定输入合同；除 time_step、num_steps、total_time、beta、gamma 与初始状态向量参数外，其余细节应以源码实现为准。

最小示例

step = StepDef(
    name="step-dynamic",
    procedure_type="implicit_dynamic",
    boundary_names=("bc-root", "bc-guide"),
    output_request_names=("field-dynamic", "history-dynamic"),
    parameters={
        "time_step": 0.0005,
        "total_time": 0.005,
        "beta": 0.25,
        "gamma": 0.5,
        "initial_displacement": {"part-1.n2.UX": 0.01},
    },
)

6.3.4 StaticNonlinearProcedure

StaticNonlinearProcedure 是当前正式静力非线性过程类。该类用于在静力载荷作用下按增量和迭代方式求解非线性平衡路径。

数据字段

definition
类型为 StepDef。
该字段保存静力非线性步骤定义，当前可直接确认会读取 boundary_names、nodal_load_names、distributed_load_names、output_request_names 和非线性控制参数。

compiled_model
类型为 CompiledModel。
该字段提供已编译的运行时对象集合以及步骤间状态快照入口。

problem
类型为 DiscreteProblem。
该字段提供切线装配、残量装配、约束施加、状态提交与回滚接口。

backend
类型为 LinearAlgebraBackend。
当前 provider 使用 SciPyBackend 求解每次迭代中的线性系统。

正式公开方法

get_name()
返回 str。
返回步骤名。

get_procedure_type()
返回 str。
返回过程类型键 static_nonlinear。

get_state_transfer_channel()
返回 str | None。
当前实现返回 "solid_mechanics_history"。该值用于在多步计算中标识本步提交状态的继承通道。

describe()
返回 Mapping[str, Any]。
返回步骤摘要。

build_results_session()
返回 ResultsSession。
创建静力非线性步骤的结果会话对象。

build_step_start_state()
返回 RuntimeState。
该方法用于构造本步起始状态。当前实现优先尝试读取前一相关步骤已发布的提交状态；若不存在可继承状态，则创建零状态。若步骤参数中显式提供初始位移、速度、加速度，则按参数覆盖。

restore_problem_state_from_previous_step()
返回 None。
该方法在步骤执行前将可继承的提交状态装入当前 DiscreteProblem。

publish_problem_state_to_following_steps()
返回 None。
该方法在步骤成功完成后，将当前提交状态发布到 CompiledModel 的步骤状态快照结构中。

run(results_writer)
返回 ProcedureReport。
这是当前类的正式执行入口。方法先解析 StaticNonlinearParameters，再创建 LineSearchController，恢复前序状态，构造本步初始状态，随后按增量控制求解。每个增量内部会尝试求解目标载荷因子；若失败且允许 cutback，则减半当前增量重新尝试；若收敛，则写出结果帧、历史量和最终摘要。

当前可直接确认的行为

当前实现会从步骤参数中解析 max_increments、initial_increment、min_increment、max_iterations、residual_tolerance、displacement_tolerance、allow_cutback、line_search、nlgeom。

结果历史量当前至少包括 load_factor、residual_norm、displacement_norm、iteration_count，当输出规划器请求 TIME 时还会补写 TIME。

摘要对象名称固定为 static_nonlinear_summary。当前源码可直接确认至少包含 residual_norm、displacement_norm、iteration_count、converged_increment_count、cutback_count 以及平均迭代次数等统计量。

多步状态继承方面，当前实现通过 "solid_mechanics_history" 通道与 CompiledModel.step_state_snapshots 对接。

当前边界

当 nlgeom=True 时，provider 会先执行 fail-fast 校验。当前正式几何非线性支持范围收口到 B21 的 corotational 路线、CPS4 的 total_lagrangian 路线和 C3D8 的 total_lagrangian 路线，并进一步限制材料与截面组合。

当 nlgeom=True 时，当前 provider 会拒绝 distributed load、surface pressure 和 follower pressure 当前构形语义。

line_search 当前是受控入口，但源码中的 LineSearchController.describe() 仍将启用后的模式描述为 unit_step_placeholder。因此，当前文档不能将其写成完整线搜索算法已形成稳定公开能力。

最小示例

step = StepDef(
    name="step-nl",
    procedure_type="static_nonlinear",
    boundary_names=("bc-left", "bc-right"),
    output_request_names=("field-u", "field-s", "history-time"),
    parameters={
        "max_increments": 8,
        "initial_increment": 0.125,
        "min_increment": 0.125,
        "max_iterations": 20,
        "residual_tolerance": 1.0e-10,
        "displacement_tolerance": 1.0e-10,
        "allow_cutback": True,
        "line_search": False,
        "nlgeom": True,
    },
)

7. procedures 层如何调用 solver 层

procedures 层不会替代 solver。它的正式主线是：

StepDef
    -> ProcedureBuildRequest
    -> ProcedureProvider.build(...)
    -> Assembler + DiscreteProblem + SciPyBackend
    -> ProcedureRuntime.run(...)

不同过程家族对 solver 的调用重点不同：

• StaticLinearProcedure 主要调用 assemble_tangent()、assemble_external_load()、apply_constraints() 和 solve_linear_system()。
• ModalProcedure 主要调用 reduce_matrix() 与 solve_generalized_eigenproblem()。
• ImplicitDynamicProcedure 主要调用 assemble_mass()、assemble_damping()、assemble_tangent()。
• StaticNonlinearProcedure 则围绕切线、残差、约束和状态提交组织迭代循环。

因此，过程层负责“什么时候调用 solver、调用哪些 solver 操作”，solver 层负责“这些操作怎样形成离散系统并得到数值结果”。

8. 多步状态继承与 step_state_snapshots

CompiledModel.step_state_snapshots 是过程层和编译产物之间一个非常关键但容易误解的接口。当前可确认的正式主线是：

1. CompiledModel.step_state_snapshots 以 (channel, step_name) 形式保存 RuntimeState。
2. resolve_inherited_state() 通过 CompiledModel.resolve_inherited_step_state() 读取前序状态。
3. publish_problem_state_to_following_steps() 通过 CompiledModel.publish_step_state() 发布当前状态。
4. StepProcedureRuntime.get_state_transfer_channel() 基类默认返回 None。
5. 当前源码中能直接确认重写该通道的正式过程是 StaticNonlinearProcedure，其通道名为 solid_mechanics_history。

因此，帮助文档应采用保守口径：

• 多步状态继承能力已经存在。
• 但当前最明确、最正式的继承主线主要是非线性固体力学历史状态通道。
• 不能把它外推成所有过程家族都共享完全一致的跨步继承语义。

9. 对象构造、引用与编译短例

step = StepDef(
    name="Step-1",
    procedure_type="static_linear",
    boundary_names=("BC-FIX",),
    nodal_load_names=("LOAD-TIP",),
    output_request_names=("field-u",),
)

compiled = Compiler().compile(model)
procedure = compiled.get_step_runtime("Step-1")

这段示例对应三个连续动作：

1. StepDef 在定义层只保存过程类型和对象引用名。
2. Compiler.compile() 之后，这个定义对象会通过 procedure provider 映射为具体的 ProcedureRuntime。
3. compiled.get_step_runtime("Step-1") 返回的是过程运行时对象，而不是原始定义对象。

10. 边界对照表

下表用于澄清本层最容易混淆的相邻对象或相邻层。

11. 本章主线图

StepDef
    -> ProcedureProvider
    -> ProcedureRuntime
    -> DiscreteProblem / Backend
    -> ResultsWriter
    -> ResultStep / ResultFrame / ResultHistorySeries / ResultSummary

第 10 章 Kernel 层

本章把 kernel 作为独立体系讲清楚。它不再只是“编译后有哪些字段”的附属说明，而是 pyFEM 正式运行时结构中的独立层。

1. 这一层为什么存在

kernel 层解决的是“局部物理对象是什么”。它把定义层里的材料、截面、单元、约束和相互作用，翻译成 solver 可以直接读取的 runtime 对象。

这一层之所以不能继续混进“运行时层大桶”，原因有三点：

1. 它不负责步骤推进，这件事属于 procedures 层。
2. 它不负责全局矩阵装配和线性代数求解，这件事属于 solver 层。
3. 它只定义局部物理对象及其最小接口，并提供局部矩阵、向量和状态语义。

2. Kernel Runtime 家族地图

下表先给出 kernel 层对象家族地图，帮助读者先建立层内分工。

3. Kernel 与相邻层边界

4. Runtime 家族总览

下表只回答“kernel 家族内部有哪些核心对象以及各自承担什么职责”。

5. 核心对象

5.1 MaterialRuntime

• 所属层：kernel 层
• 家族：材料 runtime 家族
• 职责：根据应变、更新模式和已有状态返回材料响应。
• 核心字段：当前以抽象接口为主，无统一字段合同。
• 相邻对象关系：由 MaterialDef 经 provider 构造，通常由 ElementRuntime 读取。
• 典型误解：它不是步骤对象，也不是结果对象。

当前正式公开接口如下。

当前可直接确认的正式实现类如下。

5.2 SectionRuntime

• 所属层：kernel 层
• 家族：截面 runtime 家族
• 职责：表达截面类型，并把材料 runtime 与截面级几何参数绑定到一起。
• 核心字段：当前以抽象接口为主，无统一字段合同。
• 相邻对象关系：由 SectionDef 经 provider 构造，通常由 ElementRuntime 读取。
• 典型误解：它不是定义层 SectionDef 的同义词，而是编译后的截面对象。

当前正式公开接口如下。

需要特别注意：SectionRuntime 基类本身并不强制规定 get_material_runtime()、get_thickness()、get_area() 这类方法，但当前正式实现类会按各自类型提供相应访问器。

当前可直接确认的正式实现类如下。

5.3 ElementRuntime

• 所属层：kernel 层
• 家族：单元 runtime 家族
• 职责：返回单元局部切线、残量、质量、阻尼、表面载荷和单元输出。
• 核心字段：当前以抽象接口为主，无统一字段合同。
• 相邻对象关系：由 ElementRecord、SectionRuntime、MaterialRuntime 共同构造，并由 Assembler 和结果构造逻辑调用。
• 典型误解：它不装配全局系统，它只提供局部贡献。

当前正式公开接口如下。

当前可直接确认的正式实现类如下。

5.4 ConstraintRuntime

• 所属层：kernel 层
• 家族：约束 runtime 家族
• 职责：描述当前约束涉及的自由度集合及其目标值。
• 核心字段：当前以抽象接口为主，无统一字段合同。
• 相邻对象关系：由 BoundaryDef 经 provider 构造，并由 Assembler 收集后施加到全局系统。
• 典型误解：它不是求解器本体，只是约束数据的 runtime 表达。

当前正式公开接口如下。

当前可直接确认的正式实现类是 DisplacementConstraintRuntime，它对应当前正式主线里的位移边界条件。

5.5 InteractionRuntime

• 所属层：kernel 层
• 家族：相互作用 runtime 家族
• 职责：表达当前已注册的相互作用 runtime 对象。
• 核心字段：当前以抽象接口为主，无统一字段合同。
• 相邻对象关系：由 InteractionDef 经 provider 构造，并通过状态分配与描述接口进入正式执行范围。
• 典型误解：当前相互作用家族在正式主线中的作用较轻，不应把它扩写成已形成完整接触框架。

当前正式公开接口如下。

当前可直接确认的正式实现类是 NoOpInteractionRuntime，它对应当前最小正式 no-op 相互作用主线。

5.6 ElasticIsotropicRuntime

ElasticIsotropicRuntime 是当前正式线弹性材料运行时类。该类由材料 provider 根据 MaterialDef.material_type 创建，供梁、平面连续体和三维实体单元在积分点或等效材料点评估应力与材料切线。

数据字段

name
类型为 str。
该字段保存材料运行时名称。当前示例可写为 "steel"。

young_modulus
类型为 float。
该字段保存杨氏模量，例如 2.1e11。

poisson_ratio
类型为 float。
该字段保存泊松比，例如 0.3。

density
类型为 float。
默认值为 0.0。单元质量矩阵计算会读取该值。

正式公开方法

get_name()
返回 str。
返回材料名称。

get_material_type()
返回 "linear_elastic"。
该方法返回当前材料类型键。

allocate_state()
返回 dict[str, Any]。
这是材料状态入口。当前初始状态字典至少包含 strain、stress、mode、strain_measure、stress_measure、tangent_measure。

update(strain, state=None, mode="3d")
返回 MaterialUpdateResult。
这是材料应力和材料切线的正式入口。输入 strain 是当前材料点评估所用的应变向量或应变表示，state 是上一步或上一次迭代的材料状态，mode 用于声明当前材料更新采用的力学模式。返回对象当前可直接确认至少包含应力、切线矩阵和更新后的状态字典。

当前可直接确认的行为

当前源码可直接确认的模式集合包括 3d、solid、plane_stress、plane_strain、uniaxial、beam_axial，以及 3d_total_lagrangian、solid_total_lagrangian、plane_stress_total_lagrangian、plane_strain_total_lagrangian。

allocate_state() 返回的是完整可写状态字典，而不是只读描述对象。单元运行时会把该状态字典保存到材料状态映射中。

当前边界

当前文档未将 MaterialUpdateResult 的完整字段结构展开为稳定公开合同；除应力、切线矩阵和更新状态外，其余细节应以源码实现为准。

mode 不是任意字符串输入。当前正式写法应以单元和截面实现实际传入的模式为准。

最小示例

material = ElasticIsotropicRuntime(
    name="steel",
    young_modulus=2.1e11,
    poisson_ratio=0.3,
    density=7850.0,
)
result = material.update(
    strain=(1.0e-4, 0.0, 0.0, 0.0, 0.0, 0.0),
    mode="solid",
)

5.7 J2PlasticityRuntime

J2PlasticityRuntime 是当前正式 J2 塑性材料运行时类。该类在维持弹塑性应力更新的同时保存塑性历史变量，因此比 ElasticIsotropicRuntime 具有更明确的状态管理语义。

数据字段

name
类型为 str。
该字段保存材料名称。

young_modulus
类型为 float。
保存杨氏模量。

poisson_ratio
类型为 float。
保存泊松比。

yield_stress
类型为 float。
保存屈服应力，例如 250.0e6。

hardening_modulus
类型为 float。
保存线性硬化模量，例如 1.0e9。

density
类型为 float。
默认值为 0.0。

tangent_mode
类型为 str。
当前可直接确认的合法值为 "consistent" 或 "numerical"。

正式公开方法

__post_init__()
返回 None。
该方法在构造完成后执行参数校验。当前可直接确认会检查 young_modulus > 0、poisson_ratio 位于 (-1, 0.5)、yield_stress > 0、hardening_modulus >= 0 且 tangent_mode 属于允许集合。

get_name()
返回 str。
返回材料名称。

get_material_type()
返回 "j2_plasticity"。
返回当前材料类型键。

allocate_state()
返回 dict[str, Any]。
这是塑性材料状态入口。当前初始状态字典至少包含 strain、stress、plastic_strain、equivalent_plastic_strain、plastic_multiplier、yield_function、is_plastic、mode、kinematic_regime、strain_measure、stress_measure、tangent_measure。

update(strain, state=None, mode="3d")
返回 MaterialUpdateResult。
这是塑性应力更新和一致切线或数值切线的正式入口。当前帮助文档未将返回对象的完整键表冻结为稳定公开合同。

当前可直接确认的行为

该类会显式维护塑性应变、等效塑性应变和屈服函数等历史量。

当前源码可直接确认的正式支持模式包括 solid、plane_strain、uniaxial、beam_axial 以及对应的 Total Lagrangian 子集。

当前边界

plane_stress 和 plane_stress_total_lagrangian 当前不应写成该类的正式支持模式。

当前文档未进一步展开塑性状态字典内部所有键的演化规则；更细的增量更新细节应以源码实现为准。

最小示例

material = J2PlasticityRuntime(
    name="j2-steel",
    young_modulus=2.1e11,
    poisson_ratio=0.3,
    yield_stress=250.0e6,
    hardening_modulus=1.0e9,
    tangent_mode="consistent",
)

5.8 BeamSectionRuntime

BeamSectionRuntime 是当前正式二维梁截面运行时类。B21Runtime 在计算轴向刚度、弯曲刚度和质量矩阵时直接读取该对象。

数据字段

name
类型为 str。
保存截面名称，例如 "beam-sec"。

material_runtime
类型为 MaterialRuntime。
当前正式主线中通常绑定 ElasticIsotropicRuntime 或 J2PlasticityRuntime。

area
类型为 float。
保存截面面积，例如 0.03。

moment_inertia_z
类型为 float。
保存绕局部 z 轴的截面惯性矩，例如 2.0e-4。

shear_factor
类型为 float。
默认值为 1.0。当前帮助文档未进一步展开该参数在全部梁公式中的使用范围。

parameters
类型为 dict[str, Any]。
保存附加截面参数。当前文档未将完整参数键表冻结为稳定公开合同。

正式公开方法

get_name()
返回 str。
返回截面名称。

get_section_type()
返回 "beam"。
返回当前截面类型键。

get_material_runtime()
返回 MaterialRuntime。
返回绑定的材料运行时对象。

get_area()
返回 float。
返回截面面积。

get_moment_inertia_z()
返回 float。
返回截面惯性矩。

describe()
返回 Mapping[str, Any]。
返回可序列化截面摘要，其中当前可直接确认至少包含 name、section_type、material_name 和 parameters。

当前可直接确认的行为

B21Runtime 读取该对象的 area 和 moment_inertia_z 参与单元刚度和质量计算。

当前边界

当前文档未进一步展开 parameters 中所有可选键。

最小示例

section = BeamSectionRuntime(
    name="beam-sec",
    material_runtime=material,
    area=0.03,
    moment_inertia_z=2.0e-4,
)

5.9 PlaneStressSectionRuntime 与 PlaneStrainSectionRuntime

这两个类都是当前正式平面截面运行时实现。它们都向 CPS4Runtime 提供厚度和材料对象，但在材料更新模式上分别对应平面应力和平面应变。

PlaneStressSectionRuntime

PlaneStressSectionRuntime 是当前正式平面应力截面运行时类。

数据字段

name
类型为 str。
保存截面名称。

material_runtime
类型为 MaterialRuntime。
绑定的材料运行时对象。

thickness
类型为 float。
默认值为 1.0。当前 CPS4Runtime.compute_mass() 会读取该值参与总质量计算。

parameters
类型为 dict[str, Any]。
保存附加截面参数。当前文档未进一步展开其稳定键表。

正式公开方法

get_name()
返回 str。
返回截面名称。

get_material_runtime()
返回 MaterialRuntime。
返回绑定的材料对象。

get_thickness()
返回 float。
返回厚度值。

get_section_type()
返回 "plane_stress"。
返回平面应力截面类型键。

describe()
返回 Mapping[str, Any]。
返回截面摘要。

当前可直接确认的行为

CPS4Runtime 会根据 get_section_type() 的返回值选择平面应力材料更新语义。

当前边界

J2PlasticityRuntime 当前不应写成与 PlaneStressSectionRuntime 组合后形成正式支持主线。

最小示例

plane_stress = PlaneStressSectionRuntime(
    name="ps-sec",
    material_runtime=material,
    thickness=1.0,
)

PlaneStrainSectionRuntime

PlaneStrainSectionRuntime 是当前正式平面应变截面运行时类。

数据字段

name
类型为 str。
保存截面名称。

material_runtime
类型为 MaterialRuntime。
绑定的材料运行时对象。

thickness
类型为 float。
默认值为 1.0。

parameters
类型为 dict[str, Any]。
保存附加截面参数。

正式公开方法

get_name()
返回 str。
返回截面名称。

get_material_runtime()
返回 MaterialRuntime。
返回绑定的材料对象。

get_thickness()
返回 float。
返回厚度值。

get_section_type()
返回 "plane_strain"。
返回平面应变截面类型键。

describe()
返回 Mapping[str, Any]。
返回截面摘要。

当前可直接确认的行为

当前正式 CPS4 + J2PlasticityRuntime 支持范围收口到平面应变路线。

当前边界

当前文档未进一步展开平面应变截面的全部附加参数合同。

最小示例

plane_strain = PlaneStrainSectionRuntime(
    name="pe-sec",
    material_runtime=material,
    thickness=1.0,
)

5.10 SolidSectionRuntime

SolidSectionRuntime 是当前正式三维实体截面运行时类。C3D8Runtime 初始化时必须绑定该对象。

数据字段

name
类型为 str。
保存截面名称。

material_runtime
类型为 MaterialRuntime。
绑定的材料运行时对象。

parameters
类型为 dict[str, Any]。
保存附加截面参数。当前文档未进一步展开其稳定键表。

正式公开方法

get_name()
返回 str。
返回截面名称。

get_section_type()
返回 "solid"。
返回实体截面类型键。

get_material_runtime()
返回 MaterialRuntime。
返回绑定的材料对象。

describe()
返回 Mapping[str, Any]。
返回可序列化摘要，当前可直接确认至少包含 name、section_type、material_name 和 parameters。

当前可直接确认的行为

当前三维实体正式主线中，C3D8Runtime 会通过该对象读取材料运行时。

当前边界

该类不是“无截面”的占位对象，不应写成可省略。

最小示例

solid_section = SolidSectionRuntime(
    name="solid-sec",
    material_runtime=material,
)

5.11 B21Runtime

B21Runtime 是当前正式二维两节点梁单元运行时类。单元类型键为 "B21"，每个节点的自由度布局是 ("UX", "UY", "RZ")，当前正式几何非线性模式是 ("corotational",)。

数据字段

location
类型为 ElementLocation。
该字段记录单元所属作用域和单元名，例如 ElementLocation(scope_name="part-1", element_name="beam-1")。

coordinates
类型为两个二维坐标点组成的元组。
每个坐标点写成 (x, y)。两组坐标按节点顺序排列。

node_names
类型为长度为 2 的字符串元组。
示例为 ("n1", "n2")，顺序与 coordinates 一致。

dof_indices
类型为整数元组。
由于每个节点有 UX、UY、RZ 三个自由度，两个节点总共有 6 个全局自由度编号。

section_runtime
类型为 BeamSectionRuntime。
初始化时必须绑定梁截面对象。

material_runtime
类型为 MaterialRuntime。
初始化时必须绑定材料运行时对象。

正式公开方法

get_type_key()
返回 "B21"。
返回当前单元类型键。

get_dof_layout()
返回 ("UX", "UY", "RZ")。
返回每个节点的自由度布局。

get_location()
返回 ElementLocation。
返回 location 字段对应的单元位置对象。

get_dof_indices()
返回 tuple[int, ...]。
返回当前单元使用的全局自由度编号。

get_supported_geometric_nonlinearity_modes()
返回 ("corotational",)。
该方法声明当前正式几何非线性模式集合。

allocate_state()
返回 dict[str, Any]。
当前初始返回值为空字典 {}。

compute_tangent_and_residual(displacement=None, state=None)
返回 ElementContribution。
这是梁单元刚度矩阵和残量向量的正式入口。

compute_mass(state=None)
返回单元质量矩阵。
当前实现按一致质量矩阵构造，比例系数为 density * area * length / 420。

compute_damping(state=None)
返回 None。
这是阻尼矩阵入口。当前该类不返回显式阻尼矩阵。

collect_output(...)
返回 Mapping[str, Any]。
这是梁单元输出入口。当前源码可直接确认结果至少包括 reference_length、current_length、rigid_rotation、local_rotation_i、local_rotation_j、equivalent_plastic_strain，并包含梁的轴向量和端弯矩量。

当前可直接确认的行为

该类支持 corotational 几何非线性路线。

输出字段当前可直接确认至少包括 axial_strain、axial_stress、axial_force、end_moment_i、end_moment_j。

当前边界

当前帮助文档未将 collect_output() 返回映射的完整键集合冻结为稳定公开合同。

当前源码中未直接确认 B21Runtime 具有正式 compute_surface_load() 入口，因此不能把表面压力主线写到该类名下。

最小示例

element = B21Runtime(
    location=ElementLocation(scope_name="part-1", element_name="beam-1"),
    coordinates=((0.0, 0.0), (2.0, 0.0)),
    node_names=("n1", "n2"),
    dof_indices=(0, 1, 2, 3, 4, 5),
    section_runtime=section,
    material_runtime=material,
)

5.12 CPS4Runtime

CPS4Runtime 是当前正式四节点平面连续体单元运行时类。单元类型键为 "CPS4"，每个节点的自由度布局是 ("UX", "UY")，当前正式几何非线性模式是 ("total_lagrangian",)。

数据字段

location
类型为 ElementLocation。
记录单元所属作用域和单元名。

coordinates
类型为 4 个二维坐标点组成的元组。
每个坐标点写成 (x, y)。四组坐标按节点顺序排列。

node_names
类型为长度为 4 的字符串元组。
顺序与 coordinates 一致。

dof_indices
类型为整数元组。
每个节点有 UX 和 UY 两个自由度，因此一个 CPS4 单元通常对应 8 个全局自由度编号。

section_runtime
类型为 PlaneStressSectionRuntime | PlaneStrainSectionRuntime。
初始化时必须绑定平面应力或平面应变截面对象。

material_runtime
类型为 MaterialRuntime。
初始化时必须绑定材料运行时对象。

正式公开方法

get_type_key()
返回 "CPS4"。
返回单元类型键。

get_dof_layout()
返回 ("UX", "UY")。
返回每个节点的自由度布局。

get_location()
返回 ElementLocation。
返回 location 字段对应的位置对象。

get_dof_indices()
返回 tuple[int, ...]。
返回全局自由度编号。

get_supported_geometric_nonlinearity_modes()
返回 ("total_lagrangian",)。
声明当前正式几何非线性模式。

allocate_state()
返回 dict[str, Any]。
当前初始返回值为空字典 {}。

compute_tangent_and_residual(displacement=None, state=None)
返回 ElementContribution。
这是单元切线矩阵和残量向量的正式入口。当前实现会根据 nlgeom 标志在小变形和 Total Lagrangian 路线之间切换。

compute_mass(state=None)
返回单元质量矩阵。
当前实现使用 density * thickness * reference_area 计算总质量，再按四个节点平均分配，形成对角 8 x 8 结点集中的质量矩阵。

compute_damping(state=None)
返回 None。
这是阻尼矩阵接口。当前该类未形成显式阻尼矩阵公开合同。

collect_output(...)
返回 Mapping[str, Any]。
这是单元输出入口。当前源码可直接确认最小稳定输出键至少包括 strain、stress、thickness、integration_points、nlgeom_active、nlgeom_mode、strain_measure、stress_measure、tangent_measure 以及 recovery 元数据。

当前可直接确认的行为

当前输出中包含 averaging_weight 和恢复所需的 recovery 元数据。recovery 中当前源码可直接确认至少包含 target_keys、base_target_keys、extrapolation_matrix。

section_runtime.get_section_type() 会影响材料更新所采用的平面应力或平面应变模式。

当前边界

当前正式几何非线性子集收口到 total_lagrangian，不应扩写成任意几何非线性算法。

PlaneStressSectionRuntime + J2PlasticityRuntime 当前不应写成正式支持组合。

当前文档未将 compute_surface_load() 写成该类的稳定公开接口，不能把平面表面压力主线写成 CPS4Runtime 的正式能力。

最小示例

element = CPS4Runtime(
    location=ElementLocation(scope_name="part-1", element_name="plate-1"),
    coordinates=((0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)),
    node_names=("n1", "n2", "n3", "n4"),
    dof_indices=tuple(range(8)),
    section_runtime=plane_strain,
    material_runtime=material,
)

5.13 C3D8Runtime

C3D8Runtime 是当前正式八节点三维实体单元运行时类。它属于 ElementRuntime 家族，单元类型键为 "C3D8"，每个节点的自由度布局是 ("UX", "UY", "UZ")。当前正式几何非线性模式是 ("total_lagrangian",)。当前帮助文档已可直接确认，它是当前唯一形成正式表面压力载荷主线的单元实现。

数据字段

location
类型是 ElementLocation。
它记录该单元所属的作用域和单元名。当前示例可写成 ElementLocation(scope_name="part-1", element_name="block-1")。

coordinates
类型是 8 个三维坐标点组成的元组。
每个坐标点写成 (x, y, z)。这 8 组坐标按节点顺序排列，对应一个 C3D8 单元的 8 个节点。

node_names
类型是长度为 8 的字符串元组。
它保存这 8 个节点的名称，顺序应与 coordinates 一致。

dof_indices
类型是整数元组。
由于每个节点有 UX、UY、UZ 三个自由度，一个 C3D8 单元通常对应 24 个全局自由度编号。

section_runtime
类型是 SolidSectionRuntime。
这表示 C3D8Runtime 初始化时必须绑定实体截面对象。

material_runtime
类型是 MaterialRuntime。
这表示 C3D8Runtime 初始化时必须绑定材料运行时对象。

正式公开方法

get_type_key()
返回 "C3D8"。
该方法返回当前运行时对象的单元类型键。

get_dof_layout()
返回 ("UX", "UY", "UZ")。
该方法返回每个节点的自由度布局。

get_location()
返回 ElementLocation。
返回 location 字段对应的位置对象。

get_dof_indices()
返回 tuple[int, ...]。
返回 24 个全局自由度编号。

get_supported_geometric_nonlinearity_modes()
返回 ("total_lagrangian",)。
这表示当前正式几何非线性路线收口在 Total Lagrangian。

allocate_state()
返回 dict[str, Any]。
当前这一版实现中，初始返回值为空字典 {}。

compute_tangent_and_residual(displacement=None, state=None)
返回 ElementContribution。
这是单元切线矩阵和单元残量向量的正式入口。当前实现中，该方法会先整理位移输入，再根据是否开启 nlgeom，在小变形路线与 Total Lagrangian 路线之间切换。

compute_mass(state=None)
返回单元质量矩阵。
当前实现中，质量矩阵按总质量平均分到 8 个节点的方式构造。总质量等于材料密度乘参考体积，结果是一个 24 x 24 的结点集中的质量矩阵。

compute_damping(state=None)
返回 None。
这是阻尼矩阵接口。当前帮助文档未将 C3D8Runtime 的具体阻尼实现展开为稳定公开合同。

collect_output(...)
返回 Mapping[str, Any]。
这是单元输出入口。当前源码可直接确认结果映射至少包含 strain、stress、integration_points、nlgeom_active、nlgeom_mode、strain_measure、stress_measure、tangent_measure，以及 recovery 元数据。当前字段中还可直接确认 type_key、location、scope_name、node_names、node_keys、section_name、section_type、material_name、averaging_weight。

compute_surface_load(local_face, load_type, components, state=None)
返回等效节点力向量。
这是表面分布载荷入口。当前正式支持范围收口到小变形 pressure 或 p 表面载荷。

当前可直接确认的行为

compute_tangent_and_residual() 会在小变形路线与 Total Lagrangian 路线之间切换。

compute_mass() 按参考体积和密度构造结点集中的质量矩阵。

collect_output() 当前已直接确认至少可返回 strain 和 stress，并保留积分点数据与恢复元数据。

compute_surface_load() 已形成正式主线，但当前只适用于小变形 pressure 表面载荷。

当前边界

当前仅正式支持小变形 pressure 表面载荷。

nlgeom=True 下的表面分布载荷不应写成当前已支持能力。

follower pressure 当前不应写成已支持能力。

当前帮助文档未将完整输出键表展开为稳定公开合同。

最小示例

element = C3D8Runtime(
    location=ElementLocation(scope_name="part-1", element_name="block-1"),
    coordinates=(
        (0.0, 0.0, 0.0),
        (1.0, 0.0, 0.0),
        (1.0, 1.0, 0.0),
        (0.0, 1.0, 0.0),
        (0.0, 0.0, 1.0),
        (1.0, 0.0, 1.0),
        (1.0, 1.0, 1.0),
        (0.0, 1.0, 1.0),
    ),
    node_names=("n1", "n2", "n3", "n4", "n5", "n6", "n7", "n8"),
    dof_indices=tuple(range(24)),
    section_runtime=solid_section,
    material_runtime=material,
)

5.14 DisplacementConstraintRuntime

DisplacementConstraintRuntime 是当前唯一正式约束 runtime。它的角色不是“再解释一遍边界条件”，而是把定义层边界条件变成 solver 能直接收集的受约束自由度集合。

• 当前可确认的核心字段： name、boundary_type、target_name、target_type、scope_name、constrained_dofs、dof_values、parameters
• collect_constrained_dofs() 返回： tuple[ConstrainedDof, ...]
• describe() 会保留约束目标、作用域和规定值等摘要

帮助文档在这里最该提醒读者的是：

• BoundaryDef.dof_values 还是定义层输入；
• DisplacementConstraintRuntime.constrained_dofs 才是 solver 实际施加约束时读取的 DOF 集合。

5.15 NoOpInteractionRuntime

NoOpInteractionRuntime 是当前最小正式相互作用实现。它存在的意义是把 interaction 家族纳入正式运行时结构，但不把未来接触、耦合、tie 等能力提前写成已支持。

• 当前可确认的核心字段： name、interaction_type、scope_name、parameters
• 当前公开方法： get_name()、get_interaction_type()、describe()

这类对象在帮助文档里的正确写法是：

• 它已经是正式对象家族中的一个最小实现；
• 但它不代表接触主线已经完整形成。

6. 当前正式实现家族

下表把当前 kernel 层已进入正式主线的实现家族收束到一张总览表中。

7. provider 与 placeholder runtime 在 kernel 层中的含义

这里需要明确区分两层概念：

1. provider 绑定发生在编译层。
2. 被绑定出来的正式实现或 placeholder，形状上属于 kernel runtime 家族。

当前编译主线会通过 RuntimeRegistry 为材料、截面、单元、约束和相互作用分别查找 provider。若命中 provider，就生成正式 kernel runtime；若未命中，就生成与该家族对应的 placeholder runtime，例如：

• MaterialRuntimePlaceholder
• SectionRuntimePlaceholder
• ElementRuntimePlaceholder
• ConstraintRuntimePlaceholder
• InteractionRuntimePlaceholder

对 placeholder runtime 的正式口径保持保守：

1. 它表示“编译结构保留了这个位置”。
2. 它不等于“该家族能力已正式支持”。
3. 文档不得把 placeholder runtime 当成稳定用户接口。

8. 对象使用短例

下面的例子只演示 kernel 对象如何进入 CompiledModel 并在后续执行中被读取。

compiled = Compiler().compile(model)

material_runtime = compiled.material_runtimes["Steel"]
section_runtime = compiled.section_runtimes["BEAM_SEC"]
element_runtime = compiled.get_element_runtime("BeamPart.E1")
constraint_runtime = compiled.constraint_runtimes["BC-FIX"]

这条链说明：

1. MaterialDef 不会被 solver 直接读取，solver 读取的是 MaterialRuntime 参与形成的单元贡献。
2. SectionDef 在编译后变成 SectionRuntime，再由单元 runtime 读取。
3. ElementRecord 在编译后变成 ElementRuntime，这是 solver 直接装配的局部对象。

9. 边界对照表

10. 本章主线图

SectionDef / MaterialDef / ElementRecord / BoundaryDef / InteractionDef
    -> provider 绑定
    -> kernel runtimes
    -> Assembler / procedures / post 服务

第 11 章 Solver 层

本章把 solver 作为独立体系讲清楚。它负责形成全局离散系统、施加约束、调用线性代数后端并管理 trial / committed 状态。

1. 这一层为什么存在

solver 层解决的是“局部 runtime 贡献怎样变成全局数值问题”。它之所以不能继续隐藏在 procedures 或 kernel 里，原因有四点：

1. kernel 只提供局部物理对象和局部贡献，不负责全局系统装配。
2. procedures 负责步骤编排，不直接承担矩阵求解和状态管理实现。
3. solver 需要统一处理切线矩阵、质量矩阵、阻尼矩阵、约束和自由度约化。
4. RuntimeState 与 StateManager 提供的是求解内部状态，而不是结果层对象。

因此，solver 层应被正式写成“离散系统与状态推进层”，而不是继续被称作运行时层里的一组内部细节。

2. Solver 家族地图

下表先给出本层对象家族地图，帮助读者先建立层内分工，再进入具体对象。

3. solver 层与相邻层的边界

下表用于澄清最容易混淆的相邻层。

4. 核心对象

4.1 Assembler

Assembler 是当前正式装配类。它读取 CompiledModel 中的单元、约束和载荷定义，生成全局刚度矩阵、残量向量、质量矩阵、阻尼矩阵以及受约束系统。

数据字段

_compiled_model
类型为 CompiledModel。
构造函数接收该对象，并在后续装配过程中访问 element_runtimes、constraint_runtimes、dof_manager 以及定义层载荷对象。

_nlgeom
类型为 bool。
构造函数参数 nlgeom 会写入该字段。当前 assemble_tangent() 和 assemble_residual() 所调用的单元状态解析逻辑会读取这一标志。

正式公开方法

assemble_tangent(state=None)
返回 numpy.ndarray。
这是全局切线矩阵入口。当前实现会遍历全部 element_runtimes，对每个单元调用 element_runtime.tangent_residual(...)，读取返回的局部刚度矩阵并散射到全局矩阵。

assemble_residual(state=None)
返回 numpy.ndarray。
这是全局内力残量向量入口。当前实现同样遍历全部单元，读取 ElementContribution.residual 并散射到全局向量。

assemble_mass(state=None)
返回 numpy.ndarray。
这是全局质量矩阵入口。当前实现对每个单元调用 element_runtime.mass(...) 并进行全局装配。

assemble_damping(state=None)
返回 numpy.ndarray。
这是全局阻尼矩阵入口。当前实现对每个单元调用 element_runtime.damping(...)；若单元返回 None，则该单元不向全局阻尼矩阵贡献条目。

assemble_external_load(step_definition, time=0.0, state=None, load_scale=1.0)
返回 numpy.ndarray。
这是全局外载向量入口。当前实现会先处理 step_definition.nodal_load_names，再处理 step_definition.distributed_load_names，并把荷载值写入对应自由度。

collect_constraints(boundary_names)
返回 tuple[ConstrainedDof, ...]。
该方法从 constraint_runtimes 中收集位移约束自由度和值，并在发现同一自由度收到冲突值时抛出 SolverError。

build_constraint_value_map(boundary_names, scale_factor=1.0)
返回 dict[int, float]。
该方法把约束集合转换为 dof_index -> prescribed_value 映射。

apply_constraints(matrix, rhs, boundary_names, scale_factor=1.0)
返回 tuple[numpy.ndarray, numpy.ndarray]。
这是对全局线性系统施加位移约束的正式入口。当前实现内部转调 apply_prescribed_values(...)。

apply_prescribed_values(matrix, rhs, prescribed_values)
返回 tuple[numpy.ndarray, numpy.ndarray]。
该方法对任意线性系统施加给定位移值。当前实现会先从右端中扣除原矩阵列对规定值的贡献，再把对应行列清零，并把对角项改为 1.0。

reduce_matrix(matrix, boundary_names)
返回 ReducedSystem。
该方法根据位移约束筛出自由自由度，并返回只包含自由自由度子矩阵的约化系统。

collect_element_outputs(state=None)
返回 dict[str, dict[str, Any]]。
这是单元输出收集入口。当前返回值是 qualified_element_name -> output_dict 映射。

extract_element_displacement(element_runtime, global_displacement)
返回 numpy.ndarray。
该方法按单元自由度编号从全局位移向量中抽取局部位移子向量。

当前可直接确认的行为

assemble_tangent() 和 assemble_residual() 都会把全局位移向量按单元自由度切片，再把局部位移作为 tuple 传入单元运行时。

assemble_external_load() 当前支持节点载荷和分布载荷两类定义对象，并读取每个载荷定义里 parameters["scale"] 的缩放系数，缺省值为 1.0。