Read Me
Description
===========
Wavepacket C++ is a C++ library to numerically solve the Schroedinger equation
for distinguishable particles.
A Python interface / Python module is also available, see the end of this
readme for installation instructions.
The code is under the permissive ISC license. See the file
license/Wavepacket.txt 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@wppy.org.
Depending on the complexity of the feature, this will lead to an immediate,
rapid, or priorized implementation.
System requirements (C++ library)
=================================
Note that Wavepacket provides a mostly automatized installation in a virtual machine.
See README_VirtualMachine for the details, and check Vagrantfile; the latter
mostly consists of a shell script to automate the build; as such, it may
provide hints on how to build Wavepacket or its dependencies.
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. Building on Windows should be principally
possible, but is rather complicated right now. It is on the Todo list, though.
* CMake >= 3.19
You can download it from https://cmake.org.
In general, CMake is strongly backwards-compatible, so any later version
should also work.
* A compiler that implements the C++-17 standard, in particular std::filesystem.
Any modern g++ (version 7 or later) or Clang++ (version 8 or later) should be fine.
* The tensor library that we use
- clone it via git
git clone https://github.com/juanjosegarciaripoll/tensor.git
- checkout the current CMake development version
git checkout cmake
Being a development version, compatibility may change quickly, though. The build is
currently tested against a specific commit. To reproduce
git checkout 9f46d55
- You will need to enable FFTW support, which also requires the fftw3 libraries
(run CMake with "-D TENSOR_FFTW=ON")
- You do _not_ need Arpack, which only adds more dependency management.
Disable with "-D TENSOR_ARPACK=OFF".
* The boost libraries from http://www.boost.org
- You need at least boost version 1.74; most distributions should come with this version
nowadays
* If you want to install the Python interface, a reasonably modern Python.
* doxygen if you want to build the documentation
* gnuplot, ffmpeg, possibly ImageMagick if you want to process the plotting output
Compilation and getting started (C++)
=====================================
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 with the following steps.
1. Run "cmake -S $WP_SRCDIR -B $WP_BUILDDIR". Here, $WP_SRCDIR is the
source directory, where this readme resides, $WP_BUILDDIR is the build
directory for CMake, which can be deleted after installation.
If this does not work, see the notes in the next section.
2. Build "make -C $WP_BUILDDIR -j 4" (or however many cores you have).
3. 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, drop me a mail (ulf@wavepacket.org). I usually run these tests
only on my private machine, so spurious numerical noise may occur and lead to test
errors. I would be glad to know that to fix the tests.
4. Install everything by running "make -C $WP_BUILDDIR install", usually with admin privileges.
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 -S $WP_SRCDIR -B $WP_BUILDDIR
2. After running cmake once, run
ccmake $WP_BUILDDIR
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. Select the build directory and you get a
list of all settings.
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, WP_BUILD_PYTHON, WP_BUILD_DOC
Set to "ON" or "OFF" to enable / disable these features
* Python3_ROOT
If you want to build the Python extension, set this to the path of the configured
virtual environment (see the Python section below).
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 library/ for additional
details. The building is also documented in the package documentation (the
"Hello, world" tutorial). Check also the "Demos" subdirectory where you
can find some demo source code to try this out.
The package documentation is available online:
http://wavepacket.sourceforge.net/cpp-doc/current/index.xhtml
and also optionally compiled when building the library.
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/.
The Python interface
====================
The Python bindings allows access to the WavePacket classes via Python.
This can be useful because debugging and experimenting is simpler
and faster in Python as compared to C++.
For more details on how to use the Python bindings and the limitations, see
the tutorial "Using the Python interface"
http://wavepacket.sourceforge.net/cpp-doc/current/sec_python.xhtml
Note that this module is not a Python package with a "Python look&feel", but a
binding to a C++ library. It may feel awkward at times as a result. For
example, you need to wrap all CTensors in numpy.arrays for proper manipulation.
Setting up a virtual environment
--------------------------------
To build the Python interface, you should preferably set up a virtual environment.
This somewhat encapsulates the dependencies that Wavepacket needs from the
primary Python installation. You can use the same venv later for running Wavepacket,
by starting the Python interpreter as <venv>/bin/python instead of the system's
native Python.
To set up the virtual environment in a directory <venv>, you can run the
following commands. You may have to add a suffix "3" to the commands (e.g.,
python -> python3) depending on the system.
- python -m venv <venv>
- <venv>/bin/pip install -r <path_to_wavepacket_sources>/python/requirements.txt
You may also need to install FFMpeg if you want to write out the plot sequences
as video files.
Building with the Python interface
----------------------------------
The build with the Python interface is completely analogous to the C++ version (see above).
All you need to do is to set the WP_BUILD_PYTHON option, that is, run
cmake -D WP_BUILD_PYTHON=ON -S $WP_SRCDIR -B $WP_BUILDDIR -D Python3_ROOT=<venv>
To make sure that everything works, I would recommend to run the tests (run
"ctest" in the binary directory), because they will fail on runtime errors.
Using the Python interface
--------------------------
Starting with version 0.3.2, Wavepacket no longer installs the Python bindings
as a Python package, but puts it in the installation directory. As a
consequence, you need to tell Python where to find the Wavepacket bindings. By
default, they are installed under ${INSTALL_DIR}/lib/wavepacket_python. By
default, the ${INSTALL_DIR} is /usr/local.
* You can set the PYTHONPATH variable. It is a colon-separated list of directories,
so something like "export PYTHONPATH=/usr/local/lib/wavepacket_python" should do the trick.
* Or you can set the path variable directly in Python with
import sys
sys.path.append('/usr/local/lib/wavepacket_python')
Afterwards, you can just "import wavepacket" and use all classes from this namespace, e.g.,
"wavepacket.PlaneWaveDof(...)". See the tutorial and the demos for more information.