wavepacket 0.1.0__tar.gz → 0.3.0__tar.gz

wavepacket-0.3.0/.github/workflows/ci_testing.yml

@@ -0,0 +1,30 @@
+name: Wavepacket CI
+run-name: Testing ${{ github.ref_name }} with ref ${{ github.ref }}
+
+on:
+  push
+
+jobs:
+  Run-all-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        id: cp311
+        with:
+          python-version: '3.11'
+      - uses: actions/setup-python@v6
+        id: cp312
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-python@v6
+        id: cp313
+        with:
+          python-version: '3.13'
+      - uses: actions/setup-python@v6
+        id: cp314
+        with:
+          python-version: '3.14'
+      - run: ${{ steps.cp313.outputs.python-path }} -m venv ~/venv
+      - run: ~/venv/bin/python -m pip install tox
+      - run: cd $GITHUB_WORKSPACE && ~/venv/bin/tox

wavepacket-0.3.0/.gitignore

@@ -0,0 +1,67 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/

wavepacket-0.3.0/.readthedocs.yaml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+  apt_packages:
+    - dvipng
+    - texlive-binaries
+formats:
+  - htmlzip
+sphinx:
+  configuration: doc/conf.py
+python:
+  install:
+    - requirements: doc/requirements.txt
+    - method: pip
+      path: .

wavepacket-0.3.0/CHANGELOG.rst

@@ -0,0 +1,70 @@
+=========
+ChangeLog
+=========
+
+0.3
+---
+
+- (#32) added ChebychevSolvers
+  - added a ChebychevSolver for real-time propagation
+  - added RelaxationSolver for imaginary-time propagation
+  - added function to normalize a state
+  - Added various documentation on Chebychev solver use, relaxation,
+    and polynomial solver theory
+
+- (#24) added ExpressionSum and OneSidedLiouvillian
+        for more complex expressions
+
+- (#31) added diagonalize() function for operator eigenstates and -energies
+
+- (#11) operator truncation and systematic handling of operator time-dependence
+
+- (#12) Added some documentation on the construction of thermal states
+
+- (#12) Changed the implementation of builder.random_wave_function();
+  it now constructs random numbers exp(i * phi) because these are more useful.
+
+- (#13) Tutorials and demos also can be downloaded as Jupyter notebooks
+  and mostly render fine as notebooks.
+
+- significantly improved type information, simplified attributes,
+  implemented some annotation best practices
+
+
+0.2
+---
+
+- (#18) added spherical harmonics expansion:
+  degree of freedom, operator, generator
+
+- (#19) added time-dependent functions and laser fields as operators,
+  including helper functions for sin**2 and rectangular pulses with soft turn-on
+
+- (#20) added functionality related to projections
+  - projection operator for projecting onto a state or subspace
+  - population() function to easily calculate populations of target states
+  - Gram-Schmidt orthogonalization and normalization
+
+- (#21) added more initial states
+  random wave functions, zero densities and wave functions, unit density
+- (#21) added function grid.fbr_density() to calculate density in FBR
+
+- (#22) 1D plotting helpers
+  - added plotting classes StackedPlot1D and SimplePlot1D
+  - added a tutorial on plotting
+
+- (#23) Added a notebook with the PendularStates demos converted from the older versions
+
+- (#15) added CI build using tox for different Python versions
+        Wavepacket now supports every Python >= 3.11
+
+
+0.1
+---
+
+Initial release.
+
+Scope is the simulation of a harmonic oscillator with an ordinary ODE solver,
+plus a bit of introductory documentation and a demo.
+
+That is, infrastructure, not so much content.

{wavepacket-0.1.0 → wavepacket-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Ulf Lorenz
+Copyright (c) 2024-2025 Ulf Lorenz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{wavepacket-0.1.0 → wavepacket-0.3.0}/PKG-INFO

@@ -1,29 +1,27 @@
 Metadata-Version: 2.4
 Name: wavepacket
-Version: 0.1.0
+Version: 0.3.0
 Summary: A package for the propagation of quantum-mechanical wave functions.
 Author: Ulf Lorenz
-Requires-Python: >=3.12
+Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Chemistry
 Classifier: Topic :: Scientific/Engineering :: Physics
 License-File: LICENSE
 Requires-Dist: numpy >= 2.1.3
 Requires-Dist: scipy >= 1.14.1
-Requires-Dist: matplotlib >= 3.10 ; extra == "demos"
-Requires-Dist: sphinx >= 8.1.3 ; extra == "doc"
-Requires-Dist: sphinx-autoapi >= 3.4.0 ; extra == "doc"
-Requires-Dist: numpydoc >= 1.8.0 ; extra == "doc"
-Requires-Dist: myst-nb >= 1.2 ; extra == "doc"
-Requires-Dist: sphinx-rtd-theme >= 3.0.2 ; extra == "doc"
-Requires-Dist: pytest >= 8.3 ; extra == "test"
+Requires-Dist: matplotlib >= 3.10
 Project-URL: Home, https://github.com/ulflor/wavepacket
-Provides-Extra: demos
-Provides-Extra: doc
-Provides-Extra: test
 
 Description
 -----------

wavepacket-0.3.0/doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

wavepacket-0.3.0/doc/advanced/pendular_states.md

@@ -0,0 +1,172 @@
+---
+file_format: mystnb
+kernelspec:
+    name: python3
+---
+
+# Pendular states
+
+This web page can be downloaded as notebook: {nb-download}`pendular_states.ipynb` (Jupyter)
+or {download}`pendular_states.md` (Markdown)
+
+The goal of this demo is the partial reproduction of some results of a paper by Ortigoso et al.[^ortigoso]
+Besides discussing pretty cool physics, it aims to demonstrate
+how to extract non-trivial data with minimal fuss and plot it.
+
+## Alignment of molecules, some theory
+
+If a molecule interacts with a non-resonant laser field, the electronic ground state is shifted in energy.
+We can calculate the shift with standard perturbation theory and cavity-dressed states as
+
+$$
+\Delta E \propto - \sum_n \frac{|\langle \Phi_0 | \hat{\vec{\mu}} \vec E |\Phi_n \rangle|^2}{E_n - E_i - \omega}
+    = - \frac{1}{2} \alpha(\omega) E^2 \cos^2 \theta
+$$
+
+in terms of the dipole operator $\mu$, the electric field with strength $E$ and frequency $\omega$,
+and where the summation includes all excited states $\Phi_n$ with energies $E_n$.
+Calculating the energy shift is difficult, but that is not our goal here.
+Instead, we absorb all these calculations in a material-specific dynamic polarizability $\alpha(\omega)$.
+Then only a dependency on the angle $\theta$ between the effective dipole moment and the laser
+polarization axis remains.
+
+If we plug this energy shift into the formula of a rigid linear rotor, we arrive at the Hamiltonian
+
+$$
+\hat H = \frac{\hat{L}^2}{2I} - \frac{1}{2} \ \alpha E^2 \cos^2\theta.
+$$
+
+This Hamiltonian describes a linear rotor (first term) trapped in a cosine-shaped potential that draws the
+rotor towards the laser polarization axis ($\alpha > 0$) or away from it ($\alpha < 0$).
+In the following, we only consider the former case of a positive polarizability.
+As the final step, we introduce three further manipulations:
+
+1. We assume that the electric field changes slowly over time. Effectively, this adds a time-dependent shape function
+   to the second term in the Hamiltonian. We will follow the reference and assume a Gaussian shape.
+2. Because only the product of electric field strength and polarizability matters, we replace it by a
+   single parameter.
+3. To get rid of the moment of inertia, we rescale the time such that we can set $I=1$.
+
+With these manipulations, we arrive at the final formulation of a scaled model Hamiltonian
+
+$$
+\hat H = \frac{\hat{L}^2}{2} - \frac{\Delta}{2} \ \cos^2\theta \ \mathrm{e}^{- (t - \delta)^2 / \sigma^2}
+$$
+
+In the following, we will follow ref.[^ortigoso] further by studying the dynamics of this Hamiltonian
+in different parameter regimes.
+
+## Non-adiabatic alignment
+
+The natural timescales of the scaled Hamiltonian are determined by the energy levels of the free rotor.
+For low-lying rotational states, these time scales are somewhere on the order of 0.1 ... 1.
+If the laser pulse is shorter than this timescale, the laser effectively "kicks" the rotor,
+after which it starts to tumble.
+
+As alignment measure, we usually employ the expectation value of the squared cosine.
+In the dynamics shown below, we can clearly see the out of equilibrium dynamics after the laser pulse at t = 0.15.
+This plot corresponds to the first graph of figure 1 of ref.[^ortigoso].
+The stronger the laser field the faster the subsequent dynamics of the rotor.
+
+Note that at certain points in time, the rotor exhibits alignment recurrence even after the laser field has passed.
+This field-free alignment is used in practice because the molecule is aligned, yet undisturbed by external fields.
+
+```{code-cell}
+import math
+import matplotlib.pyplot as plt
+import numpy as np
+
+import wavepacket as wp
+
+def calculate_alignment(Delta, sigma, l0=0, m=0):
+    delay = 3 * sigma
+
+    # tiny optimization: smaller grids are faster
+    thetaDof = wp.grid.SphericalHarmonicsDof(25+l0, m)
+    grid = wp.grid.Grid(thetaDof)
+
+    psi0 = wp.builder.product_wave_function(grid, wp.SphericalHarmonic(l0, m))
+
+    kinetic = wp.operator.RotationalKineticEnergy(grid, 0, 0.5)
+    cos2 = wp.operator.Potential1D(grid, 0, lambda theta: np.cos(theta)**2)
+    laser = wp.operator.TimeDependentOperator(grid,
+                                              lambda t: Delta * math.exp(-(t-delay)**2/sigma**2))
+
+    hamiltonian = kinetic - 0.5 * cos2 * laser
+    equation = wp.expression.SchroedingerEquation(hamiltonian)
+    solver = wp.solver.OdeSolver(equation, dt=sigma / 50)
+
+    results = [(t, wp.operator.expectation_value(cos2, psi))
+               for (t, psi) in solver.propagate(psi0, 0, 500)]
+    times = np.array([t for (t, _) in results])
+    expectation_values = np.array([abs(val) for (_, val) in results])
+    
+    return times, expectation_values
+
+times, expectation_values_100 = calculate_alignment(Delta=100, sigma=0.05)
+_, expectation_values_400 = calculate_alignment(Delta=400, sigma=0.05)
+_, expectation_values_900 = calculate_alignment(Delta=900, sigma=0.05)
+plt.plot(times, expectation_values_100, '-k',
+         times, expectation_values_400, '--k',
+         times, expectation_values_900, ':k');
+```
+
+Note that the actual work is encapsulated in a function with only a few parameters.
+This was a deliberate choice to make the code reusable over this whole demo,
+hence the parameters "l0" (initial angular momentum) and "m" (magnetic quantum number), which will only be
+used further below.
+When changing the laser field parameters, you would otherwise have to retype quite some boilerplate
+code to eventually recreate the solver.
+Encapsulation saves us some noise here, plus it guarantees a homogenous setup.
+
+## Adiabatic alignment
+
+If the laser pulse is much longer than the relevant rotational time scales, we are in the adiabatic limit.
+The rotor aligns with the laser pulse when the latter is turned on
+and largely regresses to the field-free state as the laser is turned off.
+This plot corresponds to the third graph of figure 1 of ref[^ortigoso].
+
+```{code-cell}
+times, expectation_values_100 = calculate_alignment(Delta=100, sigma=5)
+_, expectation_values_400 = calculate_alignment(Delta=400, sigma=5)
+_, expectation_values_900 = calculate_alignment(Delta=900, sigma=5)
+plt.plot(times, expectation_values_100, '-k',
+         times, expectation_values_400, '--k',
+         times, expectation_values_900, ':k');
+```
+
+Stronger laser fields correspond to a higher degree of alignment, although this converges for large field strengths.
+The alignment is much stronger than in the non-adiabatic case, but at the cost of an external alignment field
+that may perturb molecular dynamics.
+
+## Alignment of an excited rotational state
+
+Finally, we can also study the alignment of rotationally excited states.
+A new feature in this case is that the magnetic quantum number "m" no longer needs to be zero.
+Let us reproduce figure 3 of ref.[^ortigoso].
+
+```{code-cell}
+data = [calculate_alignment(Delta=400, sigma=0.05, l0=5, m=m) for m in range(6)]
+
+times = data[0][0]
+results = [vals for (t, vals) in data]
+
+# factor of 2 because positive and negative m yield the same result
+average = results[0]
+for m in range(1,6):
+    average = average + 2 * results[m]
+average /= 11
+
+plt.plot(times, average, '-k',
+         times, results[0], '-.k',
+         times, results[2], '--k',
+         times, results[4], ':k');
+```
+
+The plot shows the average over all magnetic quantum numbers (solid line), and the individual results for
+m = 0, 2, 4 (dot-dashed, dashed, dotted line).
+While an increasing magnetic quantum number results in less field-free alignment, the total alignment is
+similar for all even values of m.
+The averaged alignment, however, is significantly damped, and smaller due to the lower alignment of odd values of m.
+
+[^ortigoso]: Ortigoso et al. <https://doi.org/10.1063/1.478241>

wavepacket-0.3.0/doc/advanced/polynomial_solvers.md

@@ -0,0 +1,233 @@
+---
+file_format: mystnb
+kernelspec:
+    name: python3
+---
+
+# Background theory: Polynomial solvers
+
+This web page can be downloaded as notebook: {nb-download}`polynomial_solvers.ipynb` (Jupyter)
+or {download}`polynomial_solvers.md` (Markdown)
+
+The usage of the most common Chebychev solver is documented in {doc}`/tutorials/chebychev_solvers`,
+see there on the practical aspects.
+Here, we want to give some more theoretical details on the subject for those inclined to dig deeper.
+In particular, we shall derive the formulas in a little more depth, discuss the magic values for the alpha
+number, and compare the performance of Chebychev solver to that of ODE solvers.
+
+We will restrict the discussion to closed systems with real eigenvalues.
+The use of Chebychev polynomials was pioneered by Tal-Ezer and Kosloff [^ChebychevReal].
+It is possible to extend the treatment to purely imaginary eigenvalues, this is discussed in
+{doc}`/tutorials/relaxation`, and the original work [^ChebychevImag].
+An extension of the Chebychev method to arbitrary complex-valued systems (open systems, absorbing boundary conditions)
+was introduced by Huisinga et al. [^faber], but we omit this discussion for simplicity.
+
+## Basic theory
+
+For a time-independent, closed system, the time evolution operator is defined by
+
+$$
+    \psi(t+\Delta t) = \hat U(\Delta t) \psi(t) = \mathrm{e}^{-\imath \hat H \Delta t} \psi(t).
+$$
+
+```{note}
+This and the following discussion also applies to density operators. Replace all operators by
+corresponding Liouvillians (operators in dual space) and the wave function by the density operator (state in dual
+space) and all arguments can be trivially translated.
+```
+
+The basic idea of polynomial solvers is to expand this exponential in a convenient series of classical polynomials.
+Complex Chebychev polynomials are used because of their superior convergence properties.
+Our first problem is that this polynomial series converges only in the interval [-i, i].
+Translated appropriately, this means that the Hamiltonian must have all eigenvalues in the interval [-1, 1].
+To get there, we first rescale the Hamiltonian,
+
+$$
+    \mathrm{e}^{-\imath \hat H \Delta t} = \mathrm{e}^{-\imath (E_{\mathrm{min}} + \Delta E / 2) \Delta t}
+        \mathrm{e}^{-\imath \alpha \hat H_\mathrm{norm}}
+$$
+
+where
+
+\begin{eqnarray*}
+    \alpha =& \frac{\Delta E \ \Delta t}{2}\\
+    \hat H_\mathrm{norm} =& \frac{2}{\Delta E} (\hat H - E_\mathrm{min} - \frac{\Delta E}{2})
+    .
+\end{eqnarray*}
+
+Here, $E_\mathrm{min}, \Delta E$ denote the Hamiltonian's smallest eigenvalue and the spectral range,
+respectively.
+It can be checked that the normalized Hamiltonian has all eigenvalues in the interval [-1, 1].
+
+The first exponent is just a constant factor,
+and we only expand the second exponential with the normalized Hamiltonian and "time" $\alpha$ as
+
+$$
+    \mathrm{e}^{-\imath \hat H_\mathrm{norm} \alpha} = \sum_{n=0}^N a_n(\alpha) \phi_n(-\imath \hat H_\mathrm{norm}),
+$$
+
+where up to constants, the coefficients "a" are Bessel functions of the first kind and the functions are the
+complex Chebychev polynomials.
+
+## Convergence
+
+The huge advantage of Chebychev polynomials is the availability of an exact upper bound for the propagation error.
+We start with two inequalities, see [^abramowitz], equations 22.14.4 and 9.1.62, which readily generalize to
+functions of operators:
+
+\begin{align*}
+    |\phi_n(x)| =& |T_n(-\imath x)| &\leq 1 (x \in [-\imath, \imath])
+        \qquad \rightarrow \qquad \|\phi_n(-\imath \hat H_\mathrm{norm}) \psi\| \leq \|\psi\|\\
+    |J_n(x)| \leq& \frac{|x/2|^n}{n!}
+\end{align*}
+
+Now let us assume that we used the first N terms of the expansion and want to know the error when propagating a state.
+We get for a normalized state
+
+\begin{align*}
+    \| \mathrm{e}^{-\imath \alpha \hat H_\mathrm{norm}} \psi \ 
+        - \ \sum_{n=0}^N a_n(\alpha) \phi_n(-\imath \hat H_\mathrm{norm}) \psi \|
+        =& \| \sum_{n=N+1}^\infty a_n(\alpha) \phi_n(-\imath \hat H_\mathrm{norm} \psi)\|\\
+    \leq& \sum_{n=N+1}^\infty a_n(\alpha) \|\phi_n(-\imath \hat H_\mathrm{norm} \psi)\|\\
+    \leq& \sum_{n=N+1}^\infty a_n(\alpha)\\
+    \leq& \sum_{n=N+1}^\infty \frac{(\alpha/2)^n}{n!}
+\end{align*}
+
+We do not care about the exact value of the error, just note two properties of the expression:
+
+1. There is an upper bound for the error independent of the initial state. That is, the convergence is continuous,
+   there are no individual states for which the series does not converge.
+2. For large enough N, the right-hand side decreases exponentially with increasing N.
+
+In practice, we do not target a specific value of the (upper bound of the) propagation error,
+but simply truncate the series as soon as the Bessel function has reached a certain cutoff.
+This cutoff can still be considered a proxy for the order of magnitude of the error,
+but is not a rigorous quantity.
+
+## Efficiency of the Chebychev solver and good alpha values
+
+Now we can finally discuss good alpha values for acceptable efficiencies.
+This discussion is very brief in the original papers.
+
+The computational cost is essentially proportional to the order of expansion n;
+the Chebychev polynomials are calculated through a recursion relation, and each recursion requires one expensive
+evaluation of the Hamiltonian / Liouvillian.
+The order of expansion, that is, the cost, is defined by the Bessel functions dropping below a certain threshold.
+The size of the time step, that is, the gain, however, is proportional to the alpha value, i.e., the
+argument of said Bessel function.
+
+So we can rephrase the question: At which value of alpha do we get most gain per cost?
+Let us plot the behaviour of the Bessel functions for different values of alpha
+
+```{code-cell}
+import matplotlib.pyplot as plt
+import numpy as np
+import scipy
+
+alpha, n = np.meshgrid([20, 40, 60, 80], np.arange(120))
+y = np.abs(scipy.special.jv(n, alpha))
+
+fig, ax = plt.subplots()
+ax.set_ylim(1e-12, 1)
+ax.semilogy(n, y);
+```
+
+We can clearly see that the Bessel functions are significant up to $n \approx \alpha$, then they decay rapidly,
+approaching values of 1e-12 within roughly 30 orders.
+No matter our timestep, we always have to include these thirty orders to get a well-converged solution.
+Hence, a good alpha value should definitely not be smaller than about 30.
+
+As an example, let us compare alpha values of 20 and 60.
+For the former, we need an order of 50, but our time step is shorter, and we need to step
+three times. Altogether that makes approximately 150 applications of the Hamiltonian.
+For the latter, we need a single time step with an order of 90, hence about 90 applications of
+the Hamiltonian.
+Thus, the latter alpha value requires only about 60% of the computing time of the smaller alpha value.
+
+This gain starts to level off when alpha becomes larger than this constant decay.
+Hence, the proposition of using an alpha value of at least 40 to avoid inefficiencies, and there is little point
+of increasing alpha beyond, say, 100.
+Both values are not exact numbers, however, just crude rules of thumb.
+
+However, very large orders of expansion may lead to artefacts.
+For example the values of the Bessel functions may become inaccurate, depending on the implementation details.
+Therefore, we would recommend not increasing alpha beyond something like 100, but that is also not a hard value.
+For example, we encountered a Matlab version around 2010
+that would produce infinite solutions for large orders (200 or 300).
+
+As a side note, the plot also shows that the precision has remarkably little influence on the efficiency.
+Even if we go for embarrassingly large values of 1e-6, the required polynomial orders are reduced only by about 10,
+which is why we use a fixed value of 1e-12 for the cutoff.
+
+## Comparison between Chebychev and ODE solvers
+
+So far we have only *claimed* that the Chebychev solver is much faster than ODE solvers,
+so let us back this up with numbers.
+We choose the truncated harmonic oscillator example from {doc}`/tutorials/chebychev_solvers`.
+
+```{code-cell}
+import math
+import wavepacket as wp
+
+grid = wp.grid.Grid(wp.grid.PlaneWaveDof(-10, 10, 128))
+psi0 = wp.builder.product_wave_function(grid, wp.Gaussian(-5, 0, rms=1))
+
+kinetic = wp.operator.CartesianKineticEnergy(grid, 0, mass=1, cutoff=35)
+potential = wp.operator.Potential1D(grid, 0, lambda x: 0.5 * x ** 2, cutoff=35)
+equation = wp.expression.SchroedingerEquation(kinetic + potential)
+```
+
+First, we need to measure the speed.
+A good proxy is the number of times that our Hamiltonian is applied, because this is often the most expensive
+single operation.
+To count this value, we write a custom "counting expression" that just measures how often the solver calls it.
+
+```{code-cell}
+class CountingExpression(wp.expression.ExpressionBase):
+    def __init__(self, wrapped_expression):
+        super().__init__(False)
+
+        self._wrapped_expression = wrapped_expression
+        self.count = 0
+
+    def apply(self, state, t):
+        self.count += 1
+        return self._wrapped_expression.apply(state, t)
+```
+
+Then we only wrap our (truncated) expression and propagate for a common time.
+
+```{code-cell}
+counting_equation = CountingExpression(equation)
+
+solver_chebychev = wp.solver.ChebychevSolver(counting_equation, math.pi/2, (0, 70))
+solver_chebychev.step(psi0, t=0)
+print(f"Chebychev solver:                      count={counting_equation.count}, alpha={solver_chebychev.alpha:.4}")
+
+counting_equation.count = 0
+solver_rk45 = wp.solver.OdeSolver(counting_equation, math.pi/2)
+solver_rk45.step(psi0, t=0)
+print(f"Runge-Kutta 4/5 solver:                count={counting_equation.count}")
+
+counting_equation.count = 0
+solver_rk45_precise = wp.solver.OdeSolver(counting_equation, math.pi/2, rtol=1e-9, atol=1e-9)
+solver_rk45_precise.step(psi0, t=0)
+print(f"High-precision Runge-Kutta 4/5 solver: count={counting_equation.count}")
+```
+
+So even when comparing against a low-precision ODE solver
+(default 1e-6 for relative and absolute error of a single elementary time step),
+the Chebychev solver yields a factor of 4.5 in performance.
+If you require the higher precisions that you get for free with the Chebychev solver,
+simple ODE solvers are easily an order of magnitude slower.
+
+[^abramowitz]: M. Abramowitz and I. Stegun, "Handbook of Mathematical Functions"
+
+[^ChebychevReal]: H. Tal Ezer and R. Kosloff, J. Chem. Phys. 81:3967 (1986)
+<https://openscholar.huji.ac.il/sites/default/files/ronniekosloff/files/jcp1.448136.pdf>
+
+[^ChebychevImag]: R. Kosloff and H. Tal-Ezer, Chem. Phys. Lett. 127(3) 223 (1986)
+<https://openscholar.huji.ac.il/sites/default/files/ronniekosloff/files/cpl86.pdf>
+
+[^faber]:  W. Huisinga et al., J. Chem. Phys. 110, 5538 (1999)
+<https://publications.imp.fu-berlin.de/91/1/JCP05538.pdf>