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

# 快速开始

## 安装

通过 pip 安装 Phynexis：

```bash
pip install phynexis
```

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

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

## 第一个示例

```python
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` 实例
]

### 属性

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

## Model 类

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

### 核心方法

```python
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"` 迭代求解器：

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

---

# 高级用法

## 并行计算

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

```python
from phynexis.parallel import ParallelContext

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

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

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

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

## 自定义材料模型

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

```python
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'`**

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

```bash
pip install --upgrade phynexis
```

**Q: 求解器收敛失败**

检查以下事项：

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

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

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

```python
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 类型注解