diff --git a/docs/zh/install_setup.md b/docs/zh/install_setup.md index 27b8edd9e..2716b941e 100644 --- a/docs/zh/install_setup.md +++ b/docs/zh/install_setup.md @@ -2,15 +2,30 @@ ## 1. 开始安装 -### 1.1 安装 PaddlePaddle +### 1.1 python 环境安装[可选] + +如果你还没有 python 环境或者 python 版本小于 3.7,则推荐使用 Anaconda 安装并配置 python 环境,否则可以忽略本步骤 + +1. 根据系统环境,从 [https://repo.anaconda.com/archive/](https://repo.anaconda.com/archive/) 中下载对应的 Anaconda3 安装包,并手动安装 +2. 创建 python 3.7 环境,并进入该环境 + + ``` sh + # 使用 conda 创建 python 环境,并命名为 "ppsci" + conda create -n ppsci python=3.7 # 3.8 也可以 + + # 进入创建好的 "ppsci" 环境 + conda activate ppsci + ``` + +### 1.2 安装 PaddlePaddle 请在 [PaddlePaddle](https://www.paddlepaddle.org.cn/install/quick?docurl=/documentation/docs/zh/develop/install/pip/linux-pip.html) 官网按照您的运行环境,安装 **develop** 版的 PaddlePaddle -### 1.2 安装 PaddleScience +### 1.3 安装 PaddleScience -从 [1.2.1 git 安装](#121-git) 和 [1.2.2 pip 安装](#122-pip) 任选一种安装方式即可 +从 [1.3.1 git 安装](#121-git) 和 [1.3.2 pip 安装](#122-pip) 任选一种安装方式即可 -#### 1.2.1 git 安装 +#### 1.3.2 git 安装 1. 执行以下命令,从 github 上克隆 PaddleScience 项目,进入 PaddleScience 目录,并将该目录添加到系统环境变量中 @@ -30,7 +45,7 @@ pip install -r requirements.txt ``` -#### 1.2.2 pip 安装 +#### 1.3.3 pip 安装 执行以下命令进行 pip 安装 diff --git a/docs/zh/user_guide.md b/docs/zh/user_guide.md new file mode 100644 index 000000000..273c79609 --- /dev/null +++ b/docs/zh/user_guide.md @@ -0,0 +1,164 @@ +# 使用指南 + +本文档介绍如何使用 PaddleScience 中的常用基础功能和进阶功能,基础功能包括断点继续训练、迁移学习、模型评估、模型推理;进阶功能包括分布式训练(暂时只支持数据并行)、混合精度训练、梯度累加。 + +## 1. 基础功能 + +### 1.1 断点继续训练 + +在模型的日常训练中,可能存在机器故障或者用户手动操作而中断训练的情况,针对这种情况 PaddleScience 提供了断点继续训练的功能,即在训练时默认会保存最近一个训练完毕的 epoch 对应的参数,包括以下几个文件: + +1. `latest.pdparams`,该文件保存了模型内所有网络层的参数。 +2. `latest.pdopt`,该文件保存了优化器所含的所有参数(如 Adam 等一些带有动量记录功能的优化器) +3. `latest.pdeqn`,该文件保存了所有方程的参数,在一些逆问题中如果方程本身含有待估计(可学习)的参数,那么该文件就会保存这些参数。 +4. `latest.pdstates`,该文件保存了当前 epoch 的最优指标以及当前文件对应的 epoch 数。 +5. `latest.pdscaler`(可选),在开启自动混合精度(AMP)功能时,该文件保存了 `GradScaler` 梯度缩放器内部的参数。 + +因此我们只需要在 `Solver` 时,手动指定 `pretrained_model_path` 参数,即可自动载入上述的几个文件,从 `latest` 中记录的 epoch 开始继续训练。 + +``` py hl_lines="9" +import ppsci + +... +... + +solver = ppsci.solver.Solver( + ..., + ..., + pretrained_model_path="/path/to/latest" +) +``` + +???+ Warning "路径填写注意事项" + + 此处只需将路径填写到 "latest" 为止即可,不需要加上其后缀,程序会自动根据 "/path/to/latest",自动补充所需后缀名来加载 `latest.pdparams`、`latest.pdopt` 等文件。 + +### 1.2 迁移学习 + +迁移学习是一种广泛使用、低成本提高模型精度的训练方式。在 PaddleScience 中,只需在 `model` 实例化完毕之后,手动为其载入预训练模型,即可进行迁移学习 + +``` py hl_lines="9" +import ppsci +import ppsci.utils +from ppsci.utils import save_load + +... +... + +model = ... +save_load.load_pretrain(model, "/path/to/pretrain") +``` + +???+ Warning "路径填写注意事项" + + 同样地,此处只需将路径填写到预训练文件的文件名为止即可,不需要加上其后缀,程序会自动根据 "/path/to/pretrain",自动补充所需后缀名来加载 `/path/to/pretrain.pdparams` 文件。 + +???+ info "迁移学习注意事项" + + 在迁移学习时,相对于完全随机初始化的参数而言,载入的预训练模型参数是一个较好的初始化状态,不需要太大的学习率,因此可以将学习率适当调小 2~10 倍以获得更稳定的训练过程和更好的精度。 + +### 1.3 模型评估 + +当模型训练完毕之后,如果我们想手动评估某一个模型在数据集上的精度,则在 `Solver` 实例化时指定参数 `pretrained_model_path` 为模型路径,然后调用 `Solver.eval()` 即可。 + +``` py hl_lines="10" +import ppsci +import ppsci.utils + +... +... + +solver = ppsci.solver.Solver( + ..., + ..., + pretrained_model_path="/path/to/model" +) +solver.eval() +``` + +???+ Warning "路径填写注意事项" + + 同样地,此处只需将路径填写到预训练文件的文件名为止即可,不需要加上其后缀,程序会自动根据 "/path/to/model",自动补充所需后缀名来加载 `/path/to/model.pdparams` 文件。 + +## 2. 进阶功能 + +### 2.1 分布式训练 + +#### 2.1.1 数据并行 + +接下来以 `examples/pipe/poiseuille_flow.py` 为例,介绍如何正确使用 PaddleScience 的数据并行功能。分布式训练细节可以参考:[Paddle-使用指南-分布式训练-快速开始-数据并行](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/06_distributed_training/cluster_quick_start_collective_cn.html)。 + +1. 在 constraint 实例化完毕后,将 `ITERS_PER_EPOCH` 重新赋值为经过自动多卡数据切分后的 `dataloader` 的长度(一般情况下其长度等于单卡 dataloader 的长度除以卡数,向上取整),如代码中黄色高亮行所示。 + + ``` py linenums="146" title="examples/pipe/poiseuille_flow.py" hl_lines="22" + ITERS_PER_EPOCH = int((N_x * N_y * N_p) / BATCH_SIZE) + + pde_constraint = ppsci.constraint.InteriorConstraint( + equation["NavierStokes"].equations, + {"continuity": 0, "momentum_x": 0, "momentum_y": 0}, + geom=interior_geom, + dataloader_cfg={ + "dataset": "NamedArrayDataset", + "num_workers": 1, + "batch_size": BATCH_SIZE, + "iters_per_epoch": ITERS_PER_EPOCH, + "sampler": { + "name": "BatchSampler", + "shuffle": False, + "drop_last": False, + }, + }, + loss=ppsci.loss.MSELoss("mean"), + evenly=True, + name="EQ", + ) + ITERS_PER_EPOCH = len(pde_constraint.data_loader) + + # wrap constraints together + constraint = {pde_constraint.name: pde_constraint} + + EPOCHS = 3000 if not args.epochs else args.epochs + ``` + +2. 使用分布式训练命令启动训练,以四卡为例 + + ``` sh + # 指定 0,1,2,3 张卡启动分布式训练 + export CUDA_VISIBLE_DEVICES=0,1,2,3 + python -m paddle.distributed.launch --gpus="0,1,2,3" poiseuille_flow.py + ``` + + + +### 2.2 自动混合精度训练 + +接下来介绍如何正确使用 PaddleScience 的自动混合精度精度功能。自动混合精度训练细节可以参考:[Paddle-使用指南-性能调优-自动混合精度训练(AMP)](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/performance_improving/amp_cn.html)。 + +实例化 `Solver` 时加上 2 个参数: `use_amp=True`, `amp_level="O1"`(或`amp_level="O2"`)。如代码中黄色高亮行所示,通过指定 `use_amp=True`,开启自动混合精度功能,其次通过设置 `amp_level="O1"`,指定混合精度所用的模式,`O1` 为自动混合精度,`O2` 为更激进的纯 fp16 训练模式,一般推荐使用 `O1`。 + +``` py linenums="1" hl_lines="5 6" +# initialize solver +solver = ppsci.solver.Solver( + ..., + ..., + use_amp=True, + amp_level="O1", # or amp_level="O2" +) +``` + +### 2.3 梯度累加 + +接下来介绍如何正确使用 PaddleScience 的梯度累加功能。自动混合精度训练细节可以参考:[Paddle-使用指南-性能调优-自动混合精度训练(AMP)-动态图下使用梯度累加](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/performance_improving/amp_cn.html#dongtaituxiashiyongtiduleijia)。 + +实例化 `Solver` 时加上 1 个参数: `update_freq=N_ACCUMULATE`。如代码中黄色高亮行所示,`N_ACCUMULATE` 可以是 2 或者更大的倍数,推荐使用 2、4、8,此时全局 `batch size` 等于 `update_freq * batch size`。梯度累加对于部分训练任务有一定的性能提升。 + +``` py linenums="1" hl_lines="5" +# initialize solver +solver = ppsci.solver.Solver( + ..., + ..., + update_freq=2, # or 4, 8 +) +``` diff --git a/examples/pipe/poiseuille_flow.py b/examples/pipe/poiseuille_flow.py index b2c7ed24e..f48862157 100644 --- a/examples/pipe/poiseuille_flow.py +++ b/examples/pipe/poiseuille_flow.py @@ -23,16 +23,17 @@ import matplotlib.pyplot as plt import numpy as np import paddle -import seaborn as sns -import ppsci from ppsci.utils import checker -from ppsci.utils import config -from ppsci.utils import logger if not checker.dynamic_import_to_globals("seaborn"): - raise ModuleNotFoundError(f"Please install seaborn through pip first.") + raise ModuleNotFoundError("Please install seaborn through pip first.") + +import seaborn as sns +import ppsci +from ppsci.utils import config +from ppsci.utils import logger if __name__ == "__main__": args = config.parse_args() @@ -140,6 +141,7 @@ def output_trans_p(self, out): ) } + # set constraint BATCH_SIZE = 128 ITERS_PER_EPOCH = int((N_x * N_y * N_p) / BATCH_SIZE) @@ -163,12 +165,15 @@ def output_trans_p(self, out): name="EQ", ) + # wrap constraints together + constraint = {pde_constraint.name: pde_constraint} + EPOCHS = 3000 if not args.epochs else args.epochs # initialize solver solver = ppsci.solver.Solver( model, - {pde_constraint.name: pde_constraint}, + constraint, OUTPUT_DIR, optimizer, epochs=EPOCHS, diff --git a/mkdocs.yml b/mkdocs.yml index 2a2758628..a1cc85220 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,7 @@ nav: - ppsci.utils: zh/api/utils.md - ppsci.validate: zh/api/validate.md - ppsci.visualize: zh/api/visualize.md + - 使用指南: zh/user_guide.md - 贡献指南: zh/contribute.md - 技术稿件: zh/technical_doc.md - 共创计划: zh/cooperation.md