Getting Started

This guide will help you install Kvantify Qrunch, run your first molecular simulation, and understand the basic workflow.

Prerequisites 

You will need the following:

to use Qrunch, you need a personal license and associated repository URL from Kvantify. Go to https://kvantify.com/products/qrunch to see licensing options.
Python 3.11 available on your system. The QDK is only tested for Python 3.11 and is thus the recommended Python version. Python 3.11 is also the minimum required version of the package.
Conda or uv to create and manage Python environments (optional but recommended).

Installation 

We first need to install the Kvantify Qrunch.

Installation Steps 

(Optional) create and activate a fresh environment.

Conda

conda create --name qrunch-user-env python=3.11
conda activate qrunch-user-env

venv

python3.11 -m venv .venv
source .venv/bin/activate

uv

mkdir qrunch-user-env
cd qrunch-user-env
uv init -p 3.11

Install Kvantify Qrunch:
With pip
Install qrunch using pip from the provided url:
pip install qrunch --extra-index-url $KVANTIFY_INDEX_URL
With uv
Install qrunch using uv from the provided url:
uv add qrunch --index $KVANTIFY_INDEX_URL source .venv/bin/activate
where the last line may be omitted if you run your scripts using uv run ….
where $KVANTIFY_INDEX_URL is the URL provided to you by Kvantify along with your license. It is a token-based Cloudsmith repository URL of the form: https://dl.cloudsmith.io/{TOKEN}/kvantify/qrunch/python/simple/ with {TOKEN} replaced by your personal token.

Troubleshooting 

Python version error: Ensure the interpreter is 3.11.
```
python -V
```
If not 3.11, activate the correct env (see Step 1).

Open Sources Notice 

This product makes use of open-source software.

Python Dependencies

A list of Python packages used by this software is available in the wheel metadata. Each dependency is provided under its respective open-source license, as listed on PYPI.

Compiled Library

This product distributes a precompiled version of the open-source package `cppe`, licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). The corresponding source code, license text, and build information are available as a python source wheel via the same distribution channel as the precompiled wheel. This wheel is identical to the one found on the cppe project on PYPI. Our terms do not restrict reverse engineering where necessary to debug modifications to `cppe` as permitted under the LGPL-3.0.

Register a License 

Before we can run the first molecular simulation, we need to register a valid Kvantify Qrunch license.

Prerequisites 

You will need the following:

A valid Kvantify Qrunch license file (.txt).
The file path to your license file.

Options 

Use the wheel entrypoint (recommended)

After installing the wheel, you can run the following command in your terminal or command prompt:
```
qrunch.license add {path/to/the/license.txt}
```
Replace {path/to/the/license.txt} with the actual path to your license file.

If you have previously installed a license, you can overwrite it by adding the –overwrite flag.

Also, to show your registered license, you can run the show command:
```
qrunch.license show
```
Use the Python API

Add the following imports at the top of your Python script:
```
from pathlib import Path
import qrunch as qc
```
Replace path/to/the/license.txt with the actual path to your license file:
```
qc.register_license_file("path/to/the/license.txt")
```

Verification 

If the license is registered successfully, Kvantify Qrunch will run without license-related errors. If there is a problem (e.g., file not found or invalid license), you will receive a clear error message at runtime.

The license file is cached in your user config folder (alongside other apps’ preferences), so you only have to do this once. It does not need to be in every script.

Your First Quantum Chemistry Calculation 

In this example, we calculate the ground state energy of the Lithium Hydride (LiH) molecule using a minimal basis set (STO-3G) and the FAST Variational Quantum Eigensolver (FAST-VQE).

Note

If the names below sound new, skim Quantum Circuits for Computational Chemists and What Is an Adaptive-VQE and FAST-VQE for the chemistry to quantum translation and why FAST-VQE is the superior method for NISQ ( Noisy Intermediate-Scale Quantum) devices.

Full Script 

The script below shows the minimal setup to define the molecule, build the ground state problem, and run the calculation.

"""Run FAST-VQE on LiH as the first script."""

import qrunch as qc



def main() -> float:
    """Run FAST-VQE on LiH as the first script."""
    # Build molecular configuration for Lithium Hydride (LiH) molecule.
    molecular_configuration = qc.build_molecular_configuration(
        molecule=[
            ("H", 0.0, 0.0, 0.0),
            ("Li", 1.5474, 0.0, 0.0),
        ],
        basis_set="sto3g",
    )

    # Build the ground state problem.
    problem_builder = qc.problem_builder_creator().ground_state().standard().create()
    ground_state_problem = problem_builder.build_restricted(molecular_configuration)

    fast_vqe_calculator = qc.calculator_creator().vqe().iterative().standard().create()

    result = fast_vqe_calculator.calculate(ground_state_problem)

    return result.total_energy.value


if __name__ == "__main__":
    main()

We will now explain this script line by line.

Explanation 

Import the QDK library

import qrunch as qc

import qrunch as qc loads the public and stable API. This is the only import you need for most tasks, and the only one that is guaranteed to be supported across versions.

Define the molecular configuration

    # Build molecular configuration for Lithium Hydride (LiH) molecule.
    molecular_configuration = qc.build_molecular_configuration(
        molecule=[
            ("H", 0.0, 0.0, 0.0),
            ("Li", 1.5474, 0.0, 0.0),
        ],
        basis_set="sto3g",
    )

We specify a simple Lithium Hydride molecule with Cartesian coordinates (in Ångström) and the minimal basis set STO-3G.

Build the ground state problem

    # Build the ground state problem.
    problem_builder = qc.problem_builder_creator().ground_state().standard().create()
    ground_state_problem = problem_builder.build_restricted(molecular_configuration)

The problem_builder is an object that can construct the electronic structure problem of a given molecular configuration. Thus this define how to obtain the molecular integrals and the active space.

The problem_builder.build_restricted(molecular_configuration) create the restricted ground state electronic structure problem (The molecular integrals, etc.) for LiH.

Create the VQE calculator

    fast_vqe_calculator = qc.calculator_creator().vqe().iterative().standard().create()

The calculator defines the quantum algorithm used to solve the problem. By default, the adaptive VQE pipeline selects FAST-VQE for a compact, hardware-friendly ansatz. The calculation is done using our proprietary ExcitationGateSimulator (a quantum simulator optimized for chemistry) as default.

Calculate the energy

    result = fast_vqe_calculator.calculate(ground_state_problem)

Calling fast_vqe_calculator.calculate(ground_state_problem) performs the actual calculation and returns a result object.

The result object contains the total energy and other properties of the calculated ground state.

Running the Example 

After saving the script as run_lithium_hydride.py, you can run it directly from the command line:

$ python run_lithium_hydride.py

You should see output similar to the following:

Total energy:  -7.882245617108695

Tip

Values vary slightly due to numerical precision. If your value is close, the setup works.

Set Up Access to a Quantum Computer (Optional)

If you want to run calculations on a real quantum computer, you need to set up access to a quantum backend.

Amazon Web Services (AWS) Braket 

Set up an AWS account with Braket permissions and then configure the AWS CLI, For more details, see Setting up access to AWS Braket.

validation:

Ensure that your AWS CLI is configured correctly by running:
```
aws braket get-device --device-arn arn:aws:braket:::device/quantum-simulator/amazon/sv1 --region us-east-1
```
This command should return a json response with device details.
After the AWS CLI is correctly configured, Qrunch can be smoke tested against Braket by running the script in aws_configuration_test.py, provided in the .data/scripts folder of the Qrunch wheel. This demonstrates that Kvantify Qrunch can communicate with AWS Braket and that it has permissions to execute a tiny test job on an online state-vector simulator (SV1).

The script is a modified version of the script above, modified in two places:
1. In the import section. we additionally import the braket Devices enum to select a device:
from braket.devices import Devices import qrunch as qc
1. We create a sampler using the Amazon Braket backend, and add it to the calculator. In the FAST-VQE algorithm, the sampler is used during gate selection, so it must be provided there:
# Create an Amazon Braket SV1 sampler braket_sampler = qc.sampler_creator().backend().choose_backend().amazon_braket(Devices.Amazon.SV1).create() # Use a FAST gate selector with the Braket sampler gate_selector = qc.gate_selector_creator().fast().with_sampler(braket_sampler).with_shots(10).create() fast_vqe_calculator = ( qc.calculator_creator().vqe().iterative().standard().with_gate_selector(gate_selector).create() )
The script can be run as above, and you should see that it runs on the Braket SV1 simulator. You can change the device to any other supported Braket device, including real quantum hardware.

IQM resonance 

Set up an IQM account and get your personal token from the web dashboard (login here: IQM Resonance). Login to the web dashboard with your credentials.

validation: After setting up your IQM account, Qrunch can be smoke tested against IQM Resonance by modifying the script above in two places:

    # Create an IQM Resonance sampler
    iqm_sampler = (
        qc.sampler_creator()
        .backend()
        .choose_backend()
        .iqm_resonance(
            token="{your_token}",  # Replace with your IQM token
            device="emerald:mock",  # Simulated quantum device
        )
        .create()
    )

    # Use a FAST gate selector with the IQM sampler
    gate_selector = qc.gate_selector_creator().fast().with_sampler(iqm_sampler).with_shots(10).create()

    fast_vqe_calculator = (
        qc.calculator_creator().vqe().iterative().standard().with_gate_selector(gate_selector).create()
    )

Here, we create a sampler using the IQM Resonance backend, and add it to the calculator. In the FAST-VQE algorithm, the sampler is used during gate selection, so it must be provided there:

Now the script can be run as before, and you should see that it runs on the IQM Resonance Emerald mock. The “mock” device validates the behavior of the real Emerald quantum computer but returns random results. Since the mock device is not a simulator, the results will not correspond to the expected energy. To run in a real quantum device, replace “emerald:mock” with “emerald”, or any of the other options not ending in “mock”. You can change the device to any other supported IQM device, including real (non-mock) quantum hardware.

Next Steps 

You are now up and running and can now investigate the documentation to explore how to:

See Create a MolecularConfiguration to change basis set, specify spin, using an xyz file to specify coordinates.
See Construct a Ground State Energy Problem to choose an unrestricted calculation, or define an active space.
See Calculate the Ground State Energy Using the FAST-VQE to customize the calculator.