Chemistry Library Installation and Validation

The Quantum Development Kit provides support for quantum chemistry applications through the Microsoft.Quantum.Chemistry NuGet package. As with other NuGet packages, it's straightforward to add the chemistry library to your project.

Visual Studio 2017: If you are using Visual Studio 2017, you can add the quantum chemistry packages by using the NuGet Package Manager. To open the Package Manager, right-click on the project you'd like to add the chemistry library to and select "Manage NuGet Packages...," as in the screenshot below.

From the Browse tab, search for the package name "Microsoft.Quantum.Chemistry."

Note

Make sure to tick "Include prerelease."

This will list the packages available for download. Click on the "Microsoft.Quantum.Chemistry on the left-hand pane, select the latest pre-release version on the right-hand pane, and click "Install":

For more details, see the Package Manager UI guide.

Alternatively, you can use the Package Manager Console to add the quantum chemistry library to your project with a command line interface.

From the package manager console, run the following:

Install-Package Microsoft.Quantum.Chemistry

For more details, see the Package Manager Console guide.

Command line or Visual Studio Code 2017: Using the command line on its own or from within Visual Studio Code, you can use the dotnet command to add NuGet package reference to your project:

dotnet add package Microsoft.Quantum.Chemistry

Verifying Your Installation

Like the rest of the Quantum Development Kit, the quantum chemistry library comes with a number of fully documented samples to help you get up and running quickly. To test your installation using these samples, clone the main samples repository, then run one of the samples. For example, to run the [MolecularHydrogen] sample:

git clone https://github.com/Microsoft/Quantum.git
cd Quantum/Chemistry/MolecularHydrogen
dotnet run

To verify the installation of the quantum chemistry library using Microsoft Visual Studio after cloning the repository:

  1. Open the ChemistrySamples.sln solution in the Chemistry folder.
  2. Select Samples/1. Simple Molecules/MolecularHydrogen as the StartUp project.
  3. Press F5 to run the molecular Hydrogen quantum phase estimation demo.

See Obtaining energy level estimates for more information on estimating the values of energy levels.

Using the Quantum Development Kit with NWChem

The MolecularHydrogen sample uses molecular input data that is manually configured. While this is fine for small examples, quantum chemistry at scale require Hamiltonians with millions or billions of terms. Such Hamiltonians, generated by scalable computational chemistry packages are too large to import by hand.

The quantum chemistry library for the Quantum Development Kit is designed to work well with computational chemistry packages, most notably the NWChem computational chemistry platform developed by the Environmental Molecular Sciences Laboratory (EMSL) at Pacific Northwest National Laboratory. In particular, the Microsoft.Quantum.Chemistry package provides tools for loading instances of quantum chemistry simulation problems represented in the Broombridge schema, also supported for export by recent versions of NWChem.

To get up and running using NWChem together with the Quantum Development Kit, we suggest one of the following methods:

See End-to-end with NWChem for more information on how to work with NWChem to chemical models to analyze with the Quantum Developmen Kit chemistry library.

Getting started using Broombridge files provided with the samples

The IntegralData/YAML folder in the Quantum Development Kit Samples repository contains Broombridge-formated molecule data files.

As a simple example, use the chemistry library sample, GetGateCount to load the Hamiltonian from one of Broombridge files and perform gate estimates of quantum simulation algorigthms:

cd Quantum/Chemistry/GetGateCount
dotnet run -- --path=../IntegralData/YAML/h2.yaml --format=YAML

See Loading a Hamiltonian from file for more information on how to input molecules represented by the Broombridge schema.

See Obtaining resource counts for more information on resource estimation.

Getting started using the EMSL Arrows Builder

EMSL Arrows is a tool that uses NWChem and chemical computational databases to generate molecule data. EMSL Arrows Builder for the Microsoft Quantum Development Kit allows you to enter your model using multiple molecular model builders and generate the Broombridge datafile to be used by the Quantum Development Kit.

From the EMSL page, click on the ['Instuctions'] tab, and follow the ['Simple Examples'] instructions to generate Broombridge files. Then try running the ['GetGateCount'] to see the quantum resource estimates for these molecules.

Installing NWChem from Source

Full instructions on how to install NWChem from source are provided by PNNL.

Tip

If you wish to use NWChem from Windows 10, the Windows Subsystem for Linux is a great option. Once you have installed Ubuntu 18.04 LTS for Windows, run ubuntu18.04 from your favorite terminal and follow the instructions above to install NWChem from source.

Once you have compiled NWChem from source, you can run the yaml_driver script provided with NWChem to quickly produce Broombridge instances from NWChem input decks:

$NWCHEM_TOP/contrib/quasar/yaml_driver input.nw

This command will create a new input.yaml file in the Broombridge format within your current directory.

Using NWChem with Docker

Pre-built images for using NWChem are available cross-platform via Docker Hub. To get started, follow the Docker installation instructions for your platform:

Tip

If you are using Docker for Windows, you will need to share the drive containing your temporary directory (usually this is the C:\ drive) with the Docker daemon. See the Docker documentation for more details.

Once you have Docker installed, you can either use the PowerShell module provided with the Quantum Development Kit samples to run the image, or you can run the image manually. We detail using PowerShell here; if you would like to use the Docker image manually, please see the documentation provided with the image.

Running NWChem through PowerShell Core

To use the NWChem Docker image with the Quantum Development Kit, we provide a small PowerShell module that handles moving files in and out of NWChem for you. If you don't already have PowerShell Core installed, you can download it cross-platform from the PowerShell repository on GitHub.

Note

PowerShell Core is also used for some samples to demonstrate interoperability with data science and business analytics workflows.

Once you have PowerShell Core installed, import InvokeNWChem.psm1 to make NWChem commands available in your current session:

cd Quantum/utilities/
Import-Module ./InvokeNWChem.psm1

This will make the Convert-NWChemToBroombridge command available in your current PowerShell session. To download any needed images from Docker and use them to run NWChem input decks and capture output to Broombridge, run the following:

Convert-NWChemToBroombridge ./input.nw

This will create a Broombridge file by running NWChem on input.nw. By default, the Broombridge output will have the same name and path as the input deck, with the .nw extension replaced by .yaml. This can be overridden by using the -DestinationPath parameter to Convert-NWChemToBroombridge. More information can be obtained by using PowerShell's built-in help functionality:

Convert-NWChemToBroombridge -?
Get-Help Convert-NWChemToBroombridge -Full