LoQS v1.3

The Logical Qubit Simulator (LoQS) is designed to simulate a few logical qubits with arbitrary noise models and arbitrary quantum and classical operations.

Installation

The following installation instructions can be used on M1/M2 Macs using Anaconda/Miniconda to create a local virtual environment.

conda create -n loqs-env python=3.14
conda activate loqs-env
pip install loqs
# pip install -e . ## for "editable" cloned repo install

There are various optional requirements that are available, including:

• parallel: Enables single-node (loky) and SLURM-array (submitit) parallelization over shots and/or programs. submitit's SLURM-array support requires Linux/macOS -- it registers a POSIX-only signal internally and does not work on Windows.
• mpi: Enables multi-node parallelization over shots and/or programs via mpi4py. Requires a working MPI installation (e.g. OpenMPI/MPICH) already present in the environment -- pip install alone does not provide one.
• dev: Allows the use of black and flake8 prior to committing (see Code Formatting and Linting below).
• docs: Allows building of the documentation (see Documentation below).
• quantumsim: Enables the QuantumSim (state) backend.
• pygsti: Enables the PyGSTi (circuit, model, state) backend.
• pymatching: Enables the PyMatching (minimum-weight perfect matching) decoder for certain codepacks.
• stim: Enables the STIM (state) backend.
• test: Allows testing (see Testing below)
• visualization: Enables some of the visualization tools in loqs.tools. Note that pdflatex is also required for full visualization support.

There are several helper "categories" for optional dependencies, including:

• backends: Packages needed to enable all backends
• nobackends: The complement of backends, i.e. all developer packages with no backends (useful for testing)
• all: All optional dependencies except mpi, which requires a real MPI installation and is deliberately excluded so it stays opt-in -- combine explicitly instead, e.g. pip install -e ".[all,mpi]"

To use these, simply modify the last line of the installation instructions. For example:

pip install -e ".[all]"

(where the quotes are only needed if using zsh instead of bash).

For developers who may want an editable version of pyGSTi, you can run:

pip install -e git+https://github.com/sandialabs/pyGSTi.git@v0.9.14#egg=pyGSTi

to get the 0.9.14 release of pyGSTi, which will be located in src. Alternatively, you can use any other tag or commit hash instead of v0.9.14 if you are working off of a feature branch.

Documentation

This project uses MkDocs and Jupytext-compatible Markdown notebooks under docs/notebooks/ for its documentation and interactive tutorials. In order to build or preview the documentation locally, do at least an installation of loqs[docs].

Local Building & Preview

To build and serve the documentation locally, run:

python docs/serve.py

This will launch a local server typically accessible at http://127.0.0.1:8000/.

More details on the documentation structure and Jupytext workflow are available in docs/DOCS_README.

Interactive Cloud Notebooks (Binder)

The tutorials and examples are configured to be run interactively in the cloud using Binder! You can open any of the tutorial or example notebooks directly in your browser by clicking the "Launch Binder" badges on the generated documentation pages.

Note that the first launch may take up to 5-10 minutes to build the Binder environment.

Contributing Interactive Notebooks

The easiest way to modify and add interactive notebooks is to use loqs-nb-sync, a command-line tool that's automatically installed alongside LoQS when you install the docs extra (pip install ".[docs]").

1. Navigate to docs/notebooks, where all interactive notebooks are kept as Markdown for easy source control.
2. Generate a working Jupyter notebook via loqs-nb-sync to-ipynb <target_to_edit>.md.
3. Edit the notebook, e.g. jupyter lab to start a server, edit, and save.
4. Sync your edits back to Markdown via loqs-nb-sync to-md <target_to_edit>.ipynb.
5. Commit your changes!

Always use loqs-nb-sync for both directions -- converting or syncing these notebooks any other way can leave broken links in the result.