diff --git a/CMakeLists.txt b/CMakeLists.txt index 85cf22d..05f3e7d 100644 --- a/CMakeLists.txt +++ b/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 #----------------------------------------------------------------------------# diff --git a/README.md b/README.md index bbc0efb..f4e3c06 100644 --- a/README.md +++ b/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,16 +86,18 @@ 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. @@ -99,7 +105,7 @@ 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 diff --git a/doc/conf.py b/doc/conf.py index d92409c..6ea89a2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -71,6 +71,7 @@ 'sphinx.ext.mathjax', 'sphinx.ext.todo', 'sphinx.ext.githubpages', + 'sphinx.ext.autosectionlabel' ] if qiree_config['options']['breathe']: diff --git a/doc/main/acknowledgments.rst b/doc/main/acknowledgments.rst index ad02999..625d3eb 100644 --- a/doc/main/acknowledgments.rst +++ b/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 diff --git a/doc/main/examples.rst b/doc/main/examples.rst deleted file mode 100644 index 0dc8015..0000000 --- a/doc/main/examples.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. Copyright 2024 UT-Battelle, LLC, and other QIR-EE developers. -.. See the doc/COPYRIGHT file for details. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _examples: - -******** -Examples -******** - - diff --git a/doc/main/installation.rst b/doc/main/installation.rst index 3dbe0f6..0e1ed5c 100644 --- a/doc/main/installation.rst +++ b/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 diff --git a/doc/main/introduction.rst b/doc/main/introduction.rst index 14ca5b6..23736f4 100644 --- a/doc/main/introduction.rst +++ b/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` 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`. diff --git a/doc/main/overview.rst b/doc/main/overview.rst deleted file mode 100644 index f200f69..0000000 --- a/doc/main/overview.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. Copyright 2024 UT-Battelle, LLC, and other QIR-EE developers. -.. See the doc/COPYRIGHT file for details. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _overview: - -******** -Overview -******** - -This section summarizes key usage patterns and implementation details from -QIR-EE. diff --git a/doc/main/usage.rst b/doc/main/usage.rst index d3ccc69..46f2752 100644 --- a/doc/main/usage.rst +++ b/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 length 2 + qubit 0 experiment : {0: 526, 1: 498} + qubit 1 experiment : {0: 526, 1: 498} + + +Software library +================ + +TODO