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.

Functions

expectation_value(→ complex)

Calculates the expectation value of an operator for a given state.

Package Contents

class wavepacket.operator.OperatorBase(grid: wavepacket.grid.Grid)

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.

Attributes:

grid: wp.grid.Grid: The grid on which the operator is defined.

property grid: Returns the grid on which the operator is defined.

apply(state: wavepacket.grid.State, t: float | None = None) → 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, optional

The time at which the operator is applied.: The default value None raises an exception for time-dependent operators.

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.

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.

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.

Returns:

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

wavepacket.operator.expectation_value(op: wavepacket.operator.operatorbase.OperatorBase, state: wavepacket.grid.State, t: float | None = None) → complex

Calculates the expectation value of an operator for a given state.

Parameters:

opwp.operator.OperatorBase

The operator whose expectation value is calculated.

statewp.grid.State

The wave function or density operator that is used for the calculation.

tfloat, optional

The time at which the operator should be evaluated.: Only required for time-dependent operators, where the default value None raises an exception.

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

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.

Raises:

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

class wavepacket.operator.PlaneWaveFbrOperator(grid: wavepacket.grid.Grid, dof_index: int, generator: wavepacket.typing.Generator)

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.

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.

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.

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.

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)

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.

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.

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.

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.

Returns:

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

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

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 moment of inertia of the rotor. Only fixed values are supported by this operator (no vibrational coupling).

Raises:

wp.InvalidValueError: If the moment of inertia is not positive, or if the degree of freedom does not describe a spherical harmonics expansion.

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.grid.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.