Versions.Main
Looking at the project, you may come across the question "Why are there two different versions of WavePacket?". There is a bit of history involved, as usual, but the two projects also cater slightly different use-cases.
Both projects are active and supported. Both projects do not drown in user-feedback, so feedback / requirements from users are generally treated with high priority.
Short version
To quickly understand the pros and cons of the two versions, a small list:
| Matlab /Octave version | C++ / Python version |
|---|---|
| Suggestion: Suitable for common use cases, such as wavepacket propagation | Suggestion: Suitable for exotic use-cases, e.g. auxilliary density operators as in HEOM or similar approaches (more details, see section "long version") |
| Matlab (Octave support added in Version 7) | C++ with Python bindings |
| Mature, used in developer's research | In development, spare-time project |
| Framework approach: you usually write an input script where you set parameters and run the calculation | Toolbox approach: you write a program where you create objects (grid, operators, ...) and piece your simulation together. |
| Well-supported plots and animations | (as of 0.3.5) some support for one-dimensional plots and animations |
| Support for wavepackets (grid-based), density operators (eigenstate basis, ODE solvers), quantum-classics | Support for wavepackets and density-operators (both grid-based) |
Comparison of input
To further aid the comparison, here is the input for a Gaussian wavepacket in a one-dimensional harmonic oscillator. The input is taken from this demo, I stripped all comments and plot setup for brevity.
Matlab / Octave version:
the usual setup is contained in a function qm_init() that looks like that:
function qm_init
global hamilt plots space time
space.dof{1} = grid.fft;
space.dof{1}.n_pts = 128;
space.dof{1}.x_min = -10;
space.dof{1}.x_max = 10;
space.dof{1}.mass = 1;
time.steps.m_start = 000;
time.steps.m_stop = 020;
time.steps.m_delta = pi/10;
time.steps.s_number = 100;
time.dof{1} = init.gauss;
time.dof{1}.width = sqrt(2);
time.dof{1}.pos_0 = -3.0;
time.dof{1}.mom_0 = 0.0;
hamilt.truncate.e_min = 0.0;
hamilt.truncate.e_max = 50.0;
hamilt.pot{1,1} = pot.taylor;
hamilt.pot{1,1}.coeffs = [0;1];
C++ / Python version
For brevity, only the Python script is shown. It is run like an ordinary Python program. The example may be not up-to-date, but the basic idea still holds.
import math
import wavepacket as wp
xDof = wp.PlaneWaveDof(-10, 10, 128)
grid = wp.Grid([xDof])
hamiltonian = wp.CartesianKineticEnergy(grid, 0, mass = 1.0) \
+ wp.HarmonicPotential(grid, 0, mass = 1, omega = 1)
equation = wp.SchroedingerEquation(hamiltonian)
psi_0 = wp.buildProductWavefunction( \
grid, \
[ wp.GaussianState(x_0 = -3, p_0 = 0, sigma = 2) ])
propaPrimitive = wp.ChebychevPrimitive(equation)
propagator = wp.Propagator(propaPrimitive, dt = math.pi / 10)
propagator.propagate(psi_0, 0, 20)
Long version
The older and more developed version was the Matlab/Octave version. It is mature, and works very well for all problems that most users will ever encounter. However, it turned out over time that there were some problems with it:
- Obviously, the Matlab version requires a Matlab installation. Matlab is a great environment with lots of convenience also for the user. However, even though licenses are available in many academic institutions, Matlab is still a heavy dependency. And there have been academic institutions where this is a problem. Hence, Octave support has been added with version 7.
- The Matlab/Octave version follows a framework approach. Roughly speaking, it works a little like a prefabricated building that is delivered as a black box with a construction team. You can customize some aspects (here: the grid size, laser fields etc.), but the general outline is fixed. If you want to implement a use-case that was not envisioned by the code creators, this is generally doable, but becomes complex pretty quickly.
There were some more ideas, for example the C++11 standard, or the idea of doing test-driven development with Wavepacket, but that was the main driver for trying to get another project running. Over time, most reasons have vanished, for example, version 7 of the Matlab version will run (mostly?) under GNU Octave. And a lot of potential advantages turned out to be dead ends; for example, the C++ version supports density operators in a grid representation, but open systems are usually defined in terms of Hamiltonian eigenstates. However, there still remains the second issue: Non-standard use cases are difficult to do, even though they are rather rare. Two examples:
- You want to approximate a thermal density operator with a set of random thermal wave functions, propagate this set of wavefunctions in time and calculate expectation values by averaging over them (see, for example, https://doi.org/10.1063/1.4862739 and references therein).
- You want to propagate an open quantum system with memory effects. Several approaches, for example HEOM or Tannor's approaches (e.g. https://doi.org/10.1063/1.479669) store the memory of the bath in auxiliary density matrices that are coupled to the "real" density matrix. Your task, then, is to propagate this set of N+1 density matrices together in time.
Such use cases which typically appear in the context of open and thermal quantum systems, benefit from a different approach, the toolbox approach. Coming back to the house analogy, you would not get a house, but lots of standard components, say, window frames in all sizes, and all required tools, from which you build your own house. The drawback is that building a standard house is slightly more involved, but you can do custom designs without digging too deep into details. For a standard wavepacket propagation, you would get a lot of default components, like grids, operators etc., which you "only" need to plug together to represent your final differential equations.
This is the general approach taken by the C++ version. You get a propagator that encapsulates the concrete differential equation, and which you can apply to multiple random thermal wavefunctions without problems. Or you define a system of equations for your bath with memory and propagate multiple density operators in parallel.
However, this flexibility comes with a cost: Certain things are more cumbersome to implement than in the Matlab/Octave version's framework approach, for example the split-operator method, which is why these are less supported in the C++ version compared to the Matlab/Octave version.
Put together, this hopefully explains the suggestion from the short comparison: If in doubt, use the Matlab/Octave version, it will get you very far with a rather low entry barrier. If you want to do one of these special things that do not fit into the "setup(); propagate(); finish()" scheme, seriously consider the C++/Python version.