File	Date	Author	Commit
Demos	2018-12-19	bsch63	[9585c0] If demo examples run flawlessly over night, thi...
Sources	2018-12-20	bsch63	[3ce026] Deleted obsolete file: Sources/+hop/hopping.m
README	2018-12-20	bsch63	[e33cab] Modified README again

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.0 of WavePacket released on Dec 20, 2018. Note that this is the first version of WavePacket that also offers 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). 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). 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 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). 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(state) 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, 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 service for 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 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 which 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
+grid - class definitons for various discrete variable representations
+ham  - certain aspects of the Hamiltonians, e.g. the coupling of the channels 
+hop  - several variants of surface hopping trajectory algorithms
+i_o  - saving/loading wavefunctions|trajectories during propagation
+init - various models for initial wavefunctions
+kin  - class definitions for various 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; among others: Hermite/Laguerre polynomials, elliptic functions, Lyapunov/Sylvester solvers, etc
+nip  - various model functions for negative imaginary potentials used to absorb boundary conditions
+oct  - utilities for (optimal) control 
+ode  - solvers for ordinary differential equations
+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 (see above)
@traj - sampling phase-space densities by (quantum-)classical trajectories (see above)

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