Reference.Variables.space.dof

Variable "space.dof" in the Matlab/Octave version of WavePacket

Wavefunction simulations using objects of class wave are based on representing quantum states and operators on multidimensional grids. These grids are constructed as direct products of one-dimensional grids each of which implements one discrete variable representation (DVR), see the corresponding section in the WavePacket central Wiki. The DVR grid gives the points where the wave function is defined, along with the appropriate weights to use in numercal integration, and the corresponding finite basis representation (FBR) grid defines some quantum number of the basis functions, which is grid-dependent. The convention is that an integration in the DVR always requires the given weights, while an integration in the FBR can be done by just summing up; that is, when transforming to the FBR, proper normalization is taken care of.

Within WavePacket, all of this is implemented in an object-oriented way using Matlab/Octave classes: Each element of the cell vector "space.dof" stands for one of the degrees of freedom and it serves to specify an object of one of the different grid (DVR) classes . The choice of grid types (or DVR schemes) along with the setting of the respective class properties is illustrated in this example

space.dof{1} = dof.fft;
space.dof{1}.x_min = -10;
...

etc. The first line defines the object type, the second (and further) lines set some adjustable parameter. For each grid, a certain kinetic energy operator is automatically included in the Hamiltonian. For a list of the implemented grid classes and their settable properties, see the tables given below as well as the corresponding package folder.

dof.fft	Uses an equally-spaced grid as DVR, which is equivalent to an expansion in plane waves as corresponding FBR, and employs the Fourier method to transform forth and back. The associated kinetic energy operator is -1/(2m) ∂2/∂x2.	default
mass	The mass m used for the kinetic energy operator.	1
n_pts	The number of points to use in the grid.	empty
x_min	The lower bound of the grid.	empty
x_max	The upper bound of the grid.	empty
periodic	If set to true, use non-periodic boundary conditions when setting up the Hamiltonian matrix with the Fourier-Grid Hamiltonian method.	true.

For a more in-depth explanation of how to optimally choose the grid parameters, along with a discussion of different boundary conditions in WavePacket, the interested reader is referred to our Wiki page on Fourier grid representations and absorbing boundary conditions.

dof.legendre	The FBR of this grid is an expansion in spherical harmonics Ylm(θ, φ) with fixed quantum number m (i.e., effectively only one degree of freedom). The DVR consists of the points of the corresponding Gaussian quadrature. whose coordinates are given as x = cos θ. The associated kinetic energy is that of a free (linear, rigid) rotor, L2/(2mR2).	default
mass	The mass m occurring in the kinetic energy.	1
R_dof	Gives the index of the radial degree of freedom that enters the kinetic energy as R. Cannot be set together with R_0.	empty
R_0	Gives the fixed value of R in the kinetic energy. Cannot be set together with R_dof.	empty
l_max	The maximum angular momentum that can be represented with this grid. The number of grid points is given by lmax - m_0 + 1.	empty
m_0	Constant value of the minor quantum number m.	0

The Gauss-Legendre DVR is used for problems where the minor quantum number (most often called m) is conserved while the major quantum number (typically named l) can vary. Note that for homonuclear diatomic molecules, symmetry arguments require that l is always either even or odd. If your potential does not fulfill this automatically (linearly polarized lasers do), you have to apply the required symmetry. The Legendre DVR considers the quantum number l as (angular) momentum.

dof.hermite	The FBR is given by an expansion in harmonic oscillator eigenfunctions, the DVR are the associated Gauss-Hermite quadrature points. The associated kinetic energy operator is -1/(2m) ∂2/∂x2.	default
mass	The mass m entering in the kinetic energy and the harmonic oscillator expression.	1
omega	The frequency of the harmonic potential whose eigenstates we use. The potential has the shape V = ½ m ω2 x2.	1
v_2	The force constant m ω2. Can be specified instead of omega.	empty
r_e	Position of the minimum of the harmonic oscillator.	0
n_pts	Number of basis functions/grid points to use.	empty

The Gauss-Hermite DVR is suited for an expansion in eigenfunctions of the harmonic oscillator (Hermite polynomials times an exponential). In contrast to other DVR methods, the grid points are not natively bounded to some interval, but can lie anywhere on the real axis. However, they are always concentrated somewhere around the minimum of the harmonic oscillator.

Furthermore, the Gauss-Hermite quadrature is conveniently defined in scaled coordinates (corresponding to m ω = 1, r_e = 0). To use them for real problems, you have to supply the shift and the properties of the harmonic potential you want to use.

Public methods

Every grid class has to offer the following public methods. These methods are meant for work with wavefunction objects; only the last one is for trajectory objects

method	explanation
init_grid	This function sets the DVR, FBR, and weight grids. It is called internally during the setup of the calculation. This function needs to be called before the grid can be used
init_kin	This function sets up the internal kinetic energy operator and its exponentiated form with the given splitting factor; each grid has a (diagonal) associated kinetic energy. This function is called internally during the setup of the calculation, and needs to be called before the kinetic energy operator can be used
dvr2fbr	Takes as input argument a wave function in the DVR, and returns the corresponding wave function in the FBR
fbr2dvr	Takes as input argument a wave function in the FBR and returns the corresponding wave function in the DVR
matrix2dvr	Takes a matrix in the FBR and converts it into the DVR
kinetic2dvr	Returns the matrix corresponding to the underlying kinetic energy operator of the grid in the DVR representation. Used in qm_bound for constructing the Hamiltonian to diagonalize
kinetic	Applies the kinetic energy operator for this dimension to the wave function (for all (coupled) channels!). The result is stored in psi.new. If new == true, the input wave function comes from psi.new, otherwise we take it from psi.dvr
kinetic_exp	Takes the wavefunction stored in psi.dvr (for all (coupled) channels!) and applies the operator exp(-i⋅K⋅f⋅dt) to it. The result is stored again in psi.dvr afterwards. Fraction f should be chosen as 1 or ½ for use in Lie-Trotter or Strang-Marchuk splitting method, respectively
momentum	Applies some momentum operator to the input wave function psi. The definition of the momentum operator is not meaningful for any grid except the fft grid; this function should therefore generally be avoided
eval_kin	Evaluate kinetic energy function for trajectory objects

Public properties

Every grid class has to offer the following public properties. Most of them can be set to tune the grid.

method	explanation
label	Name associated with the degree of freedom
dof	Index of the degree of freedom (i.e., for psi.dvr
n_pts	Number of grid points
dvr_min	Lower bound of the DVR grid; used e.g. for auto-determining ranges when plotting. Read-only
dvr_max	Upper bound of the DVR grid. Read-only
fbr_min	Lower bound (quantum number or whatever) of the FBR grid. Read-only
fbr_max	Upper bound of the FBR grid. Read-only
kin_max	Maximum kinetic energy of the internal kinetic energy that can be represented on the grid. Read-only.
nokin	If set to 'true', all calls to grid_kinetic and grid_kinetic_exp do nothing, i.e., effectively disables the internal kinetic energy operator. Useful for implementing your own kinetic energy operators via hamilt.kin