wavepacket.builder ================== .. py:module:: wavepacket.builder .. autoapi-nested-parse:: Functions to assemble wave functions or density operators. .. !! processed by numpydoc !! Functions --------- .. autoapisummary:: wavepacket.builder.direct_product wavepacket.builder.pure_density wavepacket.builder.unit_density wavepacket.builder.zero_density wavepacket.builder.product_wave_function wavepacket.builder.random_wave_function wavepacket.builder.unit_wave_function wavepacket.builder.zero_wave_function Package Contents ---------------- .. py:function:: 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 :math:`\psi, \phi`, this function returns the density operator as :math:`| \psi \rangle\langle \phi |`. This operation can be useful to build up a density operator piece by piece. :Parameters: **ket** : wp.grid.State The ket state :math:`\psi` **bra** : wp.grid.State The bra state :math:`\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. .. !! processed by numpydoc !! .. py:function:: 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: **psi** : wp.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. .. seealso:: :obj:`direct_product` This function is identical to `direct_product(psi, psi)` .. !! processed by numpydoc !! .. py:function:: 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. .. !! processed by numpydoc !! .. py:function:: 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. .. !! processed by numpydoc !! .. py:function:: 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: **grid** : wp.grid.Grid The grid on which the product wave function is assembled **generators** : wpt.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. **normalize** : bool, 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. .. !! processed by numpydoc !! .. py:function:: 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 :doc:`/advanced/thermal_states`. 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. .. rubric:: 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) .. !! processed by numpydoc !! .. py:function:: 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. .. rubric:: Examples Given a potential V, applying the potential to wave function returns the product :math:`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) .. !! processed by numpydoc !! .. py:function:: 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. .. !! processed by numpydoc !!