Merge branch 'develop' into add_front_image

Author: HydrogenSulfate

README.md

@@ -1,85 +1,77 @@
-*Current version of PaddleScience is v1.0 Beta.*
+# PaddleScience
 
-# Introduction
+> *Developed with [PaddlePaddle](https://www.paddlepaddle.org.cn/)*
 
-PaddleScience extends the PaddlePaddle framework with reusable
-software components for developing novel scientific computing applications. Such new
-applications include Physics-informed Machine Learning, neural network based PDE solvers,
-machine learning for CFD, and so on. PaddleScience is currently under active development.
-Its design is evolving and its APIs are subject to change.
+[![Doc](https://img.shields.io/readthedocs/paddlescience-docs/latest)](https://paddlescience-docs.readthedocs.io/zh/latest/)
+[![License](https://img.shields.io/github/license/PaddlePaddle/PaddleScience)](./LICENSE)
 
-# Core features and organization
+[**PaddleScience使用文档**](https://paddlescience-docs.readthedocs.io/zh/latest/)
 
-PaddleScience currently focuses on the PINNs model. The core components are as follows.
+## 简介
 
-- PDE, delineating partial differential equations in symbolic forms. Specific PDEs derive the
-    the base PDE class.
+PaddleScience 是一个基于深度学习框架 PaddlePaddle 开发的科学计算套件，利用深度神经网络的学习能力和 PaddlePaddle 框架的自动(高阶)微分机制，解决物理、化学、气象等领域的问题。支持物理机理驱动、数据驱动、数理融合三种求解方式，并提供了基础 API 和详尽文档供用户使用与二次开发。
 
-- Geometry, a declarative interface for defining the geometric domain. Automatic
-    discretization is supported
+<div align="center">
+    <img src="./docs/images/overview/panorama.png" width="80%" height="80%">
+</div>
 
-- Neural net, currently supporting fully connected layers with customizable size and depth.
+## 特性
 
-- Loss, defining what exact penalties are enforced during the training process. By default,
-    the L2 loss is applied. In the current design, the total loss is a weighted sum of
-    four parts, the equation loss, the boundary condition loss, the initial condition loss and the data loss.
+- 支持简单几何和复杂 STL 几何的采样与布尔运算。
+- 支持包括 Dirichlet、Neumann、Robin 以及自定义边界条件。
+- 支持物理机理驱动、数据驱动、数理融合三种问题求解方式。涵盖流体、结构、气象等领域 8+ 案例。
+- 支持结果可视化输出与日志结构化保存。
+- 完善的 type hints，用户使用和代码贡献全流程文档，经典案例 AI studio 快速体验，降低使用门槛，提高开发效率。
+- 更多特性正在开发中...
 
-- Optimizer, specifying which optimizer to use for training. Adam is the default option. More
-    optimizers, such as BFGS, will be available in the future.
+## 安装使用
 
-- Solver, managing the training process given the training data in a batchly fashion.
+1. 执行以下命令，从 github 上克隆 PaddleScience 项目，进入 PaddleScience 目录，并将该目录添加到系统环境变量中
 
-- Visualization, an easy access to the graph drawing utilities.
+    ``` shell
+    git clone https://github.com/PaddlePaddle/PaddleScience.git
+    cd PaddleScience
+    export PYTHONPATH=$PWD:$PYTHONPATH
+    ```
 
-# Getting started
+2. 安装必要的依赖包
 
-## Prerequisites
+    ``` shell
+    pip install -r requirements.txt
+    ```
 
-Hardware requirements: NVIDIA GPU V100, NVIDIA GPU A100
+3. 验证安装
 
-Package dependencies: paddle, cuda (11.0 or higher), numpy, scipy, sympy, matplotlib, vtk, pyevtk, wget.
+    ``` py
+    python -c "import ppsci; ppsci.utils.run_check()"
+    ```
 
-PaddleScience currently relies on new features of the Paddle framework so please be advised to download the latest version of Paddle on GitHub or on Gitee.
+4. 开始使用
 
-For more details on installation, please refer to the offical [PaddlePaddle repository on GitHub](https://github.com/PaddlePaddle/Paddle) or [PaddlePaddle repository on Gitee](https://gitee.com/paddlepaddle/Paddle).
+    ``` py
+    import ppsci
 
-## Download and environment setup
+    # write your code here...
+    ```
 
-``` shell
-Download from GitHub: git clone https://github.com/PaddlePaddle/PaddleScience.git
-Download from Gitee:  git clone https://gitee.com/PaddlePaddle/PaddleScience.git
+更多安装方式请参考 [**安装与使用**](https://paddlescience-docs.readthedocs.io/zh/latest/zh/install_setup/)
 
-cd PaddleScience
-export PYTHONPATH=$PWD:$PYTHONPATH
+## 快速开始
 
-pip install -r requirements.txt
-```
+参考 [**快速开始**](https://paddlescience-docs.readthedocs.io/zh/latest/zh/quickstart/)
 
-## Run examples
+## 经典案例
 
-Some examples are baked in for quick demonstration. Please find them in the `examples` directory. To run an example, just enter the subdirectory and run the demo code in Python commandline.
+请参考 [**经典案例**](https://paddlescience-docs.readthedocs.io/zh/latest/zh/examples/viv/)
 
-``` shell
-# Darcy flow (Poisson equation)
-cd examples/darcy
-python darcy2d.py
+## 支持
 
-# LDC steady (Steady Navier-Stokes eqution)
-cd examples/ldc
-python ldc2d_steady_train.py
+如使用过程中遇到问题或想提出开发建议，欢迎在 [**Issue**](https://github.com/PaddlePaddle/PaddleScience/issues/new) 页面新建 issue。
 
-# Lid Driven Cavity unsteady with continue-time method (Unsteady Navier-Stokes equation)
-cd examples/ldc
-python ldc2d_unsteady_t.py
+## 贡献代码
 
-# Flow around a circular cylinder with discrete-time method (Unsteady Navier-Stokes equation)
-cd examples/cylinder/3d_unsteady_discrete/baseline
-python cylinder3d_unsteady.py
+PaddleScience 项目欢迎并依赖开发人员和开源社区中的用户，请参阅 [**贡献指南**](https://paddlescience-docs.readthedocs.io/zh/latest/zh/contribute/)。
 
-```
+## 证书
 
-## Short tutorials on how to construct and solve a PINN model
-
-[A tutorial on Lid Driven Cavity flow](./examples/ldc/README.md)
-
-[A tutorial on Darcy flow in porous medium](./examples/darcy/README.md)
+[Apache License 2.0](https://github.com/PaddlePaddle/PaddleScience/blob/develop/LICENSE)

docs/index.md

@@ -4,6 +4,8 @@
 
 PaddleScience 是一个基于深度学习框架 PaddlePaddle 开发的科学计算套件，利用深度神经网络的学习能力和 PaddlePaddle 框架的自动(高阶)微分机制，解决物理、化学、气象等领域的问题。支持物理机理驱动、数据驱动、数理融合三种求解方式，并提供了基础 API 和详尽文档供用户使用与二次开发。
 
+![panorama](./images/overview/panorama.png)
+
 ## 特性
 
 - 支持简单几何和复杂 STL 几何的采样与布尔运算。
@@ -15,11 +17,11 @@ PaddleScience 是一个基于深度学习框架 PaddlePaddle 开发的科学计
 
 ## 支持
 
-- 如使用过程中遇到问题或想提出开发建议，欢迎在 [Issue](https://github.com/PaddlePaddle/PaddleScience/issues/new) 页面新建 issue。
+- 如使用过程中遇到问题或想提出开发建议，欢迎在 [**Issue**](https://github.com/PaddlePaddle/PaddleScience/issues/new) 页面新建 issue。
 
 ## 贡献代码
 
-PaddleScience 项目欢迎并依赖开发人员和开源社区中的用户，请参阅 [贡献指南](https://paddlescience-docs.readthedocs.io/zh/latest/zh/contribute/)。
+PaddleScience 项目欢迎并依赖开发人员和开源社区中的用户，请参阅 [**贡献指南**](https://paddlescience-docs.readthedocs.io/zh/latest/zh/contribute/)。
 
 ## 证书
 

docs/zh/examples/cylinder2d_unsteady_transformer_physx.md

@@ -110,19 +110,19 @@ $$Re \sim(100, 750)$$
 
 首先展示代码中定义的各个参数变量，每个参数的具体含义会在下面使用到时进行解释。
 
-``` py linenums="51" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="51" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:51:62
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:51:62
 --8<--
 ```
 
 #### 3.2.1 约束构建
 
 本案例基于数据驱动的方法求解问题，因此需要使用 PaddleScience 内置的 `SupervisedConstraint` 构建监督约束。在定义约束之前，需要首先指定监督约束中用于数据加载的各个参数，代码如下：
 
-``` py linenums="67" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="67" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:67:84
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:67:84
 --8<--
 ```
 
@@ -141,9 +141,9 @@ examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:67:84
 
 定义监督约束的代码如下：
 
-``` py linenums="86" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="86" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:86:94
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:86:94
 --8<--
 ```
 
@@ -166,37 +166,37 @@ examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:86:94
 
 用 PaddleScience 代码表示如下：
 
-``` py linenums="99" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="99" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:99:105
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:99:105
 --8<--
 ```
 
 其中，`CylinderEmbedding` 的前两个参数在前文中已有描述，这里不再赘述，网络模型的第三、四个参数是训练数据集的均值和方差，用于归一化输入数据。计算均值、方差的的代码表示如下：
 
-``` py linenums="28" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="28" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:28:45
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:28:45
 --8<--
 ```
 
 #### 3.2.3 学习率与优化器构建
 
 本案例中使用的学习率方法为 `ExponentialDecay`，学习率大小设置为0.001。优化器使用 `Adam`，梯度裁剪使用了 Paddle 内置的 `ClipGradByGlobalNorm` 方法。用 PaddleScience 代码表示如下：
 
-``` py linenums="107" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="107" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:107:121
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:107:121
 --8<--
 ```
 
 #### 3.2.4 评估器构建
 
 本案例训练过程中会按照一定的训练轮数间隔，使用验证集评估当前模型的训练情况，需要使用 `SupervisedValidator` 构建评估器。代码如下：
 
-``` py linenums="123" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="123" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:123:150
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:123:150
 --8<--
 ```
 
@@ -206,39 +206,39 @@ examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:123:150
 
 完成上述设置之后，只需要将上述实例化的对象按顺序传递给 `ppsci.solver.Solver`，然后启动训练、评估。
 
-``` py linenums="153" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py"
+``` py linenums="153" title="examples/cylinder/2d_unsteady/transformer_physx/train_enn.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_enn_v2.py:153:
+examples/cylinder/2d_unsteady/transformer_physx/train_enn.py:153:
 --8<--
 ```
 
 ### 3.3 Transformer 模型
 
 上文介绍了如何构建 Embedding 模型的训练、评估，在本节中将介绍如何使用训练好的 Embedding 模型训练 Transformer 模型。因为训练 Transformer 模型的步骤与训练 Embedding 模型的步骤基本相似，因此本节在两者的重复部分的各个参数不再详细介绍。首先将代码中定义的各个参数变量展示如下，每个参数的具体含义会在下面使用到时进行解释。
 
-``` py linenums="58" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="58" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:58:74
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:58:74
 --8<--
 ```
 
 #### 3.3.1 约束构建
 
 Transformer 模型同样基于数据驱动的方法求解问题，因此需要使用 PaddleScience 内置的 `SupervisedConstraint` 构建监督约束。在定义约束之前，需要首先指定监督约束中用于数据加载的各个参数，代码如下：
 
-``` py linenums="82" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="82" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:82:99
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:82:99
 --8<--
 ```
 
 数据加载的各个参数与 Embedding 模型中的基本一致，不再赘述。需要说明的是由于 Transformer 模型训练的输入数据是 Embedding 模型 Encoder 模块的输出数据，因此我们将训练好的 Embedding 模型作为 `CylinderDataset` 的一个参数，在初始化时首先将训练数据映射到编码空间。
 
 定义监督约束的代码如下：
 
-``` py linenums="101" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="101" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:101:106
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:101:106
 --8<--
 ```
 
@@ -253,9 +253,9 @@ examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:101:106
 
 用 PaddleScience 代码表示如下：
 
-``` py linenums="111" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="111" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:111:119
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:111:119
 --8<--
 ```
 
@@ -265,19 +265,19 @@ examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:111:119
 
 本案例中使用的学习率方法为 `CosineWarmRestarts`，学习率大小设置为0.001。优化器使用 `Adam`，梯度裁剪使用了 Paddle 内置的 `ClipGradByGlobalNorm` 方法。用 PaddleScience 代码表示如下：
 
-``` py linenums="121" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="121" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:121:135
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:121:135
 --8<--
 ```
 
 #### 3.3.4 评估器构建
 
 训练过程中会按照一定的训练轮数间隔，使用验证集评估当前模型的训练情况，需要使用 `SupervisedValidator` 构建评估器。用 PaddleScience 代码表示如下：
 
-``` py linenums="137" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="137" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:137:163
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:137:163
 --8<--
 ```
 
@@ -287,25 +287,25 @@ examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:137:163
 
 在本文中首先定义了对 Transformer 模型输出数据变换到物理状态空间的代码：
 
-``` py linenums="32" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="32" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:32:52
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:32:52
 --8<--
 ```
 
-``` py linenums="78" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="78" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:78:79
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:78:79
 --8<--
 ```
 
 可以看到，程序首先载入了训练好的 Embedding 模型，然后在 `OutputTransform` 的 `__call__` 函数内实现了编码向量到物理状态空间的变换。
 
 在定义好了以上代码之后，就可以实现可视化器代码的构建了：
 
-``` py linenums="165" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="165" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:165:193
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:165:193
 --8<--
 ```
 
@@ -315,23 +315,23 @@ examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:165:193
 
 完成上述设置之后，只需要将上述实例化的对象按顺序传递给 `ppsci.solver.Solver`，然后启动训练、评估。
 
-``` py linenums="193" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="193" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py:193:
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py:193:
 --8<--
 ```
 
 ## 4. 完整代码
 
-``` py linenums="1" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="1" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py
 --8<--
 ```
 
-``` py linenums="1" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py"
+``` py linenums="1" title="examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py"
 --8<--
-examples/cylinder/2d_unsteady/transformer_physx/train_transformer_v2.py
+examples/cylinder/2d_unsteady/transformer_physx/train_transformer.py
 --8<--
 ```