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 | int | str | collections.abc.Sequence[wavepacket.typing.Generator | int | str], 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 | int | Sequence[wp.typing.Generator | int] Normally a list containing for each degree of freedom either a callable that take the DVR grid points as input and returns the raw wave function value as output, or the index of the occupied channel. For convenience, you can directly give the callable / channel. for one-dimensional problems without specifying a list. Technically, giving a channel sets the wave function to zero except for the one DVR grid point whose index is given, where it is one Usually, this only makes sense for a channel degree of freedom. **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 !!