Add automatic website publishing

.github/workflows/default.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Install dependencies
+      run: sudo apt-get install -y build-essential python-dev-is-python3 python3-numpy
+
+    - name: Build library
+      run: make PYTHON=python && cp -r permanent/ docs/
+
+    - uses: ammaraskar/sphinx-action@master
+      with:
+        build-command: "make html"
+        docs-folder: "docs/"
+
+    - uses: actions/upload-artifact@v1
+      with:
+        name: DocumentationHTML
+        path: docs/build/html/
+
+    - name: Commit documentation changes
+      run: |
+        git clone https://github.com/msricher/matrix-permanent.git --branch gh-pages --single-branch gh-pages
+        cp -r docs/build/html/* gh-pages/
+        cd gh-pages/
+        touch .nojekyll
+        git config --local user.email "[email protected]"
+        git config --local user.name "GitHub Action"
+        git add .
+        git commit -m "Update documentation" -a || true
+
+    - name: Push documentation changes
+      uses: ad-m/github-push-action@master
+      with:
+        branch: gh-pages
+        directory: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pull_request.yml

@@ -0,0 +1,27 @@
+name: Pull Request Docs Check
+
+on: [pull_request]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Install dependencies
+      run: sudo apt-get install -y build-essential python-dev-is-python3 python3-numpy
+
+    - name: Build library
+      run: make PYTHON=python && cp -r permanent/ docs/
+
+    - uses: ammaraskar/sphinx-action@master
+      with:
+        build-command: "make html"
+        docs-folder: "docs/"
+
+    - uses: actions/upload-artifact@v1
+      with:
+        name: DocumentationHTML
+        path: docs/build/html/

docs/requirements.txt

@@ -0,0 +1,4 @@
+numpy
+sphinx
+sphinx-rtd-theme
+sphinx-copybutton

docs/source/index.rst

@@ -1,16 +1,141 @@
-Welcome to Permanent's documentation!
-=====================================
+Permanent
+=========
 
 .. toctree::
-   :maxdepth: 4
-   :caption: Contents:
+   :maxdepth: 2
+   :caption: Contents
 
    install
    api
 
+About
+-----
+
+The permanent of a (square) matrix, like the determinant is a polynomial
+in the entries of the matrix. Unlike the determinant, the signatures of
+the permutations are not taken into account making the permanent much
+more difficult to compute because decomposition methods cannot be used.
+
+The permanent commonly appears in problems related to quantum mechanics,
+and the most common brute-force combinatorial method has time complexity
+:math:`\mathcal{O}(N!N)`, thus it is useful to look for more efficient
+algorithms. The two algorithms considered to be the fastest are one by
+Ryser (based on the inclusion-exclusion principle), and one by Glynn
+(based on invariant theory).
+
+This library aims to solve the need for an efficient library that solves
+the permenent of a given matrix.
+
+Algorithms
+----------
+
+``permanent.opt()``
+
+Compute the permanent of a matrix using the best algorithm for the shape
+of the given matrix.
+
+**Parameters:**
+
+-  ``matrix``: ``np.ndarray(M, N, dtype=(np.double|np.complex))``
+
+**Returns:**
+
+-  ``permanent``: ``(np.double|np.complex)`` - Permanent of matrix.
+
+--------------
+
+``permanent.combinatoric()``
+
+Compute the permanent of a matrix combinatorically.
+
+**Formula:**
+
+.. math::
+
+   \text{per}(A) = \sum_{\sigma \in P(N,M)}{\prod_{i=1}^M{a_{i,{\sigma(i)}}}}
+
+**Parameters:**
+
+-  ``matrix``: ``np.ndarray(M, N, dtype=(np.double|np.complex))``
+
+**Returns:**
+
+-  ``permanent``: ``(np.double|np.complex)`` - Permanent of matrix.
+
+--------------
+
+``permanent.glynn()``
+
+**Formula:**
+
+.. math::
+
+   \text{per}(A) = \frac{1}{2^{N-1}} \cdot \sum_{\delta}{
+       \left(\sum_{k=1}^N{\delta_k}\right){\prod_{j=1}^N{\sum_{i=1}^N{\delta_i a_{i,j}}}}}
+
+**Additional Information:** The original formula has been generalized
+here to work with :math:`M`-by-:math:`N` rectangular permanents with
+:math:`M \leq N` by use of the following identity (shown here for
+:math:`M \geq N`):
+
+.. math::
+
+   \text{per}\left(\begin{matrix}a_{1,1} & \cdots & a_{1,N} \\ \vdots & \ddots & \vdots \\ a_{M,1} & \cdots & a_{M,N}\end{matrix}\right) = \frac{1}{(M - N + 1)!} \cdot \text{per}\left(\begin{matrix}a_{1,1} & \cdots & a_{1,N} & 1_{1,N+1} & \cdots & 1_{1,M} \\ \vdots & \ddots & \vdots & \vdots & \ddots & \vdots \\ a_{M,1} & \cdots & a_{M,N} & 1_{M,N+1} & \cdots & 1_{M,M}\end{matrix}\right)
+
+This can be neatly fit into the original formula by extending the inner
+sums over :math:`\delta` from :math:`[1,M]` to :math:`[1,N]`:
+
+.. math::
+
+   \text{per}(A) = \frac{1}{2^{N-1}} \cdot \frac{1}{(N - M + 1)!}\cdot \sum_{\delta}{
+           \left(\sum_{k=1}^N{\delta_k}\right)
+           \prod_{j=1}^N{\left(
+               \sum_{i=1}^M{\delta_i a_{i,j}} + \sum_{i=M+1}^N{\delta_i}
+           \right)}
+       }
+
+**Parameters:**
+
+-  ``matrix``: ``np.ndarray(M, N, dtype=(np.double|np.complex))``
+
+**Returns:**
+
+-  ``permanent``: ``(np.double|np.complex)`` - Permanent of matrix.
+
+--------------
+
+``permanent.ryser()``
+
+**Formula:**
+
+.. math::
+
+   \text{per}(A) = \sum_{k=0}^{M-1}{
+           {(-1)}^k
+           \binom{N - M + k}{k}
+           \sum_{\sigma \in P(N,M-k)}{
+               \prod_{i=1}^M{
+                   \sum_{j=1}^{M-k}{a_{i,{\sigma(j)}}}
+               }
+           }
+       }
+
+**Parameters:**
+
+-  ``matrix``: ``np.ndarray(M, N, dtype=(np.double|np.complex))``
+
+**Returns:**
+
+-  ``permanent``: ``(np.double|np.complex)`` - Permanent of matrix.
+
+License
+-------
+
+This code is distributed under the GNU General Public License version 3
+(GPLv3). See http://www.gnu.org/licenses/ for more information.
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/source/install.rst

@@ -3,7 +3,8 @@ Installation
 The permanent package allows you to solve the permanent of a given matrix using the optimal algorithm for your matrix dimensions. You can either use the pre-defined parameters or fine tune them to your machine.
 
 Setting up your environment
-===========================
+---------------------------
+
 #. Install Python on your machine. Depending on your operating system, the instructions may vary.
 
 #. Install gcc on your machine. Depending on your operating system, the instructions may vary.
@@ -43,7 +44,8 @@ Setting up your environment
 Now that you have your environment set up and activated you are ready to compile the source code into an executable. Here you have two options - compile the code as is with the pre-defined parameters for algorithm swapping, **or** compile the code with machine specific tuning for algorithm swapping. *Note that machine specific tuning will run a series of tests. This will take anywhere from 10 minutes to 1 hour depending on your system.*
 
 Option 1: Use given parameters
-==============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 #. Compile the permanent code.
 
 	.. code-block:: bash
@@ -75,7 +77,8 @@ Option 1: Use given parameters
 		<browser> build/html/index.html
 
 Option 2: Tune parameters
-=========================
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 #. Compile the permanent code with the ``tuning`` flag.
 
 	.. code-block:: bash
@@ -103,7 +106,8 @@ Option 2: Tune parameters
 		<browser> build/html/index.html
 
 Notes about the ``Makefile``
-===============================
+----------------------------
+
 The Makefile in this project is used to compile C and Python libraries and includes rules for installation, testing, and cleaning. Here's a breakdown of its sections:
 
 #. Variables:
@@ -135,4 +139,3 @@ The Makefile in this project is used to compile C and Python libraries and inclu
 * ``permanent/permanent.so``: Compiles Python extension module.
 * ``src/libpermanent.o``: Compiles object code.
 * ``libpermanent.a, libpermanent.so``: Compiles static and shared C libraries respectively.
-