Description

Wavepacket C++ is a C++ library to numerically solve the Schroedinger equation
for distinguishable particles. You can also build a Python interface with some
utility functions for plotting.

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.

Installation

Wavepacket offers three different modes of installation:

• Binary Python package under Windows
  Download Python, download a zip file,
  use Wavepacket somewhat like a normal Python module.

• Installation in a virtual environment
  Download a virtualization environment, run a script to provision a virtual machine,
  use a Jupyter notebook to run Python scripts.

• Building from sources
  Set up your system, build and go.

When you are done, you can start to use Wavepacket.

1. Binary Python package

The Binary package is bundled manually for Windows and comes with an own Readme.
It can be found under python/Readme_PythonPackage.md.

2. Installation in a virtual environment

The huge advantage is Plug&Play: With essentially three commands, you get
WavePacket compiled and running. In particular, WavePacket runs on Windows that way.
However, there are a few drawbacks:

• The Jupyter notebook does not work in some edge cases.
  For example, plotting (currently) does not work as it should
  (you can still save them, though).
• It is slightly slower. Quoted figures are 10-20% performance
  penalty.

Installing WavePacket on a virtual machine

1. Install vagrant from https://vagrantup.com.

2. Install VirtualBox from https://www.virtualbox.org.

3. In the WavePacket root directory (== the directory that contains this file),
   modify the VagrantFile with a text editor. Most importantly, you may want to
   adjust the lines in the highlighted block, in particular config.vm.synced_folder

4. Open a terminal ("Windows console") and cd to the WavePacket root directory
   with the Vagrantfile
5. Run "vagrant up".
   Get some coffee. The VM is set up, which requires quite some downloads and some
   heavy compilation.

You now have a working VM with WavePacket installed.
If you ever want to remove it again, just type "vagrant destroy" in the wavepacket root.
You can always recreate the VM with "vagrant up" after destruction.

Running WavePacket on a virtual machine

The VM is configured such that it runs a Jupyter notebook server on the VM, and
you control it from a browser on your host machine.

1. Open a terminal, cd to the WavePacket root directory.
2. Start the VM: "vagrant up"
3. Open a console in the VM: "vagrant ssh"
4. In the VM, start Jupyter with the shortcut command "notebook"
5. Open your favorite browser, and point it to "http://127.0.0.1:18888"
6. Work with the Jupyter notebook to your heart's desire.
7. When you are done with the VM, leave the ssh shell: "exit"
   and stop the VM with "vagrant halt".

I recommend to get a basic understanding of Jupyter notebooks / Python. In particular,
the tab-autocompletion, the '?' operator and the help() function will make an
exploration of the Wavepacket API much simpler.

I also recommend to put all Jupyter notebooks in the synchronized folder.
Then you have them safely tucked away on your host system and can always destroy
the VM, for example because you want to install another WavePacket version.

Caveats, known problems with the VM solution

• "VirtualBox does not work on my Windows machine."

Under Windows, there are two incompatible ways of running a VM. Either the VM
takes special privileges, or you use the Windows-internal hypervisor (HyperV).
HyperV is disabled by default, but required for certain VM programs, in particular
WSL2 or Docker. VirtualBox does not currently work together with HyperV.

If you are one of the unlucky persons using HyperV, you need to use this as backend.
Append "--provider hyperv" to all vagrant calls, and modify the "hyperv" provider
settings in the Vagrantfile instead of the "virtualbox" one.

• If for whatever reason you need to login in the VM (e.g., start it from the
  VirtualBox GUI), the user in the VM is called "vagrant" with password "vagrant".

3. Installing from sources

Wavepacket uses CMake for the build, and requires a handful of external libraries.
Instead of spending many lines on detailing the build, I will assume you know the
basics of building a library and point you to the information you need.

• Read the various CMakeLists.txt in the source code. In particular the top-level
  CMakeLists.txt contains build settings you can change. Even as a non-CMake expert,
  the very basic layout should be reasonably comprehensible.
• Read the file "Vagrantfile". Besides some setup, it contains a heavily documented
  shell script that provisions the virtual machine. Even if you choose not to
  follow these exact steps, it describes a working reference build from scratch,
  including all non-trivial dependencies.

First steps after installation

You can either write C++ programs that use the Wavepacket library,
or you can use the Python bindings and run Wavepacket in Python. Note,
however, that Wavepacket is not a native Python library, so it may
feel awkward here and there.

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/.

as a C++ library

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></source_file></executable_name>

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.

as a Python module

1. Install Python

Under Linux, this is usually part of the system installation,
but you may want to also install FFMPeg to write out plot animations.

1. Set up a venv

The first step whenever you do something with Python. Run

python3 -m venv <dir_to_venv></dir_to_venv>

Windows users probably run "py.exe" instead. From now on only
use the programs in <dir_to_venv>/bin (Windows: <dir_to_venv scripts="">).</dir_to_venv></dir_to_venv>

1. Install required packages

<venv_bin>/pip install -r <wavepacket_root>/python/requirements.txt</wavepacket_root></venv_bin>

1. We need to tell Python where the Wavepacket bindings are.
   With Wavepacket installed under <install_root>, the bindings are located under
   <install_root>/lib/wavepacket_python by default.
   There are two ways to instruct Python:</install_root></install_root>

a) set the environment variable PYTHONPATH; in a bash:
export PYTHONPATH='<install_root>/lib/wavepacket_python'
b) start Python, and execute</install_root>

  import sys
  sys.path.append("<install_root>/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.