Create a MolecularConfiguration

Goal

Define a molecule and its quantum chemistry settings as a MolecularConfiguration for use in Kvantify Qrunch calculations.

Prerequisites

Basic familiarity with molecular geometry and basis sets
Optional: An .xyz file containing your molecule

Creation Methods

Choose one of the following methods to build a MolecularConfiguration:

Manual coordinates as a list of tuples

import qrunch as qc

molecular_configuration = qc.build_molecular_configuration(
    [
        ("H", 0.0, 0.0, 0.0),
        ("Li", 1.5474, 0.0, 0.0),
    ],
    basis_set="sto3g",
)

From .xyz file

from pathlib import Path
import qrunch as qc

molecular_configuration = qc.build_molecular_configuration(
    molecule=Path.cwd() / "path/to/molecules/h2.xyz",
    basis_set="sto3g",
)

Optional Settings

Adjust charge, spin difference, or coordinate units (default is Angstrom: units=”angstrom”). Use these with either method above:

import qrunch as qc

molecular_configuration = qc.build_molecular_configuration(
    molecule=[
        ("H", 0.0, 0.0, 0.0),
        ("Li", 1.5474, 0.0, 0.0)
    ],
    basis_set="sto3g",
    charge=1,
    spin_difference=3,
    units="bohr",
)

Basis Set Options

You can also supply basis sets as enums or per-atom-type dictionaries:

As enum:

from qrunch.chemistry.molecule.basis_sets import BasisSet
import qrunch as qc

molecular_configuration = qc.build_molecular_configuration(
    molecule=[("H", 0.0, 0.0, 0.0), ("Li", 1.5474, 0.0, 0.0)],
    basis_set=BasisSet.STO3G,
)

As dictionary:

from qrunch.chemistry.molecule.atom import Atom
from qrunch.chemistry.molecule.basis_sets import BasisSet
import qrunch as qc

basis_set = {
    Atom("Li"): BasisSet.STO3G,
    Atom("H"): BasisSet.PCSEG0,
}

molecular_configuration = qc.build_molecular_configuration(
    molecule=[("H", 0.0, 0.0, 0.0), ("Li", 1.5474, 0.0, 0.0)],
    basis_set=basis_set,
)

As atom specific dictionary:

from qrunch.chemistry.molecule.atom import Atom
from qrunch.chemistry.molecule.basis_sets import BasisSet
import qrunch as qc

basis_set = {
    Atom("O"): BasisSet.STO3G,
    Atom("H"): BasisSet.PCSEG0,
    Atom("H", label="1"): BasisSet.CCPVQZ,
}

molecular_configuration = qc.build_molecular_configuration(
    molecule=[
        ("O", 1.5474, 0.0, 0.0)
        ("H", 0.0, 0.0, 0.0),
        ("H_1", 0.0, 0.0, 0.0),
    ],
    basis_set=basis_set,
)

Here the first hydrogen uses the generic hydrogen basis set (pc-seg-0), while the second hydrogen (with label “1”) uses the cc-pVQZ basis.

An xyz File can also be modified to include labels. A label is provided by appending an integer directly to the atomic symbol..

Standard XYZ format

A standard XYZ file uses plain atomic symbols:

5
This is a comment line
H 0.0 0.0 0.0
C 1.0 0.0 0.0
O 0.0 1.0 0.0
N 0.0 0.0 1.0
H 1.0 1.0 1.0

Labeled atom symbols

Qrunch also accepts labeled atomic symbols, where an integer label is appended directly to the element symbol:

5
This is a comment line
H1 0.0 0.0 0.0
C3 1.0 0.0 0.0
O  0.0 1.0 0.0
N1 0.0 0.0 1.0
H2 1.0 1.0 1.0

In this format:

The element symbol must appear first (e.g. H, C, O)
The label must be a non-negative integer
No separator is used between the symbol and the label
Labels are optional; unlabeled atoms remain valid

The label does not change the chemical identity of the atom. It exists solely to provide a stable identifier for basis set identification.

Verify the Result

Print the MolecularConfiguration to check that atoms, basis sets, charge, spin difference, and units are as expected.
Use it directly in a problem builder.

Troubleshooting

Unknown atom symbol: Check spelling and capitalization (“Li” not “li”).
File not found: Ensure the path to your .xyz file is correct.
Invalid basis set name provided.: Verify that the basis set name is supported.

Next Step

You can use the molecular_configuration to build a ground-state problem:

Construct a Ground State Energy Problem