wavepacket 0.1.0__tar.gz

wavepacket-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wavepacket-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: wavepacket
+Version: 0.1.0
+Summary: A package for the propagation of quantum-mechanical wave functions.
+Author: Ulf Lorenz
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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"
+Project-URL: Home, https://github.com/ulflor/wavepacket
+Provides-Extra: demos
+Provides-Extra: doc
+Provides-Extra: test
+
+Description
+-----------
+
+Wavepacket is a Python package to define and simulate small
+quantum systems. Or, more 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.
+
+There are many different quantum systems and consequently approaches
+to solve them. Here we focus on a particular niche:
+
+- Wavepacket solves the differential equations directly. This simplifies
+  the maths, but limits the system size to few degrees of freedom.
+  If you want to deal with larger systems, look out for MCTDH.
+- Wavepacket uses the DVR approximation heavily. This allows you to
+  directly define your potentials as functions of real-space coordinates
+  instead of setting up opaque operator matrices.
+  The latter approach is simpler an more concise if you are only
+  interested in harmonic oscillators or qubits, though.
+- Wavepacket is a Python-only package relying chiefly on numpy.
+  This is slower than natively implemented code, but you gain
+  great tooling support, for example matplotlib, Jupyter notebooks or
+  integrated documentation.
+- Most of the code can handle both wave functions and density operators.
+  This allows you to convert a closed system into an open
+  system with minimal fuss.
+
+For example use cases, we have been using various precursors of this
+package for simulating small molecular systems and for teaching.
+Besides examples shipped with this package, see
+https://sourceforge.net/p/wavepacket/wiki/Demos.Main for more applications.
+
+The project is currently a first iteration to flesh out everything. Once
+0.1 is released, I plan to quickly translate the existing C++ code from
+a precursor project and reach a stable state. More can be found on the
+project homepage https://github.com/ulflor/wavepacket
+
+
+Support
+-------
+
+If you lack a feature that you would like to have, open an issue at
+`our issue tracker <https://github.com/ulflor/wavepacket/issues>`_.
+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, feel free to contact one of the developers; there is enough work for
+multiple developers, it is just not documented yet.
+
+
+History
+-------
+
+The original version of Wavepacket was written in Matlab and is still
+maintained under https://sourceforge.net/p/wavepacket/matlab. It is stable,
+battle-tested and works.
+
+However, Matlab is pretty expensive, so not all interested users had
+access to it. Also, the project's architecture did not support some
+advanced use cases without digging deep into the code. 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. However, deploying C++ code is difficult.
+In particular, there was no cheap route towards building a "good"
+Python package, or towards easily building a Windows version.
+Also, the underlying tensor library was slowly
+getting fewer and fewer commits over the years, so I am currently
+moving to a Python-only package. 
+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, and the tooling is better by orders
+of magnitude.
+

wavepacket-0.1.0/README.rst

@@ -0,0 +1,83 @@
+Description
+-----------
+
+Wavepacket is a Python package to define and simulate small
+quantum systems. Or, more 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.
+
+There are many different quantum systems and consequently approaches
+to solve them. Here we focus on a particular niche:
+
+- Wavepacket solves the differential equations directly. This simplifies
+  the maths, but limits the system size to few degrees of freedom.
+  If you want to deal with larger systems, look out for MCTDH.
+- Wavepacket uses the DVR approximation heavily. This allows you to
+  directly define your potentials as functions of real-space coordinates
+  instead of setting up opaque operator matrices.
+  The latter approach is simpler an more concise if you are only
+  interested in harmonic oscillators or qubits, though.
+- Wavepacket is a Python-only package relying chiefly on numpy.
+  This is slower than natively implemented code, but you gain
+  great tooling support, for example matplotlib, Jupyter notebooks or
+  integrated documentation.
+- Most of the code can handle both wave functions and density operators.
+  This allows you to convert a closed system into an open
+  system with minimal fuss.
+
+For example use cases, we have been using various precursors of this
+package for simulating small molecular systems and for teaching.
+Besides examples shipped with this package, see
+https://sourceforge.net/p/wavepacket/wiki/Demos.Main for more applications.
+
+The project is currently a first iteration to flesh out everything. Once
+0.1 is released, I plan to quickly translate the existing C++ code from
+a precursor project and reach a stable state. More can be found on the
+project homepage https://github.com/ulflor/wavepacket
+
+
+Support
+-------
+
+If you lack a feature that you would like to have, open an issue at
+`our issue tracker <https://github.com/ulflor/wavepacket/issues>`_.
+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, feel free to contact one of the developers; there is enough work for
+multiple developers, it is just not documented yet.
+
+
+History
+-------
+
+The original version of Wavepacket was written in Matlab and is still
+maintained under https://sourceforge.net/p/wavepacket/matlab. It is stable,
+battle-tested and works.
+
+However, Matlab is pretty expensive, so not all interested users had
+access to it. Also, the project's architecture did not support some
+advanced use cases without digging deep into the code. 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. However, deploying C++ code is difficult.
+In particular, there was no cheap route towards building a "good"
+Python package, or towards easily building a Windows version.
+Also, the underlying tensor library was slowly
+getting fewer and fewer commits over the years, so I am currently
+moving to a Python-only package. 
+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, and the tooling is better by orders
+of magnitude.

wavepacket-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "wavepacket"
+authors = [{ name = "Ulf Lorenz" }]
+readme = "README.rst"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics"
+]
+dynamic = ["version", "description"]
+
+dependencies = [
+    "numpy >= 2.1.3",
+    "scipy >= 1.14.1"
+]
+
+[project.urls]
+Home = "https://github.com/ulflor/wavepacket"
+
+[project.optional-dependencies]
+test = [
+    "pytest >= 8.3"
+]
+doc = [
+    "sphinx >= 8.1.3",
+    "sphinx-autoapi >= 3.4.0",
+    "numpydoc >= 1.8.0",
+    "myst-nb >= 1.2",
+    "sphinx-rtd-theme >= 3.0.2"
+]
+demos = [
+    "matplotlib >= 3.10"
+]

wavepacket-0.1.0/src/wavepacket/__init__.py

@@ -0,0 +1,25 @@
+"""
+A package for the propagation of quantum-mechanical wave functions.
+"""
+
+__version__ = "0.1.0"
+
+from . import builder
+from . import expression
+from . import grid
+from . import operator
+from . import solver
+from . import testing
+from . import typing
+
+
+from .exceptions import (BadFunctionCall, BadGridError, BadStateError, ExecutionError,
+                         InvalidValueError)
+from .generators import Gaussian, PlaneWave
+from .logging import log
+
+
+__all__ = ['__version__', 'log', 'BadFunctionCall', 'BadGridError', 'BadStateError',
+           'ExecutionError', 'InvalidValueError',
+           'Gaussian', 'PlaneWave',
+           'builder', 'expression', 'grid', 'operator', 'solver', 'testing', 'typing']

wavepacket-0.1.0/src/wavepacket/builder/__init__.py

@@ -0,0 +1,8 @@
+"""
+Functions to assemble wave functions or density operators.
+"""
+
+__all__ = ['direct_product', 'pure_density', 'product_wave_function']
+
+from .density import direct_product, pure_density
+from .wave_function import product_wave_function

wavepacket-0.1.0/src/wavepacket/builder/density.py

@@ -0,0 +1,73 @@
+import numpy as np
+
+import wavepacket as wp
+from ..grid import State
+
+
+def pure_density(psi: State) -> State:
+    """
+    Given an input wave function, create the corresponding pure density operator.
+
+    This function only performs the direct product, it does not apply
+    further modifications like normalizations.
+
+    Parameters
+    ----------
+    psi : wp.grid.State
+         The input wave function
+
+    Returns
+    -------
+    wp.grid.State
+        The corresponding density operator.
+
+    Raises
+    ------
+    wp.BadStateError
+        If the input is not a valid wave function.
+
+    See also
+    --------
+    direct_product : This function is identical to `direct_product(psi, psi)`
+    """
+    return direct_product(psi, psi)
+
+
+def direct_product(ket: State, bra: State) -> State:
+    """
+    Returns the direct product of wave functions as a density operator.
+
+    Given two wave functions :math:`\psi, \phi`, this function returns the
+    density operator as :math:`| \psi \\rangle\langle \phi |`.
+    This operation can be useful to build up a
+    density operator piece by piece.
+
+    Parameters
+    ----------
+    ket : wp.grid.State
+         The ket state :math:`\psi`
+    bra : wp.grid.State
+         The bra state :math:`\phi`. Note that the function performs a
+         complex conjugation of this state prior to multiplication.
+
+    Returns
+    -------
+    wp.grid.State
+        The direct product of the two states.
+
+    Raises
+    ------
+    wp.BadStateError
+        If one of the input states is not a valid wave function.
+    wp.BadGridError
+        If the input states are defined on different grids.
+    """
+    if not ket.is_wave_function() or not bra.is_wave_function():
+        raise wp.BadStateError("Density operator can only be constructed from wave functions.")
+
+    if ket.grid != bra.grid:
+        raise wp.BadGridError("Grid for bra and ket states does not match")
+
+    rho_matrix = np.outer(ket.data, np.conj(bra.data))
+
+    return State(ket.grid, np.reshape(rho_matrix, ket.grid.operator_shape))

wavepacket-0.1.0/src/wavepacket/builder/wave_function.py

@@ -0,0 +1,63 @@
+from collections.abc import Sequence
+from typing import Iterable
+
+import numpy as np
+
+import wavepacket as wp
+import wavepacket.typing as wpt
+from ..grid import Grid, State
+
+
+def product_wave_function(grid: Grid,
+                          generators: wpt.Generator | Sequence[wpt.Generator],
+                          normalize: bool = True) -> State:
+    """
+    Builds a product wave function from a set of one-dimensional wave functions.
+
+    Parameters
+    ----------
+    grid : wp.grid.Grid
+           The grid on which the product wave function is assembled
+    generators : Sequence[wp.typing.Generator]
+                A list of callables that specifies the wave function
+                along each degree of freedom. The `generators` return
+                the one-dimensional functions in the DVR, i.e., raw function
+                values at the grid points.
+    normalize : bool, default=true
+               If the norm is non-zero and this value is set, the resulting
+               product wave function is normalized, otherwise the product
+               is returned directly.
+
+    Returns
+    -------
+    wp.grid.State
+        The product wave function in the Wavepacket-default weighted DVR.
+
+    Raises
+    ------
+    wp.InvalidValueError
+        If the number of generators does not match the grid dimensions.
+    """
+    generator_list = generators
+    if not isinstance(generator_list, Iterable):
+        generator_list = [generators]
+
+    if len(generator_list) != len(grid.dofs):
+        raise wp.InvalidValueError(
+            "To build a wave function, you need as many generators as degrees of freedoms."
+            f"Given {len(generator_list)} generators for {len(grid.dofs)} DOFs.")
+
+    result_data = np.ones(grid.shape, dtype=complex)
+    for dof_index, generator in enumerate(generator_list):
+        dof = grid.dofs[dof_index]
+        array = generator(dof.dvr_points)
+        array = dof.from_dvr(array, 0)
+
+        result_data *= grid.broadcast(array, dof_index)
+
+    result = State(grid, result_data)
+    norm = np.sqrt(wp.grid.trace(result))
+    if normalize and norm > 0:
+        return result / norm
+    else:
+        return result

wavepacket-0.1.0/src/wavepacket/exceptions.py

@@ -0,0 +1,48 @@
+class BadFunctionCall(Exception):
+    """
+    Signals that a function was called incorrectly.
+
+    A typical but rare use-case would be a function that was
+    called with incorrect parameters.
+    """
+    pass
+
+
+class BadGridError(Exception):
+    """
+    An invalid grid was supplied.
+
+    Most often, you attempt an operation between objects that must be defined on the
+    same grid. For example, the addition of two operators defined on different grids
+    is not a useful operation. The grid may also miss required properties, for example
+    an operation may expect a specific degree of freedom type along some index.
+    """
+    pass
+
+
+class BadStateError(Exception):
+    """
+    An invalid state was supplied.
+
+    Either the state is completely invalid (neither wave function nor density operator),
+    or you supplied the wrong type of state to a function, for example passing a
+    density operator where a wave function was required.
+    """
+    pass
+
+
+class ExecutionError(Exception):
+    """
+    An unrecoverable problem was encountered in foreign code.
+
+    The main example is the :py:class:`wavepacket.solver.odesolver` getting
+    an error back while integrating.
+    """
+    pass
+
+
+class InvalidValueError(Exception):
+    """
+    A function argument was incorrect, for example out of bounds.
+    """
+    pass

wavepacket-0.1.0/src/wavepacket/expression/__init__.py

@@ -0,0 +1,10 @@
+"""
+Classes that wrap operators into expressions for use in partial differential equations.
+"""
+
+__all__ = ['CommutatorLiouvillian',
+           'ExpressionBase', 'SchroedingerEquation']
+
+from .expressionbase import ExpressionBase
+from .liouvillian import CommutatorLiouvillian
+from .schroedingerequation import SchroedingerEquation

wavepacket-0.1.0/src/wavepacket/expression/expressionbase.py

@@ -0,0 +1,44 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from ..grid import State
+
+
+class ExpressionBase(ABC):
+    """
+    Base class for expressions.
+
+    By deriving from this class and implementing the method
+    :py:meth:`ExpressionBase.apply`, you can add custom expressions.
+
+    Notes
+    -----
+    All differential equations have the form
+    :math:`\dot \\rho = \mathcal{L}(\\rho)` (or equivalently
+    :math:`\dot \psi = \hat H \psi`), that is, the left-hand side
+    is just the time derivative. This matches the common convention for the
+    Liouville von-Neumann equation, but differs from the usual
+    form of the Schrödinger equation, where the imaginary factor
+    is on the left-hand side of the equation.
+    """
+
+    @abstractmethod
+    def apply(self, state: State, t: Optional[float] = None) -> State:
+        """
+        Applies the expression to the input state and returns the result.
+
+        Parameters
+        ----------
+        state : wp.grid.State
+            The state on which the expression is applied.
+        t : float, optional
+            The time at which the expression is evaluated. Default is None,
+            which will raise an exception if the contained expression is time-dependent.
+
+        Raises
+        ------
+        wp.BadStateError
+            If the state is invalid or has the wrong time. For example, a Schroedinger equaiton
+            makes little sense for a density operator.
+        """
+        pass

wavepacket-0.1.0/src/wavepacket/expression/liouvillian.py

@@ -0,0 +1,64 @@
+from typing import Optional
+
+import wavepacket as wp
+from .expressionbase import ExpressionBase
+from ..grid import State
+from ..operator import OperatorBase
+
+
+class CommutatorLiouvillian(ExpressionBase):
+    """
+    Represents a commutator expression in a Liouville von-Neumann equation.
+
+    Given an operator `H`, this commutator expression is given by
+    :math:`\mathcal{L}(\hat \\rho) = -\imath (\hat H \hat \\rho - \hat \\rho \hat H)`.
+
+    Parameters
+    ----------
+    op : wp.operator.OperatorBase
+        The operator to commute with the density operator.
+
+    Notes
+    -----
+    The extra factor of -i is added to ensure that the commutator can be directly
+    plugged into a Liouville von-Neumann equation. defined as
+    :math:`\\frac{\partial \hat \\rho}{\partial t} = \mathcal{L}(\hat \\rho)`.
+    If you need the raw commutator, you have to multiply the result with
+    the imaginary number.
+    """
+
+    def __init__(self, op: OperatorBase):
+        self._op = op
+
+    def apply(self, rho: State, t: Optional[float] = None) -> State:
+        """
+        Evaluates the commutator  for the given density operator and time.
+
+        Parameters
+        ----------
+        rho : wp.grid.State
+            The density operator to commute with
+        t : float, optional
+            The time at which the operator is evaluated. By default it is None,
+            which will throw if the contained operator is time-dependent.
+
+        Returns
+        -------
+        wp.grid.State
+            The result of the commutator.
+
+        Raises
+        ------
+        wp.BadGridError
+            If the grids of the density operator and the wrapped operator do not match.
+        wp.BadStateError
+            If the input state is not a valid density operator.
+        """
+        if rho.grid != self._op.grid:
+            raise wp.BadGridError("Input state is defined on the wrong grid.")
+
+        if not rho.is_density_operator():
+            raise wp.BadStateError("CommutatorLiouvillian requires a density operator.")
+
+        return State(rho.grid,
+                     -1j * (self._op.apply_from_left(rho.data, t) - self._op.apply_from_right(rho.data, t)))

wavepacket-0.1.0/src/wavepacket/expression/schroedingerequation.py

@@ -0,0 +1,65 @@
+from typing import Optional
+
+import wavepacket as wp
+from .expressionbase import ExpressionBase
+from ..grid import State
+from ..operator import OperatorBase
+
+
+class SchroedingerEquation(ExpressionBase):
+    """
+    Expression wrapper for a Schrödinger equation.
+
+    You should wrap a Hamiltonian in an object of this type
+    so that the solvers can subsequently solve the resulting
+    equation.
+
+    Parameters
+    ----------
+    hamiltonian : wp.operator.OperatorBase
+        The Hamiltonian that is wrapped by this class.
+
+    Notes
+    -----
+    The Schrödinger equation is given by
+    :math:`\dot \psi = -\imath \hat H \psi`,
+    so this class only multiplies the wave function with the
+    negative imaginary number, and wraps the input Hamiltonian
+    into an expression so that solvers can work with it.
+    """
+
+    def __init__(self, hamiltonian: OperatorBase):
+        self._hamiltonian = hamiltonian
+
+    def apply(self, psi: State, t: Optional[float] = None) -> State:
+        """
+        Evaluates the right-hand side of the Schrödinger equation
+        for the given input state and time.
+
+        Parameters
+        ----------
+        psi : wp.grid.State
+             The input state that is evaluated.
+        t : float, optional
+            The time at which the Schrödinger equation is evaluated.
+            The default `None` throws if the wrapped operator is time-dependent.
+
+        Returns
+        -------
+        wp.grid.State
+            The result of the evaluation.
+
+        Raises
+        ------
+        wp.grid.BadGridError
+            If the state's grid differs from that of the Hamiltonian.
+        wp.grid.BadStateError
+            If the input state is not a wave function.
+        """
+        if psi.grid != self._hamiltonian.grid:
+            raise wp.BadGridError("Input state has wrong grid.")
+
+        if not psi.is_wave_function():
+            raise wp.BadStateError("SchroedingerEquation requires a wave function.")
+
+        return State(psi.grid, -1j * self._hamiltonian.apply_to_wave_function(psi.data, t))