Users.Basics.Main

Basic setup of simulations using the Matlab/Octave version of WavePacket

This chapter describes the basics of WavePacket's inner workings and of how to set up a calculation. To run a basic time-independent or time-dependent calculation, use qm_bound or qm_propa), respectively. These functions are the actual workhorses, and do the main calculations. In order to run them properly, you have to take the following steps:

• Create a new directory for your calculation data (not strictly mandatory, but usually a good idea).

• In this directory, create some file with an initialization function (typically called qm_init.m, see also the demo examples). This function should set up all global variables for the calculation.

• Start MatLab or Octave, and make this directory your current working directory. Make sure also to include the source directory in Matlab's or Octave's search path using the addpath command.

• Run the calculation. For this, you have to run the following sequence:

  1. Run qm_setup('wave') to purge the workspace from previous calculations, closes all files still open, asks Matlab or Octave to recompile functions. Most importantly, it creates an object named "state" belonging - in this case - to class wave (for wavefunctions, represented on grids). Alternatively, you could also use qm_setup to create an object of class traj (for classical densities, represented by swarms of trajectories).
     In the latter case you may want to specify two additional integer arguments for the call to qm_setup, i.e. the number of trajectories and an initialization of Matlab's or Octave's random number generator. In case of non-adiabatic dynamics, there are also options of trajectory simulations available, in particular, various versions of surface hopping trajectories, see class mssh, class fssh, and class sssh for multiple, fewest, and single switch(es) surface hopping variants, respectively. Yet other options are objects of class ket or rho that deal with state vectors or density matrices in an eigen/energy representation, respectively. Note that out of the options listed here, the first one ('wave') is the default which is used when no argument is specified upon calling qm_setup.

  2. Run your initialization function, typically named qm_init. This function should set a number of global parameters that tell the simulation how to proceed. Possibly this function may also set certain properties of global object "state" and/or some settings may depend on the class of it.

  3. Run qm_propa('method') for a dynamical simulation. If "state" is an object of class wave , this will run a quantum simulation solving a time-dependent Schrödinger equation (TDSE). If, however, "state" is an object of class traj , this will run a fully classical simulation solving a classical Liouville equation (CLE) approximately by propagating a bundle of trajectories. If one of the surface-hopping trajectory techniques has been chosen, a mixed quantum-classical Liouville equation (QCLE) will be approximately solved. The input argument 'method' is a text string specifying the numerical method to be employed. There is a rather large choice; depending on the class of object "state", see the reference guide. When not specified otherwise by the user, the default is to use a "Strang-Marchuk splitting" scheme for propagation of wavefunctions or a "leap frog" integrator for the propagation of (surface hopping or purely classical) trajectories.

  4. Alternatively, you may run qm_bound() for a bound-state quantum simulation solving a time-independent Schrödinger equation (TISE) by grid methods. Of course, this requires "state" to be an object of class wave.

  5. Run qm_cleanup(). This closes the logfile and does some minor cleanup.

After the calculation, the directory holds a couple of new WavePacket output files. The log file qm_propa.log (or equivalent files) holds a copy of all the output that went into the MatLab or Octace console. In addition, depending on your parameters, there may also be various image files or movie files. It is also possible to store wave functions, trajectories, etc., which is explained on a separate page of this Wiki which is then available e.g. for further (repeated) visualization running qm_movie(state).

Two notes might be interesting for writing scripts.

• As long as you do not call qm_setup(•) again, all parameters are still available as global variables. Usually, you have to import them into the current workspace by a call like

  global expect hamilt space state time ...
  

• If you want to run multiple calculations with similar arguments, there are two possibilities. Either you modify your qm_init(params) function to accept (one or several) additional parameter(s), and run repeatedly

  qm_setup(...); qm_init(params); qm_propa(...); qm_cleanup();
  

or you just change the parameters in your script and run qm_propa(•) after each tweaking.