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.ChebychevSolver wavepacket.solver.RelaxationSolver wavepacket.solver.OdeSolver wavepacket.solver.SolverBase Package Contents ---------------- .. py:class:: ChebychevSolver(expression: wavepacket.expression.ExpressionBase, dt: float, spectrum: tuple[float, float]) Bases: :py:obj:`wavepacket.solver.solverbase.SolverBase` Solver that expands the time evolution operator into Chebychev polynomials. This solver is fast and accurate, but works only for time-independent closed systems, and requires explicit bounds for the spectrum of the Hamiltonian or Liouvillian, which is more setup work. There is a dedicated tutorial for this solver, see :doc:`/tutorials/chebychev_solvers`. :Parameters: **expression: wp.expression.Expression** The Schrödinger equation or Liouvillian that describes the right-hand side of the differential equation. **dt: float** The time step that is propagated in one go. **spectrum: tuple[float, float]** Lower and upper bound of the spectrum of the Hamiltonian or Liouvillian. If the bound is generous, the solver is less efficient. If the spectrum extends beyond the bounds, the solution may diverge. :Attributes: **alpha: float, readonly** The Kosloff alpha number "spectral range * dt / 2". Ideally, it should be around 40. Smaller values reduce efficiency, much larger values can cause problems with overflows. **order: int, readonly** The order of the expansion. .. rubric:: Notes The name of this class deviates from the nowadays official transcription, which is "Chebyshev". The original references by Tal-Ezer and Kosloff, however, use the outdated spelling, so we tried to be consistent with these references. .. !! processed by numpydoc !! .. py:attribute:: alpha :type: Final[float] .. py:attribute:: order :type: Final[int] :value: 0 .. 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:: RelaxationSolver(hamiltonian: wavepacket.operator.OperatorBase, dt: float, spectrum: tuple[float, float]) Bases: :py:obj:`wavepacket.solver.solverbase.SolverBase` Solver for propagation in imaginary time. This class is similar to the :py:class:`wp.solver.ChebychevSolver`, but in imaginary time. It relaxes an initial wave function to the ground state of a system or a density operator to the density operator of a system at finite temperature. There is a dedicated tutorial for this solver, see :doc:`/tutorials/relaxation`. :Parameters: **hamiltonian: wp.operator.OperatorBase** The Hamiltonian operator that describes the right-hand side of the differential equation. **dt: float** The time step that is propagated in one go. **spectrum: tuple[float, float]** Lower and upper bound of the spectrum of the Hamiltonian or Liouvillian. If the bound is generous, the solver is less efficient. If the spectrum extends beyond the bounds, the solution may diverge. :Attributes: **alpha: float, readonly** The Kosloff alpha number "spectral range * dt / 2". Ideally, it should be around 40. Smaller values reduce efficiency, much larger values can cause problems with overflows. **order: int, readonly** The order of the expansion. .. !! processed by numpydoc !! .. py:attribute:: alpha :type: Final[float] .. py:attribute:: order :type: Final[int] :value: 0 .. 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:: 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. :Raises: wp.InvalidValueError If the timestep is not positive. .. !! processed by numpydoc !! .. py:attribute:: dt :type: Final[float] .. 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) -> Iterator[tuple[float, wavepacket.grid.State]] 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: Tuple[float, wp.grid.State] A tuple consisting of the time and the result of the propagation at that time. The time starts optionally with t0 and progresses in units of dt. :Raises: wp.InvalidValueError If num_steps is negative. .. rubric:: Examples >>> solver = ... >>> psi0 = ... >>> for time, psi in solver.propagate(psi0, t0, 5): >>> print(f't = {time}, trace = {wp.trace(psi)}') .. !! processed by numpydoc !!