newtonprop.interface module¶
Recommended interface for a stateful Newton propagator
Typically, an efficient propagator will rely on low-level data structures.
Since conversion between high- and low-level 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=1e-12)[source]¶ Bases:
object
Abstract base class for a stateful interface for using the Newton propagator
This must be sub-classed 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 operator-function
\(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 zero-state 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 in-place. 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 time-dependent 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 time-dependent operators, whichnewtonprop.propagator.step()
does not know anything about.
Public methods, attributes, and properties:
-
func
¶ The scalar version of the operator-function \(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 (read-only)
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