update README and docs for FSM

Author: Dengda98

README.md

@@ -23,7 +23,8 @@
 
 **欢迎Star！**
 
-[**PyFMM**](https://github.com/Dengda98/PyFMM) 是一个基于Fast Marching Method求解程函方程 $|\nabla T|^2 = s^2$ 的C/Python程序包，包括示例和注释。  
+[**PyFMM**](https://github.com/Dengda98/PyFMM) 是一个基于 **Fast Marching/Sweeping Method** 求解程函方程 $|\nabla T|^2 = s^2$ 的C/Python程序包，包括示例和注释。  其中 **Fast Sweeping Method** 包括了并行版本，详见[**在线文档**](https://pyfmm.readthedocs.io/zh-cn/latest/)或文献 [(Zhao, 2007)](https://www.jstor.org/stable/43693378)。
+
 [**PyFMM**](https://github.com/Dengda98/PyFMM) is a C/Python package for solving eikonal equation using Fast Marching Method, with examples and annotations.  
 
 **PyFMM** 目前可在Linux、Mac系统上运行，在Windows系统上可借助[WSL](https://learn.microsoft.com/en-us/windows/wsl/)、[WinLibs](https://winlibs.com/)等工具运行。

docs/source/API/C_extension/include/fsm.rst

@@ -0,0 +1,5 @@
+fsm.h
+--------------------------
+
+.. doxygenfile:: fsm.h
+    :project: h_PyFMM

docs/source/API/h_pyfmm_api.rst

@@ -8,6 +8,7 @@ C extension API
    C_extension/include/const
    C_extension/include/coord
    C_extension/include/diff
+   C_extension/include/fsm
    C_extension/include/fmm
    C_extension/include/heapsort
    C_extension/include/index

docs/source/API/pyfmm_api.rst

@@ -5,5 +5,6 @@
    :maxdepth: 2
 
 
+   pyfmm/_version
    pyfmm/traveltime
    pyfmm/c_interfaces

docs/source/about_FSM.rst

@@ -0,0 +1,66 @@
+关于Fast Sweeping Method
+=========================
+
+:Author: Zhu Dengda
+:Email:  [email protected] 
+
+
+-----------------------------------------------------------
+
+**Fast Sweeping Method(FSM)** 的基本原理详见 :ref:`(Zhao, 2004) <zhao_2004>`，
+**PyFMM** 使用的并行方法详见 :ref:`(Zhao, 2007) <zhao_2007>` 中2.1节。并行实现基于 :code:`OpenMP`。
+
+
+参数简介
+------------
+
+主要使用的函数都在 :class:`pyfmm.traveltime <pyfmm.traveltime>` 模块中，
+其中函数参数和 **FSM** 相关的包括：
+
++ :code:`useFSM` (Bool)   (default: False)
+  
+  是否使用 **FSM** 计算全局走时场。这将决定以下相关的参数是否起作用。
+
++ :code:`FSMmaxLoops` (int)   (default: 1)
+
+  最大迭代次数。对于3D模型，一次迭代包括向8个方向扫描（Sweep）。根据
+  :ref:`(Zhao, 2004) <zhao_2004>` 的测试，速度缓和变化的情况下，
+  一次迭代即可达到很好的精度，但对于速度剧烈变化的情况，需要一次以上的迭代来收敛。
+
++ :code:`FSMparallel` (bool)   (default: False)
+
+  是否使用 **并行FSM**。并行方法详见 :ref:`(Zhao, 2007) <zhao_2007>` 的
+  2.1节。简单说，8个方向的Sweep多线程同时进行，再对每个节点取最小值，算一次迭代。
+  但要注意的是，这种并行方法是一种 **FSM** 变体，即 **流程本身并不是可并行的。** 
+  原始的  **FSM** 每次Sweep是一次Gauss-Seidel式迭代，上一次Sweep结果会影响到
+  下一次Sweep。 **并行FSM** 将8次Sweep分多线程单独进行，这要求 
+  :code:`FSMmaxLoops > 2` 。
+
++ :code:`FSMeps` (float)   (default: 0.0)
+
+  每次Sweep后，走时的最大更新量小于 :code:`FSMeps` 时提前结束计算。 
+
+
+
+
+Fast Marching OR Fast Sweeping ?
+------------------------------------ 
+
+不存在谁好谁坏。  
+
+**FSM** 的一个核心技巧就是 **并行** ，基于此有不少工作对 **FSM** 做各种并行改进。而 **Fast Marching Method(FMM)** 本身是串行实现以保证强因果性。
+
+这里引用 :ref:`(Zhao, 2007) <zhao_2007>` 中关于 **FSM** 关于串行或并行的一些讨论： 
+
+.. epigraph::
+
+    In general if the characteristics are straight lines, sweepings with different orderings are almost independent of each other and the parallel sweeping algorithm should be as efficient as the original fast sweeping algorithm. However if the characteristics are curved then different orderings implemented sequentially may propagate information faster on a curved characteristics than different orderings implemented in parallel.
+
+结合我的测试结果，我的观点是：
+
++ 对于速度缓和变化的模型， **FSM** 仅需8次sweep（1次迭代）即可收敛，此时计算效率和 **FMM** 持平，再加上并行， **FSM** 计算效率甚至可以达到 **FMM** 的8倍（接近理论值），且计算误差保持一致（可以以均匀模型做测试）。
+
+
++ 但对于速度变化剧烈的模型， **FSM** 需要更多的迭代次数来收敛，尤其是并行算法。当只设置收敛条件 :code:`FSMeps` （如1e-3） 而不设置 :code:`FSMmaxLoops` 时（给定一个较大的 :code:`FSMeps` ），迭代过程中的走时最大更新量可能很难收敛到给定的条件而导致计算效率下降。此时串行的 **FSM** 相比与并行尽管表现出更好的稳定性，但也需要2~3次迭代（1次往往不够），计算时间也是 **FSM** 的2~3倍。
+
+在实际模型中速度变化是未知的，而 **FSM** 的计算结果受较多参数的影响。但影响 **FMM** 结果的因素不多，基本就是靠网格点的稠密程度决定。根据原理， **FMM** 的计算结果呈现无条件稳定，再加上堆排序算法， **FMM** 的计算效率也不落下风。

docs/source/examples/01_uniform.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### 计算均匀介质中的走时场"
+    "#### 计算均匀矩形介质中的走时场"
    ]
   },
   {

docs/source/examples/01_uniform_spherical.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### 计算均匀球体中的走时场"
+    "#### 计算均匀球型介质中的走时场"
    ]
   },
   {

docs/source/index.rst

@@ -19,8 +19,8 @@
 -----------------------------------------------------------
 
 
-**PyFMM** ： 基于Fast Marching Method求解程函方程 :math:`|\nabla T|^2 = s^2` 的程序包。
-代码根据 :ref:`主要参考 <main_ref>` 中详述的原理进行实现。 
+**PyFMM** ： 基于 **Fast Marching/Sweeping Method** 求解程函方程 :math:`|\nabla T|^2 = s^2` 的程序包。
+代码根据 :ref:`主要参考 <main_ref>` 中详述的原理进行实现，其中 **Fast Sweeping 及其并行方法** 基于 :ref:`(Zhao, 2004) <zhao_2004>` 和 :ref:`(Zhao, 2007) <zhao_2007>`
 
 我主要使用该代码计算地震波从震源出发在复杂介质中传播形成的初至波走时场，
 并使用梯度下降获得满足费马原理的射线路径，故代码中的一些术语偏专业性。
@@ -77,6 +77,7 @@
 
    install
    jupyter_examples
+   about_FSM
    API/pyfmm_api
    API/h_pyfmm_api
 
@@ -98,3 +99,14 @@
 .. [3] Rawlinson, N., and M. Sambridge (2004). Wave front evolution in 
        strongly heterogeneous layered media using the fast marching method, 
        Geophysical Journal International 156, no. 3, 631–647, doi: 10.1111/j.1365-246X.2004.02153.x.
+
+.. _zhao_2004:
+
+.. [4] Zhao, H. (2004). A fast sweeping method for Eikonal equations, 
+       Math. Comp. 74, no. 250, 603–627, doi: 10.1090/S0025-5718-04-01678-3.  
+
+.. _zhao_2007:
+
+.. [5] Zhao, H. (2007). Parallel implementations of the fast sweeping method, 
+       Journal of Computational Mathematics 25, no. 4, 421–429.
+

docs/source/install.rst

@@ -19,14 +19,20 @@
     jupyter 
 
 
-C程序的编译链接基于 :code:`gcc` 编译器，编译命令使用 :code:`make`，确保系统已安装相应工具。 
+C程序的编译链接基于 :code:`gcc` 编译器 + :code:`OpenMP` ，编译命令使用 :code:`make`，确保系统已安装相应工具。 
 
 以ubuntu为例，安装 :code:`gcc` 和 :code:`make` :
 
 ::
 
     sudo apt install build-essential 
 
+目前常见编译器应该已内置 :code:`OpenMP` 工具，或可运行以下命令安装:
+
+:: 
+
+    sudo apt install libomp-dev
+
 
 Makefile位于 :code:`pyfmm/C_extension/Makefile` ，你可以自定义你的编译器和编译命令。 
 
@@ -135,4 +141,6 @@ For Windows
   + 下载 **PyFMM** 程序包
   + 在 :code:`pyfmm/C_extension/Makefile` 中修改编译器为 :code:`CC = clang` （似乎 :code:`gcc` 不太好做交叉编译），将编译选项增加为 :code:`CFLAGS = --target=x86_64-apple-darwin ...(其它不变)`  
   + 在程序根目录下，运行 :code:`pip install -v .` 重新安装
+  
   这样更改后重新安装，就可解决架构不匹配的问题。 **如果你是类似问题，可以在** :code:`CFLAGS` **中指定其它架构，详见** `clang编译器说明 <https://clang.llvm.org/docs/CrossCompilation.html>`_ 。
+

docs/source/jupyter_examples.rst

@@ -7,7 +7,7 @@ Jupyter 使用示例
 
 -----------------------------------------------------------
 
-以下示例的 *.ipynb* 文件 可在 `链接 <https://github.com/Dengda98/PyFMM/tree/main/docs/source/examples>`_ 中下载。
+以下示例的 :code:`.ipynb` 文件 可在 `链接 <https://github.com/Dengda98/PyFMM/tree/main/docs/source/examples>`_ 中下载。
 更多示例有待补充。