Merge pull request #49 from Asthestarsfalll/develop

为PaddleScience添加中文文档

docs/source/examples/darcy.rst

@@ -158,6 +158,6 @@ the graphs in vtp file which one can play using `Paraview <https://www.paraview.
 
     .. code-block::
 
-        rslt = solution(geo).numpy()
+        rslt = solution(geo)
         psci.visu.save_vtk(geo, rslt, 'rslt_darcy_2d')
         np.save(rslt, 'rslt_darcy_2d.npy')

docs/source/examples/ldc2d.rst

@@ -152,7 +152,6 @@ the graphs in vtp file which one can play using `Paraview <https://www.paraview.
 
     .. code-block::
     
-        rslt = solution(geo).numpy()
         rslt = solution(geo)
         u = rslt[:, 0]
         v = rslt[:, 1]

docs/source_cn/api/algorithm.rst

@@ -0,0 +1,22 @@
+算法
+=========
+
+.. automodule:: paddlescience.algorithm.algorithm_pinns
+
+.. py:class:: PINNs(net,loss)
+
+
+    内嵌物理知识神经网络算法
+
+        **参数:** 
+
+            - **net** (*NetworkBase*) - 在PINNs算法中使用的神经网络
+            - **loss** (*LossBase*) - 在PINNs算法中使用的损失函数
+
+
+    **样例**
+
+    .. code-block::
+
+        import paddlescience as psci
+        algo = psci.algorithm.PINNs(net=net, loss=loss)

docs/source_cn/api/discretize.rst

@@ -0,0 +1,19 @@
+离散化
+===================================
+
+.. autofunction:: paddlescience.discretize
+    :no-undoc-member:
+.. py:class:: discretize(pde, geo, time_nsteps=None, space_nsteps=None)
+
+
+    离散化PDE和Geometry
+
+        **参数:**
+
+            - **pde** (PDE) - 偏微分方程。
+            - **geo** (Geometry) - 需要离散化的Geometry或其子类实例。
+
+        **返回:**
+
+            - **pde_disc** (PDE) - 保留参数。
+            - **geo_disc** (DiscreteGeometry) - DiscreteGeometry的实例

docs/source_cn/api/geometry.rst

@@ -0,0 +1,42 @@
+几何图形
+===================================
+
+.. automodule:: paddlescience.geometry.rectangular
+
+.. py:class:: Rectangular(space_origin=None, space_extent=None)
+
+   二维矩形
+
+      **参数:**
+
+      - **space_origin** - 矩形左下角的坐标。
+      - **space_extent** - 矩形右上角的坐标。
+
+   **样例**
+
+      .. code-block:: python
+
+         import paddlescience as psci
+         geo = psci.geometry.Rectangular(space_origin=(0.0,0.0), space_extent=(1.0,1.0))
+
+.. automodule:: paddlescience.geometry.geometry_discrete
+
+.. py:class:: GeometryDiscrete()
+
+   离散几何
+
+   .. py:function:: get_bc_index()
+   
+      获得边界索引
+
+         **返回:** bc-index - 返回边界上点的索引。
+
+         **返回类型:** numpy数组。
+
+   .. py:function:: get_space_domain()
+
+      获取空间域上的坐标
+
+         **返回:** space_domain - 返回空间上的坐标
+
+         **返回类型:** numpy数组。

docs/source_cn/api/loss.rst

@@ -0,0 +1,27 @@
+损失函数
+===================================
+
+.. automodule:: paddlescience.loss.loss_L2
+
+.. py:class:: L2(pdes, geo, aux_func=None, eq_weight=None, bc_weight=None, synthesis_method='add', run_in_batch=True)
+
+   L2 loss由三个部分组成：方程损失，边界条件损失以及初始条件损失。
+
+      **参数:**
+
+         - **pdes** (*PDE*) – 用于计算方程损失的偏微分方程。
+         - **geo** (`GeometryDiscrete <https://paddlescience.paddlepaddle.org.cn/api/geometry.html#paddlescience.geometry.geometry_discrete.GeometryDiscrete>`_) – 计算损失的离散几何。
+         - **aux_func** (*Callable|None*) – 可选，默认为None。如果被指定，它应该是一个返回包含Paddle Tensors的列表的函数。该列表被用作方程右边的值去计算损失。
+         - **eq_weight** (*float|None*) – 可选，默认为None。如果被指定，与方程损失(the equation loss)相乘后再合成总loss。
+         - **bc_weight** (*numpy.array|None*) –可选，默认为None。如果被指定，它应该是一个一维的numpy数组(array)，其元素数量与边界条件点相同。 其作为权重去计算边界条件损失。
+         - **synthesis_method** (*string*) – 可选, 默认为'add'。在合成损失的三个部分时所使用的方法。如果是'add'，则直接将三部分相加；如果是'norm'，则通过计算2-norm计算最终损失。
+         - **run_in_batch** (*bool*) – 可选, 默认为True。如果是True，在每一个batch上计算方程损失。如果是False，则在每一个点上计算方程损失。
+
+   **样例**
+
+   .. code-block::
+
+      import paddlescience as psci
+      net = psci.loss.L2(pdes=pdes, geo=geo)
+
+

docs/source_cn/api/network.rst

@@ -0,0 +1,26 @@
+神经网络
+===================================
+
+.. automodule:: paddlescience.network.network_fc
+
+.. py:class:: FCNet(num_ins, num_outs, num_layers, hidden_size, dtype='float32', activation='tanh')
+
+
+   一个多层的全连接网络。除了最后一层，每层都包含矩阵乘法、矩阵逐元素加法和激活函数的操作。
+
+      **参数:**
+
+         - **num_ins** (int) - 网络输入的维度。
+         - **num_outs** (int) - 网络输出的维度。
+         - **num_layer** (int) - 网络的隐藏层数量。
+         - **hidden_size** (int) - 网络隐藏层的神经元数量。
+         - **dtype** (string) - 可选项，默认'float32'。网络权重和偏置的数据类型，目前只支持'float32'。
+         - **activation** (string) - 可选项，默认'tanh'。网络每层激活函数的类型，可以是'tanh'或者'sigmoid'。
+
+   **样例**
+
+   .. code-block:: python
+
+      import paddlescience as psci
+      net = psci.network.FCNet(2, 3, 10, 50, dtype='float32', activiation='tanh')
+

docs/source_cn/api/optimizer.rst

@@ -0,0 +1,38 @@
+优化器
+=========
+
+.. automodule:: paddlescience.optimizer.optimizer
+
+.. py:class:: Adam(**kargs)
+
+
+   Adam优化器出自 `Adam论文 <https://arxiv.org/abs/1412.6980>`_ 的第二节，能够利用梯度的一阶矩估计和二阶矩估计动态调整每个参数的学习率。
+
+      **参数:**
+
+         - **learning_rate** (*float|LRScheduler, optional*) - 用于更新的学习率，它可以是一个数据类型为float的值，也可以是LRScheduler的子类实例。默认值为0.001.
+         - **beta1** (*float|Tensor,* *可选*) - 一阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Tensor类型。默认值为0.9.
+         - **beta2** (*float|Tensor,* *可选*) - 二阶矩估计的指数衰减率，是一个float类型或者一个shape为[1]，数据类型为float32的Tensor类型。默认值为0.999.
+         - **epsilon** (*float|Tensor,* *可选*) - 保持数值稳定性的短浮点类型值，默认值为1e-08
+         - **parameters** (*list|tuple,* *可选*) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为None，这时所有的参数都将被优化。
+         - **weight_decay** (*float|WeightDecayRegularizer,* *可选*) - 正则化方法。可以是float类型的L2正则化系数或者正则化策略: paddle.regularizer.L1Decay, paddle.regularizer.L2Decay 。如果一个参数已经在 ParamAttr 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 ParamAttr 中设置正则化，这里的设置才会生效。默认值为None，表示没有正则化。
+         - **grad_clip** (*GradientClipBase,* *可选*) - 梯度裁剪的策略，支持三种裁剪策略：
+
+            - `paddle.nn.ClipGradByGlobalNorm <https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/ClipGradByGlobalNorm_cn.html#cn-api-fluid-clip-clipgradbyglobalnorm>`_ 
+            - `paddle.nn.ClipGradByNorm <https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/ClipGradByNorm_cn.html#cn-api-fluid-clip-clipgradbynorm>`_ 
+            - `paddle.nn.ClipGradByValue <https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/ClipGradByValue_cn.html#cn-api-fluid-clip-clipgradbyvalue>`_
+            默认值为None，此时将不进行梯度裁剪。
+
+         - **lazy_mode** (*bool,* *可选*) - 设为True时，仅更新当前具有梯度的元素。官方Adam算法有两个移动平均累加器（moving-average accumulators）。累加器在每一步都会更新。在密集模式和稀疏模式下，两条移动平均线的每个元素都会更新。如果参数非常大，那么更新可能很慢。 lazy mode仅更新当前具有梯度的元素，所以它会更快。但是这种模式与原始的算法有不同的描述，可能会导致不同的结果，默认为False
+         - **multi_precision** (*bool,可选*) - 权重更新时是否使用多精度，默认为False.
+         - **name** (*str*, *可选*) - 通常情况下，用户不需要考虑这个参数。具体用法请参见 `Name <https://www.paddlepaddle.org.cn/documentation/docs/zh/api_guides/low_level/program.html#api-guide-name>`_。默认为None.
+
+
+
+
+   **样例**
+
+   .. code-block::
+
+      import paddlescience as psci
+      opt = psci.optimizer.Adam(learning_rate=0.1, parameters=linear.parameters())

docs/source_cn/api/pde.rst

@@ -0,0 +1,64 @@
+PDE (偏微分方程)
+===================================
+
+.. automodule:: paddlescience.pde.pde_laplace_2d
+
+.. py:class:: Laplace2D 
+
+   二维拉普拉斯方程
+
+   .. math::
+
+         \frac{\partial^2 u}{\partial x^2} + \frac{\partial^2 u}{\partial y^2} = 0
+
+   **样例**
+
+   .. code-block:: 
+
+      import paddlescience as psci
+      pde = psci.pde.Laplace2D()
+
+   .. py:function:: set_bc_value(bc_value, bc_check_dim=None)
+
+   为PDE设置边界值（狄里克雷边界条件）
+
+      **参数:**
+
+         - **bc_value** - 数组。
+         - **bc_check_dim** (list) - 可选项，默认为None。如果不是None，该列表必须包含要设置边界条件值的维度。如果是None，则会在网络输出的所有维度设置边界条件值。
+
+.. automodule:: paddlescience.pde.pde_navier_stokes
+
+.. py:class:: NavierStokes(nu=0.01, rho=1.0) 
+   
+   二维时间无关纳维-斯托克斯方程
+
+   .. math::
+
+         \begin{eqnarray*}
+            \frac{\partial u}{\partial x} + \frac{\partial u}{\partial y} & = & 0,   \\
+            u \frac{\partial u}{\partial x} +  v \frac{\partial u}{\partial y} - \frac{\nu}{\rho} \frac{\partial^2 u}{\partial x^2} - \frac{\nu}{\rho}  \frac{\partial^2 u}{\partial y^2} + dp/dx & = & 0,\\
+            u \frac{\partial v}{\partial x} +  v \frac{\partial v}{\partial y} - \frac{\nu}{\rho} \frac{\partial^2 v}{\partial x^2} - \frac{\nu}{\rho}  \frac{\partial^2 v}{\partial y^2} + dp/dy & = & 0.
+         \end{eqnarray*}
+
+
+   **参数:**
+
+      - **nu** (*float*)- 运动粘度。
+      - **rho** (*float*) - 密度。
+
+   **样例**
+
+   .. code-block:: python
+
+      import paddlescience as psci
+      pde = psci.pde.NavierStokes(0.01, 1.0)
+
+   .. py:function:: set_bc_value(bc_value, bc_check_dim=None)
+
+   为PDE设置边界值（狄里克雷边界条件）
+
+      **参数:**
+
+         - **bc_value** - 数组。
+         - **bc_check_dim** (list)- 可选项，默认为None。如果不是None，该列表必须包含需要设置边界条件值的维度。如果是None，则会在网络输出的所有维度上设置边界条件值。

docs/source_cn/api/solver.rst

@@ -0,0 +1,47 @@
+求解器
+========
+
+.. automodule:: paddlescience.solver.solver
+
+.. py:class:: Solver(algo,opt)
+
+
+      **参数:**
+
+         - **algo** (*AlgorithmBase*) - 算法，AlgorithmBase的子类实例
+         - **opt** (*paddle.Optimizer*) - 优化器，paddle.Optimizer的子类实例
+
+   **样例**
+
+   .. code-block:: python
+
+         import paddlescience as psci
+         solver = psci.solver.Solver(algo=algo, opt=opt)
+
+
+   .. py:function:: solve(num_epoch=1000, batch_size=None, checkpoint_freq=1000)
+
+      根据设置的num_epoch进行网络训练。
+
+      **参数:**
+
+         - **num_epoch** (*int*) - 可选项, 默认值为1000. 表示训练的epoch数量。
+         - **batch_size** (*int|None*) - Under develop. 可选项, 默认值为None. 表示在训练时多少样本点在一个batch中被使用。
+         - **checkpoint_freq** (*int*) - Under develop. 可选项, 默认值为 1000. 表示经历多少个epoch后保存一次模型参数。
+
+      **返回:**
+
+         一个函数，其输入为一个Geometry Discrete实例，输出为numpy数组(array)类型。
+
+      **返回类型:**
+
+         对应问题的解(Callable)
+
+   **样例**
+
+   .. code-block::
+
+         import paddlescience as psci
+         solver = psci.solver.Solver(algo=algo, opt=opt)
+         solution = solver.solve(num_epoch=10000)
+         rslt = solution(geo)

docs/source_cn/api/visu.rst

@@ -0,0 +1,20 @@
+可视化
+=============
+
+.. automodule:: paddlescience.visu.visu_vtk
+
+.. py:function:: save_vtk(geo, data, filename='output')
+
+   将几何图形和数据保存为vtk文件以用于可视化
+
+      **参数:**
+
+         - **geo** - 几何图形，Geometry的实例
+         - **data** - 要保存的数据
+
+   **样例**
+
+   .. code-block::
+
+      import paddlescience as psci
+      pde = psci.visu.save_vtk(geo, data, filename="output")