wavepacket 0.2.0__tar.gz → 0.4.0__tar.gz

wavepacket-0.4.0/CHANGELOG.rst

@@ -0,0 +1,109 @@
+=========
+ChangeLog
+=========
+
+0.4
+---
+
+Breaking changes:
+
+- (#44) Moved functionality around: all utility functions are in the main namespace,
+    all callables in a new "special" namespace.
+- (#55) Swapped arguments for plotting functions to be consistent with how
+    solver.propagate() returns them
+
+Major changes:
+
+- (#37) Added contour plots for two-dimensional systems.
+- (#35) Added documentation on the convergence of equally-spaced grids
+  and absorbing boundary conditions
+- (#48) Added documentation on the convergence of ODE solvers
+
+Minor changes:
+
+- (#52) added unit_wave_function() to generate a wave function consisting of ones
+- (#43) copied some user input arrays to avoid accidental side effects
+- (#37) When calculating the density, you can optionally calculate the reduced
+  density along some degree of freedom.
+- (#37) When plotting data, the potentials are evaluated at the time of plotting.
+  This may be interesting for time-dependent potentials.
+- (#55) Gaussian accepts floats, not only arrays, and can be used for pulse shapes
+- (#55) Comprehensible error message when adding an incorrect object to an operator
+- (#16) Added code coverage and black+isort formatting
+
+Bug fixes:
+
+- (#35) 1D plots calculated abs(energy) instead of real(energy),
+  and did not treat unnormalized wave functions correctly.
+- (#48) The calculation of the population lacked an abs(), so the populations could
+  be negative.
+- (#16) SoftRectangularFunction had no soft turnoff
+- Random wave functions were set up in the DVR, not in the default representation.
+  In general, this should cause an incorrect norm, but could change results in more
+  subtle ways.
+
+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.2.0 → wavepacket-0.4.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.4.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: wavepacket
+Version: 0.4.0
+Summary: A package for solving Schrödinger and Liouville von Neumann equations.
+Keywords: wave packet,quantum simulation,quantum system,DVR,Schroedinger equation,Liouville von Neumann equation,open systems,wave function,density operator,Liouvillian
+Author: Ulf Lorenz
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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
+Requires-Dist: coverage >= 7 ; extra == "coverage"
+Requires-Dist: black  == 26.* ; extra == "formatting"
+Requires-Dist: pytest >= 8.3 ; extra == "test"
+Project-URL: Homepage, https://wavepacket.readthedocs.io
+Project-URL: Issues, https://github.com/ulflor/wavepacket/issues
+Project-URL: Source, https://github.com/ulflor/wavepacket
+Provides-Extra: coverage
+Provides-Extra: formatting
+Provides-Extra: test
+
+.. Be aware that this document also doubles as index.html on the documentation page.
+
+Description
+-----------
+
+Wavepacket is a Python package to simulate small quantum systems.
+Technically, it allows you to numerically solve Schrödinger and
+Liouville-von-Neumann equations for distinguishable particles.
+
+The full documentation can be found under https://wavepacket.readthedocs.io.
+See also the advanced use cases for examples of what can be done.
+
+Wavepacket focuses on a particular niche:
+
+- Direct solution of Schrödinger / Liouville von Neumann equations.
+  No electronic structure, no MCTDH, no semiclassics, at least for now.
+- Grid-based representation of operators (DVR approximation).
+- Accessibility is an overriding goal. Wavepacket should be directly usable in teaching.
+  We try to provide good tutorials / docs, but also goodies like simple plotting.
+- Exotic use cases should be as frictionless as possible.
+  For example, switching between wave functions and density operators is supported well.
+  Or random thermal wave functions are not much more complex to use than Gaussian states.
+- Performance is a subordinate goal.
+  For specific systems, you can easily improve the performance by integer factors.
+
+
+Links
+-----
+
+Documentation:
+    https://wavepacket.readthedocs.io
+Source:
+    https://github.com/ulflor/wavepacket
+Issue tracker:
+    https://github.com/ulflor/wavepacket/issues
+
+
+Support
+-------
+
+There are three different avenues for feedback and support:
+
+- The prefered option is through the mailing list wavepacket@python.org.
+  You may want to subscribe at https://mail.python.org/mailman3/lists/wavepacket.python.org/
+  to ensure you receive all answers.
+- You can use the Forum on github: https://github.com/ulflor/wavepacket/discussions
+  You need a github account to post messages.
+- You can open a new issue for bug reports or feature requests directly at
+  https://github.com/ulflor/wavepacket/issues.
+  This requires a github account.
+  You can of course also report bugs or request features on the mailing list or in the forum.
+  Depending on the complexity of the feature, this will lead to an immediate,
+  rapid, or prioritized implementation.
+
+
+Contribution
+------------
+
+I currently lack a formal procedure for new contributors, but you are
+very welcome to contribute to the project. If you do not know what to do,
+use one of the support channels from the previous section ; there is enough
+work for multiple developers, also for non-coding skills (there is never enough
+documentation).
+
+
+History
+-------
+
+The original long-time version of Wavepacket was written in Matlab and is still
+actively maintained under https://sourceforge.net/p/wavepacket/matlab. It is stable,
+battle-tested and works.
+
+However, Matlab is expensive, and not all users had (legal)
+access to it. Also, the project's architecture did not support some
+advanced use cases well. Finally,
+C++11 had just come out and looked cool, so I started a
+reimplementation in C++ around 2013, adding Python bindings as an
+afterthought. The C++ project will be superseded by this Python package, but
+can be found under https://sourceforge.net/p/wavepacket/cpp.
+
+This worked really well, except that deploying C++ code is difficult.
+In particular, there was no cheap route towards building a "good"
+Python package, especially under Windows, which restricted accessibility.
+
+The solution is this Python-only version based on numpy.
+The Python version is slower by a factor of two to three compared
+to C++-backed code. This is, however, often cancelled by a
+parallelization of the tensor operations.
+

wavepacket-0.4.0/README.rst

@@ -0,0 +1,88 @@
+.. Be aware that this document also doubles as index.html on the documentation page.
+
+Description
+-----------
+
+Wavepacket is a Python package to simulate small quantum systems.
+Technically, it allows you to numerically solve Schrödinger and
+Liouville-von-Neumann equations for distinguishable particles.
+
+The full documentation can be found under https://wavepacket.readthedocs.io.
+See also the advanced use cases for examples of what can be done.
+
+Wavepacket focuses on a particular niche:
+
+- Direct solution of Schrödinger / Liouville von Neumann equations.
+  No electronic structure, no MCTDH, no semiclassics, at least for now.
+- Grid-based representation of operators (DVR approximation).
+- Accessibility is an overriding goal. Wavepacket should be directly usable in teaching.
+  We try to provide good tutorials / docs, but also goodies like simple plotting.
+- Exotic use cases should be as frictionless as possible.
+  For example, switching between wave functions and density operators is supported well.
+  Or random thermal wave functions are not much more complex to use than Gaussian states.
+- Performance is a subordinate goal.
+  For specific systems, you can easily improve the performance by integer factors.
+
+
+Links
+-----
+
+Documentation:
+    https://wavepacket.readthedocs.io
+Source:
+    https://github.com/ulflor/wavepacket
+Issue tracker:
+    https://github.com/ulflor/wavepacket/issues
+
+
+Support
+-------
+
+There are three different avenues for feedback and support:
+
+- The prefered option is through the mailing list wavepacket@python.org.
+  You may want to subscribe at https://mail.python.org/mailman3/lists/wavepacket.python.org/
+  to ensure you receive all answers.
+- You can use the Forum on github: https://github.com/ulflor/wavepacket/discussions
+  You need a github account to post messages.
+- You can open a new issue for bug reports or feature requests directly at
+  https://github.com/ulflor/wavepacket/issues.
+  This requires a github account.
+  You can of course also report bugs or request features on the mailing list or in the forum.
+  Depending on the complexity of the feature, this will lead to an immediate,
+  rapid, or prioritized implementation.
+
+
+Contribution
+------------
+
+I currently lack a formal procedure for new contributors, but you are
+very welcome to contribute to the project. If you do not know what to do,
+use one of the support channels from the previous section ; there is enough
+work for multiple developers, also for non-coding skills (there is never enough
+documentation).
+
+
+History
+-------
+
+The original long-time version of Wavepacket was written in Matlab and is still
+actively maintained under https://sourceforge.net/p/wavepacket/matlab. It is stable,
+battle-tested and works.
+
+However, Matlab is expensive, and not all users had (legal)
+access to it. Also, the project's architecture did not support some
+advanced use cases well. Finally,
+C++11 had just come out and looked cool, so I started a
+reimplementation in C++ around 2013, adding Python bindings as an
+afterthought. The C++ project will be superseded by this Python package, but
+can be found under https://sourceforge.net/p/wavepacket/cpp.
+
+This worked really well, except that deploying C++ code is difficult.
+In particular, there was no cheap route towards building a "good"
+Python package, especially under Windows, which restricted accessibility.
+
+The solution is this Python-only version based on numpy.
+The Python version is slower by a factor of two to three compared
+to C++-backed code. This is, however, often cancelled by a
+parallelization of the tensor operations.

wavepacket-0.4.0/doc/advanced/ode_solvers.md

@@ -0,0 +1,264 @@
+---
+file_format: mystnb
+kernelspec:
+    name: python3
+---
+
+# Background theory: ODE solvers
+
+This web page can be downloaded as notebook: {nb-download}`ode_solvers.ipynb` (Jupyter)
+or {download}`ode_solvers.md` (Markdown)
+
+Here, we want to have a look at conventional ODE solvers.
+In particular, how do you check calculations, and how do you speed up a calculation?
+
+For the impatient, the main results of the following treatise are:
+
+* Poor convergence can show up as a divergent norm.
+  In practice, however, ODE solvers use adaptive step sizes;
+  for reasonable parameters, they just take forever.
+* The required time step, hence the performance,
+  is dictated by the largest (absolute) eigenvalue, not by the typical energies.
+* Truncate aggressively and shift energies to improve performance.
+
+## Some basics
+
+### ODE solvers theory
+
+We start from the Schrödinger equation
+
+$$
+    \imath \dot \psi(t) = \hat H(t) \psi(t)
+$$
+
+and expand the wave function in a complete basis with time-dependent coefficients,
+$|\psi(t)\rangle = \sum_n c_n(t) |\phi_n\rangle$.
+Inserting and multiplying with $\langle \phi_m |$ gives the formula for the coefficients,
+
+$$
+    \imath \dot c_m(t) = \sum_n \langle \phi_m| \, \hat H \, |\phi_n \rangle \ c_n(t)
+$$
+
+This is a system of ordinary differential equations,
+and any explicit solver can be used for the time evolution, most notably Runge-Kutta algorithms.
+A similar derivation can be done for the Liouville von-Neumann equation for density operators.
+
+ODE solvers have the big advantage that they are robust work horses.
+You can throw any problem at them: time-dependent Hamiltonians, complex-valued Hamiltonians,  open systems, ...
+they will produce a solution.
+Nowadays, they always come with adaptive time steps,
+so you only need to set an error bound, and the algorithm chooses an appropriate time step for you.
+
+The big drawback is performance; ODE solvers do not exploit any knowledge of the system,
+and this makes optimized solvers like polynomial solvers more efficient for specific classes of problems.
+Typically, ODE solvers are not unitary, so the norm is not a conserved quantity and diverges on poor convergence.
+However, because of the adaptive steps, this does not usually happen,
+instead the algorithm chooses tiny step sizes with corresponding long run times.
+
+### Model system
+
+As example system, we choose a one-dimensional harmonic oscillator
+with a shifted Gaussian as initial state.
+
+```{code-cell}
+import wavepacket as wp
+
+grid = wp.grid.Grid(wp.grid.PlaneWaveDof(-10, 10, 128))
+hamiltonian = (wp.operator.CartesianKineticEnergy(grid, 0, 1.0)
+              + wp.operator.Potential1D(grid, 0, lambda x: 0.5 * x ** 2))
+equation = wp.expression.SchroedingerEquation(hamiltonian)
+
+psi0 = wp.builder.product_wave_function(grid, wp.special.Gaussian(x=-3, rms=2))
+```
+
+Let us have a look at the projection onto the Hamiltonian eigenstates:
+
+```{code-cell}
+import matplotlib.pyplot as plt
+import numpy as np
+
+eigenstates = [state for _, state in wp.diagonalize(hamiltonian)]
+projection = [wp.population(psi0, state) for state in eigenstates]
+
+plt.semilogy(np.arange(128), projection, '+');
+```
+
+In theory, the population should decay smoothly.
+In practice, strange things start to happen around the 50th eigenstate.
+If we play around with the grid parameters,
+it can be shown that this is an artifact of the finite grid extent and the finite number of grid points.
+We skip the demonstration here to reduce the run time of the notebook.
+This finite grid error is a common issue and discussed in depth in {doc}`plane_wave_grid`.
+
+## Convergence behavior
+
+Intuitively, we would assume that the time step is determined by the specific dynamics,
+i.e., the initial wave function for our time-independent system.
+For example, a low-energy state evolves slower in time than a high-energy state,
+hence it should allow larger time steps.
+Unfortunately, this intuition is incorrect.
+
+To understand what happens let us force a calculation to not converge.
+This is a contrived example; scipy's ODE solvers always use adaptive stepping,
+so we need to choose absurd parameters to render this mechanism ineffective.
+To understand where exactly things go awry,
+we can plot the populations of the individual eigenstates
+
+```{code-cell}
+solver = wp.solver.OdeSolver(equation, 0.1, atol=1e10, first_step=0.01)
+x = np.arange(128)
+
+for t, psi in solver.propagate(psi0, 0, 2):
+    print(f"t = {t}      Trace = {wp.trace(psi)}")
+
+    populations = [wp.population(psi, state) for state in eigenstates]
+    plt.semilogy(x, populations, '+')
+```
+
+We succeed: The norm diverges rapidly.
+From the plot of the populations,
+we find that the divergence is caused only by the high-energy contributions.
+These are completely irrelevant for the actual dynamics,
+but require small timesteps for accurate time evolution.
+
+Improving the efficiency thus require an optimization of the operator spectrum.
+There are two options: We can shift the spectrum, or we can truncate it.
+
+### Shifting the spectrum
+
+The solver spends most effort on the correct propagation of the populated
+states with the highest energies.
+This burden can be reduced by shifting the operator spectrum,
+thereby making the largest (absolute) energies smaller.
+Simple scaling laws suggest that the required time step scales with the inverse of the largest energy,
+so shifting the spectrum to be balanced around zero would ideally halve the computation time.
+
+To see what happens, let us repeat the previous analysis with the spectrum shifted by 50 atomic units
+(approximately the energy of the 50th eigenstate)
+
+```{code-cell}
+shifted_equation = wp.expression.SchroedingerEquation(hamiltonian - 50)
+
+shifted_solver = wp.solver.OdeSolver(shifted_equation, 0.1, atol=1e10, first_step=0.01)
+x = np.arange(128)
+
+for t, psi in shifted_solver.propagate(psi0, 0, 2):
+    print(f"t = {t}      Trace = {wp.trace(psi)}")
+
+    populations = [wp.population(psi, state) for state in eigenstates]
+    plt.semilogy(x, populations, '+')
+```
+
+The good news is that the shift helps visibly with the divergent trace.
+Alas, now the populations of the low-energy eigenstates start to diverge.
+This causes problems with adaptive step sizes,
+because the low-energy eigenstates have larger populations,
+therefore they contribute more to the step error. 
+
+As a consequence, shifting by half of the spectral range is probably not optimal.
+To figure out the optimal value, we use a "Counting expression" that measures
+how often our Hamiltonian is applied, which is the expensive part of the algorithm.
+
+```{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 can try out the computational effort for different energy shifts:
+
+```{code-cell}
+for shift in range(0, 51, 10):
+    shifted_equation = wp.expression.SchroedingerEquation(hamiltonian - shift)
+    counter = CountingExpression(shifted_equation)
+    solver = wp.solver.OdeSolver(counter, 0.5)
+
+    solver.step(psi0, 0)
+    print(f"Shift = {shift} a.u.      count = {counter.count}")
+```
+
+We find an optimal shift of around 40 a.u., which reduces the computational effort by about 25%,
+only half the maximum possible reduction.
+The drawback of this shifting is the required guesswork to find a suitable energy shift;
+after all computing time is often cheaper than the scientist's attention.
+And choosing the time step suboptimally yields even smaller gains.
+
+### Truncating the spectrum
+
+The second manipulation is a direct truncation of the operator spectrum.
+While this may appear clumsy, there are good reasons to truncate aggressively:
+
+1. As the previous analyses have shown, high-energy eigenstates are poorly represented by the grid anyway.
+   In the example here, this affects everything above about the 50th eigenstate.
+   Aggressive truncation therefore only invalidates results that were already incorrect in the first place.
+
+   In theory, we could remove these artifacts by extending the grid,
+   but then we pay twice: The larger grid makes all computations slower,
+   and to faithfully propagate the large-energy components, we need smaller time steps.
+   And at the end of the day, the gain in accuracy is tiny.
+   because the populations of the high-energy eigenstates are small, after all.
+2. Whenever we simulate existing physical systems, we use models.
+   These models are _always_ low-energy approximations of the real system.
+   For example, we neglect anharmonic contributions,
+   or we ignore the coupling to highly excited electronic states,
+   maybe we even ignore excited states entirely within the Born-Oppenheimer approximation.
+   In the particular example here, we can safely assume that the 50th excited state
+   will be anything but a harmonic eigenstate.
+
+   Again, this means that by truncating the Hamiltonian,
+   we merely trade one incorrect approximation for another, so no harm is done.
+
+Truncating the spectrum of the Hamiltonian requires an expensive diagonalization,
+so we truncate the individual components instead.
+
+Similar to the shifting of the spectrum, we can study the effect of truncation on the efficiency.
+
+```{code-cell}
+for cutoff in range(50, 201, 50):
+    truncated_hamiltonian = (wp.operator.CartesianKineticEnergy(grid, 0, 1.0, cutoff=cutoff)
+                            + wp.operator.Potential1D(grid, 0, lambda x: 0.5 * x ** 2, cutoff=cutoff))
+    truncated_equation = wp.expression.SchroedingerEquation(truncated_hamiltonian)
+    counter = CountingExpression(truncated_equation)
+    solver = wp.solver.OdeSolver(counter, 0.5)
+
+    solver.step(psi0, 0)
+    print(f"Cutoff = {cutoff} a.u.      count = {counter.count}")
+```
+
+The computational effort drops considerably when reducing the cutoff,
+which supports the thesis that significant effort is spent on propagating high-energy contributions.
+After truncating the kinetic and potential energy to 50 a.u. each,
+we are left with less than half of the original computational effort.
+If we show more restraint and truncate only at 100 a.u., we still reduce the computational effort by one third.
+These numbers suggest an advantage of truncation:
+Even suboptimal or cautious guesses reduce the computational effort significantly.
+
+How bad is the approximation for the dynamics?
+To answer this question, we can look at the projection of the truncated result on the untruncated result;
+any deviation from one can serve as a figure of merit of the additional error.
+
+```{code-cell}
+import math
+
+truncated_hamiltonian = (wp.operator.CartesianKineticEnergy(grid, 0, 1.0, cutoff=50)
+                        + wp.operator.Potential1D(grid, 0, lambda x: 0.5 * x ** 2, cutoff=50))
+truncated_equation = wp.expression.SchroedingerEquation(truncated_hamiltonian)
+truncated_solver = wp.solver.OdeSolver(truncated_equation, math.pi / 2)
+truncated_result = truncated_solver.step(psi0, 0)
+
+solver = wp.solver.OdeSolver(equation, math.pi/2)
+result = solver.step(psi0, 0)
+
+print(f"Overlap after pi/2: {wp.population(truncated_result, result)}")
+```
+
+The additional deviation in the sixth decimal is of a similar magnitude
+and therefore consistent with the grid error,
+so we have introduced no undue additional approximation.