Data classes

QDK/Chemistry uses immutable data classes to represent molecular information, electronic structure results, and quantum objects. These classes serve as the inputs and outputs for algorithm classes, enabling a clean flow of data through the computational pipeline. All data classes support serialization to JSON and HDF5 formats for persistence and interoperability.

Comprehensive details on each data class can be found in the API documentation. Here, we provide a quick reference guide to help users understand the purpose and typical sources of commonly encountered data classes. Each of the links below leads to a detailed description of the data class, including its attributes, methods, and usage examples.

Contents

• Serialization
• Ansatz
• BasisSet
• Hamiltonian
• Orbitals
• LatticeGraph
• MajoranaMapping
• Pauli Operators
• Structure
• Symmetries
• Wavefunction
• QpeResult
• Circuit

Quick reference

The following table summarizes the available data classes in QDK/Chemistry and their purposes. For detailed documentation, refer to the linked pages.

Data Class	Purpose	Typical Source
Structure	Molecular geometry (atoms and coordinates)	User input
BasisSet	Atomic orbital basis definitions	Library lookup, User input
Orbitals	Molecular orbital coefficients and energies	ScfSolver
Hamiltonian	One- and two-electron integrals	HamiltonianConstructor
Wavefunction	Electronic state (orbitals + CI coefficients)	MCCalculator
QubitOperator	Pauli operator representation	QubitMapper
Symmetries	Physical symmetries	Factory methods, User input
LatticeGraph	Lattice topology for model Hamiltonians	Factory methods, User input
MajoranaMapping	Fermion-to-qubit encoding (Majorana-to-Pauli table)	Factory methods, User input
PauliOperator	Pauli operator expressions with arithmetic	User construction
QpeResult	Phase estimation results (phase, energy, aliases)	PhaseEstimation
Circuit	Quantum circuit (OpenQASM, Q#, QIR, Qiskit)	StatePreparation, User input

QubitOperator and term partitions

A QubitOperator carries an optional term_partition field describing how its Pauli terms are organised into algorithm-relevant subsets. The partition is index-based — it stores indices into pauli_strings — so it serialises cheaply alongside the operator.

The partition is optional metadata — term_partition is None means the partition has not been computed for this operator. Transformations that change term ordering or qubit support (for example to_interleaved()) reset the partition to None on the new instance.

Algorithms that consume a partition treat its presence as an explicit signal to exploit it — for example, the Trotter time-evolution builder reads term_partition and uses it for schedule-level Suzuki recursion and reduction.

FlatPartition

FlatPartition stores a single-level grouping: each group is a tuple of term indices. It is suitable for algorithms that only need to know which terms belong together, such as qubit-wise commuting measurement grouping in QdkExpectationEstimator.

The groups field is a tuple of tuples: ((idx0, idx1, ...), (idx2, ...), ...). Each inner tuple lists the indices of terms in pauli_strings that belong to that group.

LayeredPartition

LayeredPartition stores a two-level hierarchy: groups contain parallelisable layers, and each layer contains term indices. It is suitable for Trotter-style decompositions where the outer level controls Strang/Suzuki splitting order and each inner layer groups operators with disjoint qubit supports that can be applied simultaneously.

The groups field is a nested tuple: (((idx0, idx1), (idx2,)), ...). The outer level is groups, the middle level is layers within a group, and the innermost level is term indices.

Both classes carry a strategy label (e.g. "geometry_coloring", "qubit_wise_commuting") identifying how the partition was produced. They serialise as part of QubitOperator in both JSON and HDF5 formats.