newtonprop.interface module¶
Recommended interface for a stateful Newton propagator
Typically, an efficient propagator will rely on lowlevel data structures.
Since conversion between high and lowlevel structures in every call of
newtonprop.propagator.step()
would be wasteful, it is better to use a
stateful propagator that only does the conversion once, holds the required
state, and converts back only on demand.
While a stateful propagator could be achieved through a wrapper function and
closures, a more straightforward implementation holds the necessary state in a
class. To encourage a consistent interface, you should subclass
NewtonPropagatorBase
for this purpose.
Summary¶
Classes:
NewtonPropagatorBase 
Abstract base class for a stateful interface for using the Newton propagator 
__all__
: NewtonPropagatorBase
Reference¶

class
newtonprop.interface.
NewtonPropagatorBase
(data, func='exp', m_max=10, maxrestart=100, tol=1e12)[source]¶ Bases:
object
Abstract base class for a stateful interface for using the Newton propagator
This must be subclassed before it can be used.
Parameters:  data – data that underlies the abstract operator \(A\). The propagator
will use this together with a time parameter t to construct the
argument A for
newtonprop.propagator.step()
.  func (callable or str) – The scalar version of the operatorfunction
\(f\). Must take one complex argument and return a
complex value. If given as a string, the corresponding callable
will be looked up in
funcs
.  m_max (int) – Maximal Krylov dimension. Initializes the corresponding attribute.
 maxrestart (int) – Maximum number of Newton restarts. Initializes the corresponding attribute.
 tol (float) – Desired precision of the result. Initializes the corresponding attribute.
Subclasses will customize the behavior mostly by overriding a number of private methods, outlined below. These methods may act on the following (private) attributes:

_data
¶ Internal data that may be used to calculate \(A\). Obtained from data via
_convert_data_to_internal()
.

_v0
¶ The state set by
set_initial_state()
, in its original format

_v
¶ The current state, in an internal format. The internal format is determined by
_convert_state_to_internal()
.
Private methods:

_check
()[source]¶ Check completeness and consistency of attributes
After
set_initial_state()
, check that all attributes are defined and are consistent. If not, raise anAttributeError
.

_convert_state_to_internal
(v)[source]¶ Convert the initial state v into a more efficient internal format.
This is used when setting
_v
from the v given inset_initial_state()
. By default, the state is passed on unchanged.

_convert_state_from_internal
(v)[source]¶ Convert v in internal format of
_v
to original formatIf
_v
uses an internal format different from the v inset_initial_state()
, this method must be overridden to convert_v
back to the original format. It is used bystate
for this purpose. By default, the internal state is passed on unchanged.

static
_convert_data_to_internal
(data)[source]¶ Convert data to
_data
Optional conversion of the data passed to the initializer to a more efficient internal format. By default, the data is stored unchanged.

_inner
(a, b)[source]¶ Inner product between two states a, b in the format of
_v
Must return a complex number. This is an abstract method, and thus must be implemented by any subclass of
NewtonPropagatorBase
.An example implementation is:
def _inner(self, a, b): return numpy.vdot(a, b)

_norm
(a)[source]¶ Norm of a state a in the format of
_v
Must return a complex number. This is an abstract method, and thus must be implemented by any subclass of
NewtonPropagatorBase
.An example implementation is:
def _norm(self, a): return numpy.linalg.norm(a)

_zero
(a)[source]¶ A new zerostate compatible with the format of
_v
Must allocate and return a new state in the same internal format as
_v
, but containing zeros, so that the state can set inplace. This is an abstract method, and thus must be implemented by any subclass ofNewtonPropagatorBase
.An example implementation is:
def _zero(self, a): return numpy.zeros(shape=a.shape, dtype=a.dtype)

_A
(t)[source]¶ Callable
A(v)
encoding the abstract operator \(A(t)\).Must return a callable
A(v)
that takes a state v in the internal format of_v
and returns a state in the same format. This is an abstract method, and thus must be implemented by any subclass ofNewtonPropagatorBase
.Assuming
self._data
contains a nested list[L0, [L1, eps]]
whereL0
andL1
are numpy matrices containing a superoperator, andeps
is a callable with argument t for a timedependent control, an example implementation is:def _A(self, t): Lmatrix = ( self._data[0] + self._data[1][0] + self._data[1][1](t)) def L(v): return Lmatrix @ v return L
Note
This method does not calculate
A(v)
directly, but returns a callable that does. This is to take into account timedependent operators, whichnewtonprop.propagator.step()
does not know anything about.
Public methods, attributes, and properties:

func
¶ The scalar version of the operatorfunction \(f\), as a callable

m_max
¶ Maximal Krylov dimension (int)

maxrestart
¶ Maximum number of Newton restarts (int)

tol
¶ Desired precision of the result (float)

funcs
= {'exp': <function _exp>, 'expi': <function _expi>, 'expmi': <function _expmi>}¶ Registry of func names (class attribute)
Cf. the func argument of
newtonprop.propagator.step()
. You may extend this with your own function names.

state
¶ The current state (readonly)
After a call to
set_initial_state()
, this is the state set by that call. After a call tostep()
, it is the result of that propagation step.

step
(t, dt)[source]¶ Perform a single propagation step
Parameters: Construct an abstract operator \(A(t)\) based on the data the propagator was initialized with, and calculate
\[v_\text{out} = f(A(t)\,dt) \, v_\text{in}\]where \(v_\text{in}\) is the current
state
, and \(f\) is the function specified by func during initialization.The state \(v_\text{out}\) becomes \(v_\text{in}\) for the next call to
step()
. The time parameter t should generally be the midpoint of the interval covered by \(dt\).The results of the propagation step may be read from
state
. Thestep()
method does not return anything.
 data – data that underlies the abstract operator \(A\). The propagator
will use this together with a time parameter t to construct the
argument A for