Merge pull request #28 from jiaqileng/adding-documentation-and-bug-fixes

Adding documentation and bug fixes

Author: skushnir123

docs/api.rst

@@ -0,0 +1,17 @@
+API
+===
+
+.. automodule:: qhdopt.qhd
+   :members:
+
+.. automodule:: qhdopt.qhd_base
+   :members:
+
+.. automodule:: qhdopt.utils
+   :members:
+
+.. automodule:: qhdopt.backend.backend
+   :members:
+
+.. automodule:: qhdopt.backend.dwave_backend
+   :members:

docs/conf.py

@@ -5,6 +5,9 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import pathlib
+import sys
+sys.path.insert(0, pathlib.Path(__file__).parents[1].resolve().as_posix())
 
 project = 'QHDOPT'
 copyright = '2024, Samuel Kushnir, Jiaqi Leng, Yuxiang Peng'
@@ -14,7 +17,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

docs/index.rst

@@ -3,18 +3,27 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to QHDOPT's documentation!
+QHDOPT
 ==================================
+QHDOPT (QHD-based OPTimizer) is a software package for nonconvex optimization.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+QHDOPT implements a quantum optimization algorithm named Quantum Hamiltonian Descent (QHD) on available quantum computers (such as the D-Wave systems).
+QHD is a quantum-upgraded version of gradient descent (GD).
+Unlike the classical GD, QHD demonstrates a significant advantage in solving nonconvex optimization problems.
+
+QHDOPT is for everyone!
+QHDOPT aims to eliminate the technical barrier of using QHD for the broader operations research (OR) community.
+We do not assume users to have prior knowledge of quantum computing, while we allow expert users to specify advanced solver parameters for customized experience. Our target users include:
 
+Professionals pursuing an off-the-shelf nonconvex optimization solver to tackle problems in operations research (e.g., power systems, supply chains, manufacturing, health care, etc.),
+Researchers who hope to advance the theory and algorithms of optimization via quantum technologies,
+Experts in quantum computation who want to experiment with hyperparameters and/or encodings in QHD to achieve even better practical performance.
+Fast compilation empowered by SimuQ
+QHDOPT has a built-in compiler powered by SimuQ, a framework for programming and compiling quantum Hamiltonian systems.
 
+Automatic post-processing
+QHDOPT automatically post-processes the results returned by the quantum machines. The post-processing includes decoding the raw measurement results and improving their precision (i.e., fine-tuning) via a classical local solver. Users may disable the fine-tuning if needed.
 
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   api