Skip to content

[Doc&Fix] Update config doc and correct API #905

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zhiminzhang0830 merged 3 commits into from
May 20, 2024
Merged

[Doc&Fix] Update config doc and correct API #905

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
255206b
update config document and adapt viv code to new config module
HydrogenSulfate May 18, 2024
234d7d0
update 'how to use optuna' in document
HydrogenSulfate May 18, 2024
a0b9851
Fix
HydrogenSulfate May 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 136 additions & 64 deletions docs/zh/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -697,78 +697,150 @@ solver = ppsci.solver.Solver(

=== "examples/fsi/conf/viv.yaml"

``` yaml linenums="1" hl_lines="1 4 19 25 31 34 42 59"
hydra: # (1)
run:
``` yaml linenums="1"
defaults: # (1)
- ppsci_default # (2)
- TRAIN: train_default # (3)
- TRAIN/ema: ema_default # (4)
- TRAIN/swa: swa_default # (5)
- EVAL: eval_default # (6)
- INFER: infer_default # (7)
- _self_ # (8)

hydra:
run:
# dynamic output directory according to running time and override name
dir: outputs_VIV/${now:%Y-%m-%d}/${now:%H-%M-%S}/${hydra.job.override_dirname}
job:
dir: outputs_VIV/${now:%Y-%m-%d}/${now:%H-%M-%S}/${hydra.job.override_dirname} # (9)
job:
name: ${mode} # name of logfile
chdir: false # keep current working direcotry unchaned
config:
override_dirname:
exclude_keys:
- TRAIN.checkpoint_path
- TRAIN.pretrained_model_path
- EVAL.pretrained_model_path
- mode
- output_dir
- log_freq
callbacks:
init_callback:
_target_: ppsci.utils.callbacks.InitCallback # (2)
sweep:
chdir: false # keep current working directory unchanged
callbacks:
init_callback: # (10)
_target_: ppsci.utils.callbacks.InitCallback # (11)
sweep:
# output directory for multirun
dir: ${hydra.run.dir}
subdir: ./

# general settings (3)
mode: train # running mode: train/eval
seed: 42
output_dir: ${hydra:run.dir}
log_freq: 20

# set data file path (4)
VIV_DATA_PATH: "./VIV_Training_Neta100.mat"

# model settings (5)
MODEL:
input_keys: ["t_f"]
output_keys: ["eta"]
num_layers: 5
hidden_size: 50
activation: "tanh"

# training settings (6)
TRAIN:
epochs: 100000
iters_per_epoch: 1
save_freq: 10000
eval_during_train: true
eval_freq: 1000
batch_size: 100
lr_scheduler:
epochs: ${TRAIN.epochs}
iters_per_epoch: ${TRAIN.iters_per_epoch}
learning_rate: 0.001
step_size: 20000
gamma: 0.9
pretrained_model_path: null
checkpoint_path: null

# evaluation settings (7)
EVAL:
pretrained_model_path: null
batch_size: 32
# general settings
mode: train # running mode: train/eval # (12)
seed: 42 # (13)
output_dir: ${hydra:run.dir} # (14)
log_freq: 20 # (15)
use_tbd: false # (16)

VIV_DATA_PATH: "./VIV_Training_Neta100.mat" # (17)

# model settings
MODEL: # (18)
input_keys: ["t_f"] # (19)
output_keys: ["eta"] # (20)
num_layers: 5 # (21)
hidden_size: 50 # (22)
activation: "tanh" # (23)

# training settings
TRAIN: # (24)
epochs: 100000 # (25)
iters_per_epoch: 1 # (26)
save_freq: 10000 # (27)
eval_during_train: true # (28)
eval_freq: 1000 # (29)
batch_size: 100 # (30)
lr_scheduler: # (31)
epochs: ${TRAIN.epochs} # (32)
iters_per_epoch: ${TRAIN.iters_per_epoch} # (33)
learning_rate: 0.001 # (34)
step_size: 20000 # (35)
gamma: 0.9 # (36)
pretrained_model_path: null # (37)
checkpoint_path: null # (38)

# evaluation settings
EVAL: # (39)
pretrained_model_path: null # (40)
batch_size: 32 # (41)

# inference settings
INFER: # (42)
pretrained_model_path: "https://paddle-org.bj.bcebos.com/paddlescience/models/viv/viv_pretrained.pdparams" # (43)
export_path: ./inference/viv # (44)
pdmodel_path: ${INFER.export_path}.pdmodel # (45)
pdiparams_path: ${INFER.export_path}.pdiparams # (46)
input_keys: ${MODEL.input_keys} # (47)
output_keys: ["eta", "f"] # (48)
device: gpu # (49)
engine: native # (50)
precision: fp32 # (51)
onnx_path: ${INFER.export_path}.onnx # (52)
ir_optim: true # (53)
min_subgraph_size: 10 # (54)
gpu_mem: 4000 # (55)
gpu_id: 0 # (56)
max_batch_size: 64 # (57)
num_cpu_threads: 4 # (58)
batch_size: 16 # (59)
```

1. `hydra:` 下的配置段用于控制 hydra 运行时的一些行为，如输出目录、回调函数等，用户只需要修改 `dir:` 后的内容，即可控制输出目录，其余的字段一般不需关注。
2. `callbacks:` 下的配置段用于控制回调函数，如此处添加了负责程序运行前自动固定随机种子、初始化 logger 并创建输出目录的回调函数 `InitCallback`，一般不需要修改这里。
3. `general settings` 下的四个通用设置，包括运行模式 `mode`、随机数种子 `seed`、输出目录 `output_dir` 和日志记录频率 `log_freq`。
4. `set XXX file path` 下的字段，用于控制数据集的路径，如 `VIV_DATA_PATH` 等。
5. `MODEL` 下的字段，用于控制模型结构，如 `disp_net`、`stress_net` 等。
6. `TRAIN:` 下的字段，用于控制训练过程，如 `epochs`、`iters_per_epoch` 等
7. `EVAL:` 下的字段，用于控制评估过程，如 `pretrained_model_path`、`eval_with_no_grad` 等
1. `defaults:` - 定义一系列默认配置项的开头。
2. `- ppsci_default` - 使用名为`ppsci_default`的默认配置。
3. `- TRAIN: train_default` - 在`TRAIN`命名空间下应用`train_default`默认配置。
4. `- TRAIN/ema: ema_default` - 在`TRAIN`的`ema`子命名空间下应用`ema_default`配置。
5. `- TRAIN/swa: swa_default` - 在`TRAIN`的`swa`子命名空间下应用`swa_default`配置。
6. `- EVAL: eval_default` - 在`EVAL`命名空间下应用`eval_default`默认配置。
7. `- INFER: infer_default` - 在`INFER`命名空间下应用`infer_default`默认配置。
8. `- _self_` - 表示当前文件本身的配置将被包含，用于覆盖或添加默认设置。
9. `dir: outputs_VIV/...` - 设置动态输出目录，基于当前时间以及覆盖名称。
10. `init_callback:` - 定义初始化回调的设置。
11. `_target_: ppsci.utils.callbacks.InitCallback` - 指定初始化回调的具体实现类或函数。
12. `mode: train` - 设置当前运行模式为训练模式。
13. `seed: 42` - 设置全局随机种子为42，以确保实验可重复性。
14. `output_dir: ${hydra:run.dir}` - 设置输出目录，与Hydra配置的运行目录相同。
15. `log_freq: 20` - 设置日志记录频率，每20次进行记录。
16. `use_tbd: false` - 关闭 tensorboard 功能。
17. `VIV_DATA_PATH: "./VIV_Training_Neta100.mat"` - 指定VIV的数据文件路径（可以其它数据集或超参值）。
18. `MODEL:` - 开始定义模型相关设置。
19. `input_keys: ["t_f"]` - 设置模型的输入键为`t_f`。
20. `output_keys: ["eta"]` - 设置模型的输出键为`eta`。
21. `num_layers: 5` - 设置模型层数为5。
22. `hidden_size: 50` - 设置模型隐藏层的大小为50。
23. `activation: "tanh"` - 使用双曲正切函数作为激活函数。
24. `TRAIN:` - 开始定义训练相关设置。
25. `epochs: 100000` - 设置训练的总轮数为100000轮。
26. `iters_per_epoch: 1` - 每个轮次包含1次迭代。
27. `save_freq: 10000` - 每10000次迭代保存一次模型或检查点。
28. `eval_during_train: true` - 在训练过程中启用评估。
29. `eval_freq: 1000` - 每1000次迭代进行一次评估。
30. `batch_size: 100` - 设置训练批次大小为100。
31. `lr_scheduler:` - 开始定义学习率调度器的设置。
32. `epochs: ${TRAIN.epochs}` - 学习率调度器使用的轮数与训练的轮数相同。
33. `iters_per_epoch: ${TRAIN.iters_per_epoch}` - 学习率调度器使用的每个轮次的迭代数与训练的相同。
34. `learning_rate: 0.001` - 设置初始学习率为0.001。
35. `step_size: 20000` - 每20000步调整学习率。
36. `gamma: 0.9` - 学习率调整的比率为0.9。
37. `pretrained_model_path: null` - 初始预训练模型路径，可以是实际路径或 url，默认为空表示不使用预训练模型。
38. `checkpoint_path: null` - 检查点路径，用于指定模型加载的检查点，默认为空表示不加载检查点。
39. `EVAL:` - 开始定义评估相关设置。
40. `pretrained_model_path: null` - 评估时使用的预训练模型路径，默认为空表示不使用预训练模型。
41. `batch_size: 32` - 评估时的批次
42. `INFER:` - 开始定义推理（推断）相关的设置。
43. `pretrained_model_path: "https://..."` - 指定预训练模型的路径，可以是实际路径或 url，用于推理。
44. `export_path: ./inference/viv` - 设置模型导出路径，即推理所需的模型文件保存位置。
45. `pdmodel_path: ${INFER.export_path}.pdmodel` - 指定Paddle模型的结构文件路径。
46. `pdiparams_path: ${INFER.export_path}.pdiparams` - 指定Paddle模型的参数文件路径。
47. `input_keys: ${MODEL.input_keys}` - 推理时使用的输入键与模型定义时相同。
48. `output_keys: ["eta", "f"]` - 设置推理时的输出键，包括"eta"和"f"。
49. `device: gpu` - 指定推理使用的设备为GPU。
50. `engine: native` - 设置推理引擎为原生（可能是指使用特定库或框架的默认引擎）。
51. `precision: fp32` - 设置推理的精度为32位浮点数。
52. `onnx_path: ${INFER.export_path}.onnx` - 如果支持，指定ONNX模型文件的路径。
53. `ir_optim: true` - 启用中间表示（Intermediate Representation）的优化。
54. `min_subgraph_size: 10` - 设置子图优化的最小大小，用于提升推理性能。
55. `gpu_mem: 4000` - 指定推理时GPU可使用的内存量（单位可能是MB）。
56. `gpu_id: 0` - 指定使用哪个GPU进行推理，这里是第一个GPU。
57. `max_batch_size: 64` - 设置推理时支持的最大批次大小。
58. `num_cpu_threads: 4` - 指定用于推理的CPU线程数量。
59. `batch_size: 16` - 设置推理时的实际批次大小为16。

### 2.13 训练

Expand Down
40 changes: 16 additions & 24 deletions docs/zh/examples/viv.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@

| 预训练模型 | 指标 |
|:--| :--|
| [viv_pretrained.pdparams](https://paddle-org.bj.bcebos.com/paddlescience/models/aneurysm/viv_pretrained.pdparams)<br>[viv_pretrained.pdeqn](https://paddle-org.bj.bcebos.com/paddlescience/models/aneurysm/viv_pretrained.pdeqn) | 'eta': 1.1416150300647132e-06<br>'f': 4.635014192899689e-06 |
| [viv_pretrained.pdparams](https://paddle-org.bj.bcebos.com/paddlescience/models/aneurysm/viv_pretrained.pdparams)<br>[viv_pretrained.pdeqn](https://paddle-org.bj.bcebos.com/paddlescience/models/aneurysm/viv_pretrained.pdeqn) | eta_l2/MSE.eta: 0.00875<br/>eta_l2/MSE.f: 0.00921 |

## 1. 背景简介

Expand Down Expand Up @@ -102,25 +102,17 @@ examples/fsi/viv.py:25:26

本文采用监督学习的方式，对模型输出 $\eta$ 和基于 $\eta$ 计算出的升力 $f$，这两个物理量进行约束。

在定义约束之前，需要给监督约束指定文件路径等数据读取配置。

``` py linenums="28"
--8<--
examples/fsi/viv.py:28:44
--8<--
```

#### 3.4.1 监督约束

由于我们以监督学习方式进行训练，此处采用监督约束 `SupervisedConstraint`：

``` py linenums="46"
``` py linenums="28"
--8<--
examples/fsi/viv.py:46:52
examples/fsi/viv.py:28:48
--8<--
```

`SupervisedConstraint` 的第一个参数是监督约束的读取配置，此处填入在 [3.4 方程构建](#34) 章节中实例化好的 `train_dataloader_cfg`；
`SupervisedConstraint` 的第一个参数是监督约束的读取配置，此处填入在 [3.2 方程构建](#32) 章节中实例化好的 `train_dataloader_cfg`；

第二个参数是损失函数，此处我们选用常用的MSE函数，且 `reduction` 设置为 `"mean"`，即我们会将参与计算的所有数据点产生的损失项求和取平均；

Expand All @@ -130,9 +122,9 @@ examples/fsi/viv.py:46:52

在监督约束构建完毕之后，以我们刚才的命名为关键字，封装到一个字典中，方便后续访问。

``` py linenums="53"
``` py linenums="49"
--8<--
examples/fsi/viv.py:53:54
examples/fsi/viv.py:49:50
--8<--
```

Expand All @@ -142,17 +134,17 @@ examples/fsi/viv.py:53:54

``` yaml linenums="42"
--8<--
examples/fsi/conf/viv.yaml:42:57
examples/fsi/conf/viv.yaml:42:49
--8<--
```

### 3.6 优化器构建

训练过程会调用优化器来更新模型参数，此处选择较为常用的 `Adam` 优化器和 `Step` 间隔衰减学习率。

``` py linenums="56"
``` py linenums="52"
--8<--
examples/fsi/viv.py:56:58
examples/fsi/viv.py:52:54
--8<--
```

Expand All @@ -164,35 +156,35 @@ examples/fsi/viv.py:56:58

在训练过程中通常会按一定轮数间隔，用验证集（测试集）评估当前模型的训练情况，因此使用 `ppsci.validate.SupervisedValidator` 构建评估器。

``` py linenums="60"
``` py linenums="56"
--8<--
examples/fsi/viv.py:60:82
examples/fsi/viv.py:56:72
--8<--
```

评价指标 `metric` 选择 `ppsci.metric.MSE` 即可；

其余配置与 [监督约束构建](#341) 的设置类似。
其余配置与 [3.4.1 监督约束构建](#341) 的设置类似。

### 3.8 可视化器构建

在模型评估时，如果评估结果是可以可视化的数据，我们可以选择合适的可视化器来对输出结果进行可视化。

本文需要可视化的数据是 $t-\eta$ 和 $t-f$ 两组关系图，假设每个时刻 $t$ 的坐标是 $t_i$，则对应网络输出为 $\eta_i$，升力为 $f_i$，因此我们只需要将评估过程中产生的所有 $(t_i, \eta_i, f_i)$ 保存成图片即可。代码如下：

``` py linenums="84"
``` py linenums="74"
--8<--
examples/fsi/viv.py:84:103
examples/fsi/viv.py:74:93
--8<--
```

### 3.9 模型训练、评估与可视化

完成上述设置之后，只需要将上述实例化的对象按顺序传递给 `ppsci.solver.Solver`，然后启动训练、评估、可视化。

``` py linenums="105"
``` py linenums="95"
--8<--
examples/fsi/viv.py:105:123
examples/fsi/viv.py:95:111
--8<--
```

Expand Down
Loading