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.ExpressionSum wavepacket.expression.CommutatorLiouvillian wavepacket.expression.OneSidedLiouvillian wavepacket.expression.SchroedingerEquation Package Contents ---------------- .. py:class:: ExpressionBase(time_dependent: bool) 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. :Parameters: **time_dependent: bool** Sets whether the expression is time-dependent or not. :Attributes: **time_dependent: bool, readonly** If the expression is time-dependent or not. Some functionality, for example special solvers, may require time-independent expressions. This property typically evaluates the time-dependence of the underlying operator(s). .. 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:attribute:: time_dependent :type: Final[bool] .. py:method:: apply(state: wavepacket.grid.State, t: float) -> 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 The time at which the expression is evaluated. Only really needed for time-dependent expressions, but to keep the interface uniform, this parameter is required. :Raises: wp.BadGridError If the grids of the state and the wrapped operator do not match. wp.BadStateError If the state is invalid or has the wrong time. For example, a Schrödinger equation makes little sense for a density operator. .. !! processed by numpydoc !! .. py:class:: ExpressionSum(expressions: Iterable[ExpressionBase]) Bases: :py:obj:`ExpressionBase` Sum of multiple expressions. You should rarely construct this class directly. It is created implicitly if you sum two or more expressions. Note that it is perfectly possible to construct an invalid sum, for example, by adding a SchroedingerEquation to some Liouvillian; the result will not accept any state without exceptions. :Parameters: **expressions** : Iterable[wp.operator.ExpressionBase] The expressions that should be summed up. :Raises: wp.InvalidValueError if the list of expressions is empty. .. !! processed by numpydoc !! .. py:method:: apply(state: wavepacket.grid.State, t: float) -> wavepacket.grid.State 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 The time at which the expression is evaluated. Only really needed for time-dependent expressions, but to keep the interface uniform, this parameter is required. :Raises: wp.BadGridError If the grids of the state and the wrapped operator do not match. wp.BadStateError If the state is invalid or has the wrong time. For example, a Schrödinger equation 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: float) -> wavepacket.grid.State 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 The time at which the expression is evaluated. Only really needed for time-dependent expressions, but to keep the interface uniform, this parameter is required. :Raises: wp.BadGridError If the grids of the state and the wrapped operator do not match. wp.BadStateError If the state is invalid or has the wrong time. For example, a Schrödinger equation makes little sense for a density operator. .. !! processed by numpydoc !! .. py:class:: OneSidedLiouvillian(op: wavepacket.operator.OperatorBase, side: Side = Side.LEFT) Bases: :py:obj:`wavepacket.expression.expressionbase.ExpressionBase` An expression that simply applies an operator from the left or right of a density operator. This operator is basically the same as the :py:class:`wp.expression.SchroedingerEquation` but applies the operator onto a density operator, and it lacks the factor of "-1j". This expression is found occasionally in the context of open quantum systems or when relaxing a density operator to a thermal state. :Parameters: **op** : wp.operator.OperatorBase The operator to apply with the density operator. **side: wp.expression.OneSidedLiouvillian.Side** If the operator should be applied from the LEFT or RIGHT of the density operator. .. !! processed by numpydoc !! .. py:class:: Side(*args, **kwds) Bases: :py:obj:`enum.Enum` Create a collection of name/value pairs. Example enumeration: >>> class Color(Enum): ... RED = 1 ... BLUE = 2 ... GREEN = 3 Access them by: - attribute access: >>> Color.RED - value lookup: >>> Color(1) - name lookup: >>> Color['RED'] Enumerations can be iterated over, and know how many members they have: >>> len(Color) 3 >>> list(Color) [, , ] Methods can be added to enumerations, and members can have their own attributes -- see the documentation for details. .. !! processed by numpydoc !! .. py:attribute:: LEFT :value: 0 .. py:attribute:: RIGHT :value: 1 .. py:method:: apply(rho: wavepacket.grid.State, t: float) -> wavepacket.grid.State 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 The time at which the expression is evaluated. Only really needed for time-dependent expressions, but to keep the interface uniform, this parameter is required. :Raises: wp.BadGridError If the grids of the state and the wrapped operator do not match. wp.BadStateError If the state is invalid or has the wrong time. For example, a Schrödinger equation makes little sense for a 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: float) -> wavepacket.grid.State 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 The time at which the expression is evaluated. Only really needed for time-dependent expressions, but to keep the interface uniform, this parameter is required. :Raises: wp.BadGridError If the grids of the state and the wrapped operator do not match. wp.BadStateError If the state is invalid or has the wrong time. For example, a Schrödinger equation makes little sense for a density operator. .. !! processed by numpydoc !!