From 07792bcad93490092ba11167e5a1c5ddab167639 Mon Sep 17 00:00:00 2001 From: Michelle Richer Date: Thu, 7 Mar 2024 08:40:16 -0500 Subject: [PATCH] Add automatic website publishing --- .github/workflows/default.yml | 47 ++++++++++ .github/workflows/pull_request.yml | 27 ++++++ docs/requirements.txt | 4 + docs/source/index.rst | 135 +++++++++++++++++++++++++++-- docs/source/install.rst | 13 +-- 5 files changed, 216 insertions(+), 10 deletions(-) create mode 100644 .github/workflows/default.yml create mode 100644 .github/workflows/pull_request.yml create mode 100644 docs/requirements.txt diff --git a/.github/workflows/default.yml b/.github/workflows/default.yml new file mode 100644 index 0000000..b98b46c --- /dev/null +++ b/.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 "action@github.com" + 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 }} diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml new file mode 100644 index 0000000..2f26679 --- /dev/null +++ b/.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/ diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..a7649ab --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +numpy +sphinx +sphinx-rtd-theme +sphinx-copybutton diff --git a/docs/source/index.rst b/docs/source/index.rst index b2e8e4e..7026b2d 100644 --- a/docs/source/index.rst +++ b/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` diff --git a/docs/source/install.rst b/docs/source/install.rst index d2abfcd..56fa34c 100644 --- a/docs/source/install.rst +++ b/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 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 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. -