1. INTRODUCTION

TEBDOL [1] is a program for calculating time evolution of a system of
ultracold atoms in one-dimensional and two-dimensional optical
lattices. It utilizes the time-evolving block decimation algorithm
(TEBD). One-dimensional version is parallelized using MPI.

2. INSTALLATION

TEBDOL is written in Common Lisp and has the following dependencies:

* Steel Bank Common Lisp (SBCL)

  SBCL is an ANSI Common Lisp compiler. Source and binaries are
  available at http://sbcl.org/. TEBDOL was tested with version 1.2.4.

* Basic Linear Algebra Subprograms (BLAS) and Linear Algebra Package
  (LAPACK)

  BLAS and LAPACK libraries provide vector and matrix routines. There
  are several vendor-provided implementations available. TEBDOL was
  tested with OpenBLAS 0.2.12, which can be download at
  http://www.openblas.net/. It also works with Intel MKL.

* Message Passing Interface (MPI)

  MPI provides support for parallelization. TEBDOL was tested with
  version 1.6.5.

* GNU Scientific Library (GSL)

  GSL is used for random number generation. TEBDOL was tested with
  version 1.16.

After installing SBCL, BLAS/LAPACK, MPI, and GSL, you'll need to edit
the parameters in the script "run" in the top-level directory:

* LD_LIBRARY_PATH  Paths to directories containing the libraries.
* SBCL             Path to the SBCL binary.
* DSS              Maximum amount of memory allocated for a single
                   SBCL process.

You'll probably also need to edit the file "conf.lisp", where you can
specify the name of the BLAS/LAPACK library and switch MPI
implementation between OpenMPI and MPICH.

3. USAGE

There are several examples in the directory "examples":

* Test of the MPI communication ("mpi.lisp").

  The library is compiled by running it as a single process:

  $ mpirun -n 1 ./run examples/mpi.lisp

  MPI communication can be tested with a command:

  $ mpirun -n 4 ./run examples/mpi.lisp

* Phase revivals in one dimension ("revivals.lisp").

  An initial state can be created with a command:

  $ ./run inputs/revivals.lisp

  Time evolution is then calculated with a command:

  $ ./run examples/revivals.lisp

  To run TEBDOL in 4 processes in parallel you can run the script
  using mpirun:

  $ mpirun -n 4 ./run examples/revivals.lisp

  If you're running it on a single machine you should limit the number
  of BLAS/LAPACK threads:

  $ OMP_NUM_THREADS=1 mpiexec -n 4 ./run examples/revivals.lisp

* Load balancer example ("balancer.lisp").

  This is the same calculation as a previous one. The source code
  shows how to use the load balancer.

* Equilibration example ("trotzky.lisp").

  This example simulates time evolution of a model from article
  [2]. Usage is similar to previous examples:

  $ ./run inputs/trotzky.lisp
  $ ./run examples/trotzky.lisp

* Many-body localization in two dimensions ("mbl.lisp").

  This example is inspired by article [3]. Usage:

  $ ./run inputs/mbl.lisp
  $ ./run examples/mbl.lisp

  The lattice size and the number of particles should be increased to
  observe a proper crossover from thermalization to localization.

* Boson expansion in two dimensions ("expans.lisp").

  This example is inspired by article [4]. Usage:

  $ ./run examples/expans.lisp

The sample outputs are in the directory "outputs".

4. FILES

asdf.conf: A configuration file for Another System Definition Facility.
conf.lisp: Basic program configuration.
run: Main execution script.
examples/*: Example calculations.
outputs/*: Sample outputs of the examples.
inputs/*: Input files and programs to create them.
tebdol/array.lisp: Array tensor routines.
tebdol/bhm.lisp: Bose-Hubbard model.
tebdol/blas.lisp: Interface to BLAS and LAPACK.
tebdol/exp.lisp: Tensor exponential.
tebdol/mpi.lisp: Interface to MPI.
tebdol/mps.lisp: Routines for working with matrix product states.
tebdol/part.lisp: Partitioning routines including a load balancer.
tebdol/serial.lisp: Serialization routines.
tebdol/tebd.lisp: Time-evolving block decimation algorithm.
tebdol/tebdol.asd: System definition.
tebdol/tensor.lisp: Symmetric tensor routines.
tebdol/ttns.lisp: Routines for working with tree tensor network states.
tebdol/util.lisp: Miscellaneous utilities.

5. AUTHOR

Miroslav Urbanek <miroslav.urbanek@mff.cuni.cz>

6. REFERENCES

[1] M. Urbanek and P. Soldán, "Parallel implementation of the
time-evolving block decimation algorithm for the Bose–Hubbard model",
Comput. Phys. Commun. 199, 170–177
(2016). doi:10.1016/j.cpc.2015.10.016

[2] S. Trotzky et al., "Probing the relaxation towards equilibrium in
an isolated strongly correlated one-dimensional Bose gas", Nature
Physics 8, 325–330 (2012). doi:10.1038/nphys2232

[3] J.-y. Choi et al., "Exploring the many-body localization
transition in two dimension", Science 352, 1547–1552
(2016). doi:10.1126/science.aaf8834

[4] J. Hauschild et al., "Sudden expansion and domain-wall melting of
strongly interacting bosons in two-dimensional optical lattices and on
multileg ladders", Physical Review A 92, 053629
(2015). doi:10.1103/PhysRevA.92.053629
