wavepacket.solver
=================

.. py:module:: wavepacket.solver

.. autoapi-nested-parse::

   
   This module contains classes to solve the equations of motion set up by the
   classes in the :py:mod:`wavepacket.expression` module.
















   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   wavepacket.solver.OdeSolver
   wavepacket.solver.SolverBase


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

.. py:class:: OdeSolver(expr: wavepacket.expression.ExpressionBase, dt: float, **kwargs)

   Bases: :py:obj:`wavepacket.solver.solverbase.SolverBase`


   
   A solver that uses scipy's ODE integrators as backend.

   This solver merely wraps `scipy.integrate.solve_ivp()` in a Wavepacket
   solver. ODESolvers tend to be workhorses that can be applied to most
   systems without a second thought at the expense of performance.
   See [Rf8b071083a66-1]_ for more details on the convergence of solvers.

   :Parameters:

       **expr** : wp.expression.ExpressionBase
           The right-hand side of the differential equation that encapsulates the quantum system.

       **dt** : float
           The elementary time step for the time evolution.

       **\*\*kwargs**
           Additional keyword parameters can be supplied that are directly forwarded to scipy.
           The most important parameters are "method" (defaults to "RK45") and "rtol", "atol"
           for the relative and absolute error tolerances (booth default to 1e-6).












   .. rubric:: References

   .. [Rf8b071083a66-1] https://sourceforge.net/p/wavepacket/cpp/blog/2021/04/convergence-2

   .. only:: latex

      [Rf8b071083a66-1]_


   ..
       !! processed by numpydoc !!

   .. py:method:: step(state: wavepacket.grid.State, t: float) -> wavepacket.grid.State

      
      Evolves the given state for one elementary time step.

      Given a wave function or density operator at time t,
      this function should return the propagated wave function
      or density operator at the new time t+dt, where dt is
      the elementary time step.

      :Parameters:

          **state** : wp.grid.State
              The state to be evolved in time

          **t** : float
              The time at which the time evolution starts



      :Returns:

          wp.grid.State
              The state at the new time t+dt.











      ..
          !! processed by numpydoc !!


.. py:class:: SolverBase(dt: float)

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


   
   Abstract base class for all differential equation solvers.

   Each solver must take in the constructor the size of an
   elementary time step, and it must implement a method :py:meth:`step`
   to evolve a state by one elementary time step forward in time.

   Usually, a solver does not need to know what step it evolves or
   how a differential equation looks in detail. The form of the
   differential equation is encapsulated in a
   :py:class:`wavepacket.expression.ExpressionBase` instance that
   is usually supplied to the specific implementations.

   A solver may, however, implicitly assume properties of the
   differential equation. It may also take additional arguments,
   these details are documented in the specific implementations.

   :Parameters:

       **dt** : float
           The size of an elementary time step.

   :Attributes:

       **dt**
           ..






   :Raises:

       wp.InvalidValueError
           If the timestep is not positive.







   ..
       !! processed by numpydoc !!

   .. py:property:: dt
      :type: float


      
      Returns the size of the elementary time step.
















      ..
          !! processed by numpydoc !!


   .. py:method:: step(state: wavepacket.grid.State, t: float) -> wavepacket.grid.State
      :abstractmethod:


      
      Evolves the given state for one elementary time step.

      Given a wave function or density operator at time t,
      this function should return the propagated wave function
      or density operator at the new time t+dt, where dt is
      the elementary time step.

      :Parameters:

          **state** : wp.grid.State
              The state to be evolved in time

          **t** : float
              The time at which the time evolution starts



      :Returns:

          wp.grid.State
              The state at the new time t+dt.











      ..
          !! processed by numpydoc !!


   .. py:method:: propagate(state0: wavepacket.grid.State, t0: float, num_steps: int, include_first: bool = True)

      
      Generator function that yields the propagated wave function at multiple time steps.

      This function allows you to propagate in one go with a for loop.
      It repeatedly calls :py:meth:`step` and returns the wave function and current time.

      :Parameters:

          **state0** : wp.grid.State
              The initial state to be propagated in time.

          **t0** : float
              The initial time at which the state is given

          **num_steps** : int
              For how many elementary time steps the state should be propagated.

          **include_first** : bool
              If true, the function will start by yielding the initial state.




      :Yields:

          float
              The time at which the state is yielded. Starts optionally with t0 and progresses in units of dt.

          wp.grid.State
              The propagated state at the given time.



      :Raises:

          wp.InvalidValueError
              If num_steps is negative.







      ..
          !! processed by numpydoc !!