truncated Variational Hamiltonian Ansatz

This repository contains the source code for the Variational Hamiltonian Ansatz VHA and its variant truncated Variational Hamiltonian Ansatz tVHA. It is based on the code of Qiskit and Qiskit Nature.

• truncated Variational Hamiltonian Ansatz
  • Installation
  • First steps
  • Chemistry Drivers for Windows
  • PSI4 (Windows)
  • PyQuante (Windows)
  • Gaussian (Windows)
  • Troubleshooting
  • Contribute your own code
  • How to cite this work

Installation

Download this package from tVHA homepage or clone it via git git clone git@github.com:cpossel/tvha.git.

Go into the main folder of the downloaded folder and run

bash pip install .

For developers it is recommended to run

bash pip install -e .[develop]

To check whether the installation was successful, one can run pip show tvha.

If you are on a Linux system or use WSL, installation is complete after above step. On Windows systems, please check below section.

First steps

The best starting point is to go to the examples folder and check out the files there.

Chemistry Drivers for Windows

A computational chemistry program/library, called "driver", is needed in addition to the Python packages listed in pyproject.toml.

By default, PySCF is already installed on Linux when you follow above instructions.

Since the recommended driver PySCF does not support Windows, the recommended way is to install WSL. If you still want to stick to Windows, you can find the installation instructions below.

For Windows, these drivers are available:

• PSI4 (recommended)
• PyQuante (reduced functionality)
• Gaussian (commercial)

Please be aware that the code must be adjusted in some places to use these drivers instead of PySCF.

PSI4 (Windows)

powershell cd path/to/this/repo conda create -n my_qiskit_env conda activate my_qiskit_env conda install psi4 python=3.12 -c psi4 -c conda-forge pip install .

Above commands create a new conda environment called my_qiskit_psi4_env and install all required packages into it.

Since installing PSI4 is sometimes troublesome, please follow above commands closely. It is important to create a new empty environment from the command line without any python version or package specified before installing PSI4 as done with above commands. Using the Anaconda GUI to create an empty environment didn't work during testing.

Test in a python shell if the installation of PSI4 succeeded:

python import psi4

PyQuante (Windows)

powershell conda install -c rpmuller pyquante2_pure

PyQuante is not actively maintained and contains only very basic functionality. So, use it only if you have no other choice.

Gaussian (Windows)

See Qiskit/Gaussian and Gaussian.

Below guide assumes Gaussian is installed in C:\G16W\. You should adjust the path accordingly.

1. Add g16.exe to PATH

   In conda environment (easiest permanent solution; see also https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#setting-environment-variables):

   powershell conda env config vars set PATH="$env:PATH;C:\G16W"

   Check if it succeeded (might need conda activate <my_env> for changes to take place):

   powershell $env:PATH

   or

   powershell conda env config vars list

   If successful, a warning about overwriting the PATH environment variable arises everytime the conda environment is launched. During 'overwriting' only a path is appended and nothing deleted, so this shouldn't (hopefully) pose any problem.

   Alternatively one of the following approaches can be used (non-permanent):

- In python (before all other imports):

    ```python
    import os
    os.environ["PATH"] += ";C:\G16W"
    ```

- Or in powershell (before starting the python script):

    ```powershell
    $env:Path += ";C:\G16W"
    ```

1. Set GAUSS_EXEDIR environment variable

   Add GAUSS_EXEDIR=C:\G16W permanently to the currently active conda environment:

   powershell conda env config vars set GAUSS_EXEDIR=C:\G16W

   Check if it succeeded (might need conda activate <my_env> for changes to take place):

   powershell $env:GAUSS_EXEDIR

   or

   powershell conda env config vars list

   Now everything should be set up correctly.

   You might get one of the following errors:

   • ImportError: DLL load failed while importing qcmatrixio: Das angegebene Modul wurde nicht gefunden. (The specified module was not found.)
   • qiskit_nature.exceptions.QiskitNatureError: 'qcmatrixio extension not found. See Gaussian driver readme to build qcmatrixio.F using f2py'

   The missing module can be installed via

   powershell conda install -c anaconda intel-fortran-rt

   Alternatively, one can try conda install icc_rt.

Troubleshooting

If you have issues and the documentation didn't help, feel free to open an issue (see also CONTRIBUTING) or write an email to clemens.possel@ict.fraunhofer.de. Be aware that this software comes with no warranty and all support is purely voluntarily.

Contribute your own code

See CONTRIBUTING

How to cite this work

Feel free to use this software. Please be aware that any work and results based on this software shall cite this work (see also license). Therefore use the following publication (or extract it from CITATION.cff):

Possel, C., Hahn, W., Shirazi, R., Walt, M., Pinski, P., Wilhelm, F. K., & Bagrets, D. (2025). Truncated Variational Hamiltonian Ansatz: efficient quantum circuit design for quantum chemistry and material science. arXiv preprint arXiv:2505.19772.

Further publications based on this software are listed here:

Illésová, S., Novák, V., Bezděk, T., Beseda, M., & Possel, C. (2025). Numerical Optimization Strategies for the Variational Hamiltonian Ansatz in Noisy Quantum Environments. arXiv preprint arXiv:2505.22398.