adding some more documentation

Author: mrachh

docs/conf.py

@@ -12,16 +12,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
-import os
-import sphinx.ext.autodoc
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.append(os.path.abspath('sphinxext'))
-sys.path.insert(0,os.path.abspath('../../texext'))
 
 # -- General configuration ------------------------------------------------
 
@@ -33,12 +27,8 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.todo',
-    'sphinx.ext.napoleon',
     'sphinx.ext.mathjax',
-    'texext',
-#    'sphinxcontrib.bibtex',
+    'sphinx_math_dollar'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -74,7 +64,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en' 'en' 'en' 'en' 
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

docs/install.rst

@@ -18,6 +18,13 @@ For the basic libraries
 * GNU make
 
 
+Optional:
+
+* for building Python wrappers you will need ``python3``, ``pip3`` and ``numpy``.
+* for building standard MATLAB wrappers: MATLAB
+* for modifying MATLAB wrappers (experts only): ``mwrap``
+
+
 Quick install instructions
 *********************************************
 
@@ -52,12 +59,25 @@ You may then link to the FMM library using the ``-lfmm2d`` option.
 To verify successful compilation of the program, run ``make test``
 which compiles some fortran test drivers in ``test/`` linked against
 the static library, after which it
-runs the test programs. The last 4 lines of the terminal output should be::
+runs the test programs. The last 17 lines of the terminal output should be::
 
    cat print_testreshelm.txt
    Successfully completed 27 out of 27 tests in hfmm2d testing suite
+   Successfully completed 27 out of 27 tests in hf-hfmm2d testing suite
    Successfully completed 27 out of 27 tests in hfmm2d vec testing suite
+   Successfully completed 1 out of 1 tests in helm2d_mps testing suite
+   cat print_testreslap.txt
+   Successfully completed  9 out of  9 tests in cfmm2d testing suite
+   Successfully completed  9 out of  9 tests in cfmm2d vec testing suite
+   Successfully completed  9 out of  9 tests in lfmm2d testing suite
+   Successfully completed  9 out of  9 tests in lfmm2d vec testing suite
+   Successfully completed  9 out of  9 tests in rfmm2d testing suite
+   Successfully completed  9 out of  9 tests in rfmm2d vec testing suite
+   cat print_testresbh.txt
+   Successfully completed  1 out of  1 tests in bhfmm2d testing suite
    rm print_testreshelm.txt
+   rm print_testreslap.txt
+   rm print_testresbh.txt
 
 
 To verify successful installation of the program, and the correct
@@ -118,6 +138,78 @@ The corresponding makefiles are ``hfmm2d_example.make``,
 ``hfmm2d_vec_example.make``, and ``hfmm2d_legacy_example.make``.
 
 
+Building Python wrappers
+****************************
+
+First make sure you have python (version 3 or higher), pip and numpy installed. 
+
+You may then execute ``make python`` (after copying over the
+operating system specific make.inc.* file to make.inc) which calls
+pip for the install and then runs some tests.
+
+To rerun the tests, you may run ``pytest`` in ``python/`` 
+or alternatively run ``python python/test_hfmm.py`` and 
+``python python/test_lfmm.py``.
+
+See ``python/hfmmexample.py`` and ``python/lfmmexample.py`` to see
+usage examples for the Python wrappers.
+
+.. note::
+   On windows, you will need to update ``distutils.cfg`` located in 
+   ``(PYTHON_INSTALL_DIR)\Lib\distutils`` and set it to::
+ 
+       [build]
+       compiler=mingw32
+
+       [build_ext]
+       compiler=mingw32
+
+   which forces python to use the mingw compiler for building its
+   modules. In case you wish to revert to using VC/C++ for building python
+   modules, make sure to update distutils.cfg appropriately.
+
+
+A few words about Python environments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There can be confusion and conflicts between various versions of Python and installed packages. It is therefore a very good idea to use virtual environments. Here's a simple way to do it (after installing python-virtualenv)::
+
+  Open a terminal
+  virtualenv -p /usr/bin/python3 env1
+  . env1/bin/activate
+
+Now you are in a virtual environment that starts from scratch. All pip installed packages will go inside the env1 directory. (You can get out of the environment by typing ``deactivate``)
+
+It's advisable to install numpy into a virtual environment using pip as.
+
+  virtualenv -p /usr/bin/python3 env1
+  . env1/bin/activate
+  pip install numpy
+
+
+Building the MATLAB wrappers
+****************************
+
+First make sure you have MATLAB installed. 
+
+Then run ``make matlab`` (after copying over the operating
+system specific make.inc.* file to make.inc) which links the .m files to
+the .c file in the matlab folder. 
+
+To run tests, you can run ``matlab test_hfmm3d.m`` and 
+``matlab test_lfmm3d.m`` and it should return with $0$ crashes.
+
+Example codes for demonstrating the Helmholtz and Laplace
+interfaces are ``hfmm3d_example.m`` and ``lfmm3d_example.m``.
+
+In order to build the MATLAB routines with the optimized direct kernel 
+evaluation routines on a Mac, we recommend building mex with gcc
+instead of clang. The relevant xml files for configuring mex to use
+gcc can be found at https://github.com/danfortunato/matlab-gcc.
+Follow the instructions there to configure mex with gcc, and set
+CC = ``gcc-<version number>`` in your make.inc file. 
+
+
 Tips for installing dependencies
 **********************************
 
@@ -170,3 +262,66 @@ Download and install ``git`` for windows
 (Available `here <https://git-scm.com/download/win>`_).
 
 
+Tips for installing optional dependencies
+******************************************
+
+Installing python and pip
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On Ubuntu linux
+##################
+
+::
+
+  sudo apt-get install python3 python3-pip
+
+
+On Mac OSX
+############
+
+Make sure you have homebrew installed. See `Tips for installing dependencies -> On Mac OSX <install.html#mac-inst>`__ 
+
+::
+  
+  brew install python3
+
+
+On Windows
+###########
+
+Download and install python3.7 from python.org.
+
+Configuring MATLAB
+~~~~~~~~~~~~~~~~~~~
+
+On Windows
+############
+
+Update ``MINGW_LPATH`` in ``make.inc.windows.mingw`` to point to the
+appropriate installation directory (it should be the one within the
+``gcc`` folder).
+
+To setup mingw as the C compiler on MATLAB run ``configuremingw.p``
+(which can be downloaded from 
+`here <https://www.mathworks.com/matlabcentral/answers/uploaded_files/88639/configuremingw.p>`_)
+and choose the mingw directory. To verify successful setup run ``mex
+-setup`` from matlab and it should be configured to compile with mingw.
+
+
+Installing MWrap
+~~~~~~~~~~~~~~~~~~
+
+If you make any changes to the 
+fortran code, you will need to regenerate the .c files
+from the .mw files for which mwrap is required.
+This is not needed for most users.
+`MWrap <http://www.cs.cornell.edu/~bindel/sw/mwrap>`_
+is a very useful MEX interface generator by Dave Bindel.
+
+Make sure you have ``flex`` and ``bison`` installed.
+Download version 0.33.5 or later from https://github.com/zgimbutas/mwrap, un-tar the package, cd into it, then::
+  
+  make
+  sudo cp mwrap /usr/local/bin/
+
+

docs/math.rst

@@ -35,7 +35,7 @@ given by
 .. math::
    :label: rlap_nbody
 
-    u(x) = \sum_{j=1}^{N} c_{j} \log{(\|x-x_{j}\|)} - v_{j} d_{j}\cdot \nabla \log{(\|x-x_{j}\|)}  \, , 
+    u(x) = -\frac{1}{2\pi}\left(\sum_{j=1}^{N} c_{j} \log{(\|x-x_{j}\|)} - v_{j} d_{j}\cdot \nabla \log{(\|x-x_{j}\|)}\right)  \, , 
 
 and its gradient $\nabla u(x) \in \mathbb{R}^{2}$
 at the source and target locations. When $x=x_{j}$, the term
@@ -51,14 +51,14 @@ $j=1,2,\ldots N$,
 denote a collection of dipole strengths, and let $d_{j} \in \mathbb{R}^{2}$,
 $j=1,2,\ldots N$, denote the corresponding dipole orientation vectors.
 
-The Laplace FMM (rfmm2d) computes 
+The Laplace FMM (lfmm2d) computes 
 the potential $u(x) \in \mathbb{C}$ 
 given by
 
 .. math::
    :label: llap_nbody
 
-    u(x) = \sum_{j=1}^{N} c_{j} \log{(\|x-x_{j}\|)} - v_{j} d_{j}\cdot \nabla \log{(\|x-x_{j}\|)}  \, , 
+    u(x) = -\frac{1}{2\pi} \left(\sum_{j=1}^{N} c_{j} \log{(\|x-x_{j}\|)} - v_{j} d_{j}\cdot \nabla \log{(\|x-x_{j}\|)}\right)  \, , 
 
 and its gradient $\nabla u(x) \in \mathbb{C}^{2}$
 at the source and target locations. (The outputs are complex-valued in this case because
@@ -83,7 +83,7 @@ given by
 .. math::
    :label: clap_nbody
 
-    u(z) = \sum_{j=1}^{N} c_{j} \log{(\|z-\xi_{j}\|)} - \frac{v_{j}}{z-\xi_{j}}  \, , 
+    u(z) = -\frac{1}{2\pi}\left(\sum_{j=1}^{N} c_{j} \log{(\|z-\xi_{j}\|)} - \frac{v_{j}}{z-\xi_{j}}\right)  \, , 
 
 and its 
 derivatives $u'(z), u''(z) \in
@@ -111,7 +111,7 @@ given by
 .. math::
    :label: helm_nbody
 
-    u(x) = \sum_{j=1}^{N} c_{j} H_{0}^{(1)}(k\|x-x_{j}\|) - v_{j} d_{j}\cdot \nabla H_{0}^{(1)}(k\|x-x_{j}\|)  \, , 
+    u(x) = \frac{i}{4}\left(\sum_{j=1}^{N} c_{j} H_{0}^{(1)}(k\|x-x_{j}\|) - v_{j} d_{j}\cdot \nabla H_{0}^{(1)}(k\|x-x_{j}\|)\right)  \, , 
 
 and its gradient $\nabla u(x) \in \mathbb{C}^{2}$
 at the source and target locations, where $H_{0}^{(1)}$ is the Hankel function
@@ -136,21 +136,21 @@ given by
 .. math::
    :label: biharm_nbody
 
-    u(z) &= \sum_{j=1}^{N} 2 \, c_{j,1} \log{\|z - \xi_{j}\|} + 
+    u(z) &= \frac{1}{2\pi} \left(\sum_{j=1}^{N} 2 \, c_{j,1} \log{\|z - \xi_{j}\|} + 
     c_{j,2} \frac{z-\xi_{j}}{\overline{z-\xi_{j}}} + \frac{v_{j,1}}{z - \xi_{j}} + 
     \frac{v_{j,3}}{\overline{z-\xi_{j}}} + 
-    v_{j,2} \frac{z - \xi_{j}}{(\overline{z-\xi_{j}})^2} \, , \\
-    P_{z} \frac{\mathrm{d}}{\mathrm{d} z}u(z) &= \sum_{j=1}^{N} \frac{c_{j,1}}{z-\xi_{j}} -
-    \frac{v_{j,1}}{(z-\xi_{j})^2} \, \\
+    v_{j,2} \frac{z - \xi_{j}}{(\overline{z-\xi_{j}})^2} \right) \, , \\
+    P_{z} \frac{\mathrm{d}}{\mathrm{d} z}u(z) &= \frac{1}{2\pi} \left(\sum_{j=1}^{N} \frac{c_{j,1}}{z-\xi_{j}} -
+    \frac{v_{j,1}}{(z-\xi_{j})^2} \right) \, \\
     P_{\overline{z}} \frac{\mathrm{d}}{\mathrm{d} z} u(z) &= 
-    \sum_{j=1}^{N} \frac{c_{j,2}}{\overline{z-\xi_{j}}} + 
-    \frac{v_{j,2}}{(\overline{z-\xi_{j}})^2} \,
+    \frac{1}{2\pi} \left(\sum_{j=1}^{N} \frac{c_{j,2}}{\overline{z-\xi_{j}}} + 
+    \frac{v_{j,2}}{(\overline{z-\xi_{j}})^2} \right) \,
     ,\\
     \frac{\mathrm{d}}{\mathrm{d}\overline{z}} u(z) &= 
-    \sum_{j=1}^{N} \frac{c_{j,1}}{\overline{z-\xi_{j}}} - 
+    \frac{1}{2\pi}\left(\sum_{j=1}^{N} \frac{c_{j,1}}{\overline{z-\xi_{j}}} - 
     c_{j,2} \frac{z-\xi_{j}}{(\overline{z-\xi_{j}})^2} - 
     \frac{v_{j,3}}{(\overline{z-\xi_{j}})^2} - 
-    2v_{j,2} \frac{z - \xi_{j}}{(\overline{z-\xi_{j}})^3} \, , \\
+    2v_{j,2} \frac{z - \xi_{j}}{(\overline{z-\xi_{j}})^3}\right) \, , \\
 
 at the source and target locations. 
 When $z=\xi_{j}$, the term
@@ -216,7 +216,7 @@ Stokes FMM
 Let $G^{\textrm{stok}}(x,y)$ denote the Stokeslet given by
 
 .. math::
-    G^{\textrm{stok}}(x,y) = \frac{1}{2}
+    G^{\textrm{stok}}(x,y) = \frac{1}{4\pi}
     \begin{bmatrix}
     -\log{\|x-y \|} +  \frac{(x_{1}-y_{1})^2}{\|x-y\|^2} & \frac{(x_{1}-y_{1})
     (x_{2}-y_{2})}{\|x-y \|^2} \\
@@ -294,7 +294,7 @@ given by
 .. math::
     :label: helm_nbody_vec
 
-    u_{\ell}(x) = \sum_{j=1}^{N} c_{\ell,j} H_{0}^{(1)}(k\|x-x_{j}\|) - v_{\ell,j} d_{\ell,j}\cdot \nabla H_{0}^{(1)}(k\|x-x_{j}\|)  \, , 
+    u_{\ell}(x) = \frac{i}{4}\left(\sum_{j=1}^{N} c_{\ell,j} H_{0}^{(1)}(k\|x-x_{j}\|) - v_{\ell,j} d_{\ell,j}\cdot \nabla H_{0}^{(1)}(k\|x-x_{j}\|)\right)  \, , 
 
 and its gradients $\nabla u_{\ell}(x) \in \mathbb{C}^{2}$
 at the source and target locations. 

docs/requirements.txt

@@ -1,2 +1,2 @@
-texext
 sphinxcontrib.bibtex
+sphinx-math-dollar