wavepacket.expression
=====================

.. py:module:: wavepacket.expression

.. autoapi-nested-parse::

   
   Classes that wrap operators into expressions for use in partial differential equations.
















   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   wavepacket.expression.ExpressionBase
   wavepacket.expression.CommutatorLiouvillian
   wavepacket.expression.SchroedingerEquation


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

.. py:class:: ExpressionBase

   Bases: :py:obj:`abc.ABC`


   
   Base class for expressions.

   By deriving from this class and implementing the method
   :py:meth:`ExpressionBase.apply`, you can add custom expressions.












   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

   .. py:method:: apply(state: wavepacket.grid.State, t: Optional[float] = None) -> wavepacket.grid.State
      :abstractmethod:


      
      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.







      ..
          !! processed by numpydoc !!


.. py:class:: CommutatorLiouvillian(op: wavepacket.operator.OperatorBase)

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











   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

   .. py:method:: apply(rho: wavepacket.grid.State, t: Optional[float] = None) -> wavepacket.grid.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.







      ..
          !! processed by numpydoc !!


.. py:class:: SchroedingerEquation(hamiltonian: wavepacket.operator.OperatorBase)

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











   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

   .. py:method:: apply(psi: wavepacket.grid.State, t: Optional[float] = None) -> wavepacket.grid.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.







      ..
          !! processed by numpydoc !!