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.
`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 in (unweighted) DVR are complex numbers uniformly distributed on the unit circle.

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