Fragment Interaction API

The fragment API computes counterpoise-corrected interaction energies of two-fragment dimers. run and Molecule are also top-level exports of q2m3. mode="classical_only" needs only the core install. mode="full" needs the sqd extra and Linux x86_64. See Fragment Interaction Energy for a complete run.

Workflow

q2m3.fragments.run(molecule, *, avas_labels, avas_threshold, basis='cc-pvdz', mode='full', references=None, seed=0, lucj=None, reference=None, ccsd_t_budget=None)[source]

Compute counterpoise-corrected interaction energies of molecule.

A dimer gives a FragmentInteractionResult. A single molecule gives the SubsystemResult of subsystem "M". Both modes select the AVAS active spaces and, for a dimer, check their correspondence before any correlated step. Both modes compute HF and frozen-core MP2. mode="classical_only" never builds the SQD stage runner. mode="full" also runs the frozen-core CCSD(T) reference when its predicted cost fits ccsd_t_budget (default CCSDTBudget()), builds the active-space integrals, runs SQD for all subsystems in one child interpreter, and estimates the QPE and SQD resources. A rejected CCSD(T) leaves e_ccsd_t null with the reason.

references holds reference files, read by import_references with the fragment id and basis of this run, and ExternalReference records. They form the active-space, basis and model error terms of a dimer result.

Raises:

  • TypeError – avas_labels is not a sequence of strings, avas_threshold is not a real number, or references is a single string or path.

  • ValueError – mode is not "full" or "classical_only", an AVAS label is malformed or matches no AO, or references is given for a single molecule.

  • ImportError – mode="full" and the optional sqd backend is missing.

  • ReferenceImportError – A reference file violates the import format, or two references share a category.

  • FragmentWorkflowError – The RHF or the CCSD of a subsystem does not converge, or label resolution, the ghost guard or the preflight rejects an active space.

  • ActiveSpaceMismatchError – The monomer active spaces do not correspond to the dimer active space.

Parameters:

  • molecule (Molecule)

  • avas_labels (Sequence[str])

  • avas_threshold (float)

  • basis (str)

  • mode (str)

  • references (Sequence[str | PathLike[str] | ExternalReference] | None)

  • seed (int)

  • lucj (Any)

  • reference (Any)

  • ccsd_t_budget (Any)

Return type:

FragmentInteractionResult | SubsystemResult

class q2m3.fragments.Molecule(symbols, coordinates_angstrom, fragments, charges, multiplicities, name=None)[source]

Geometry in Angstrom, with an optional split into two fragments.

charges and multiplicities hold one entry per fragment, or one entry for a single molecule (fragments is None).

Parameters:

  • symbols (tuple[str, ...])

  • coordinates_angstrom (tuple[tuple[float, float, float], ...])

  • fragments (tuple[tuple[int, ...], tuple[int, ...]] | None)

  • charges (tuple[int, ...])

  • multiplicities (tuple[int, ...])

  • name (str | None)

classmethod from_xyz(source, *, fragments=None, charges=None, multiplicities=None, name=None)[source]

Build a molecule from an XYZ file path or XYZ text in Angstrom.

A string that contains no newline is read as a file path.

Raises:

ValueError – The XYZ text is malformed, an element is unknown, the fragments are not exactly two non-empty sets that partition the atoms, the number of charges or multiplicities does not match the fragments, or a multiplicity is not 1.

Parameters:

  • source (str | PathLike[str])

  • fragments (Sequence[Sequence[int]] | None)

  • charges (Sequence[int] | None)

  • multiplicities (Sequence[int] | None)

  • name (str | None)

Return type:

Molecule

property charge: int

Total charge of the molecule.

geometry_sha256()[source]

Lowercase hex SHA-256 of the geometry and fragment definition.

The digested bytes are compact ASCII JSON with sorted keys (json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True)). The payload keys are symbols, coordinates_angstrom (lists of Python float), fragments (lists of atom indices, or null), charges and multiplicities. name is not digested.

Return type:

str

Result Contracts

class q2m3.fragments.result.FragmentInteractionResult(*, schema_version='fragments.result.v1', fragment_id, mode, basis, subsystems, delta_e, references, errors, correspondence, provenance, null_reasons, warnings=())[source]

Counterpoise-corrected interaction energies of one fragment dimer, in Ha.

delta_e maps each layer in ENERGY_LAYERS to E(AB) - E(A) - E(B), all three in the dimer basis. Null entries of delta_e and errors have null_reasons entries under dotted keys such as delta_e.casci and errors.model.

Parameters:

  • schema_version (str)

  • fragment_id (str)

  • mode (str)

  • basis (str)

  • subsystems (Mapping[str, SubsystemResult])

  • delta_e (Mapping[str, float | None])

  • references (tuple[ExternalReference, ...])

  • errors (ErrorDecomposition)

  • correspondence (CorrespondenceReport | None)

  • provenance (Mapping[str, Any])

  • null_reasons (Mapping[str, str])

  • warnings (tuple[str, ...])

validate()[source]

Recompute the interaction energies and check the null reasons.

Raises:

ValueError – The subsystems are not AB, A, B; a classical-only result holds an SQD record, or a full result lacks one; the provenance lacks a required key; a stored interaction energy or error term differs from the recomputed one by more than DELTA_E_TOLERANCE_HA; the model error is not the sum of the active-space and basis errors; the recorded same-basis reference source is not the one used; a reference category is unknown or repeated; or a null field has no reason.

Return type:

FragmentInteractionResult

class q2m3.fragments.result.SubsystemResult(*, name, real_atoms, ghost_atoms, n_ao, e_hf, e_mp2, e_ccsd_t, e_casci, e_sqd, active_space, sqd, resources, null_reasons)[source]

Energies and records of one subsystem: AB, A, B, or M (one molecule).

Every None field has a null_reasons entry under its field name; a missing resource estimate uses resources.<qpe|sqd>. Each resource slot holds only an estimate from that slot’s estimator. e_sqd and e_casci are derived from sqd by promote_sqd_energies().

Parameters:

  • name (Literal['AB', 'A', 'B', 'M'])

  • real_atoms (tuple[int, ...])

  • ghost_atoms (tuple[int, ...])

  • n_ao (int)

  • e_hf (float | None)

  • e_mp2 (float | None)

  • e_ccsd_t (float | None)

  • e_casci (float | None)

  • e_sqd (float | None)

  • active_space (ActiveSpaceRecord | None)

  • sqd (SQDResult | None)

  • resources (Mapping[str, ResourceEstimate | None])

  • null_reasons (Mapping[str, str])

validate()[source]

Check the null reasons, the resource slots and the SQD record.

Raises:

ValueError – A null field has no null_reasons entry; a resource key is not qpe or sqd; a resource slot holds something other than an estimate from that slot’s estimator; sqd is not exactly an SQDResult or fails its own validation; the active space is not the one of the SQD run; or e_sqd or e_casci differs from the value derived from sqd.

Return type:

SubsystemResult

References And Report

q2m3.fragments.import_references(path, *, fragment_id, basis)[source]

Read the references of fragment_id from a CSV or QCSchema JSON file.

A reference whose basis equals basis (ignoring case) is a same-basis full-space reference; any other is an external reference. Values are returned in Ha.

Raises:

ReferenceImportError – The file is neither .csv nor .json; a CSV column is missing; a unit is not Ha, kcal/mol or kJ/mol; a value is not a number; no CSV row has fragment_id; or the QCSchema record lacks a field or names another fragment.

Parameters:

  • path (str | PathLike[str])

  • fragment_id (str)

  • basis (str)

Return type:

tuple[ExternalReference, …]

class q2m3.fragments.result.ExternalReference(fragment_id, method, basis, delta_e, category)[source]

Imported interaction energy of one fragment dimer, in Ha.

category is "same_basis_full_space" when basis is the workflow basis and "external" otherwise.

Parameters:

  • fragment_id (str)

  • method (str)

  • basis (str)

  • delta_e (float)

  • category (str)

q2m3.fragments.render_report(results, *, ks_table=None)[source]

Return one Markdown report for all fragment results of one call.

Parameters:

  • results (Sequence[FragmentInteractionResult]) – Fragment results to report, in report order.

  • ks_table (Mapping[str, float] | None) – Experimental labels mapped to imported Ks values. They are listed as given.

Raises:

ValueError – The report contains a term of BANNED_TERMS.

Return type:

str

Exceptions

Typed failures raised by the fragment interaction-energy workflow.

exception q2m3.fragments.errors.FragmentWorkflowError[source]

The fragment workflow cannot produce a valid result for its input.

exception q2m3.fragments.errors.ActiveSpaceMismatchError[source]

Monomer active spaces do not correspond to the dimer active space.

exception q2m3.fragments.errors.ReferenceImportError[source]

An imported reference table violates the required format.

exception q2m3.fragments.errors.ExternalProgramError[source]

An external quantum-chemistry program is not available or did not complete.