[Doc] Update guidance of development (#965)

HydrogenSulfate · web-flow · commit 2436c5aa44c7 · 2024-08-09T16:39:14.000+08:00
* update SPINN url

* update url

* annotate latex which may occur error when latex font is not installed

* add mtl submodule to loss.__all__

* update doc

* update pre-commit guidance

* update synchronization of upstream guidance
diff --git a/README.md b/README.md
diff --git a/docs/index.md b/docs/index.md
@@ -72,7 +72,7 @@
 
 | 问题类型 | 案例名称 | 优化算法 | 模型类型 | 训练方式 | 数据集 | 参考资料 |
 |-----|---------|-----|---------|----|---------|---------|
-| 三维亥姆霍兹方程 | [SPINN(Helmholtz3D)](./zh/examples/spinn.md) | 机理驱动 | ModifiedMLP | 无监督学习 | - | [Paper](https://arxiv.org/pdf/2306.15969) |
+| 亥姆霍兹方程 | [SPINN(Helmholtz3D)](./zh/examples/spinn.md) | 机理驱动 | SPINN | 无监督学习 | - | [Paper](https://arxiv.org/pdf/2306.15969) |
 | 相场方程 | [Allen-Cahn](./zh/examples/allen_cahn.md) | 机理驱动 | MLP | 无监督学习 | [Data](https://paddle-org.bj.bcebos.com/paddlescience/datasets/AllenCahn/allen_cahn.mat) | [Paper](https://arxiv.org/pdf/2402.00326) |
 | 微分方程 | [拉普拉斯方程](./zh/examples/laplace2d.md) | 机理驱动 | MLP | 无监督学习 | -        | - |
 | 微分方程 | [伯格斯方程](./zh/examples/deephpms.md) | 机理驱动 | MLP | 无监督学习 | [Data](https://github.com/maziarraissi/DeepHPMs/tree/master/Data) | [Paper](https://arxiv.org/pdf/1801.06637.pdf) |
@@ -173,7 +173,9 @@
 
 ## 🎈其他领域支持
 
-除 PaddleScience 套件外，Paddle 框架还支持了 DeepXDE 的所有案例，分子动力学套件 DeepMD-kit 部分案例和功能，以及正在适配中的 Modulus 。
+--8<--
+./README.md:adaptation
+--8<--
 
 <div class="container">
     <a href="https://github.com/lululxvi/deepxde/tree/master?tab=readme-ov-file#deepxde">
diff --git a/docs/zh/api/arch.md b/docs/zh/api/arch.md
@@ -25,6 +25,7 @@
         - ModifiedMLP
         - NowcastNet
         - SFNONet
+        - SPINN
         - TFNO1dNet
         - TFNO2dNet
         - TFNO3dNet
diff --git a/docs/zh/api/utils/misc.md b/docs/zh/api/utils/misc.md
@@ -20,5 +20,6 @@
         - run_on_eval_mode
         - run_at_rank0
         - plot_curve
+        - check_flag_enabled
       show_root_heading: True
       heading_level: 3
diff --git a/docs/zh/development.md b/docs/zh/development.md
@@ -42,6 +42,23 @@ PaddleScience 相关的论文复现、API 开发任务开始之前需提交 RFC
 
     如果出现 PaddleScience is installed successfully.✨ 🍰 ✨，则说明安装验证成功。
 
+7. 安装 pre-commit[重要]
+
+    PaddleScience 是一个开源的代码库，由多人共同参与开发，因此为了保持最终合入的代码风格整洁、一致，
+    PaddleScience 使用了包括 [isort](https://github.com/PyCQA/isort#installing-isort)、[black](https://github.com/psf/black) 等自动化代码检查、格式化插件，
+    让 commit 的代码遵循 python [PEP8](https://pep8.org/) 代码风格规范。
+
+    因此在 commit 您的代码之前，请务必先在 `PaddleScience/` 目录下执行以下命令安装 `pre-commit`，否则提交的 PR 会被 code-style 检测到代码未格式化而无法合入。
+
+    ``` sh
+    pip install pre-commit
+    pre-commit install
+    ```
+
+    如果已经将代码进行了 commit，则可以在安装上述 pre-commit 之后，手动执行 pre-commit 命令，对代码进行格式化：`pre-commit run --files 你提交的代码文件/文件夹`，然后手动 `git add` 被修改了的文件，再 `git commit` 即可。
+
+    关于 pre-commit 的详情请参考 [Paddle 代码风格检查指南](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/git_guides/codestyle_check_guide_cn.html)
+
 ## 2. 编写代码
 
 完成上述准备工作后，就可以基于 PaddleScience 开始开发自己的案例或者功能了。
@@ -920,25 +937,22 @@ mkdocs serve
 
 ## 4. 整理代码并提交
 
-### 4.1 安装 pre-commit
+### 4.1 整理代码
+
+在完成范例编写与训练后，确认结果无误，就可以整理代码。
+使用 git 命令将所有新增、修改的代码文件以及必要的文档、图片等一并提交到本地 `dev_model` 分支上。
 
-PaddleScience 是一个开源的代码库，由多人共同参与开发，因此为了保持最终合入的代码风格整洁、一致，
-PaddleScience 使用了包括 [isort](https://github.com/PyCQA/isort#installing-isort)、[black](https://github.com/psf/black) 等自动化代码检查、格式化插件，
-让 commit 的代码遵循 python [PEP8](https://pep8.org/) 代码风格规范。
+### 4.2 同步上游代码
 
-因此在 commit 您的代码之前，请务必先在 `PaddleScience/` 目录下执行以下命令安装 `pre-commit`，否则提交的 PR 会被 code-style 检测到代码未格式化而无法合入。
+在开发过程中，上游代码可能经过更新，因此需要执行以下命令，先将上游的最新代码拉取下来，合并到当前代码中，与上游最新代码进行同步。
 
 ``` sh
-pip install pre-commit
-pre-commit install
+git remote add upstream https://github.com/PaddlePaddle/PaddleScience.git
+git fetch upstream upstream_develop
+git merge upstream_develop
 ```
 
-关于 pre-commit 的详情请参考 [Paddle 代码风格检查指南](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/dev_guides/git_guides/codestyle_check_guide_cn.html)
-
-### 4.2 整理代码
-
-在完成范例编写与训练后，确认结果无误，就可以整理代码。
-使用 git 命令将所有新增、修改的代码文件以及必要的文档、图片等一并上传到自己仓库的 `dev_model` 分支上。
+如果出现 conflict，则需要解决冲突，再使用 `git add` 和 `git commit -m "merge code of upstream"` 命令将代码提交到本地仓库，最后执行 `git push origin dev_model`，将代码推送到你的远程仓库中。
 
 ### 4.3 提交 pull request
 
diff --git a/docs/zh/examples/aneurysm.md b/docs/zh/examples/aneurysm.md
@@ -119,7 +119,7 @@ tar -xvf aneurysm_dataset.tar
 
 ???+ warning "注意"
 
-    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
+    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
 
 然后通过 PaddleScience 内置的 STL 几何类 `Mesh` 来读取、解析这些几何文件，并且通过布尔运算，组合出各个计算域，代码如下：
 
diff --git a/docs/zh/examples/bracket.md b/docs/zh/examples/bracket.md
@@ -136,7 +136,7 @@ tar -xvf bracket_dataset.tar
 
 ???+ warning "注意"
 
-    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
+    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
 
 然后通过 PaddleScience 内置的 STL 几何类 `Mesh` 来读取、解析这些几何文件，并且通过布尔运算，组合出各个计算域，代码如下：
 
diff --git a/docs/zh/examples/control_arm.md b/docs/zh/examples/control_arm.md
@@ -179,7 +179,7 @@ examples/control_arm/forward_analysis.py:36:41
 
 ???+ warning "注意"
 
-    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
+    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
 
 然后通过 PaddleScience 内置的 STL 几何类 `ppsci.geometry.Mesh` 即可读取、解析几何文件，得到计算域，并获取几何结构边界：
 
@@ -384,7 +384,7 @@ examples/control_arm/inverse_parameter.py:35:40
 
 ???+ warning "注意"
 
-    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
+    **使用 `Mesh` 类之前，必须先按照[1.4.2 额外依赖安装[可选]](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/install_setup/#142)文档，安装好 open3d、pysdf、PyMesh 3 个几何依赖包。**
 
 然后通过 PaddleScience 内置的 STL 几何类 `ppsci.geometry.Mesh` 即可读取、解析几何文件，得到计算域，并获取几何结构边界：
 
diff --git a/docs/zh/reproduction.md b/docs/zh/reproduction.md
@@ -14,7 +14,7 @@
 
 - PaddleScience
 
-    基于飞桨的 AI4S 套件，提供面向 AI4S 领域通用功能，如复杂几何形状解析、通用微分方程、数据驱动/物理机理/数理融合等求解器，方便开发 AI4S 领域相关模型，具体参考 [PaddleScience 文档](https://paddlescience-docs.readthedocs.io/zh/latest/)
+    基于飞桨的 AI4S 套件，提供面向 AI4S 领域通用功能，如复杂几何形状解析、通用微分方程、数据驱动/物理机理/数理融合等求解器，方便开发 AI4S 领域相关模型，具体参考 [PaddleScience 文档](https://paddlescience-docs.readthedocs.io/zh-cn/latest/)
 
 - 飞桨PaddlePaddle
 
@@ -194,4 +194,4 @@ PaddleScience 官网文档需满足：
 - 如果模型依赖 PaddlePaddle 未涵盖的依赖（如 pandas），则需要在文档开头对说明需安装哪些依赖项。
 - 随机控制，需要尽量固定含有随机因素模块的随机种子，保证模型可以正常复现（PaddleScience 套件提供了 `ppsci.utils.misc.set_random_seed(seed_num)` 语句来控制全局随机数）。
 - 超参数：模型内部超参数禁止写死，尽量都可以通过配置文件进行配置。
-- 文档末尾附上参考论文、参考代码网址、复现训练好的模型参数下载链接。 整体文档撰写可以参考：[文档参考样例(darcy2d)](https://paddlescience-docs.readthedocs.io/zh/latest/zh/examples/darcy2d/)。
+- 文档末尾附上参考论文、参考代码网址、复现训练好的模型参数下载链接。 整体文档撰写可以参考：[文档参考样例(darcy2d)](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/examples/darcy2d/)。
diff --git a/docs/zh/user_guide.md b/docs/zh/user_guide.md
@@ -986,7 +986,7 @@ TODO -->
 
 ### 2.5 多任务学习
 
-在机理驱动、数理融合场景中，往往会同时优化多个损失项，如控制方程残差损失、（初）边值条件损失等。在训练过程中这些损失项对参数的梯度方向可能会互相冲突，阻碍训练精度收敛，而这正是多任务学习方法能解决的问题。因此 PaddleScience 在多任务学习模块中引入了几种常见的算法，其主要通过对不同任务的权重或产生的梯度进行调整，从而缓解该问题，最终提升模型收敛精度。下面以 [`Relobralo`](https://paddlescience-docs.readthedocs.io/zh/latest/zh/api/loss/mtl/#ppsci.loss.mtl.Relobralo) 算法进行举例，使用方式如下：
+在机理驱动、数理融合场景中，往往会同时优化多个损失项，如控制方程残差损失、（初）边值条件损失等。在训练过程中这些损失项对参数的梯度方向可能会互相冲突，阻碍训练精度收敛，而这正是多任务学习方法能解决的问题。因此 PaddleScience 在多任务学习模块中引入了几种常见的算法，其主要通过对不同任务的权重或产生的梯度进行调整，从而缓解该问题，最终提升模型收敛精度。下面以 [`Relobralo`](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/api/loss/mtl/#ppsci.loss.mtl.Relobralo) 算法进行举例，使用方式如下：
 
 1. 实例化一个多任务学习方法的对象
 
diff --git a/examples/xpinn/plotting.py b/examples/xpinn/plotting.py
@@ -181,7 +181,7 @@ def log_image(
 
 PGF_WITH_LATEX = {  # setup matplotlib to use latex for output
     "pgf.texsystem": "pdflatex",  # change this if using xetex or latex
-    "text.usetex": True,  # use LaTeX to write all text
+    # "text.usetex": True,  # use LaTeX to write all text
     # "font.family": "serif",
     # "font.serif": [],  # blank entries should cause plots to inherit fonts from the document
     # "font.sans-serif": [],
diff --git a/ppsci/loss/__init__.py b/ppsci/loss/__init__.py
@@ -14,6 +14,7 @@
 
 import copy
 
+from ppsci.loss import mtl
 from ppsci.loss.base import Loss
 from ppsci.loss.chamfer import ChamferLoss
 from ppsci.loss.func import FunctionalLoss
@@ -46,6 +47,7 @@
     "MSELossWithL2Decay",
     "PeriodicMSELoss",
     "KLLoss",
+    "mtl",
 ]
 
 
