wavepacket

A package for the propagation of quantum-mechanical wave functions.

Submodules

Exceptions

`BadFunctionCall`	Signals that a function was called incorrectly.
`BadGridError`	An invalid grid was supplied.
`BadStateError`	An invalid state was supplied.
`ExecutionError`	An unrecoverable problem was encountered in foreign code.
`InvalidValueError`	A function argument was incorrect, for example out of bounds.

Classes

`SinSquare`	Shape function for a squared sinusoidal laser pulse.
`SoftRectangularFunction`	Shape function for a rectangular pulse with soft (cosine) turn-on.
`Gaussian`	Callable that defines a one-dimensional Gaussian function.
`PlaneWave`	Callable that defines a plane wave.
`SphericalHarmonic`	Callable that returns a spherical harmonic Y_l^m(theta, phi=0).

Functions

log(→ None)

Prints some data about the state for inspection.

Package Contents

exception wavepacket.BadFunctionCall

Bases: Exception

Signals that a function was called incorrectly.

A typical but rare use-case would be a function that was called with incorrect parameters.

exception wavepacket.BadGridError

Bases: Exception

An invalid grid was supplied.

Most often, you attempt an operation between objects that must be defined on the same grid. For example, the addition of two operators defined on different grids is not a useful operation. The grid may also miss required properties, for example an operation may expect a specific degree of freedom type along some index.

exception wavepacket.BadStateError

Bases: Exception

An invalid state was supplied.

Either the state is completely invalid (neither wave function nor density operator), or you supplied the wrong type of state to a function, for example passing a density operator where a wave function was required.

exception wavepacket.ExecutionError

Bases: Exception

An unrecoverable problem was encountered in foreign code.

The main example is the wavepacket.solver.odesolver getting an error back while integrating.

exception wavepacket.InvalidValueError

Bases: Exception

A function argument was incorrect, for example out of bounds.

class wavepacket.SinSquare(t0: float, half_width: float)

Shape function for a squared sinusoidal laser pulse.

Usually, you use this function to describe a smooth laser pulse with a definite start and end point (which a Gaussian does not have). The exact shape is $cos^2(\pi \frac{t - t_0}{2 \Delta})$ , and zero outside the interval $[t_0-\Delta, t_0+\Delta]$ .

Parameters:

t0: float: The center of the pulse.
half_width: The half-width of the laser pulse, $\Delta$ .

Raises:

wp.InvalidValueException: if the half-width is not positive.

class wavepacket.SoftRectangularFunction(t0: float, half_width: float, border: float | None = None)

Shape function for a rectangular pulse with soft (cosine) turn-on.

This shape function is a rectangular function with a given half-width, with an added soft turn-on and turn-off of the form $cos(\frac{t}{B})$ with the border width B.

Parameters:

t0: float: Center of the rectangular pulse.
half_width: float: Half-width of the rectangular part of the pulse.
border: float = half_width/10: Optional width of the turn-on / turn-off region.

Raises:

wp.InvalidValueError: If the half-width or the border region is not positive.

class wavepacket.Gaussian(x: float = 0.0, p: float = 0.0, *, rms: float | None = None, fwhm: float | None = None)

Bases: wavepacket.typing.Generator

Callable that defines a one-dimensional Gaussian function.

This callable can be supplied wherever a callable is required. An example would be an initial wave function for wavepacket.builder.product_wave_function(), or a potential wrapped in a wavepacket.operator.Potential1D.

Parameters:

xfloat, default=0: The center of the Gaussian.
pfloat, default=0: The momentum of the Gaussian.
rms, fwhmfloat: You must specify the width of the Gaussian using exactly one of these keyword parameters, either the root-mean-square width, or the full-width-at-half-maximum.

Raises:

wp.InvalidValueError: If the width of the Gaussian is not positive.
wp.BadFunctionCall: If both rms and fwhm have either been set or not supplied.

Notes

Up to scaling, the functional form of the Gaussian is $f(x) = e^{-(x-x_0)^2 / 2 \sigma^2 + \imath p (x-x_0)}$ . Here, sigma is the rms width, which is connected to the FWHM by $\sigma = \mathrm{FWHM} / \sqrt{8 \ln 2}$ .

class wavepacket.PlaneWave(k: float)

Bases: wavepacket.typing.Generator

Callable that defines a plane wave.

You will typically use this callable for initial states. There are often better options, especially if your FBR already defines a plane wave basis, but sometimes you may just want to represent a reasonable plane wave and not count indices to get the correct wave vector.

Parameters:

kfloat: The wave vector of the plane wave.

class wavepacket.SphericalHarmonic(l: int, m: int)

Bases: wavepacket.typing.RealGenerator

Callable that returns a spherical harmonic Y_l^m(theta, phi=0).

Usually, this callable will be used for initial states. Note that the phi-dependence of a spherical harmonic is trivial exp(i m phi), and usually not needed (we fix m and the phi-integration yields a constant). For this reason, the functor takes only the theta-values as single parameters, and returns the spherical harmonic at phi = 0.

Parameters:

lint: The rotational quantum number / angular momentum
mint: The minor rotational quantum number -l <= m <= l

Raises:

wp.InvalidValueError: If l is negative or if (-l <= m <= l) does not hold.

wavepacket.log(t: float, state: wavepacket.grid.State, precision: int = 6) → None

Prints some data about the state for inspection.

The idea is that you call this function during every solver step and get a log with the most important values about the propagation, for example the state trace (if it deviates from one, this may be caused by poor convergence).

Parameters:

tfloat: The time at which you log.
statewp.grid.State: The state to log.
precisionint, default=6: How many decimal places should be printed.