Architecture overview

Common concepts

The focus of Wavepacket is on flexible setups of simple quantum systems. To get there, the code ended up with a few common concepts.

To abstract away the difference between wave functions and density operators, a class wavepacket.grid.State has been introduced.
Most utility functions and classes can operate on wave functions as well as density operators transparently.

Where the difference can lead to confusion and errors, functionality may not be offered. For example, the wave function norm is the square root of the of the corresponding density operator (trace) norm. This has been extremely confusing when switching between the two objects, so Wavepacket does not offer a norm() function, it offers wavepacket.trace() instead,
Classes in Wavepacket are immutable after creation. This allows you to recycle objects without side effects; for example, when you have set up a Hamiltonian for the field-free case, you can sum it with the laser interaction to get the Hamiltonian for the system with a laser field. All classes and packages follow a strict hierarchy as described in the subsequent section.

The Python interpreter does not always guarantee this immutability, and we did not cover every potential pitfall. Avoid breaking this guarantee, however, because doing so can corrupt object consistency (and therefore results) in subtle ways. In particular, if you create a wavepacket.grid.State directly from a numpy array (very advanced use case), dispose the array and do not modify it afterwards.

Wavepacket is split into several subpackages with hierarchical dependencies. From lowest to highest layer, these are:

wavepacket.grid: Contains all classes that describe the representation of a state (the grid), These include degrees of freedom, wavepacket.grid.Grid itself, and the class wavepacket.grid.State.
wavepacket.builder: Contains functions to generate an initial wave function or density operator. These functions require a grid on which to create the state.
wavepacket.special: Contains special functions. These are mostly typical pulse shapes like squared sine shapes, or typical shapes for initial wave functions, such as Spherical harmonics.
wavepacket.operator: Contains operator classes. Operators are always defined on a specific grid, hence this module requires the grid module.
wavepacket.expression: Contains classes that define differential equations. These can be a Schroedinger equation or various Liouvillians. As these entities wrap an operator, this module requires the operator module.
wavepacket.solver: Contains actual Solvers for the differential equations. Hence, this module requires knowledge of the expression module.

Two other modules stand apart from this hierarchy:

wavepacket.typing contains definitions for type hinting.
wavepacket.testing contains some test helpers, for example wavepacket.testing.assert_close() to compare two states with each other.
The top-level package offers the exception classes and general utility functions, such as wavepacket.trace() or wavepacket.expectation_value().

With these concepts in mind, most functionality should be readily explorable.