diff --git a/MANIFEST.ini b/MANIFEST.ini new file mode 100644 index 0000000..517959a --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/README.md b/README.md index 4476efc..0dcc7e2 100644 --- a/README.md +++ b/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/)). diff --git a/aquapointer/.readthedocs.yaml b/aquapointer/.readthedocs.yaml new file mode 100644 index 0000000..6195059 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/aquapointer/__init__.py b/aquapointer/__init__.py index 64afdaa..0f106c0 100644 --- a/aquapointer/__init__.py +++ b/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 \ No newline at end of file +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 diff --git a/aquapointer/analog/__init__.py b/aquapointer/analog/__init__.py new file mode 100644 index 0000000..fc13f21 --- /dev/null +++ b/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 diff --git a/aquapointer/analog/water_placement.py b/aquapointer/analog/analog.py similarity index 89% rename from aquapointer/analog/water_placement.py rename to aquapointer/analog/analog.py index e23139c..51d973f 100644 --- a/aquapointer/analog/water_placement.py +++ b/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. """ diff --git a/aquapointer/analog/qubo_solution.py b/aquapointer/analog/qubo_solution.py index 6589b6d..ccd46a3 100644 --- a/aquapointer/analog/qubo_solution.py +++ b/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,9 +103,9 @@ 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. @@ -116,8 +113,7 @@ def scale_detunings( 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. diff --git a/aquapointer/analog_digital/__init__.py b/aquapointer/analog_digital/__init__.py new file mode 100644 index 0000000..c1c5c28 --- /dev/null +++ b/aquapointer/analog_digital/__init__.py @@ -0,0 +1 @@ +from aquapointer.analog_digital import processor \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/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 diff --git a/docs/source/apidoc.rst b/docs/source/apidoc.rst new file mode 100644 index 0000000..3147a48 --- /dev/null +++ b/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: \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..bf1e771 --- /dev/null +++ b/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' diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..b4360c6 --- /dev/null +++ b/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 + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/requirements.txt b/requirements.txt index db2b9d6..c72baac 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,5 +6,5 @@ scipy GridDataFormats numba openqaoa +sphinx_autodoc_typehints pylatexenc -