Update RST and README documentation (#13)

* Link installation page to introduction

* Remove redundant overview page

* Add acks

* Update installation page

* Remove examples page

...which will be absorbed into the usage page

* Fix alias in README.md

* Update README usage and example

* Add 'build examples' option

* Update docs -- usage page

* Make better aliases

* Remove alias and update executable install instructions

* Default gtest to OFF

Note that we do not require users to install gtest for qiree to work properly

CMakeLists.txt

@@ -34,7 +34,8 @@ endmacro()
 
 # Components
 option(QIREE_BUILD_DOCS "Build QIR-EE documentation" OFF)
-option(QIREE_BUILD_TESTS "Build QIR-EE unit tests" ON)
+option(QIREE_BUILD_TESTS "Build QIR-EE unit tests" OFF)
+option(QIREE_BUILD_EXAMPLES "Build QIR-EE examples" OFF)
 option(QIREE_USE_XACC "Build XACC interface" ON)
 qiree_set_default(BUILD_TESTING ${QIREE_BUILD_TESTS})
 
@@ -179,6 +180,14 @@ endif()
 
 add_subdirectory(app)
 
+#----------------------------------------------------------------------------#
+# EXAMPLES
+#----------------------------------------------------------------------------#
+
+if(QIREE_BUILD_EXAMPLES)
+   add_subdirectory(examples)
+endif()
+
 #----------------------------------------------------------------------------#
 # DOCUMENTATION
 #----------------------------------------------------------------------------#

README.md

@@ -63,7 +63,11 @@ QIR-EE Setup in Command Line
 3. `cmake ..`
 4. `make`
 
-The resulting executable can be saved with an alias: `alias qee="./[YOUR-DIR]/qir-xir/build/bin/qir-xacc"`
+The resulting path to executable files can be exported 
+
+`export PATH=${YOUR-QIREE-INSTALL-DIR}/bin:$PATH`
+
+which would allow you to access the QIR-EE from anywhere in command line.
 
 ## Executing Quantum Circuits
 (via QIR-EE and XACC)
@@ -82,24 +86,26 @@ The resulting executable can be saved with an alias: `alias qee="./[YOUR-DIR]/qi
 For basic usage:
 
 ```
-qee llvm-file-path --flag-name flag-value
+qir-xacc llvm-file-path --flag-name flag-value
 ```
-1. `qee` may be replaced with an equivalent path to the executable.
+1. `qir-xacc` may be replaced with an equivalent executable.
 2. `llvm-file-path` is used to indicate path of the LLVM (`*.ll`) file that
    specifies the quantum program (required).
 3. `-a` or `--accelerator` is the name of the quantum accelerator (hardware or
    simulator) that you wish to use (required).
 4. `-s` or `--shots` is the number of shots (optional with default at 1024).
 
-   With XACC we have tested: `aer`, `qpp`, `qsim`, `honeywell:H1-1SC`, `honeywell:H1-1E`, `honeywell:H1-1`, `ionq`.
+   With XACC we have tested: `aer`, `qpp`, `qsim`, `quantinuum:H1-1SC`, `quantinuum:H1-1E`, 
+   `quantinuum:H1-1`, `ionq`, `ionq:sim.harmony`, `ionq:sim.aria-1`, `ionq:qpu.harmony`.
+
    Note that the minimal build only includes `aer` and `qpp` for local simulators.
 
 Please refer to the documentation here (add link) for all flag options.
 
 ### Example:
 
 ```
-qee $HOME/qir-xir/examples/bell.ll --accelerator qpp
+qir-xacc $HOME/qiree/examples/bell.ll --accelerator qpp
 ```
 
 This command will execute the quantum Bell circuit described in `bell.ll` the

doc/conf.py

@@ -71,6 +71,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.todo',
     'sphinx.ext.githubpages',
+    'sphinx.ext.autosectionlabel'
 ]
 
 if qiree_config['options']['breathe']:

doc/main/acknowledgments.rst

@@ -12,7 +12,7 @@
 Acknowledgments
 ***************
 
-TODO: ASCR/ORNL acknowledgments
+This research was supported by the US Department of Energy, Office of Science Advanced Scientific Computing Research, Advanced Research for Quantum Computing. This research used resources of the Oak Ridge Leadership Computing Facility, which is a DOE Office of Science User Facility supported under Contract DE-AC05-00OR22725. The work was performed at Oak Ridge National Laboratory as part of the Advanced Integrated Development Environments for Quantum Computing (AIDE-QC) project.
 
 .. raw:: latex
 

doc/main/installation.rst

@@ -2,7 +2,7 @@
 .. See the doc/COPYRIGHT file for details.
 .. SPDX-License-Identifier: CC-BY-4.0
 
-.. _infrastructure:
+.. _installation:
 
 ************
 Installation
@@ -43,7 +43,7 @@ fewer available components.
    GoogleTest_, Development, "Test harness"
 
 .. _CMake: https://cmake.org
-.. _XACC: h
+.. _XACC: https://github.com/ORNL-QCI/xacc
 .. _Doxygen: https://www.doxygen.nl
 .. _Git: https://git-scm.com
 .. _GoogleTest: https://github.com/google/googletest
@@ -57,13 +57,46 @@ Ideally you will build QIR-EE with all dependencies to gain the full
 functionality of the code, but there are circumstances in which you may not
 have (or want) all the dependencies or features available.
 
-Toolchain installation
-======================
+Bulding QIR-EE (Basic Functionality with XACC)
+==============================================
 
-TODO: spack instructions once XACC plays nice with externals
+Once you have your build system and a minimal version XACC_ installed with
 
-Building QIR-EE
-==================
+.. code-block:: console
+
+   $ cmake .. -DQIREE_MINIMAL_BUILD=ON
+   $ make -j$(nproc --all) install
+
+then a basic build of QIR-EE involves cloning the latest development version of QIR-EE:
+
+.. code-block:: console
+
+   $ git clone https://github.com/qiree-project/qiree.git
+
+or downloading and extracting it from the GitHub-generated `zip file`_. Then:
+
+.. code-block:: console
+
+   $ cd qiree
+   $ mkdir build && cd build
+   $ cmake ..
+   $ make 
+
+Confirm that your cmake prefixes for XACC are correct. If not, then add them:
+
+.. code-block:: console
+
+   $ export CMAKE_PREFIX_PATH=$HOME/.xacc
+   $ export PYTHONPATH=$PYTHONPATH:$HOME/.xacc
+
+(or equivalent paths to your XACC installation).
+
+Building QIR-EE (with Spack)
+============================
+
+Create a `spack-environment`_ activate it, and then ``spack install``.
+
+.. _spack-environment: https://spack.readthedocs.io/en/latest/environments.html
 
 Once the QIR-EE Spack environment has been installed, set your shell's environment
 variables (``PATH``, ``CMAKE_PREFIX_PATH``, ...) by activating it.
@@ -76,7 +109,7 @@ To clone the latest development version of QIR-EE:
 
 or download it from the GitHub-generated `zip file`_.
 
-, you can configure, build, and test using the provided helper script:
+You can configure, build, and test using the provided helper script:
 
 .. code-block:: console
 

doc/main/introduction.rst

@@ -17,9 +17,12 @@ associated to the paper "A Cross-Platform Execution Engine for the Quantum
 Intermediate Representation" [#qiree_paper]_ and is maintained by the QIR-EE
 Developers.
 
-At version 0.1, this work represents a proof-of-concept for the feasibility of
+At version |release|, this work represents a proof-of-concept for the feasibility of
 a modular workflow at the lower end of the quantum software stack. We welcome
 feedback and ideas for collaborations.
 
+To get started, we recommend following the installation instructions
+:ref:`here<installation>` and being mindful of dependency requirements.
+
 .. [#qiree_vers] This documentation is generated from QIR-EE |release|.
 .. [#qiree_paper] A preprint of this paper can be found at :cite:t:`wong2024`.

doc/main/usage.rst

@@ -10,24 +10,17 @@
 Using QIR-EE
 ***************
 
-QIR-EE includes a core set of libraries for internal and external use, as
-well as applications and front ends.
+QIR-EE includes a core set of libraries for internal/external use, applications, and front ends.
 
-Software library
-================
-
-TODO
 
-.. _celer-sim:
-
-XACC interface (qir-xacc)
-=========================
+Interface Application (qir-xacc)
+================================
 
 The ``qir-xacc`` application processes an LLVM QIR file and dispatches to XACC.
 
 Usage::
 
-   Usage: ./../build/bin/qir-xacc [OPTIONS] input
+   ./../build/bin/qir-xacc [OPTIONS] input
 
    Positionals:
      input TEXT REQUIRED              QIR input file
@@ -37,3 +30,59 @@ Usage::
      -i,--input TEXT REQUIRED         QIR input file
      -a,--accelerator TEXT REQUIRED   Accelerator name
      -s,--shots INT [1024]            Number of shots
+
+
+Syntax for Execution
+====================
+
+Export Path to Executable::
+
+    export PATH=${YOUR-QIREE-INSTALL-DIR}/bin:$PATH
+
+This will allow you to access installed QIR-EE executables from anywhere in command line.
+
+Basic Usage with ``qir-xacc`` Executable::
+
+    qir-xacc llvm-file-path --flag-name flag-value
+
+With XACC we have tested: ``aer``, ``qpp``, ``qsim``, ``quantinuum:H1-1SC``, ``quantinuum:H1-1E``, ``quantinuum:H1-1``, ``ionq``, ``ionq:sim.harmony``, ``ionq:sim.aria-1``, ``ionq:qpu.harmony``.
+
+* The a minimal XACC build only includes ``aer`` and ``qpp`` for local simulators.
+
+* Credentials are required for access to ``ionq`` and ``quantinuum`` and can be stored in ``.ionq_config`` and ``.quantinuum_config`` files in the home directory, respectively.
+
+
+Example
+=======
+
+.. code-block:: console
+
+    qir-xacc $HOME/qiree/examples/bell.ll --accelerator qpp
+
+This command will execute the quantum Bell circuit described in bell.ll the (default) 
+1024 times using the ``qpp`` accelerator.
+
+The resulting output looks like:
+
+.. code-block:: console
+
+    {
+        "AcceleratorBuffer": {
+            "name": "qreg_0x5653927715a0",
+            "size": 2,
+            "Information": {},
+            "Measurements": {
+                "00": 526,
+                "11": 498
+            }
+        }
+    }
+    array <null> length 2
+    qubit 0 experiment <null>: {0: 526, 1: 498}
+    qubit 1 experiment <null>: {0: 526, 1: 498}
+
+
+Software library
+================
+
+TODO