mytoolkit/templates/md-to-pdf/manual/demo.md

title, author, version, lang, date

title	author	version	lang	date
Phynexis Python API 参考手册	Phynexis 开发团队	2.1.0	zh	2025 年 5 月

快速开始

安装

通过 pip 安装 Phynexis：

pip install phynexis

#tip-box(title: "提示")[ 建议使用虚拟环境安装，避免与系统 Python 包冲突。

python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate    # Windows

]

第一个示例

from phynexis import Model, Mesh

# 创建简单网格
mesh = Mesh.rectangle(width=1.0, height=1.0, nx=20, ny=20)

# 定义材料模型
model = Model(mesh)
model.set_material(young=210e9, nu=0.3, rho=7850)

# 求解
result = model.solve()
print(f"最大位移: {result.max_displacement:.6f} m")

---

核心 API

Mesh 类

网格是有限元分析的基础。Mesh 类提供多种工厂方法创建常见几何。

类方法

#info-box(title: "Mesh.rectangle")[ 签名: Mesh.rectangle(width, height, nx, ny)

参数:

参数	类型	说明
width	float	矩形宽度
height	float	矩形高度
nx	int	x 方向单元数
ny	int	y 方向单元数

返回: Mesh 实例 ]

属性

mesh.nodes       # ndarray, shape (n_nodes, 2) — 节点坐标
mesh.elements    # ndarray, shape (n_elements, 4) — 四边形单元拓扑
mesh.n_nodes     # int — 节点总数
mesh.n_elements  # int — 单元总数

Model 类

Model 封装了物理场求解的完整流程。

核心方法

model = Model(mesh)

# 设置材料参数
model.set_material(young=210e9, nu=0.3)

# 施加边界条件
model.fix_boundary(tag="left")           # 固定左侧边界
model.apply_force(tag="right", fx=1e6)   # 右侧施加力

# 求解
result = model.solve(solver="direct")

#warn-box(title: "注意")[ solve() 方法默认使用直接求解器。对于大规模问题（> 100,000 DOF），建议使用 "cg" 或 "gmres" 迭代求解器：

result = model.solve(solver="cg", preconditioner="ilu")

]

---

高级用法

并行计算

Phynexis 支持 MPI 并行和 OpenMP 多线程。

from phynexis.parallel import ParallelContext

with ParallelContext(nprocs=4) as ctx:
    model = Model(mesh, comm=ctx.comm)
    result = model.solve()

#danger-box(title: "危险")[ 在 ParallelContext 内部分配大规模数组时，务必确保每个进程只分配自己的局部部分。全局数组会导致内存溢出：

# ❌ 错误：每个进程都分配了全局矩阵
global_K = np.zeros((n_global, n_global))

# ✅ 正确：只分配局部矩阵
local_K = np.zeros((n_local, n_local))

]

自定义材料模型

通过继承 Material 基类实现自定义本构：

from phynexis.material import Material

class HyperelasticMaterial(Material):
    def __init__(self, C10, C01):
        self.C10 = C10
        self.C01 = C01

    def stress(self, F):
        # F: 变形梯度
        # 返回: PK1 应力张量
        ...

    def tangent(self, F):
        # 返回: 切线模量
        ...

---

故障排除

常见问题

Q: 导入时报错 ImportError: cannot import name 'Model' from 'phynexis'

说明你安装的是旧版本。请升级：

pip install --upgrade phynexis

Q: 求解器收敛失败

检查以下事项：

1. 边界条件是否充分约束了刚体位移
2. 材料参数是否合理（特别是泊松比接近 0.5 时）
3. 网格质量是否太差

Q: 并行计算结果与串行不一致

确保所有随机操作（如网格重编号）使用了相同的种子：

import numpy as np
np.random.seed(42)

---

版本历史

v2.1.0 (2025-05-01)

• 新增 GPU 加速求解器（CUDA 后端）
• 支持非线性材料模型
• 改进 mesh 生成器，支持任意多边形

v2.0.0 (2025-01-15)

• 重构核心 API，向后兼容 v1.x
• 引入 Model 类统一求解接口
• 新增 Python 类型注解