Fragment Interaction Energy¶
The interaction between two water molecules changes their total energy. This tutorial calculates that change for the S22 water dimer. You will define the two fragments, choose an active space, and compare five electronic structure methods in one calculation.
From Fragments To Interaction Energy¶
Each water molecule is one fragment. We call them A and B, and call the complete dimer AB. For each method, q2m3 calculates the interaction energy as
A negative value means that the dimer has lower energy than the separate fragments at the same geometry. All three calculations use the dimer basis. For each monomer, the partner’s atoms retain their basis functions but contribute no nuclei or electrons. These are ghost atoms. This procedure gives the counterpoise-corrected interaction energy.
The workflow first calculates Hartree–Fock (HF) and second-order Møller–Plesset perturbation theory (MP2) energies. It then compares two methods within a selected active space: complete active-space configuration interaction (CASCI) and sample-based quantum diagonalization (SQD). A frozen-core CCSD(T) calculation supplies a reference from the full orbital space when its estimated cost fits the calculation budget.
Prepare The Calculation¶
The example uses the default mode="full" and the cc-pVDZ basis.
Install the optional SQD backend from the repository root:
uv sync --frozen --extra sqd
The SQD backend supports Linux x86_64. For a calculation with only core
dependencies, use mode="classical_only" in the run call below. This mode
returns HF and MP2 energies and the selected active spaces. It skips CASCI,
SQD, CCSD(T), and resource estimates.
Download water-dimer.xyz into your working directory.
The coordinates use Angstrom. Atom indices start at zero, so atoms 0–2 form
fragment A and atoms 3–5 form fragment B.
6
S22 water dimer (system 2), Angstrom; fragment A = atoms 0-2, fragment B = atoms 3-5
O -1.551007 -0.114520 0.000000
H -1.934259 0.762503 0.000000
H -0.599677 0.040712 0.000000
O 1.350625 0.111469 0.000000
H 1.680398 -0.373741 -0.758561
H 1.680398 -0.373741 0.758561
Choose The Active Space¶
CASCI and SQD treat the same selected electrons and orbitals explicitly.
The atomic valence active space (AVAS) procedure selects these orbitals from
the atomic shells you specify. The avas_labels parameter identifies the
shells, and avas_threshold controls the selection. Both parameters require
an explicit value.
For this example, use avas_labels=["O 2p", "H 1s"] and
avas_threshold=0.7. The resulting spaces are:
Subsystem |
Active electrons |
Active orbitals |
SQD qubits |
|---|---|---|---|
Dimer AB |
12 |
8 |
16 |
Monomer A |
6 |
4 |
8 |
Monomer B |
6 |
4 |
8 |
An element label such as "O 2p" selects that shell on every oxygen atom.
An indexed label such as "0 O 2p" refers only to atom 0 in the full
geometry. q2m3 applies the same labels to all three subsystems and retains
only labels on real atoms in each monomer.
The current workflow accepts at most 10 active orbitals per subsystem. For these labels, the PySCF default threshold of 0.2 selects 12 orbitals for the dimer. The example uses 0.7 to obtain the smaller spaces above. q2m3 also checks that the monomer active spaces correspond to the dimer active space before it calculates correlated energies.
Calculate And Display The Energies¶
Run the following Python code from the directory containing
water-dimer.xyz. Molecule.from_xyz assigns the atoms to the two
fragments. run calculates their interaction energies, and render_report
formats the result as Markdown.
>>> from q2m3 import Molecule, run
>>> from q2m3.fragments import render_report
>>> dimer = Molecule.from_xyz("water-dimer.xyz", fragments=[(0, 1, 2), (3, 4, 5)], name="water-dimer")
>>> result = run(dimer, avas_labels=["O 2p", "H 1s"], avas_threshold=0.7)
>>> print(render_report([result]))
# 片段相互作用能报告
...
## 片段 water-dimer（模式 full，基组 cc-pvdz）
...
| HF | -0.005868 | -3.682 | |
| MP2 | -0.006272 | -3.935 | |
| CASCI | -0.005695 | -3.574 | |
| SQD | -0.005669 | -3.557 | |
| CCSD(T) | -0.00589... | -3.699 | |
...
The report currently uses Chinese headings. Its energy columns give \(\Delta E\) in Hartree (Ha) and kcal/mol. In this example, every method gives a negative interaction energy. SQD gives about −3.557 kcal/mol, close to the CASCI value of −3.574 kcal/mol within the same active space.
The result object also stores the energies, active spaces, and resource
estimates for AB, A, and B. Use result.delta_e to access the interaction
energies in Hartree. Continue with Read A Fragment Interaction Report to interpret the method differences and resource
estimates.
Adapt The Calculation¶
For another dimer, replace the geometry and fragment indices first. Then choose AVAS labels for the shells relevant to that interaction. Inspect the selected spaces before you compare energies across geometries.
If the selected monomer and dimer spaces do not correspond, q2m3 raises
ActiveSpaceMismatchError. Revisit the labels and threshold for the whole
dimer. FragmentWorkflowError can also indicate an unsupported active space,
such as one without an active virtual orbital or with more than 10 orbitals.
The exception message identifies the subsystem and the failed condition.
To compare against a reference calculation, add
references=["refs.csv"] to the run call. The CSV needs these columns:
Column |
Content |
|---|---|
|
The molecule name, |
|
The reference method |
|
The reference basis |
|
The reference interaction energy |
|
|
Use a reference for the same geometry and interaction-energy definition. q2m3 classifies a row with the calculation basis as a same-basis reference. It classifies a row with another basis as an external reference. Supply at most one reference in each category. The next tutorial explains how these references enter the energy comparisons.
Keep the geometry and calculation settings with your result.
result.provenance records the geometry hash, basis, AVAS settings, seed,
package versions, and thread settings. Use these records when you repeat
the calculation or compare results from different environments.