wavepacket.special
==================

.. py:module:: wavepacket.special

.. autoapi-nested-parse::

   
   Special functions for use in Wavepacket.

   These mostly encompass typical pulse shapes or initial states.















   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   wavepacket.special.Gaussian
   wavepacket.special.PlaneWave
   wavepacket.special.SphericalHarmonic
   wavepacket.special.SinSquare
   wavepacket.special.SoftRectangularFunction


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

.. py:class:: Gaussian(x: float = 0.0, p: float = 0.0, *, rms: float | None = None, fwhm: float | None = 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 keyword parameters,
           either 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: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 = 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 !!