Merge pull request #287 from HydrogenSulfate/add_overview

Add overview & optimize home page

Author: HydrogenSulfate

docs/images/overview/constraint.jpg

@@ -1,84 +1,26 @@
-# 欢迎使用 PaddleScience
+# PaddleScience
 
-## 1. 开始安装
+> *Developed with [PaddlePaddle](https://www.paddlepaddle.org.cn/)*
 
-### 1.1 安装 PaddlePaddle
+PaddleScience 是一个基于深度学习框架 PaddlePaddle 开发的科学计算套件，利用深度神经网络的学习能力和 PaddlePaddle 框架的自动(高阶)微分机制，解决物理、化学、气象等领域的问题。支持物理机理驱动、数据驱动、数理融合三种求解方式，并提供了基础 API 和详尽文档供用户使用与二次开发。
 
-请在 [PaddlePaddle](https://www.paddlepaddle.org.cn/install/quick?docurl=/documentation/docs/zh/develop/install/pip/linux-pip.html) 官网按照您的运行环境，安装 **develop** 版的 PaddlePaddle
+## 特性
 
-### 1.2 安装 PaddleScience
+- 支持简单几何和复杂 STL 几何的采样与布尔运算。
+- 支持包括 Dirichlet、Neumann、Robin 以及自定义边界条件。
+- 支持物理机理驱动、数据驱动、数理融合三种问题求解方式。涵盖流体、结构、气象等领域 8+ 案例。
+- 支持结果可视化输出与日志结构化保存。
+- 完善的 type hints，用户使用和代码贡献全流程文档，所有经典案例 AI studio 一键运行，降低使用门槛，提高开发效率。
+- 更多特性正在开发中...
 
-从 [1.2.1 git 安装](#121-git) 和 [1.2.2 pip 安装](#122-pip) 任选一种安装方式即可
+## 支持
 
-#### 1.2.1 git 安装
+- 如使用过程中遇到问题或想提出开发建议，欢迎在 [Issue](https://github.com/PaddlePaddle/PaddleScience/issues/new) 页面新建 issue。
 
-1. 执行以下命令，从 github 上克隆 PaddleScience 项目，进入 PaddleScience 目录，并将该目录添加到系统环境变量中
+## 贡献代码
 
-    ``` shell
-    git clone https://github.com/PaddlePaddle/PaddleScience.git
-    cd PaddleScience
-    export PYTHONPATH=$PWD:$PYTHONPATH
-    ```
+PaddleScience 项目欢迎并依赖开发人员和开源社区中的用户，请参阅 [贡献指南](https://paddlescience-docs.readthedocs.io/zh/latest/zh/contribute/)。
 
-2. 安装必要的依赖包
+## 证书
 
-    ``` shell
-    pip install -r requirements.txt
-
-    # 安装较慢时可以加上-i选项，提升下载速度
-    # pip install -r requirements.txt -i https://pypi.douban.com/simple/
-    ```
-
-    ???+ Info "安装注意事项"
-
-        如需使用外部导入STL文件来构建几何，以及使用加密采样等功能，还需额外安装 [pymesh](https://pymesh.readthedocs.io/en/latest/installation.html#download-the-source)（推荐编译安装） 和 [open3d](https://github.com/isl-org/Open3D/tree/master#python-quick-start)（推荐pip安装）
-
-#### 1.2.2 pip 安装
-
-**coming soon**
-
-<div style='display: none'>
-执行以下命令进行 pip 安装
-
-``` shell
-pip install -i https://pypi.org/simple/ paddlesci
-```
-
-</div>
-
-## 2. 验证安装
-
-执行以下代码，验证安装的 PaddleScience 基础功能是否正常
-
-``` py
-import ppsci
-ppsci.utils.run_check()
-```
-
-如果出现 `PaddleScience is installed successfully.✨ 🍰 ✨`，则说明安装验证成功。
-
-## 3. 开始使用
-
-- 运行内置的案例（以 **ldc2d_unsteady_Re10.py** 为例）
-
-    ``` shell
-    cd examples/ldc/
-    python ./ldc2d_unsteady_Re10.py
-    ```
-
-- 编写自己的案例（假设案例名为demo）
-
-    推荐在 `examples/` 下新建 `demo` 文件夹，然后在 `demo` 文件夹下新建 `demo.py`，最后在 `demo.py` 文件中使用 PaddleScience 提供的 [API](./zh/api/arch.md) 编写代码
-
-    ``` py linenums="1" title="examples/demo/demo.py"
-    import ppsci
-
-    # write your code here...
-    ```
-
-    编写完毕后运行你的代码
-
-    ``` shell
-    cd examples/demo
-    python ./demo.py
-    ```
+[Apache License 2.0](https://github.com/PaddlePaddle/PaddleScience/blob/develop/LICENSE)

docs/images/overview/equation.jpg

@@ -0,0 +1,81 @@
+# 欢迎使用 PaddleScience
+
+## 1. 开始安装
+
+### 1.1 安装 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.2.1 git 安装](#121-git) 和 [1.2.2 pip 安装](#122-pip) 任选一种安装方式即可
+
+#### 1.2.1 git 安装
+
+1. 执行以下命令，从 github 上克隆 PaddleScience 项目，进入 PaddleScience 目录，并将该目录添加到系统环境变量中
+
+    ``` shell
+    git clone https://github.com/PaddlePaddle/PaddleScience.git
+    cd PaddleScience
+    export PYTHONPATH=$PWD:$PYTHONPATH
+    ```
+
+2. 安装必要的依赖包
+
+    ``` shell
+    pip install -r requirements.txt
+    ```
+
+    ???+ Info "安装注意事项"
+
+        如需使用外部导入STL文件来构建几何，以及使用加密采样等功能，还需额外安装 [pymesh](https://pymesh.readthedocs.io/en/latest/installation.html#download-the-source)（推荐编译安装） 和 [open3d](https://github.com/isl-org/Open3D/tree/master#python-quick-start)（推荐pip安装）
+
+#### 1.2.2 pip 安装
+
+coming soon
+
+<div style='display: none'>
+执行以下命令进行 pip 安装
+
+``` shell
+pip install -i https://pypi.org/simple/ paddlesci
+```
+
+</div>
+
+## 2. 验证安装
+
+执行以下代码，验证安装的 PaddleScience 基础功能是否正常
+
+``` py
+import ppsci
+ppsci.utils.run_check()
+```
+
+如果出现 `PaddleScience is installed successfully.✨ 🍰 ✨`，则说明安装验证成功。
+
+## 3. 开始使用
+
+- 运行内置的案例（以 **ldc2d_unsteady_Re10.py** 为例）
+
+    ``` shell
+    cd examples/ldc/
+    python ./ldc2d_unsteady_Re10.py
+    ```
+
+- 编写自己的案例（假设案例名为demo）
+
+    推荐在 `examples/` 下新建 `demo` 文件夹，然后在 `demo` 文件夹下新建 `demo.py`，最后在 `demo.py` 文件中使用 PaddleScience 提供的 [API](./zh/api/arch.md) 编写代码
+
+    ``` py linenums="1" title="examples/demo/demo.py"
+    import ppsci
+
+    # write your code here...
+    ```
+
+    编写完毕后运行你的代码
+
+    ``` shell
+    cd examples/demo
+    python ./demo.py
+    ```

docs/images/overview/geometry.jpg

@@ -0,0 +1,101 @@
+# PaddleScience 模块介绍
+
+PaddleScience 在代码结构上划分为 12 个模块。从一般深度学习工作流的角度来看，这 12 个模块分别负责构建输入数据、构建神经网络模型、构建损失函数、构建优化器，训练、评估、可视化等功能。从科学计算角度来看，部分模块承担了不同于 CV、NLP 任务的功能，比如用于物理机理驱动的 Equation 模块，定义方程公式和辅助高阶微分计算；用于涉及几何场景采样的 Geometry 模块，定义简单、复杂几何形状并在其内部、边界采样构造数据；Constraint 模块将不同的优化目标视为一种“约束”，使得套件能用一套训练代码统一物理机理驱动、数据驱动、数理融合三种不同的求解流程。
+
+## 1. 整体工作流
+
+<figure markdown>
+  ![workflow](./images/overview/workflow.jpg){ loading=lazy style="height:80%;width:80%"}
+</figure>
+
+上图是 PaddleScience 的 workflow 示意图（以基于几何的问题求解为例），流程描述如下
+
+1. Geometry 负责构建几何并在几何上采样，完成数据构建；
+2. 用 Model 模块接受输入，得到模型输出；
+3. 科学计算任务具有特殊性，模型输出往往并不是前向计算的终点，还需要进一步按照 Equation，计算出方程公式所需的变量；
+4. 计算损失函数，并利用框架的自动微分机制，求出所有参数的梯度；
+5. 上述的优化目标可以施加在几何的不同区域上，比如interior、boundary区域，因此上图中的 Constraint 可以有多个；
+6. 将所有 Constraint 贡献的梯度累加，并用于更新模型参数；
+7. 训练过程中如果开启了评估和可视化功能，则会按一定频率自动对当前模型进行评估和预测结果可视化；
+8. Solver 是整个套件运行的全局调度模块，负责将上述过程按用户指定的轮数和频率重复运行。
+
+## 2. 模块简介
+
+### 2.1 [Arch](./zh/api/arch.md)
+
+Arch 模块负责各种神经网络模型的组网、参数初始化、前向计算等功能，内置了多种模型供用户使用。
+
+### 2.2 [AutoDiff](./zh/api/autodiff.md)
+
+AutoDiff 模块负责计算高阶微分功能，内置基于 Paddle 自动微分机制的全局单例 `jacobian`、`hessian` 供用户使用。
+
+### 2.3 [Constraint](./zh/api/constraint.md)
+
+<figure markdown>
+  ![constraint](./images/overview/constraint.jpg){ loading=lazy style="height:50%;width:50%"}
+</figure>
+
+为了在套件中统一物理信息驱动、数据驱动、数理融合三种求解方式，我们将数据构造、输入到输出的计算过程、损失函数等必要接口在其定义完毕之后，统一记录在 Constraint 这一模块中，有了这些接口，Constraint 就能表示不同的训练目标，如：
+
+- `InteriorConstraint` 定义了在给定的几何区域内部，按照给定输入到输出的计算过程，利用损失函数优化模型参数，使得模型输出满足给定的条件；
+- `BoundaryConstraint` 定义了在给定的几何区域边界上，按照给定输入到输出的计算过程，利用损失函数优化模型参数，使得模型输出满足给定的条件；
+- `SupervisedConstraint` 定义了在给定的监督数据（相当于CV、NLP中的监督训练）上，按照给定输入到输出的计算过程，利用损失函数优化模型参数，使得模型输出满足给定的条件。
+- ...
+
+这一模块有两个主要作用，一是在代码流程上统一了物理信息驱动、数据驱动两个不同的优化范式（前者类似监督训练方式，后者类似无监督训练方式），二是使得套件能应用在数理融合的场景中，只需分别构造不同的 Constraint 并让它们共同参与训练即可。
+
+### 2.4 Data
+
+Data 模块负责数据的读取、包装和预处理，由以下 3 个子模块分别负责。
+
+#### 2.4.1 [Dataset](./zh/api/data/dataset.md)
+
+Dataset 模块存放各种数据集的包装类，将数据包装成统一的结构再用于读取。
+
+#### 2.4.2 [Transform](./zh/api/data/process/transform.md)
+
+Transform 模块存放各种基于单样本的数据预处理方法，包括数据平移 `Translate` 和数据缩放 `Scale`，一般与 `data.dataset` 结合使用。
+
+#### 2.4.3 [BatchTransform](./zh/api/data/process/batch_transform.md)
+
+BatchTransform 模块存放各种基于批样本的数据预处理方法。
+
+### 2.5 [Equation](./zh/api/equation.md)
+
+<figure markdown>
+  ![equation](./images/overview/equation.jpg){ loading=lazy style="height:80%;width:80%" align="center" }
+</figure>
+
+Equation 模块负责定义各种常见方程的计算函数，如 `NavierStokes` 表示 N-S 方程，`Vibration` 表示振动方程，每个方程内部含有相关变量的计算函数。
+
+### 2.6 [Geometry](./zh/api/geometry.md)
+
+<figure markdown>
+  ![geometry](./images/overview/geometry.jpg#center){ loading=lazy style="height:50%;width:50%" }
+</figure>
+
+Geometry 模块负责定义各种常见的几何形状，如 `Interval` 线段几何、`Rectangle` 矩形几何、`Sphere` 球面几何。
+
+### 2.7 [Loss](./zh/api/loss.md)
+
+Loss 模块负责定义各种损失函数，在模型前向与方程计算完毕后，将结果与参考值计算损失值，供后续的梯度优化算法使用。
+
+### 2.8 [Optimizer](./zh/api/optimizer.md)
+
+Optimizer 模块负责定义各种优化器，如 `SGD`、`Adam`、`LBFGS`。
+
+### 2.9 [Solver](./zh/api/solver.md)
+
+Solver 模块负责定义求解器，作为训练、评估、推理、可视化的启动和管理引擎。
+
+### 2.10 [Utils](./zh/api/utils.md)
+
+Utils 模块内部存放了一些适用于多种场景下的工具类、函数，如在 `reader.py` 下的数据读取函数，在 `logger.py` 下的日志打印函数，以及在 `expression.py` 下的方程计算类。
+
+### 2.11 [Validate](./zh/api/validate.md)
+
+Validator 模块负责定义各种评估器，用于模型训练完一个 epoch 后自动在指定数据上进行评估（可选，默认不开启训练时评估）并得到评估指标。
+
+### 2.12 [Visualize](./zh/api/visualize.md)
+
+Visualizer 模块负责定义各种可视化器，用于模型评估完后在指定数据上进行预测（可选，默认不开启训练时可视化）并将结果保存成可视化的文件。

docs/images/overview/workflow.jpg

@@ -28,7 +28,10 @@ copyright: Copyright © 2022 - 2023 PaddlePaddle
 
 # Page tree
 nav:
-  - 安装使用: index.md
+  - PaddleScience:
+      - 主页: index.md
+      - 功能介绍: overview.md
+      - 安装使用: install_setup.md
   - 经典案例:
       - PINNs:
         - ViV: zh/examples/viv.md
@@ -81,6 +84,7 @@ theme:
     - navigation.sections
     - navigation.prune
     - navigation.top
+    - search.suggest
     - navigation.instant
     - navigation.expand
     - content.code.copy
@@ -121,7 +125,7 @@ markdown_extensions:
   - pymdownx.arithmatex:
       generic: true
   - toc:
-      permalink: ⚓︎
+      permalink: true
   - pymdownx.inlinehilite
   - pymdownx.superfences
   - admonition
@@ -139,7 +143,6 @@ extra_javascript:
 # Extra css
 extra_css:
   - stylesheets/extra.css
-  - stylesheets/monokai.css
 
 # Extra
 extra:

docs/index.md

@@ -24,11 +24,11 @@
 from ppsci.utils import profiler
 
 
-def eval_func(solver, epoch_id, log_freq) -> float:
+def eval_func(solver, epoch_id: int, log_freq: int) -> float:
     """Evaluation program
 
     Args:
-        solver (Solver): Main Solver.
+        solver (solver.Solver): Main Solver.
         epoch_id (int): Epoch id.
         log_freq (int): Log evaluation information every `log_freq` steps.
 

docs/install_setup.md

@@ -392,7 +392,7 @@ def train(self):
         if self.vdl_writer is not None:
             self.vdl_writer.close()
 
-    def eval(self, epoch_id=0):
+    def eval(self, epoch_id: int = 0):
         """Evaluation"""
         train_state = self.model.training
         if train_state:
@@ -412,7 +412,7 @@ def eval(self, epoch_id=0):
             self.model.train()
         return result
 
-    def visualize(self, epoch_id=0):
+    def visualize(self, epoch_id: int = 0):
         """Visualization"""
         train_state = self.model.training
         if train_state:
@@ -461,7 +461,9 @@ def predict(
             # prepare batch input dict
             for key in input_dict:
                 if not paddle.is_tensor(input_dict[key]):
-                    batch_input_dict[key] = paddle.to_tensor(input_dict[key][st:ed])
+                    batch_input_dict[key] = paddle.to_tensor(
+                        input_dict[key][st:ed], paddle.get_default_dtype()
+                    )
                 else:
                     batch_input_dict[key] = input_dict[key][st:ed]
                 batch_input_dict[key].stop_gradient = False