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/plot/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.SinSquare
   wavepacket.SoftRectangularFunction
   wavepacket.Gaussian
   wavepacket.PlaneWave
   wavepacket.SphericalHarmonic


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:: SinSquare(t0: float, half_width: float)

   
   Shape function for a squared sinusoidal laser pulse.

   Usually, you use this function to describe a smooth laser pulse
   with a definite start and end point (which a Gaussian does not have).
   The exact shape is :math:`cos^2(\pi \frac{t - t_0}{2 \Delta}`, and
   zero outside the interval :math:`[t_0-\Delta, t_0+\Delta]`.

   :Parameters:

       **t0: float**
           The center of the pulse.

       **half_width**
           The half-width of the laser pulse, :math:`\Delta`.







   :Raises:

       wp.InvalidValueException
           if the half-width is not positive.







   ..
       !! processed by numpydoc !!

.. py:class:: SoftRectangularFunction(t0: float, half_width: float, border: float = None)

   
   Shape function for a rectangular pulse with soft (cosine) turn-on.

   This shape function is a rectangular function with a given half-width,
   with an added soft turn-on and turn-off of the form
   :math:`cos(\frac{t}{B})` with the border width B.

   :Parameters:

       **t0: float**
           Center of the rectangular pulse.

       **half_width: float**
           Half-width of the rectangular part of the pulse.

       **border: float = half_width/10**
           Optional width of the turn-on / turn-off region.







   :Raises:

       wp.InvalidValueError
           If the half-width or the border region is not positive.







   ..
       !! 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)

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


   
   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:class:: SphericalHarmonic(l: int, m: int)

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


   
   Callable that returns a spherical harmonic Y_l^m(theta, phi=0).

   Usually, this callable will be used for initial states. Note that the
   phi-dependence of a spherical harmonic is trivial exp(i m phi), and
   usually not needed (we fix m and the phi-integration yields a constant).
   For this reason, the functor takes only the theta-values as single parameters,
   and returns the spherical harmonic at phi = 0.

   :Parameters:

       **l** : int
           The rotational quantum number / angular momentum

       **m** : int
           The minor rotational quantum number -l <= m <= l







   :Raises:

       wp.InvalidValueError
           If l is negative or if (-l <= m <= l) does not hold.







   ..
       !! 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 !!