Merge pull request #39 from unitaryfund/aquapointer-docs-setup

Set up aquapointer docs

MANIFEST.ini

@@ -0,0 +1,11 @@
+# aquapointer
+Package applying quantum algorithms to find locations of water molecules in a protein cavity
+
+## Getting started
+You can use [this notebook](notebooks/aquapointer_demo.ipynb) to get started with aquapointer. 
+
+## Installing aquapointer
+From the top level of the repository, where the `setup.py` file is found, just run
+```
+python setup.py install
+```

README.md

@@ -9,17 +9,34 @@
 Package applying quantum algorithms to find locations of water molecules in a protein cavity.
 
 ## Getting started
-You can use [this notebook](notebooks/aquapointer_demo.ipynb) to get started with aquapointer. 
+You can use [this notebook](notebooks/aquapointer_demo.ipynb) to get started with aquapointer.
 
 ## Installing aquapointer
 From the top level of the repository, where the `setup.py` file is found, just run
 ```
 python setup.py install
 ```
+
+## Documentation
+The documentation is found in the `docs` folder. To install the documentation you need to install `sphinx` and install the development environment.
+```
+pip install sphinx
+pip install -e .
+```
+
+To build an html version of the documentation, go to the docs directory and run the sphinx-build command, i.e.,
+```
+cd docs
+sphinx-build -b html source build
+```
+
+ Alternatively to the explicit sphinx-build command, you can use the `Makefile` shortcuts, such as `make html`.
+
+
 ## Contributing
-Aquapointer is developed by [Unitary Fund](https://unitary.fund/), [PASQAL](https://www.pasqal.com/), and [Qubit Pharmaceuticals](https://www.qubit-pharmaceuticals.com/). You are welcome to contribute to the project, open an issue or a pull request. 
+Aquapointer is developed by [Unitary Fund](https://unitary.fund/), [PASQAL](https://www.pasqal.com/), and [Qubit Pharmaceuticals](https://www.qubit-pharmaceuticals.com/). You are welcome to contribute to the project, open an issue or a pull request.
 
-You can join the [#aquapointer](https://discord.gg/cV4nEpMz) channel on the Unitary Fund Discord for community support. 
+You can join the [#aquapointer](https://discord.gg/cV4nEpMz) channel on the Unitary Fund Discord for community support.
 
 ## Funding
 Work on aquapointer is supported by [Wellcome Leap](https://wellcomeleap.org/) as part of the Quantum for Bio Program ([Q4Bio](https://wellcomeleap.org/q4bio/program/)).

aquapointer/.readthedocs.yaml

@@ -0,0 +1,28 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

aquapointer/__init__.py

@@ -3,6 +3,7 @@
 # This source code is licensed under the GPL license (v3) found in the
 # LICENSE file in the root directory of this source tree.
 
-
-from aquapointer.analog import density_mapping, qubo_solution, water_placement, utils
-from aquapointer.analog_digital import processor
+from aquapointer import analog, analog_digital, density_canvas, digital, slicing
+from aquapointer.analog_digital import processor
+from aquapointer.analog import analog, density_mapping, qubo_solution, utils
+from aquapointer.slicing import density_slices_by_axis, density_slices_by_plane, density_file_to_grid, density_origin, density_point_boundaries, generate_planes_by_axis

aquapointer/analog/__init__.py

@@ -0,0 +1,2 @@
+from aquapointer.analog.analog import find_water_positions
+from aquapointer.analog.density_mapping import find_index_of_excited_qubits, find_positions_of_excited_qubits, rescaled_positions_to_3d_map

aquapointer/analog/water_placement.py → aquapointer/analog/analog.py

@@ -30,27 +30,25 @@ def find_water_positions(
     ] = default_cost,
     location_clustering: Optional[Callable[[List[List[float]]], List[Any]]] = None,
 ) -> List[List[float]]:
+
     r"""Finds the locations of water molecules in a protein cavity from 2-D
     arrays of density values of the cavity.
 
     Args:
-        densities: List of density slices of the protein cavity as 2-D arrays
-            of density values.
-        points: List of arrays containing coordinates corresponding to each
-            element of the density arrays.
+        densities: List of density slices of the protein cavity as 2-D arrays of density values.
+        points: List of arrays containing coordinates corresponding to each element of the density arrays.
         executor: Function that executes a pulse sequence on a quantum backend.
-        processor_configs: List of ``Processor`` objects storing settings for
-            running on a quantum backend.
-        num_samples: Number of times to execute the quantum experiment or
-            simulation on the backend.
+        processor_configs: List of ``Processor`` objects storing settings for running on a quantum backend.
+        num_samples: Number of times to execute the quantum experiment or simulation on the backend.
         qubo_cost: Cost function to be optimized in the QUBO.
-        location_clustering: Optional function for merging duplicate locations
-            (typically identified in different layers).
+        location_clustering: Optional function for merging duplicate locations (typically identified in different layers).
+
 
     Returns:
         List of 3-D coordinates of the locations of water molecules in the
             protein cavity.
     """
+
     bitstrings = []
     for k, d in enumerate(densities):
         params = [58, 0, 0, 48.2]
@@ -83,7 +81,8 @@ def find_water_positions(
 
 
 def location_clustering_kmeans(water_positions: List[List[float]]) -> List[List[float]]:
-    r"""Takes a list of 3-D coordinates of the locations of water molecules in the
+    r"""
+    Takes a list of 3-D coordinates of the locations of water molecules in the
     protein cavity and merges each set of duplicate locations into a
     single location.
     """

aquapointer/analog/qubo_solution.py

@@ -44,8 +44,7 @@ def scale_gaussian(
         amp: Amplitude of the distribution.
 
     Returns:
-        The value at each point on a 2-D grid of a sum of isotropic
-    normal distributions.
+        The value at each point on a 2-D grid of a sum of isotropic normal distributions.
     """
     x = xy_data[:, 0]
     y = xy_data[:, 1]
@@ -80,15 +79,13 @@ def calculate_one_body_qubo_coeffs(
     r"""Calculates the one-body coefficients of the QUBO.
 
     Args:
-        density: Density slices of the protein cavity as a 2-D array of density
-            values.
+        density: Density slices of the protein cavity as a 2-D array of density values.
         rescaled_pos: Array of rescaled register positions.
         variance: Variance of the distribution fit to the density data.
         pos: Array of register positions.
 
     Returns:
-        Tuple of an array of one-body QUBO coefficients and their corresponding
-        scaling.
+        Tuple of an array of one-body QUBO coefficients and their corresponding scaling.
     """
     gamma_list = dsu.gamma_list(density, rescaled_pos, variance)
     distances_density = dsu.find_possible_distances(rescaled_pos)
@@ -106,18 +103,17 @@ def scale_detunings(
     max_det: float,
 ) -> NDArray:
     r"""Calculates the detunings to be used for the QUBO.
+
     Args:
-        density: Density slices of the protein cavity as a 2-D array of density
-            values.
+        density: Density slices of the protein cavity as a 2-D array of density values.
         pos: Array of register positions.
         rescaled_pos: Array of rescaled register positions.
         variance: Variance of the distribution fit to the density data.
         brad: Blockade radius distance (in micrometers).
         max_det: Maximum detuning allowed by the device.
 
     Returns:
-        Tuple of an array of one-body QUBO coefficients and their corresponding
-        scaling.
+        Tuple of an array of one-body QUBO coefficients and their corresponding scaling.
     """
     gamma_list, scale = calculate_one_body_qubo_coeffs(
         density, rescaled_pos, variance, pos
@@ -172,16 +168,14 @@ def run_qubo(
     num_samples: int = 1000,
 ) -> str:
     r"""Obtain bitstring solving the QUBO problem for the input density slice.
+    
     Args:
-        density: Density slices of the protein cavity as a 2-D array of density
-            values.
+        density: Density slices of the protein cavity as a 2-D array of density values.
         executor: Function that executes a pulse sequence on a quantum backend.
-        proc: ``Processor`` object storing settings for running
-            on a quantum backend.
+        proc: ``Processor`` object storing settings for running on a quantum backend.
 
         qubo_cost: Cost function to be optimized in the QUBO.
-        num_samples: Number of times to execute the quantum experiment or
-            simulation on the backend.
+        num_samples: Number of times to execute the quantum experiment or simulation on the backend.
 
     Returns:
         Bitstring solving the QUBO for the input density slice.
@@ -223,14 +217,12 @@ def best_solution_from_samples(
         [NDArray, NDArray, float, str, float, float], float
     ] = default_cost,
 ) -> str:
-    r"""Identify sampled bitstring with lowest QUBO cost for the input density
-    slice.
+    r"""Identify sampled bitstring with lowest QUBO cost for the input density slice.
 
     Args:
         samples: Bitstring samples obtained from executing the pulse sequence.
         rescaled_pos: Array of rescaled register positions.
-        density: Density slices of the protein cavity as a 2-D array of density
-            values.
+        density: Density slices of the protein cavity as a 2-D array of density values.
         brad: Blockade radius distance (in micrometers).
         var: Variance of the fitted density distribution.
         amp: Amplitude of the fitted density distribution.

aquapointer/analog_digital/__init__.py

@@ -0,0 +1 @@
+from aquapointer.analog_digital import processor

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/apidoc.rst

@@ -0,0 +1,35 @@
+Functions
+----------
+
+.. automodule:: aquapointer
+   :members:
+
+.. automodule:: aquapointer.analog
+   :members:
+
+.. automodule:: aquapointer.analog.analog
+   :members:
+
+.. automodule:: aquapointer.analog.density_mapping
+   :members:
+
+.. automodule:: aquapointer.analog.qubo_solution
+   :members:
+
+.. automodule:: aquapointer.analog_digital
+   :members:
+
+.. automodule:: aquapointer.digital
+   :members:
+
+.. automodule:: aquapointer.slicing
+   :members:
+
+
+Classes
+----------
+.. autoclass:: aquapointer.density_canvas
+   :members:
+
+.. autoclass:: aquapointer.analog_digital.processor
+   :members:

docs/source/conf.py

@@ -0,0 +1,40 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../../"))
+
+
+project = 'aquapointer'
+copyright = '2024, Unitary Fund, Pasqal, and Qubit Pharmaceuticals'
+author = 'Unitary Fund, Pasqal, and Qubit Pharmaceuticals'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+sys.path.append(os.path.abspath("sphinxext"))
+extensions = [ "sphinx.ext.autodoc",
+            "sphinx.ext.autosummary",
+            "sphinx_autodoc_typehints"
+            ]
+
+master_doc = "index"
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'

docs/source/index.rst

@@ -0,0 +1,21 @@
+.. aquapointer documentation master file, created by
+   sphinx-quickstart on Tue Feb 20 12:12:46 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to aquapointer's documentation!
+=======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   apidoc <apidoc.rst>
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

requirements.txt

@@ -6,5 +6,5 @@ scipy
 GridDataFormats
 numba
 openqaoa
+sphinx_autodoc_typehints
 pylatexenc
-