wavepacket
==========

.. py:module:: wavepacket

.. autoapi-nested-parse::

   
   A package for the propagation of quantum-mechanical wave functions.
















   ..
       !! processed by numpydoc !!


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/wavepacket/builder/index
   /autoapi/wavepacket/expression/index
   /autoapi/wavepacket/grid/index
   /autoapi/wavepacket/operator/index
   /autoapi/wavepacket/solver/index
   /autoapi/wavepacket/testing/index
   /autoapi/wavepacket/typing/index


Exceptions
----------

.. autoapisummary::

   wavepacket.BadFunctionCall
   wavepacket.BadGridError
   wavepacket.BadStateError
   wavepacket.ExecutionError
   wavepacket.InvalidValueError


Classes
-------

.. autoapisummary::

   wavepacket.Gaussian
   wavepacket.PlaneWave


Functions
---------

.. autoapisummary::

   wavepacket.log


Package Contents
----------------

.. py:exception:: BadFunctionCall

   Bases: :py:obj:`Exception`


   
   Signals that a function was called incorrectly.

   A typical but rare use-case would be a function that was
   called with incorrect parameters.















   ..
       !! processed by numpydoc !!

.. py:exception:: BadGridError

   Bases: :py:obj:`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.















   ..
       !! processed by numpydoc !!

.. py:exception:: BadStateError

   Bases: :py:obj:`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.















   ..
       !! processed by numpydoc !!

.. py:exception:: ExecutionError

   Bases: :py:obj:`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.















   ..
       !! processed by numpydoc !!

.. py:exception:: InvalidValueError

   Bases: :py:obj:`Exception`


   
   A function argument was incorrect, for example out of bounds.
















   ..
       !! processed by numpydoc !!

.. py:class:: Gaussian(x: float = 0.0, p: float = 0.0, rms: Optional[float] = None, fwhm: Optional[float] = None)

   Bases: :py:obj:`wavepacket.typing.Generator`


   
   Callable that defines a one-dimensional Gaussian function.

   This callable can be supplied wherever a callable is required. An example
   would be an initial wave function for :py:func:`wavepacket.builder.product_wave_function`,
   or a potential wrapped in a :py:class:`wavepacket.operator.Potential1D`.

   :Parameters:

       **x** : float, default=0
           The center of the Gaussian.

       **p** : float, default=0
           The momentum of the Gaussian.

       **rms, fwhm** : float
           You must specify the width of the Gaussian using exactly one of these values,
           either through the root-mean-square width, or the full-width-at-half-maximum.







   :Raises:

       wp.InvalidValueError
           If the width of the Gaussian is not positive.

       wp.BadFunctionCall
           If both rms and fwhm have either been set or not supplied.




   .. rubric:: Notes

   Up to scaling, the functional form of the Gaussian is
   :math:`f(x) = e^{-(x-x_0)^2 / 2 \sigma^2 + \imath p (x-x_0)}`.
   Here, sigma is the rms width, which is connected to the FWHM by
   :math:`\sigma = \mathrm{FWHM} / \sqrt{8 \ln 2}`.



   ..
       !! processed by numpydoc !!

.. py:class:: PlaneWave(k: float)

   
   Callable that defines a plane wave.

   You will typically use this callable for initial states. There are often
   better options, especially if your FBR already defines a plane wave basis,
   but sometimes you may just want to represent a reasonable plane wave and
   not count indices to get the correct wave vector.

   :Parameters:

       **k** : float
           The wave vector of the plane wave.














   ..
       !! processed by numpydoc !!

.. py:function:: log(t: numbers.Real, state: wavepacket.grid.State, precision: int = 6) -> None

   
   Prints some data about the state for inspection.

   The idea is that you call this function during every solver step and get
   a log with the most important values about the propagation, for example
   the state trace (if it deviates from one, this may be caused by poor convergence).

   :Parameters:

       **t** : float
           The time at which you log.

       **state** : wp.grid.State
           The state to log.

       **precision** : int, default=6
           How many decimal places should be printed.














   ..
       !! processed by numpydoc !!