wavepacket.builder

Functions to assemble wave functions or density operators.

Functions

`direct_product`(→ wavepacket.grid.State)	Returns the direct product of wave functions as a density operator.
`pure_density`(→ wavepacket.grid.State)	Given an input wave function, create the corresponding pure density operator.
`unit_density`(→ wavepacket.grid.State)	Returns a unit operator as density operator.
`zero_density`(→ wavepacket.grid.State)	Returns a density operator whose coefficients are constant zero.
`product_wave_function`(→ wavepacket.grid.State)	Builds a product wave function from a set of one-dimensional wave functions.
`random_wave_function`(→ wavepacket.grid.State)	Generates a random wave function.
`unit_wave_function`(→ wavepacket.grid.State)	Returns a wave function whose coefficients are a constant 1.0.
`zero_wave_function`(→ wavepacket.grid.State)	Returns a wave function whose coefficients are constant zero.

Package Contents

wavepacket.builder.direct_product(ket: wavepacket.grid.State, bra: wavepacket.grid.State) → wavepacket.grid.State

Returns the direct product of wave functions as a density operator.

Given two wave functions $\psi, \phi$ , this function returns the density operator as $| \psi \rangle\langle \phi |$ . This operation can be useful to build up a density operator piece by piece.

Parameters:

ketwp.grid.State: The ket state $\psi$
brawp.grid.State: The bra state $\phi$ . Note that the function performs a complex conjugation of this state prior to multiplication.

Returns:

wp.grid.State: The direct product of the two states.

Raises:

wp.BadStateError: If one of the input states is not a valid wave function.
wp.BadGridError: If the input states are defined on different grids.

wavepacket.builder.pure_density(psi: wavepacket.grid.State) → wavepacket.grid.State

Given an input wave function, create the corresponding pure density operator.

This function only performs the direct product, it does not apply further modifications like normalizations.

Parameters:

psiwp.grid.State: The input wave function

Returns:

wp.grid.State: The corresponding density operator.

Raises:

wp.BadStateError: If the input is not a valid wave function.

See also

direct_product: This function is identical to direct_product(psi, psi)

wavepacket.builder.unit_density(grid: wavepacket.grid.Grid) → wavepacket.grid.State

Returns a unit operator as density operator.

Parameters:

grid: wp.grid.Grid: The grid for which the unit density operator should be returned.

wavepacket.builder.zero_density(grid: wavepacket.grid.Grid) → wavepacket.grid.State

Returns a density operator whose coefficients are constant zero.

These states sometimes occur as initial states in perturbation theory approaches.

Parameters:

grid: wp.grid.Grid: The grid for which the zero density should be generated.

wavepacket.builder.product_wave_function(grid: wavepacket.grid.Grid, generators: wavepacket.typing.Generator | collections.abc.Sequence[wavepacket.typing.Generator], normalize: bool = True) → wavepacket.grid.State

Builds a product wave function from a set of one-dimensional wave functions.

Parameters:

gridwp.grid.Grid: The grid on which the product wave function is assembled
generatorswpt.Generator | Sequence[wp.typing.Generator]: One or more callables that specifies the wave function along each degree of freedom. The generators return the one-dimensional functions in the DVR, i.e., raw function values at the grid points.
normalizebool, default=true: If the norm is non-zero and this value is set, the resulting product wave function is normalized, otherwise the product is returned directly.

Returns:

wp.grid.State: The product wave function in the Wavepacket-default weighted DVR.

Raises:

wp.InvalidValueError: If the number of generators does not match the grid dimensions.

wavepacket.builder.random_wave_function(grid: wavepacket.grid.Grid, generator: numpy.random.Generator) → wavepacket.grid.State

Generates a random wave function.

The output is a state in the weighted DVR, whose coefficients are complex numbers uniformly distributed on the unit circle.

Note that such wave functions are only useful in certain situations, see Representing states at finite temperature. In particular, they are not normalized.

Parameters:

grid: wp.grid.Grid: The grid for which the random wave function is created.
generator: np.random.Generator: The Numpy generator that creates the random values.

Examples

You typically need to generate several random wave functions for a simulation. In such a case, it is advantageous to recycle the random number generator after initial seeding. That way, a single seed number allows reproduction of the random numbers.

>>> rng = np.random.default_rng(42)
>>> psi = random_wave_function(grid, rng)
>>> psi2 = random_wave_function(grid, rng)

wavepacket.builder.unit_wave_function(grid: wavepacket.grid.Grid) → wavepacket.grid.State

Returns a wave function whose coefficients are a constant 1.0.

Such a wave function is useful for technical manipulations, less for actual quantum dynamics.

Examples

Given a potential V, applying the potential to wave function returns the product $V_i \psi_i$ at every grid point i. With a unit wave function as input, this yields the potential for each grid point.

>>> unit = wp.builder.unit_wave_function(grid_1d)
>>> potvals = potential.apply(unit, 0.0)
>>> plot(grid_1d.dofs[0].dvr_grid, potvals.data)

wavepacket.builder.zero_wave_function(grid: wavepacket.grid.Grid) → wavepacket.grid.State

Returns a wave function whose coefficients are constant zero.

These states sometimes occur as initial states in perturbation theory approaches.