File	Date	Author	Commit
Demos	2019-03-15	bsch63	[219314] A few cosmetic changes
Sources	2019-05-06	bsch63	[70ae1c] If the demo example simulations won't fail, thi...
README	2019-03-25	bsch63	[a2be32] This is going to be version 6.0.2

Read Me

WavePacket is a program package for the numerical simulation of quantum-mechanical wavepacket dynamics for distinguishable particles. WavePacket comprises functions for stationary and time-evolving, closed and open quantum systems, as well as for their optimal control by external fields. This README describes the stable MATLAB version 6.0.2 of WavePacket released on March 25, 2019. Note that since version 6.0.0  WavePacket is also offering fully classical and mixed quantum-classical propagation.

1. Installation and execution of the programs
=============================================

To use the program, add the Sources directory to your Matlab source path. For each simulation, you then write an initialization function qm_init, change the working directory to the directory where this function is located, and run the follwing commands (either from console or from a Matlab script)

	qm_setup();
	state=wave; | state=traj;
	qm_init(state);
	qm_propa(state);
	qm_cleanup();

Depending on the choice in the second line, the object "state" will be either a wavefunction (sampled on a grid) or a phase-space density (sampled by classical trajectories). Accordingly, the propagation called in the fourth line numerically solves a time-dependent Schroedinger equation (TDSE) or a classical Liouville equation (CLE). If certain seetings are made within qm_init.m, the latter can be replaced by a mixed quantum-classical Liouville equation (QCLE) which is approximately solved by surface hopping trajectories (SHT) methods. Replacing qm_propa by qm_bound in the lines above, you can also run a bound state calculation that numerically solves the time-independent Schroedinger equation (TISE), for objects of class "wave" only. There is also the option to run qm_movie instead, which produces animated graphics visualizing the results from previous runs of qm_propa and/or qm_bound. Alternatively, one can run qm_matrix and qm_abncd to switch from coordinate to energy representation of quantum mechanics where the (optimal) control of quantum dynamics can be simulated by calling qm_control or qm_optimal. These two functions work for closed as well as for open quantum systems; in the latter case they solve the Liouville-von Neumann equation (LvNE) with Lindblad operators for dissipation and/or dephasing. If necessary, dimension reduction can be carried out by qm_balance and qm_truncate or qm_H2model. For a complete list of functions, see also below.

The easiest way to learn how to set up an initialization function qm_init.m is by studying the numerous examples found in the Demos directory. As indicated there by the names of the subdirectories, some of those example are for prototyical model Hamiltonians (such as Morse oscillator, spin-boson system) while others are from the field of molecular physics (vibration, rotation, electronic excitation), partly also including application of quantum optimal control theory. A thorough description of all of these examples, along with data and graphical output, can be found on the general Wavepacket wiki pages hosted at SourceForge,
	http://sourceforge.net/p/wavepacket/wiki/Home/
where also a lot of numerical details are documented. Furthermore, a detailed user guide and a reference of all variables, functions, and parameters can be found on the Wiki pages of the Matlab version,
	http://sourceforge.net/p/wavepacket/matlab/wiki/Home/
Note that the further development of the WavePacket software will be centrally administrated through the SourceForge website, providing a GIT repository as well as a ticket system for planning bug fixes or feature requests arising from the community.

2. Brief description of the files
=================================
	
The Sources directory contains the following files and subdirectories

A. WavePacket functions
------------------------

qm_setup.m    - Before WavePacket simulations: set up simulations
qm_bound.m    - Perform bound state calculations: solve TISE
qm_propa.m    - Perform wavepacket of trajectory propagations: solve TDSE or CLE or QCLE
qm_movie.m    - Visualize results from previous WavePacket calculations (qm_bound or qm_propa)
qm_matrix.m   - Transform results of qm_bound (TISE) to eigen representation
qm_abncd.m    - Set up system matrices for TDSE or LvNE in energy representation 
qm_control.m  - Solve TDSE or LvNE in energy representation 
qm_optimal.m  - Optimal control of TDSE or LvNE systems in energy representation
qm_balance.m  - Transformation to balance controllability and observability
qm_truncate.m - Truncate states that are of low controllability and observability
qm_H2model.m  - Perform H2 optimal model reduction
qm_cleanup.m  - After WavePacket simulations: close files and clean up

B. Function packages
--------------------

+amo  - various model functions for additional multiplicative operators
+aux  - auxiliary functions; perhaps of some limited usefulness but not yet fully matured
+dip  - various model functions for permanent dipole moments (1st order interaction with E-fields)
+efi  - external electric fields; typically expressed as a sequence of pulses
+exp  - calculating expectation values of most important observables
+grid - class definitons for various | discrete variable | finite basis | representations
+ham  - certain aspects of the Hamiltonians, e.g. the coupling of the channels and the truncation
+hop  - several variants of surface hopping trajectory algorithms
+i_o  - saving/loading wavefunctions|trajectories during propagation
+init - various models for initial wavefunctions or classical phase space densities
+kin  - class definitions for special kinetic energy operators, e.g. for Jacobi coordinates or triatomics
+log  - text output goes to console and to logfile in parallel
+math - mathematical utility functions: Hermite/Laguerre polynomials, elliptic functions, Lyapunov/Sylvester solvers, etc
+nip  - various model functions for negative imaginary potentials used as absorbing boundary conditions
+oct  - utilities for (optimal) control theory
+ode  - solvers for ordinary differential equations used for qm_control, qm_optimal only
+pol  - various model functions for polarizabilities (2nd order interaction with E-fields)
+pot  - various model functions for (real) potential energy functions
+sbc  - various model functions for system-bath coupling (LvNE only)
+tmp  - choice of various numerical propagation schemes for TDSE or CLE or QCLE
+vis  - graphical output functions; among others: surface and contour plots of Wigner representations 


C. Main class definition folders
--------------------------------

@wave - representing quantum states by wavefunctions given on a grid
@traj - sampling phase-space densities by (quantum-)classical trajectories

While the above two can be considered mature, the following two still are still "under construction"

@ket  - representing quantum states by ket vectors based on an eigen|energy representation
@rho  - representing quantum density operators by density matrices based on an eigen|energy representation
	
3. Contact
==========

If you have any feedback, questions, suggestions, do not hestitate to contact us. The maintenance and further development is mainly done by PD Dr. Burkhard Schmidt at Free University Berlin, Germany
	burkhard.schmidt@fu-berlin.de
Alternatively, you can also write to Dr. Ulf Lorenz
	ulf@wavepacket.org