ORNL-QCI · wongey · Nov 5, 2025 · Nov 3, 2025 · Nov 3, 2025 · Nov 3, 2025
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -36,8 +36,8 @@ endmacro()
 option(QIREE_BUILD_DOCS "Build QIR-EE documentation" OFF)
 option(QIREE_BUILD_TESTS "Build QIR-EE unit tests" ON)
 option(QIREE_BUILD_EXAMPLES "Build QIR-EE examples" OFF)
-option(QIREE_USE_QSIM "Download and build Google qsim backend" OFF)
-option(QIREE_USE_XACC "Build XACC interface" ON)
+option(QIREE_USE_QSIM "Download and build Google qsim backend" ON)
+option(QIREE_USE_XACC "Build XACC interface" OFF)
 
 qiree_set_default(BUILD_TESTING ${QIREE_BUILD_TESTS})
 

diff --git a/README.md b/README.md
@@ -1,76 +1,88 @@
 # QIR-EE
 
-The QIR Execution Engine library provides interfaces for easily processing
-[Quantum Intermediate
-Representation](https://github.com/qir-alliance/qir-spec/) code using the LLVM
-execution engine.
+The QIR Execution Engine library provides interfaces for processing [Quantum Intermediate Representation](https://github.com/qir-alliance/qir-spec/) code using the LLVM execution engine.
 
 ## Introduction
 
-Welcome to the Quantum Intermediate Representation Execution Engine (QIR-EE), a
-state-of-the-art tool designed to streamline the process of running quantum
-circuits and algorithms. Whether you're a researcher, student, or enthusiast,
-QIR-EE (pronounced 'cure-ee') is designed to make your journey into quantum
-computing as seamless as possible. This implementation is associated to the
-paper [A Cross-Platform Execution Engine for the Quantum Intermediate
-Representation](https://doi.org/10.48550/arXiv.2404.14299) and is maintained by
-the QIR-EE Developers.
+The Quantum Intermediate Representation Execution Engine (QIR-EE, pronounced 'cure-ee') is a tool designed to streamline the process of running quantum circuits and algorithms. One of our goals is to make your journey into quantum computing as seamless as possible. This implementation is associated to the paper [A Cross-Platform Execution Engine for the Quantum Intermediate Representation](https://doi.org/10.1007/s11227-025-07969-2) published in the Journal of Supercomputing, Volume 81, 1521 (2025) and is maintained by the QIR-EE Developers.
 
-At version 0.1, 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.
+This work represents the feasibility of a modular workflow at the lower end of the quantum software stack. We welcome feedback and ideas for collaborations.
 
 ## Documentation
 
-Most of the QIR-EE documentation is readable through the codebase through a
-combination of [static RST documentation](doc/index.rst) and Doxygen-markup
-comments in the source code itself. The full [QIR-EE user
-documentation][user-docs] (including selected code documentation incorporated
-by Breathe) and the [QIR-EE code documentation][dev-docs] are (TODO: will
-be) mirrored on
-our GitHub pages site. You can generate these yourself (if the necessary
-prerequisites are installed) by
-setting the `QIREE_BUILD_DOCS=ON` configuration option and running `make
-doc` (user) or `make doxygen` (developer).
+Most of the QIR-EE documentation is readable through the codebase through a combination of [static RST documentation](doc/index.rst) and Doxygen-markup comments in the source code itself. The full QIR-EE user documentation (including selected code documentation incorporated by Breathe) and the QIR-EE code documentation will be mirrored on our GitHub pages site. You can generate these yourself (if the necessary prerequisites are installed) by setting the option `-DQIREE_BUILD_DOCS=ON` running `make doc` (user) or `make doxygen` (developer).
 
-[user-docs]: https://ornl-qci.github.io/qir-ee/user/index.html
-[dev-docs]: https://ornl-qci.github.io/qir-ee/dev/index.html
+- [user-docs (coming soon)](https://ornl-qci.github.io/qir-ee/user/index.html)
+- [dev-docs (coming soon)](https://ornl-qci.github.io/qir-ee/dev/index.html)
 
 ## Getting Started
 
-There are two dependencies for QIR-EE to work properly. Please make sure to
-download and install the most current versions of:
-1. [LLVM](https://releases.llvm.org/) (we have tested versions 14 through 18)
-2. [XACC](https://github.com/ORNL-QCI/xacc) (repo that is actively
-   maintained -- not the eclipse one; currently required for execution in
-   this version of qir-ee; we recommend setting option `-DQIREE_MINIMAL_BUILD=ON`
-   during cmake for a faster build)
+### Dependencies
 
-### System Requirements
+There is a key dependency for QIR-EE to work properly. Please make sure to download and install the most current version of:
+1. [LLVM](https://releases.llvm.org/) (we have tested versions 14 through 18).
 
-- Access to a compatible quantum computing simulator or real quantum hardware.
-- Configuration files set up in your home folder that contain credential to
-  access vendor backends. (Under construction: Formats for .ionq_config and
-  .honeywell_config.)
+There is an optional dependency for QIR-EE to run on hardware backends.
+
+2. [XACC](https://github.com/ORNL-QCI/xacc): Here, we recommend setting option `-DQIREE_MINIMAL_BUILD=ON` during cmake for a faster build. Follow the [XACC prerequisites](https://xacc.readthedocs.io/en/latest/install.html) page to ensure a smoother installation.
+
+### Requirements for Basic Runs
+
+- Ability to download and build this project with cmake.
 - A QIR file with the quantum program that you want to run (see examples folder).
 
+### (Optional) Credentials for Hardware and Specialized Simulator Runs
+
+- Access to a compatible quantum computing simulator or real quantum hardware.
+- Configuration files set up in your home folder that contain credentials to
+  access vendor backends. This typically takes on the form `.backend_config` depending on the backends you have access to.
+
 ### Installation
 
+
 QIR-EE Setup in Command Line
 
-1. Clone this repo. Enter the repo.
-2. `mkdir build; cd build`
-3. `cmake ..`
-4. `make`
+1. Clone/download/unzip this repo.
 
-The resulting path to executable files can be exported
+2. Enter the repo folder.
+
+3. `mkdir build; cd build`
+
+4. `cmake ..`
+
+5. `make`
+
+By default, we have the following options. These can be adjusted in step 3.
+
+`-DQIREE_BUILD_TESTS=ON`, `-DQIREE_BUILD_DOCS=OFF`, `-DDQIREE_USE_XACC=ON`, `-DQIREE_USE_QSIM=ON`
+
+The resulting path to executable files can be exported as
 
 `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)
+
+### (via QIR-EE and QSIM)
+
+Syntax For basic usage:
+
+```
+qir-qsim llvm-file-path -s num-shots
+```
+
+The default number of shots is 1 if you don't invoke that option.
+
+Example:
+
+```
+qir-qsim $HOME/qiree/examples/teleport.ll -s 100
+```
+
+This command will execute the teleport algorithm described in `teleport.ll` with 100 shots using Google's qsim state simulator, which can handle mid-circuit measurements.
+
+### (via QIR-EE and XACC)
 
 1. Check that your cmake prefixes for XACC are correct.
 2. Typing `echo $CMAKE_PREFIX_PATH` should give you the path to your XACC
@@ -81,9 +93,7 @@ which would allow you to access the QIR-EE from anywhere in command line.
 5. If empty, then add it: `export PYTHONPATH=$PYTHONPATH:$HOME/.xacc` or an
    equivalent path to your XACC installation.
 
-### Syntax for executing QIR via XACC:
-
-For basic usage:
+Syntax For basic usage:
 
 ```
 qir-xacc llvm-file-path --flag-name flag-value
@@ -100,28 +110,17 @@ qir-xacc llvm-file-path --flag-name flag-value
 
    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:
+Example:
 
 ```
 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.
+This command will execute the quantum Bell circuit described in `bell.ll` the (default) 1024 times using the "qpp" accelerator.
 
 ## Understanding the Results
 
-After execution, you will receive a summary of the quantum circuit's results.
-This may include the xacc buffer output. Example outputs from experiments can
-be found here: [qiree-data](https://github.com/wongey/qiree-data).
-
-## Adding Custom Operations
-
-Advanced users can extend the engine's capabilities by introducing new
-operations or functionalities. Please refer to the developer documetation (link
-to be added) for further information.
+After execution, you will receive a summary of the quantum circuit's results. This may include a simple dictionary of counts for qubit strings or the xacc buffer output. Some example outputs from experiments can be found here: [qiree-data](https://github.com/wongey/qiree-data).
 
 ## Directory structure
 
@@ -130,6 +129,7 @@ to be added) for further information.
 | **app**       | Source code for installed executable applications     |
 | **cmake**     | Implementation code for CMake build configuration     |
 | **doc**       | Code documentation and manual                         |
+| **examples**  | A collection of QIR examples                          |
 | **scripts**   | Development and continuous integration helper scripts |
 | **src**       | Library source code                                   |
 | **test**      | Unit tests                                            |

diff --git a/doc/_static/references.bib b/doc/_static/references.bib
@@ -1,6 +1,19 @@
-@misc{wong2024,
-  author = {Wong, E. and Leyton Ortega, V. and Claudino, D. and Johnson, S. and Afrose, S. and Gowrishankar, M. and Cabrera, A. M. and Humble, T. S.},
+@article{wong2025,
+  author = {Wong, E. and Leyton-Ortega, V. and Claudino, D. and Johnson, S. R. and Adams, A. J. and Afrose, S. and Gowrishankar, M. and Cabrera, A. and Humble, T. S.},
   title = {A Cross-Platform Execution Engine for the Quantum Intermediate Representation},
-  year = {2024},
+  year = {2025},
+  journal = {The Journal of Supercomputing},
+  volume = {81},
+  number = {1521},
+  doi = {10.1007/s11227-025-07969-2},
+  url = {https://doi.org/10.1007/s11227-025-07969-2},
   note = {ar{X}iv print available at \url{https://arxiv.org/abs/2404.14299}}
 }
+
+@misc{qireerepo,
+title = {{QIR-EE}},
+author = {{QIR-EE Developers}},
+url = {https://github.com/ORNL-QCI/qiree},
+howpublished = {[Computer Software] \url{https://doi.org/10.11578/qiree/dc.20250114.1}},
+year = {2025},
+}
diff --git a/doc/main/acknowledgments.rst b/doc/main/acknowledgments.rst
@@ -12,7 +12,15 @@
 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.
+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
+initially performed at Oak Ridge National Laboratory as part of the Advanced Integrated
+Development Environments for Quantum Computing (AIDE-QC) project and continued under
+the Modular and Error-Aware Software Stack for Heterogeneous Quantum Computing
+Ecosystems (MACH-Q) project.
+
 
 .. raw:: latex
 

diff --git a/doc/main/installation.rst b/doc/main/installation.rst
@@ -17,12 +17,12 @@ Dependencies
 
 QIR-EE is built using modern CMake_. It has multiple dependencies to operate
 as a full-featured code, but each dependency can be individually disabled as
-needed.
+needed. These dependencies are not all strictly required to build
+and run QIR-EE, but omitting them will disable certain features.
 
 .. _CMake: https://cmake.org
 
-The code requires external dependencies to build with full functionality.
-However, any combination of these requirements can be omitted to enable
+In other words, any combination of these requirements can be omitted to enable
 limited development on experimental HPC systems or personal machines with
 fewer available components.
 
@@ -58,10 +58,36 @@ 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.
 
-Bulding QIR-EE (Basic Functionality with XACC)
+Building QIR-EE (minimal)
 ==============================================
 
-Once you have your build system and a minimal version XACC_ installed with
+Clone the latest development version of QIR-EE:
+
+.. code-block:: console
+
+   $ git clone https://github.com/qiree-project/qiree.git
+
+or download and extract it from the GitHub-generated `zip file`_. Then:
+
+.. code-block:: console
+
+   $ cd qiree
+   $ mkdir build && cd build
+   $ cmake ..
+   $ make
+
+QIR-EE runs from anywhere in terminal provided you add the install folder to your PATH:
+
+.. code-block:: console
+
+   $ export PATH=${YOUR-QIREE-INSTALL-DIR}/bin:$PATH
+
+
+Building QIR-EE (with XACC)
+==============================================
+
+XACC is a programming framework that allows the ability to run QIR files on hardware
+backends. Once you have your build system and a minimal version XACC_ installed with
 
 .. code-block:: console
 

diff --git a/doc/main/introduction.rst b/doc/main/introduction.rst
@@ -8,18 +8,17 @@
 Introduction
 ************
 
-Welcome to the Quantum Intermediate Representation Execution Engine (QIR-EE)
-[#qiree_vers]_, a state-of-the-art tool designed to streamline the process of
-running quantum circuits and algorithms. Whether you're a researcher, student,
-or enthusiast, QIR-EE (pronounced 'cure-ee') is designed to make your journey
-into quantum computing as seamless as possible. This implementation is
-associated to the paper "A Cross-Platform Execution Engine for the Quantum
-Intermediate Representation" [#qiree_paper]_ and is maintained by the QIR-EE
+
+The Quantum Intermediate Representation Execution Engine (QIR-EE, pronounced 'cure-ee')
+[#qiree_vers]_ is a tool designed to streamline the process of running quantum circuits
+and algorithms to make your journey into quantum computing as seamless as possible.
+This implementation is 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 |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.
+At version |release|, this work represents 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.

diff --git a/doc/main/usage.rst b/doc/main/usage.rst
@@ -12,6 +12,22 @@ Using QIR-EE
 
 QIR-EE includes a core set of libraries for internal/external use, applications, and front ends.
 
+Interface Application (qir-qsim)
+================================
+
+The ``qir-qsim`` application processes an LLVM QIR file and dispatches to Google QSim.
+
+Usage::
+
+   ./../build/bin/qir-qsim [OPTIONS] input
+
+   Positionals:
+     input TEXT REQUIRED              QIR input file
+
+   Options:
+     -h,--help                        Print this help message and exit
+     -i,--input TEXT REQUIRED         QIR input file
+     -s,--shots INT [1]               Number of shots
 
 Interface Application (qir-xacc)
 ================================
@@ -41,6 +57,10 @@ Export Path to Executable::
 
 This will allow you to access installed QIR-EE executables from anywhere in command line.
 
+Basic Usage with ``qir-qsim`` Executable::
+
+    qir-qsim llvm-file-path -s num-shots
+
 Basic Usage with ``qir-xacc`` Executable::
 
     qir-xacc llvm-file-path --flag-name flag-value
@@ -52,9 +72,25 @@ With XACC we have tested: ``aer``, ``qpp``, ``qsim``, ``quantinuum:H1-1SC``, ``q
 * 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
+Examples
 =======
 
+Here are some example commands and their expected outputs.
+
+.. code-block:: console
+
+    qir-qsim $HOME/qiree/examples/teleport.ll -s 100
+
+This command will execute the teleport algorithm described in teleport.ll with 100 shots.
+
+The resulting output looks like:
+
+.. code-block:: console
+
+    {"011":21,"101":22,"111":32,"001":25}
+
+Next, we show an example using the XACC interface.
+
 .. code-block:: console
 
     qir-xacc $HOME/qiree/examples/bell.ll --accelerator qpp
@@ -80,9 +116,3 @@ The resulting output looks like:
     array <null> length 2
     qubit 0 experiment <null>: {0: 526, 1: 498}
     qubit 1 experiment <null>: {0: 526, 1: 498}
-
-
-Software library
-================
-
-TODO
diff --git a/src/qirqsim/QsimQuantum.cc b/src/qirqsim/QsimQuantum.cc
@@ -3,7 +3,7 @@
 // See the top-level COPYRIGHT file for details.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //---------------------------------------------------------------------------//
-//! \file qirxacc/QsimQuantum.cc
+//! \file qirqsim/QsimQuantum.cc
 //---------------------------------------------------------------------------//
 
 #include "QsimQuantum.hh"