qcr:2606.92210.1

Properties and Operator Factories in Qiskit Nature

This Qiskit Nature tutorial explains properties (operator factories), the components that generate the additional physical observables, beyond the energy, that a quantum chemistry calculation can compute, such as the particle number, spin, magnetization, and dipole moment of a molecule. A chemistry problem is more than its Hamiltonian: to fully characterize a state you often want expectation values of other operators, and Qiskit Nature organizes these as property objects that know how to build their corresponding second-quantized operators from the problem definition. The tutorial shows how properties are attached to an electronic- or vibrational-structure problem, how each property produces the operator (or operators) that must be measured, and how, after a ground- or excited-state solve, the results object reports the evaluated values of these observables alongside the energy. It covers the built-in properties and how to access them, and explains the operator-factory pattern that lets the same machinery measure many quantities consistently. By exposing how to compute observables beyond energy, the tutorial helps users extract the full physical picture of a molecular state from a quantum calculation in Qiskit Nature.

Chemistry

Qubit

Circuit-based

Uploaded 3 days ago

Views

GitHub

390

Citing this entry? Use this QCR ID

Uploaded by

QCR Librarian

qiskit-community/qiskit-nature

390

233

In [ ]:

# --- Setup cell added by QCR (not part of the original tutorial) ---
# Source: qiskit-community/qiskit-nature @ 0.8, Apache License 2.0.
# Installs the example's dependencies. If a later cell still reports a missing
# package, restart the runtime/kernel and run again from the top.
%pip install -q qiskit-nature==0.8.0 pyscf

Properties - or - Operator Factories

Qiskit Nature has various built-in "properties". These objects are effectively operator factories, since they allow the programming of operator blueprints based on a minimal set of required information. Some commonly used examples are the ParticleNumber, AngularMomentum and Magnetization properties, all of which take only the system size as their only input, and generate a SparseLabelOp of the required size.

These properties can be registered in a problem instance which will cause them to be evaluated once a ground state and/or excited states of that problem have been found. In the following, we will explain the general concept of how this works.

The BaseProblem base class dictates the existence of the .properties attribute on any problem instance. This attribute is of type PropertiesContainer which is an object that can hold at most one instance of any SparseLabelOpsFactory (or property class, as we commonly refer to them).

In [1]:

from qiskit_nature.second_q.problems import BaseProblem

dummy_hamiltonian = None

base_problem = BaseProblem(dummy_hamiltonian)
print(base_problem.properties)

<qiskit_nature.second_q.problems.properties_container.PropertiesContainer object at 0x14c01089daf0>

You can now modify the contents of the PropertiesContainer to your desire:

In [2]:

from qiskit_nature.second_q.properties import AngularMomentum

print("AngularMomentum is in problem.properties:", AngularMomentum in base_problem.properties)

print("Adding AngularMomentum to problem.properties...")
base_problem.properties.add(AngularMomentum(2))

print("AngularMomentum is in problem.properties:", AngularMomentum in base_problem.properties)

print("Discarding AngularMomentum from problem.properties...")
base_problem.properties.discard(AngularMomentum)

print("AngularMomentum is in problem.properties:", AngularMomentum in base_problem.properties)

AngularMomentum is in problem.properties: False
Adding AngularMomentum to problem.properties...
AngularMomentum is in problem.properties: True
Discarding AngularMomentum from problem.properties...
AngularMomentum is in problem.properties: False

The specific subclasses of BaseProblem for the various stacks such as electronic structure, vibrational structure or lattice models make things even simpler for you, because they provide direct attributes for the built-in properties of Qiskit Nature:

In [3]:

from qiskit_nature.second_q.drivers import PySCFDriver

es_problem = PySCFDriver().run()

print(es_problem.properties.particle_number)
print(es_problem.properties.angular_momentum)
print(es_problem.properties.magnetization)
print(es_problem.properties.electronic_dipole_moment)
print(es_problem.properties.electronic_density)

<qiskit_nature.second_q.properties.particle_number.ParticleNumber object at 0x14bfa1aa5b80>
<qiskit_nature.second_q.properties.angular_momentum.AngularMomentum object at 0x14bfa1aa5a60>
<qiskit_nature.second_q.properties.magnetization.Magnetization object at 0x14bfa1aa5ac0>
<qiskit_nature.second_q.properties.dipole_moment.ElectronicDipoleMoment object at 0x14bfa1aa5f70>
None

Note that the ElectronicDipoleMoment is populated by default. To exclude it, you can use the drivers to_problem() method and provide the include_dipole=False keyword argument. Refer to the drivers documentation for more details.

You can see, that all properties come pre-populated except for the ElectronicDensity. But this is easy to add:

In [4]:

from qiskit_nature.second_q.properties import ElectronicDensity

density = ElectronicDensity.from_orbital_occupation(
    es_problem.orbital_occupations,
    es_problem.orbital_occupations_b,
)

es_problem.properties.electronic_density = density

The same concepts apply to the VibrationalStructureProblem and the LatticeModelProblem.

In [5]:

import tutorial_magics

%qiskit_version_table
%qiskit_copyright

Version Information

Qiskit Software	Version
`qiskit-terra`	0.23.0.dev0+fca8db6
`qiskit-aer`	0.11.0
`qiskit-ibmq-provider`	0.19.2
`qiskit-nature`	0.5.0
System information
Python version	3.9.14
Python compiler	GCC 12.2.1 20220819 (Red Hat 12.2.1-1)
Python build	main, Sep 7 2022 00:00:00
OS	Linux
CPUs	8
Memory (Gb)	62.501182556152344
Fri Oct 21 16:22:12 2022 CEST

This code is a part of Qiskit

This code is licensed under the Apache License, Version 2.0. You may
obtain a copy of this license in the LICENSE.txt file in the root directory
of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.

Any modifications or derivative works of this code must retain this
copyright notice, and modified files need to carry a notice indicating
that they have been altered from the originals.

Join the Discussion

Comments (0)

No comments yet. Be the first to share your thoughts!

Indexed by QCR Librarian

This entry was created automatically from publicly available records. QCR links to public sources and only stores repository content where the license permits redistribution.

Claim this entry →

Versions

v1 Latest

Jun 15, 2026

qcr:2606.92210.1

Cite all versions? Use the base QCR ID to always reference the latest version of this entry.

Tools used

Qiskit

Keywords

properties

observables

quantum-chemistry

qiskit

operators