Create a MolecularConfiguration

Goal

Define a molecule and its quantum chemistry settings as a MolecularConfiguration.

The molecular configuration is a key component of a typical workflow for a quantum chemistry calculation which follows three main steps:

1. Define the molecular configuration: Specify the atoms, their coordinates, and the basis set. This creates a molecular configuration that encodes the physical system you want to study.

2. Build the problem: Use the molecular configuration to construct a problem object (such as a ground state energy problem). This bundles all necessary quantum-chemical data (integrals, electron counts, etc.) for the calculation.

3. Choose and run the calculator: Select a calculator (e.g., FAST-VQE, BEAST-VQE, ADAPT-VQE) that knows how to solve the problem. The calculator takes the problem object and computes the desired properties, such as the total energy.

This “molecule → problem → calculator” flow ensures a clear separation between system definition, problem formulation, and computational method, making it easy to swap components.

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:

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", 2.9242, 0.0, 0.0)
    ],
    basis_set="sto3g",
    charge=1,
    spin_difference=3,
    units="bohr",
)

Basis Set Options

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

• As string:

  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="sto-3g",
  )
  

• As dictionary:

  In this case, you can specify different basis sets for different atom types.

  There are three options for specifying basis sets per atom, in decreasing order of precedence:

  1. Use a labeled atomic symbol (e.g., "H_1", "O_2") to target specific atoms.

  2. Use the atomic symbol as the key (e.g., "H", "O", "C"). This applies to all atoms of that element.

  3. Use the special key "DEFAULT" to set a default basis set for all atoms not explicitly specified.

  import qrunch as qc
  
  basis_set = {
      "DEFAULT": "sto-3g",
      "H": "pc-seg-0",
      "H_1": "cc-pvqz",
  }
  
  molecular_configuration = qc.build_molecular_configuration(
      molecule=[
          ("O", 1.5474, 0.0, 0.0),
          ("H_1", 0.0, 0.0, 0.0),
          ("H_2", 0.0, 0.0, 0.0),
      ],
      basis_set=basis_set,
  )
  

  This example sets a default basis of STO-3G for all atoms, but overrides it for hydrogens.

  The first hydrogen (with label 1) uses the cc-pVQZ basis specifically for that labelled atom, while the second hydrogen (with label 2) uses the generic hydrogen basis set (pc-seg-0).

In the same way as labels are used to point to a specific atom in the example above, 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.

Adding Solvent

A solvent environment can be added by first creating a solvent model, e.g., PCM using a water solvent:

solvent_model = qc.solvent_creator().pcm(solvent="water").create()

And then adding it to the molecular configuration:

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",
    solvent=solvent_model,
)

See Create a Solvent Model for more information about how to create solvent models.

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.

See Also

• API reference: Molecule

• API reference: MolecularConfiguration

Next Step

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

• Construct a Ground State Energy Problem