WavePacket (C++/Python) Git repository

Description
===========

This is a C++ library to numerically solve the Schroedinger equation for
distinguishable particles.

The code is under the (very permissive) ISC license. See the file LICENSE for further details.

The current detailed status of what is implemented can be found in the wiki
https://sourceforge.net/p/wavepacket/cpp/wiki/Features/

If you lack a feature that you would like to have, drop a mail to ulf@wavepacket.org.
Depending on the complexity of the feature, this will lead to an immediate,
rapid, or priorized implementation.

There is also a Python interface. See README.Python for instructions and details on that.


System requirements
===================

Note that there is a virtual machine image on the homepage for quick&simple installation.
See https://sourceforge.net/p/wavepacket/cpp/wiki/VirtualMachine/

To be able to compile the code, you need the following:

* A Unix system.
  I only test the build under Linux, but if you get the other requirements, any
  other Unix should be fine as well.
* CMake, at least version 3.16
    - very recent, so you may have to download it from https://cmake.org
* a compiler that implements the C++-14 standard.
  One of the later g++ (around version 5) or CLang++ version 3.4 or later should be fine.
* the tensor library that we use
    - clone it via git
      git clone https://github.com/juanjosegarciaripoll/tensor.git
      then compile and install it (usual autoconf setup)
    - note that you will need to enable FFTW support, which also requires the fftw libraries
      (run the configure script with "--with-fftw")
    - you can also try out the mps-bundle, which may offer more convenient compilation
      git clone https://github.com/juanjosegarciaripoll/mps-bundle.git
* the boost libraries from http://www.boost.org
    - You need at least boost version 1.56
* doxygen if you want to build the documentation
* gnuplot, ffmpeg, possibly ImageMagick for the processing of the plotting output


Compilation and getting started
===============================

Simple Installation
-------------------

WavePacket uses CMake for the setup of the build process.  Assuming you have
all requirements installed in standard locations, you can compile and install
the library by the following steps. They assume the wavepacket directory (where
this Readme resides) to be ${WP_SRCDIR}.

1. Create a new build directory where the binary files will be placed
   (we do a so-called out-of-source build)
2. In the build directory, run "cmake ${WP_SRCDIR}"
3. In the build directory, run "make -j 4" (or however many cores you have).
4. Optionally, check that everything went ok by running "ctest -j 4" (or however many cores you have)
   and getting a cup of coffee.
   If some test fails, this may be an error, so drop me a mail (ulflor@users.sourceforge.net)
5. Install everything by running "make install" with admin privileges
   afterwards you can remove the build directory if you wish


Configuring the build
---------------------

You can change various settings of the build process by defining variables to
your preferences. There are three ways to do so:

1. When you originally run cmake, add flags "-D<var>=<value>", for example
   cmake -DCMAKE_BUILD_TYPE=Debug ${WP_SRCDIR}
2. After running cmake once, run
   ccmake ${WP_SRCDIR}
   This fires up a textmode program where you can edit the variables and
   reconfigure/regenerate the build system by hitting "c", then "g".
   Some variables are marked as advanced, hit "t" to be able to edit them.
3. Alternatively, you can run "cmake-gui" for a graphical interface for
   the editing of the variables.

The most important variables that you may wish to change:

* CMAKE_INSTALL_PREFIX
    defines the root path where all the libraries and such will be installed.
    Default is "/usr/local"
* CMAKE_CXX_COMPILER
    the full path to the C++ compiler to use
* WP_BUILD_DEMOS, WP_BUILD_DOCUMENTATION
    Set to "ON" or "OFF" to enable / disable these features
* WP_TENSOR_CPPFLAGS, WP_TENSOR_LDFLAGS
    The flags to compile and link the tensor library. Should not be required
    because it is autodetermined from the installed tensor-config script.
    However, if installed the library in an uncommon location, it may be
    necessary to give these values explicitly.



First Steps
-----------

The installation also installs a build script to simplify the compilation of your
own programs. The syntax is

wp-build.sh  <executable_name> <source_file>

The script is documented and can be found under scripts/ for additional
details. The building is also documented in the package documentation (the
"Hello, world" tutorial). Check also the "Demos" subdirectory where you
can try this out.

The package documentation is available online: 
http://wavepacket.sourceforge.net/cpp-doc/current/index.xhtml
It contains a small tutorial that should cover the basic concepts of the library.
Also, some special use-cases/demos are discussed in depth. Several solutions to
common problems can be found under the demos (everything below directory
Demos/), and in the acceptance tests under test/acceptance/.