Before you begin

Chapter focus

What background and software do you need to complete this tutorial?

Lab notebook assignment

Download the blank Markdown lab notebook and save a working copy in the tutorial folder. This is a note-taking document, not a Jupyter notebook. Follow Set up your lab notebook after completing the software setup below. Complete Setup and provenance before running a scientific calculation. This record identifies the QDK/Chemistry version used for the tutorial.

Audience and prerequisites

This tutorial is intended for advanced undergraduate and early-stage graduate students. You should be able to read and modify basic scientific Python and interpret numerical output. You are ready to begin if you can perform the following tasks with reference material available:

  • Use NumPy arrays in a short Python calculation and interpret its numerical output.

  • Explain how eigenvalues and eigenvectors relate to the time-independent Schrödinger equation.

  • Describe molecular orbitals and electron configurations qualitatively.

  • Explain how quantum gates change qubit states and how measurement produces classical outcomes.

The tutorial does not assume prior knowledge of active-space methods, fermion-to-qubit encodings, quantum state preparation, or quantum phase estimation (QPE). The tutorial introduction provides the chemistry and quantum-computing context needed to begin, and the specialized methods are developed before they are used in calculations. Use the Python tutorial, the NumPy fundamentals, and the quantum-computing concepts overview to refresh prerequisite material.

Computer requirements

These are practical requirements for completing the tutorial rather than the full package support matrix. A supported 64-bit computer with at least 8 GiB of memory and 3 GiB of free storage is the minimum recommended configuration. For the final simulator workflow, 16 GiB of memory and a recent multicore processor provide more comfortable headroom. A GPU is not required.

The installed tutorial environment occupies approximately 1.5 GiB.

Required software

The required examples use Visual Studio Code, Python, and implementations provided directly by QDK/Chemistry. They do not require Qiskit, OpenFermion, or the Quantum Resource Estimator.

Install the desktop version of Visual Studio Code, the Microsoft Quantum Development Kit extension, the Python extension, and the Jupyter extension. These extensions provide the quantum-language, Python, Jupyter notebook, simulation, debugging, and visualization features used by the tutorial.

Q# is the QDK’s primary quantum programming language for expressing, inspecting, and executing logical circuits. The QDK also supports quantum programs built with Python frameworks such as Qiskit and Cirq. The QDK extension provides Q# language support, while the required tutorial’s Python scripts use QDK/Chemistry to generate the Q# circuit representations examined in later chapters. Create a folder for your downloaded tutorial files, then use File > Open Folder in Visual Studio Code to open it as your tutorial working folder.

Use Python 3.10 or later on a platform supported by QDK/Chemistry. Released packages support Linux on x86-64 and Arm64, macOS on Apple silicon, and Windows on x86-64 and Arm64 through the Windows Subsystem for Linux. The installation instructions contain the current support matrix. Check the version before creating the environment:

python3 --version

Continue if the command reports Python 3.10 or later; otherwise, install a newer version of Python.

Python environment setup

Use an isolated Python environment so that the tutorial dependencies do not conflict with packages used by other projects. In Visual Studio Code, select Terminal > New Terminal. From this integrated terminal, create and activate a virtual environment in the tutorial working folder:

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

The activation command above applies to Linux, macOS, and the Windows Subsystem for Linux. Install the released QDK/Chemistry package into the active environment:

python -m pip install --upgrade pip
python -m pip install qdk-chemistry==2.1.0 "ipykernel>=6.0"

This command installs the QDK/Chemistry release that matches this documentation and the Python kernel used to run the interactive Jupyter notebooks. QDK/Chemistry already requests QDK’s Jupyter support, which supplies the molecular-orbital widget used in Choosing the active space. The required workflow does not use the all, qiskit-extras, or qre optional-dependency groups. Keep the environment active while completing the tutorial.

Setup check

Download tutorial_qpe_setup.py into the tutorial working folder. Open the file in Visual Studio Code and review the complete script, including imports and setup code that may not appear in the excerpts below. Then run it from the Visual Studio Code integrated terminal:

python tutorial_qpe_setup.py

The script reports the active Python environment to help diagnose setup problems. It also verifies that the built-in QDK/Chemistry implementations required by the tutorial calculations are available.

The check succeeds when it finishes without an exception, reports a Python executable from the tutorial virtual environment, reports QDK/Chemistry version 2.1.0, confirms the IPython kernel and molecular viewer are importable, and confirms that all required built-in implementations are available. Record the QDK/Chemistry version and verification result in Setup and provenance. If the import or verification fails, confirm that the Python executable path contains the virtual-environment directory and compare the installation command with the installation instructions.

How to use the tutorial

Complete the required chapters in the order listed in the tutorial introduction because each stage uses decisions and results recorded earlier. For each chapter:

  1. Download the complete example files and open them in Visual Studio Code.

  2. Read the complete file, including imports and setup code omitted from the excerpts in the chapter.

  3. Read the chapter explanation before running the example.

  4. Run the Python example in the Visual Studio Code integrated terminal, and run any interactive Jupyter notebook as directed by the chapter.

  5. Complete the understanding check, when present.

  6. Update the linked section of the lab notebook before continuing.

In a Check your understanding section, answer each question before selecting its heading to reveal the suggested answer. Select the heading again to hide the answer.

What happens when you click on a question box (after you’ve answered the question)?

You can check your answer.

Use links to the reference documentation when you need complete application programming interface (API) details.

Further reading