wavepacket.operator

This module contains classes that define operators on a given grid.

Classes

`OperatorBase`	Base class of an operator.
`CartesianKineticEnergy`	Convenience class that implements the common Cartesian kinetic energy operator.
`PlaneWaveFbrOperator`	Base class for one-dimensional operators that are diagonal in a plane wave basis.
`FbrOperator1D`	Base class for one-dimensional operators that are diagonal in the FBR.
`RotationalKineticEnergy`	Convenience class that implements a typical rotational kinetic energy term.
`Projection`	Projects onto a subspace defined by one or more basis functions.
`Constant`	Operator that encapsulates a simple constant.
`TimeDependentOperator`	Wrapper for general time-dependent functions, usually laser fields.
`LaserField`	Operator that describes a common laser field.
`Potential1D`	Operator that represents a real-valued one-dimensional potential.

Package Contents

class wavepacket.operator.OperatorBase(grid: wavepacket.grid.Grid, time_dependent: bool)

Bases: abc.ABC

Base class of an operator.

An operator can be applied to a wave function or from the left or right to a density operator. It is defined on a grid, and can only operate on states on that grid.

Parameters:

gridwp.grid.Grid: The grid on which the operator is defined. Particular operators may require additional parameters.
time_dependent: bool: If the operator is time-dependent or not.

Attributes:

grid: wp.grid.Grid: The grid on which the operator is defined.
time_dependent: bool, readonly: If the operator is time-dependent or not. Some functionality may not work for time-dependent operators.

grid: Final[wavepacket.grid.Grid]

time_dependent: Final[bool]

apply(state: wavepacket.grid.State, t: float) → wavepacket.grid.State

Applies the operator onto a wave function or a density operator from the left.

This is a convenience function if you just want to apply the operator without detailed knowledge of the state.

Parameters:

statewp.grid.State: The state that the operator is applied on.
tfloat: The time at which the operator is applied. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wp.grid.State: The result of applying the operator on the state.

Raises:

wp.BadGridError: If the state’s grid does not match the grid of the operator.
wp.BadStateError: If the state is neither a wave function nor a density operator.

abstractmethod apply_to_wave_function(psi: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a wave function.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

psiwpt.ComplexData: The coefficients describing the wave function on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting wave function.

abstractmethod apply_from_left(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the left.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

abstractmethod apply_from_right(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the right.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

class wavepacket.operator.CartesianKineticEnergy(grid: wavepacket.grid.Grid, dof_index: int, mass: float, cutoff: float | None = None)

Bases: PlaneWaveFbrOperator

Convenience class that implements the common Cartesian kinetic energy operator.

The form of the operator is $-\frac{1}{2m} \ \frac{\partial^2}{\partial x^2}$ . It requires the degree of freedom to be a wavepacket.grid.PlaneWaveDof.

Parameters:

gridwp.grid.Grid: The grid on which the operator is defined.
dof_indexint: Degree of freedom along which the operator acts
massfloat: The mass of the particle.
cutoff: float | None, default=None: If set, truncate all operator values whose real value is above the cutoff. Default is not to truncate.

Attributes:

mass: float, readonly: The mass of the particle

Raises:

wp.InvalidValueError: If the mass is not positive, or if the degree of freedom does not describe a plane wave expansion.

mass: Final[float]

class wavepacket.operator.PlaneWaveFbrOperator(grid: wavepacket.grid.Grid, dof_index: int, generator: wavepacket.typing.Generator, cutoff: float | None = None)

Bases: wavepacket.operator.operatorbase.OperatorBase

Base class for one-dimensional operators that are diagonal in a plane wave basis.

The wavepacket.grid.PlaneWaveDof describes an expansion of the wave function in plane waves. In the corresponding FBR, derivatives are diagonal and essentially transform into a multiplication with the wave vector / FBR grid.

Functionally, this operator is identical to wavepacket.operator.FbrOperator1D, but uses the faster FFT transformation instead of a matrix multiplication.

Parameters:

gridwp.grid.Grid: The grid on which the operator is defined.
dof_indexint: The degree of freedom along which the operator is defined.
generatorwpt.Generator: A callable that gives the operator value for each FBR point.
cutoff: float | None, default None: If set, truncate all operator values whose real value is above the cutoff. Default is not to truncate.

Raises:

wp.InvalidValueError: If the supplied degree of freedom is not a plane wave expansion.

apply_to_wave_function(psi: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a wave function.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

psiwpt.ComplexData: The coefficients describing the wave function on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting wave function.

apply_from_left(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the left.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

apply_from_right(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the right.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

class wavepacket.operator.FbrOperator1D(grid: wavepacket.grid.Grid, dof_index: int, generator: wavepacket.typing.Generator, cutoff: float | None = None)

Bases: wavepacket.operator.operatorbase.OperatorBase

Base class for one-dimensional operators that are diagonal in the FBR.

Whereas wavepacket.operator.Potential1D describes potentials, which can be multiplied with a wave function or density operator at each grid point, this class describes operators that can be multiplied with a state at each FBR grid point. Examples would be a rotational kinetic energies along individual degrees of freedom.

The numerics boil down to a matrix multiplication along the respective degree of freedom. For a faster alternative along plane wave degrees of freedom, see wavepacket.operator.PlaneWaveFbrOperator

Parameters:

gridwp.grid.Grid: The grid on which the operator is defined.
dof_indexint: Degree of freedom along which the operator acts
generatorwpt.Generator: A callable that gives the operator value for each FBR point.
cutoff: float | None, default None: If set, truncate all operator values whose real value is above the cutoff. Default is not to truncate.

apply_to_wave_function(psi: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a wave function.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

psiwpt.ComplexData: The coefficients describing the wave function on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting wave function.

apply_from_left(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the left.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

apply_from_right(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the right.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

class wavepacket.operator.RotationalKineticEnergy(grid: wavepacket.grid.Grid, dof_index: int, inertia: float, cutoff: float | None = None)

Bases: FbrOperator1D

Convenience class that implements a typical rotational kinetic energy term.

The form of the operator is $-\frac{\hat L^2}{2I}$ in terms of the angular momentum operator and a moment of inertia. It requires the degree of freedom to be a wavepacket.grid.SphericalHarmonicsDof.

Parameters:

gridwp.grid.Grid: The grid on which the operator is defined.
dof_indexint: Degree of freedom along which the operator acts
inertiafloat: The fixed moment of inertia of the rotor.
cutoff: float | None, default None: If set, truncate all operator values whose real value is above the cutoff. Default is not to truncate.

Attributes:

inertia: float, readonly: The fixed moment of inertia of the rotor.
Raises
——
wp.InvalidValueError: If the moment of inertia is not positive, or if the degree of freedom does not describe a spherical harmonics expansion.

inertia: Final[float]

class wavepacket.operator.Projection(basis: wavepacket.grid.State | Sequence[wavepacket.grid.State])

Bases: wavepacket.operator.operatorbase.OperatorBase

Projects onto a subspace defined by one or more basis functions.

This class represents an idempotent projection operator, $\hat P = \sum_i |\psi_i\rangle\langle\psi_i|$ , where the basis functions $\psi_i$ span the subspace on which the operator projects.

The basis functions need not be orthogonal, they are orthonormalized using wp.orthonormalize().

Parameters:

basis: wp.grid.State | Sequence[wp.grid.State]: The basis functions $\psi_i$ that span the subspace onto which the operator projects. Need not be orthogonal, but should be linearly independent. In case of one basis function, it can be supplied directly without a list.

Raises:

wp.BadStateException: Thrown if any basis function is not a wave function or has norm zero.
wp.InvalidValueError: Thrown if no basis functions are supplied.

See also

wavepacket.grid.population: if you only want to calculate the population of some states.

apply_to_wave_function(psi: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a wave function.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

psiwpt.ComplexData: The coefficients describing the wave function on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting wave function.

apply_from_left(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the left.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

apply_from_right(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the right.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

class wavepacket.operator.Constant(grid: wavepacket.grid.Grid, value: complex)

Bases: wavepacket.operator.operatorbase.OperatorBase

Operator that encapsulates a simple constant.

Normally, you will not use this operator directly. It is only a wrapper to enable numbers where an operator is expected, in particular when doing operator arithmetic.

Parameters:

grid: wp.grid.Grid: The grid on which this operator is defined.
value: complex: The value that this operator wraps.

Attributes:

value: complex, readonly: The wrapped value.

value: Final[complex]

apply_to_wave_function(psi: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a wave function.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

psiwpt.ComplexData: The coefficients describing the wave function on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting wave function.

apply_from_left(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the left.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

apply_from_right(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the right.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

class wavepacket.operator.TimeDependentOperator(grid: wavepacket.grid.Grid, func: Callable[[float], complex])

Bases: wavepacket.operator.operatorbase.OperatorBase

Wrapper for general time-dependent functions, usually laser fields.

This operator gets a function f(t), and simply multiplies the input state with the function. It gets a full function f(t), which may also be complex.

Parameters:

grid: wp.grid.Grid: The grid on which this operator acts.
func: Callable[[float], float]: Functions that returns a potentially complex value for a given input time.

apply_to_wave_function(psi: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a wave function.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

psiwpt.ComplexData: The coefficients describing the wave function on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting wave function.

apply_from_left(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the left.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

apply_from_right(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the right.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

class wavepacket.operator.LaserField(grid: wavepacket.grid.Grid, max_field: float, shape: Callable[[float], float], omega: float, phi: float = 0)

Bases: TimeDependentOperator

Operator that describes a common laser field.

A usual laser field is defined as $E(t) = E_0 f(t) \cos(\omega t + \phi)$ in terms of the maximum field E_0, the pulse shape f, angular frequency omega and initial phase phi.

This class is meant as a shorthand for common models. If you want to model more complex laser fields, define them in a separate function and supply it directly to the wavepacket.operator.TimeDependentOperator base class.

Parameters:

grid: wp.grid.Grid: The grid on which this operator acts.
max_field: float: The maximum field strength E_0
shape: Callable[[float], float]: The pulse shape f(t). For easier use, it should be normalized to a maximum value of 1. Wavepacket comes with several predefined shapes, such as wavepacket.Lorentzian.
omega: float: The angular frequency omega
phi: float, default=0: The initial phase of the pulse

class wavepacket.operator.Potential1D(grid: wavepacket.grid.Grid, dof_index: int, generator: wavepacket.typing.Generator, cutoff: float = None)

Bases: wavepacket.operator.operatorbase.OperatorBase

Operator that represents a real-valued one-dimensional potential.

Within the DVR approximation [1], potential energy operators are diagonal in the DVR. That is, they are completely described by a value for each grid point.

Parameters:

gridwp.grid.Grid: The grid on which the operator is defined
dof_indexint: the index of the degree of freedom along which the potential is defined.
generatorwpt.Generator: A callable that generates a potential energy value for each grid point of the respective DOF. Potential energy values may be complex, then the imaginary part describes absorption or emission of the wave function.
cutoff: float, default=None: If set, defines the maximum potential value. Values larger than the cutoff are set to the cutoff. For complex potentials, only the real part is truncated.

References

[1]

https://sourceforge.net/p/wavepacket/wiki/Numerics.DVR>

Examples

Creation of a square potential along the grid’s second degree of freedom

>>> grid = ...
>>> harmonicPotential = wp.operator.Potential1D(grid, 1, lambda x: x**2)

apply_to_wave_function(psi: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a wave function.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

psiwpt.ComplexData: The coefficients describing the wave function on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting wave function.

apply_from_left(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the left.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.

apply_from_right(rho: wavepacket.typing.ComplexData, t: float) → wavepacket.typing.ComplexData

Applies the operator on a density operator from the right.

This function is mainly for Wavepacket-internal use. It ignores most error handling (usually done by the wrapping wavepacket.expression.ExpressionBase), and operates directly on coefficients to avoid the creation of temporary states.

Parameters:

rhowpt.ComplexData: The coefficients describing the density operator on which the operator acts.
tfloat: The time at which the operator should be evaluated. Only really needed for time-dependent operators, but to keep the interface uniform, this parameter is required.

Returns:

wpt.ComplexData: The coefficients of the resulting density operator.