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 2019: If you are using Visual Studio 2019, 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."
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:
For more details, see the Package Manager Console guide.
Command line or Visual Studio Code: 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
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:
- Get started using existing Broombridge files provided with the samples at IntegralData/YAML.
- Use the EMSL Arrows Builder for the Microsoft Quantum Development Kit which is a web-based frontend to NWChem, to generate new Broombridge-formated molecular input files.
- Use the Docker image provided by PNNL to run NWChem, or
- Compile NWChem for your platform.
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.
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:
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:
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.
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:
This will create a Broombridge file by running NWChem on
By default, the Broombridge output will have the same name and path as the input deck, with the
.nw extension replaced by
This can be overridden by using the
-DestinationPath parameter to
More information can be obtained by using PowerShell's built-in help functionality:
Convert-NWChemToBroombridge -? Get-Help Convert-NWChemToBroombridge -Full