[Doc] Refine documents and fix typo (PaddlePaddle#750)

* refine documents and remove redundant blankline toml

* refine more documents

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
       - id: black
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: 'v0.0.272'
+    rev: "v0.0.272"
     hooks:
       - id: ruff
 

docs/zh/api/utils/logger.md

@@ -11,6 +11,6 @@
         - debug
         - warning
         - error
-        - scaler
+        - scalar
       show_root_heading: True
       heading_level: 3

docs/zh/development.md

@@ -646,13 +646,19 @@ pip install -r docs/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
 
 PaddleScience 文档基于 [Mkdocs-Material](https://squidfunk.github.io/mkdocs-material/)、[PyMdown](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/) 等插件进行编写，其在 Markdown 语法基础上支持了多种扩展性功能，能极大地提升文档的美观程度和阅读体验。建议参考超链接内的文档内容，选择合适的功能辅助文档撰写。
 
-### 3.3 预览文档
+### 3.3 使用 markdownlint 格式化文档[可选]
+
+如果您使用的开发环境为 VSCode，则推荐安装 [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) 扩展。安装完毕后在编写完的文档内：点击右键-->格式化文档即可。
+
+### 3.4 预览文档
 
 在 `PaddleScience/` 目录下执行以下命令，等待构建完成后，点击显示的链接进入本地网页预览文档内容。
 
 ``` shell
 mkdocs serve
+```
 
+``` log
 # ====== 终端打印信息如下 ======
 # INFO     -  Building documentation...
 # INFO     -  Cleaning site directory

docs/zh/examples/cfdgcn.md

@@ -8,7 +8,7 @@
     # only linux
     wget -nc https://paddle-org.bj.bcebos.com/paddlescience/datasets/CFDGCN/data.zip
     unzip data.zip
-    wget https://paddle-org.bj.bcebos.com/paddlescience/datasets/CFDGCN/meshes.tar
+    wget -nc https://paddle-org.bj.bcebos.com/paddlescience/datasets/CFDGCN/meshes.tar
     tar -xvf meshes.tar
     wget -nc https://paddle-org.bj.bcebos.com/paddlescience/datasets/CFDGCN/SU2Bin.tgz
     tar -zxvf SU2Bin.tgz
@@ -64,7 +64,7 @@
 ``` shell
 wget -nc https://paddle-org.bj.bcebos.com/paddlescience/datasets/CFDGCN/data.zip
 unzip data.zip
-wget https://paddle-org.bj.bcebos.com/paddlescience/datasets/CFDGCN/meshes.tar
+wget -nc https://paddle-org.bj.bcebos.com/paddlescience/datasets/CFDGCN/meshes.tar
 tar -xvf meshes.tar
 ```
 
@@ -178,7 +178,7 @@ examples/cfdgcn/cfdgcn.py:126:140
 --8<--
 ```
 
-### 3.8 结果可视化
+### 3.9 结果可视化
 
 训练完毕之后程序会对测试集中的数据进行预测，并以图片的形式对结果进行可视化，如下所示。
 

docs/zh/examples/labelfree_DNN_surrogate.md

@@ -3,13 +3,15 @@
 === "模型训练命令"
 
     案例一：Pipe Flow
+
     ``` sh
     python poiseuille_flow.py
     ```
 
     案例二：Aneurysm Flow
+
     ``` sh
-    wget https://paddle-org.bj.bcebos.com/paddlescience/datasets/LabelFree-DNN-Surrogate/LabelFree-DNN-Surrogate_data.zip
+    wget -nc https://paddle-org.bj.bcebos.com/paddlescience/datasets/LabelFree-DNN-Surrogate/LabelFree-DNN-Surrogate_data.zip
     unzip LabelFree-DNN-Surrogate_data.zip
 
     python aneurysm_flow.py
@@ -18,13 +20,15 @@
 === "模型评估命令"
 
     案例一：Pipe Flow
+
     ``` sh
     python poiseuille_flow.py mode=eval EVAL.pretrained_model_path=https://paddle-org.bj.bcebos.com/paddlescience/models/poiseuille_flow/poiseuille_flow_pretrained.pdparams
     ```
 
     案例二：Aneurysm Flow
+
     ``` sh
-    wget https://paddle-org.bj.bcebos.com/paddlescience/datasets/LabelFree-DNN-Surrogate/LabelFree-DNN-Surrogate_data.zip
+    wget -nc https://paddle-org.bj.bcebos.com/paddlescience/datasets/LabelFree-DNN-Surrogate/LabelFree-DNN-Surrogate_data.zip
     unzip LabelFree-DNN-Surrogate_data.zip
 
     python aneurysm_flow.py mode=eval EVAL.pretrained_model_path=https://paddle-org.bj.bcebos.com/paddlescience/models/LabelFree-DNN-Surrogate/aneurysm_flow.pdparams
@@ -114,15 +118,9 @@ $$
 
 上式中 $f_1, f_2, f_3$ 即为 MLP 模型本身，$transform_{input}, transform_{output}$, 表示施加额外的结构化自定义层，用于施加约束和丰富输入，用 PaddleScience 代码表示如下:
 
-``` py linenums="78"
---8<--
-examples/pipe/poiseuille_flow.py:78:80
---8<--
-```
-
-``` py linenums="105"
+``` py linenums="71"
 --8<--
-examples/pipe/poiseuille_flow.py:105:111
+examples/pipe/poiseuille_flow.py:71:105
 --8<--
 ```
 
@@ -134,9 +132,9 @@ examples/pipe/poiseuille_flow.py:105:111
 
 由于本案例使用的是 Navier-Stokes 方程的2维稳态形式，因此可以直接使用 PaddleScience 内置的 `NavierStokes`。
 
-``` py linenums="117"
+``` py linenums="110"
 --8<--
-examples/pipe/poiseuille_flow.py:117:121
+examples/pipe/poiseuille_flow.py:110:115
 --8<--
 ```
 
@@ -146,9 +144,9 @@ examples/pipe/poiseuille_flow.py:117:121
 
 本文中本案例的计算域和参数自变量 $\nu$ 由`numpy`随机数生成的点云构成，因此可以直接使用 PaddleScience 内置的点云几何 `PointCloud` 组合成空间的 `Geometry` 计算域。
 
-``` py linenums="52"
+``` py linenums="45"
 --8<--
-examples/pipe/poiseuille_flow.py:52:75
+examples/pipe/poiseuille_flow.py:45:69
 --8<--
 ```
 
@@ -210,9 +208,9 @@ examples/pipe/poiseuille_flow.py:52:75
 
     以作用在流体域内部点上的 `InteriorConstraint` 为例，代码如下：
 
-    ``` py linenums="128"
+    ``` py linenums="122"
     --8<--
-    examples/pipe/poiseuille_flow.py:128:146
+    examples/pipe/poiseuille_flow.py:122:142
     --8<--
     ```
 
@@ -236,19 +234,19 @@ examples/pipe/poiseuille_flow.py:52:75
 
 训练过程会调用优化器来更新模型参数，此处选择较为常用的 `Adam` 优化器。
 
-``` py linenums="127"
+``` py linenums="107"
 --8<--
-examples/pipe/poiseuille_flow.py:114:114
+examples/pipe/poiseuille_flow.py:107:108
 --8<--
 ```
 
 #### 2.2.7 模型训练、评估与可视化
 
 完成上述设置之后，只需要将上述实例化的对象按顺序传递给 `ppsci.solver.Solver`，然后启动训练。
 
-``` py linenums="152"
+``` py linenums="144"
 --8<--
-examples/pipe/poiseuille_flow.py:152:164
+examples/pipe/poiseuille_flow.py:144:156
 --8<--
 ```
 
@@ -258,9 +256,9 @@ examples/pipe/poiseuille_flow.py:152:164
 
 2. 当我们选取截断高斯分布的动力粘性系数 ${\nu}$ 采样(均值为 $\hat{\nu} = 10^{−3}$， 方差 $\sigma_{\nu}​=2.67 \times 10^{−4}$)，中心处速度的概率密度函数和解析解对比
 
-``` py linenums="166"
+``` py linenums="159"
 --8<--
-examples/pipe/poiseuille_flow.py:166:274
+examples/pipe/poiseuille_flow.py:159:261
 --8<--
 ```
 
@@ -301,7 +299,7 @@ $$
 
 本文主要研究了两种类型的典型血管流（具有标准化的血管几何形状），狭窄流和动脉瘤流。
 狭窄血流是指流过血管的血流，其中血管壁变窄和再扩张。 血管的这种局部限制与许多心血管疾病有关，例如动脉硬化、中风和心脏病发作 。
-动脉瘤内的血管血流，即由于血管壁薄弱导致的动脉扩张，称为动脉瘤血流。 动脉瘤破裂可能导致危及生命的情况，例如，由于脑动脉瘤破裂引起的蛛网膜下腔出血 (SAH），而血液动力学的研究可以提高诊断和对动脉瘤进展和破裂的基本了解 。
+动脉瘤内的血管血流，即由于血管壁薄弱导致的动脉扩张，称为动脉瘤血流。 动脉瘤破裂可能导致危及生命的情况，例如，由于脑动脉瘤破裂引起的蛛网膜下腔出血 (SAH)，而血液动力学的研究可以提高诊断和对动脉瘤进展和破裂的基本了解 。
 
 虽然现实的血管几何形状通常是不规则和复杂的，包括曲率、分叉和连接点，但这里研究理想化的狭窄和动脉瘤模型以进行概念验证。 即，狭窄血管和动脉瘤血管都被理想化为具有不同横截面半径的轴对称管，其由以下函数参数化，
 

docs/zh/examples/topopt.md

@@ -315,7 +315,7 @@ examples/topopt/topoptmodel.py
 | Poisson30 | 0.8617 | 0.9221 | 0.9488 | 0.9670 | 0.9662 | 0.9769 | 0.9773 | 0.9786 | 0.9803 | 0.9833 | 0.9850 | 0.9853 | 0.9855 | 0.9860 | 0.9875 | 0.9873 |
 | Uniform | 0.8887 | 0.9367 | 0.9452 | 0.9468 | 0.9644 | 0.9655 | 0.9659 | 0.9695 | 0.9717 | 0.9787 | 0.9787 | 0.9816 | 0.9784 | 0.9835 | 0.9831 | 0.9845 |
 
-## 参考文献
+## 6. 参考文献
 
 - [Sosnovik I, & Oseledets I. Neural networks for topology optimization](https://arxiv.org/pdf/1709.09578)
 

docs/zh/install_setup.md

@@ -33,25 +33,47 @@
 
 ### 1.4 安装 PaddleScience
 
-从 [1.4.1 git 源码安装](#141-git) 和 [1.4.2 pip 安装](#142-pip) 任选一种安装方式即可。
+#### 1.4.1 安装基础功能
 
-#### 1.4.1 git 源码安装[**推荐**]
+从以下三种安装方式中**任选一种**。
 
-执行以下命令，从 github 上 clone PaddleScience 源代码，并以 editable 的方式安装 PaddleScience。
+=== "git 源码安装[**推荐**]"
 
---8<--
-./README.md:git_install
---8<--
+    执行以下命令，从 github 上 clone PaddleScience 源代码，并以 editable 的方式安装 PaddleScience。
+
+    --8<--
+    ./README.md:git_install
+    --8<--
+
+=== "pip 安装"
+
+    执行以下命令以 pip 的方式安装最新版本的 PaddleScience。
+
+    ``` shell
+    pip install -U paddlesci
+    ```
+
+=== "设置 PYTHONPATH"
+
+    如果在您的环境中，上述两种方式都无法正常安装，则可以选择本方式，在终端内将环境变量 `PYTHONPATH` 临时设置为 `PaddleScience` 的**绝对路径**，如下所示。
+
+    === "Linux"
+
+        ``` sh
+        cd PaddleScience/
+        export PYTHONPATH=$PYTHONPATH:$PWD
+        ```
 
-#### 1.4.2 pip 安装
+    === "Windows"
 
-执行以下命令以 pip 的方式安装 PaddleScience。
+        ``` sh
+        cd PaddleScience/
+        set PYTHONPATH=%cd%
+        ```
 
-``` shell
-pip install paddlesci
-```
+    上述方式的优点是步骤简单无需安装，缺点是当环境变量生效的终端被关闭后，需要重新执行上述命令设置 `PYTHONPATH` 才能再次使用 PaddleScience，较为繁琐。
 
-#### 1.4.3 额外依赖安装[可选]
+#### 1.4.2 安装额外功能[可选]
 
 如需使用 `.obj`, `.ply`, `.off`, `.stl`, `.mesh`, `.node`, `.poly` and `.msh` 等复杂几何文件构建几何（计算域），以及使用加密采样等功能，则需按照下方给出的命令，安装 open3d、
 pybind11、pysdf、PyMesh 四个依赖库。
@@ -145,7 +167,7 @@ pybind11、pysdf、PyMesh 四个依赖库。
 
     如果出现 `PaddleScience is installed successfully.✨ 🍰 ✨`，则说明安装验证成功。
 
-- [可选]如果已按照 [1.4.3 额外依赖安装](#143) 正确安装了 4 个额外依赖库，则可以执行以下代码，
+- [可选]如果已按照 [1.4.2 安装额外依赖](#142) 正确安装了 4 个额外依赖库，则可以执行以下代码，
     验证 PaddleScience 的 `ppsci.geometry.Mesh` 模块是否能正常运行。
 
     ``` shell

docs/zh/user_guide.md

@@ -80,6 +80,20 @@ TRAIN:
 
     这种方式通过命令行参数临时重载运行配置，而不会对 `bracket.yaml` 文件本身进行修改，能灵活地控制运行时的配置，保证不同实验之间互不干扰。
 
+!!! warning
+
+    以命令行方式设置参数时，若参数值中含有属于 [**omegaconf escaping characters**](https://omegaconf.readthedocs.io/en/2.3_branch/grammar.html#escaping-in-unquoted-strings) 的转义字符(`\\`, `[`, `]`, `{`, `}`, `(`, `)`, `:`, `=`, `\`)，则推荐使用 `{++\'++}` 将参数值包围起来，保证内部的字符不被转义，否则可能在 hydra 解析参数时引起报错，或以不正确的方式运行程序，假设我们在运行时需要指定 `PATH` 为 `/workspace/lr=0.1,s=[3]/best_model.pdparams`，该路径含有转义字符 `[`, `]` 和 `=`，因此则可以按照如下方式撰写参数。
+
+    ``` sh
+    # 正确的参数指定方式如下
+    python example.py PATH={++\'++}/workspace/lr=0.1,s=[3]/best_model.pdparams{++\'++}
+
+    # 错误的参数指定方式如下
+    # python example.py PATH=/workspace/lr=0.1,s=[3]/best_model.pdparams
+    # python example.py PATH='/workspace/lr=0.1,s=[3]/best_model.pdparams'
+    # python example.py PATH="/workspace/lr=0.1,s=[3]/best_model.pdparams"
+    ```
+
 #### 1.1.3 自动化运行实验
 
 如 [1.1.2 命令行方式配置参数](#112) 所述，可以通过在程序执行命令的末尾加上合适的参数来控制多组实验的运行配置，接下来以自动化执行四组实验为例，介绍如何利用 hydra 的 [multirun](https://hydra.cc/docs/1.0/tutorials/basic/running_your_app/multi-run/#internaldocs-banner) 功能，实现该目的。
@@ -165,7 +179,7 @@ PaddleScience/examples/bracket/outputs_bracket/
 
 ### 1.2 模型推理预测
 
-若需使用训练完毕保存或下载得到的模型文件 `*.pdprams` 直接进行推理（预测），可以参考以下代码示例。
+若需使用训练完毕保存或下载得到的模型文件 `*.pdparams` 直接进行推理（预测），可以参考以下代码示例。
 
 1. 加载 `*.pdparams` 文件内的参数到模型中
 

examples/pipe/conf/poiseuille_flow.yaml

@@ -14,6 +14,9 @@ hydra:
           - mode
           - output_dir
           - log_freq
+  callbacks:
+    init_callback:
+      _target_: ppsci.utils.callbacks.InitCallback
   sweep:
     # output directory for multirun
     dir: ${hydra.run.dir}

examples/pipe/poiseuille_flow.py

@@ -28,7 +28,6 @@
 
 import ppsci
 from ppsci.utils import checker
-from ppsci.utils import logger
 
 if not checker.dynamic_import_to_globals("seaborn"):
     raise ModuleNotFoundError("Please install seaborn through pip first.")
@@ -37,11 +36,6 @@
 
 
 def train(cfg: DictConfig):
-    # set random seed for reproducibility
-    ppsci.utils.misc.set_random_seed(cfg.seed)
-    # initialize logger
-    logger.init_logger("ppsci", osp.join(cfg.output_dir, f"{cfg.mode}.log"), "info")
-
     X_OUT = cfg.X_IN + cfg.L
     Y_START = -cfg.R
     Y_END = Y_START + 2 * cfg.R
@@ -144,7 +138,6 @@ def output_trans_p(input, out):
         evenly=True,
         name="EQ",
     )
-
     # wrap constraints together
     constraint = {pde_constraint.name: pde_constraint}
 
@@ -160,7 +153,6 @@ def output_trans_p(input, out):
         save_freq=cfg.TRAIN.save_freq,
         equation=equation,
     )
-
     solver.train()
 
 
@@ -235,11 +227,6 @@ def output_trans_p(self, input, out):
     model_p.register_output_transform(transform.output_trans_p)
     model = ppsci.arch.ModelList((model_u, model_v, model_p))
 
-    # set euqation
-    equation = {
-        "NavierStokes": ppsci.equation.NavierStokes(nu="nu", rho=RHO, dim=2, time=False)
-    }
-
     # Validator vel
     input_dict = {
         "x": data_2d_xy[:, 0:1],
@@ -349,18 +336,17 @@ def forward(self, output_dict, label_dict):
     solver = ppsci.solver.Solver(
         model,
         output_dir=cfg.output_dir,
-        equation=equation,
         validator=validator,
         pretrained_model_path=cfg.EVAL.pretrained_model_path,
         eval_with_no_grad=cfg.EVAL.eval_with_no_grad,
     )
     solver.eval()
 
-    output_dict = solver.predict(input_dict)
-    u_pred = output_dict["u"].numpy().reshape(N_y, N_x, N_p)
+    output_dict = solver.predict(input_dict, return_numpy=True)
+    u_pred = output_dict["u"].reshape(N_y, N_x, N_p)
     fontsize = 16
     idx_X = int(round(N_x / 2))  # pipe velocity section at L/2
-    nu_index = [3, 6, 9, 12, 14, 20, 49]  # pick 4 nu samples
+    nu_index = [3, 6, 9, 12, 14, 20, 49]  # pick 7 nu samples
     ytext = [0.55, 0.5, 0.4, 0.28, 0.1, 0.05, 0.001]  # text y position
 
     # Plot
@@ -409,8 +395,8 @@ def forward(self, output_dict, label_dict):
         "y": data_2d_xy_test[:, 1:2],
         "nu": data_2d_xy_test[:, 2:3],
     }
-    output_dict_test = solver.predict(input_dict_test)
-    u_max_pred = output_dict_test["u"].numpy()
+    output_dict_test = solver.predict(input_dict_test, return_numpy=True)
+    u_max_pred = output_dict_test["u"]
 
     # Analytical result, y = 0
     u_max_a = (R**2) * dP / (2 * L * data_1d_nu_distribution * RHO)