Simulation classes (quanguru.classes.QSimBase)

Contains the _parameter class and the parent classes of the Simulation object.

_parameter([value, _bound])

_parameter instances can be bound to each other to implement a (value) dependency between them.

stateBase(**kwargs)	Contains attributes and methods for initialState and a boolean to determine whether to store or discard time-evolved states.
timeBase(**kwargs)	Implements 3 basic time information, namely total time of simulation (totalTime), step size for each unitary (stepSize), and number of steps (stepCount = totalTime/stepSize).

Function Name	Docstrings	Unit Tests	Tutorials
_parameter	✅	✅	❌
stateBase	✅	✅	❌
timeBase	✅	✅	❌

setAttr(obj: paramBoundBase, attrStr: str, val: Any) → None

a customized setattr that changes the value (and _paramUpdated) if the new value is different than the old/existing. Especially useful for multi parameter sweeps (see _sweep).

setAttrParam(obj: paramBoundBase, attrStr: str, val: Any) → None

a customized setattr that changes the value stored as the value attribute of a _parameter object. The value (and _paramUpdated) is changed, if the new value is different than the old/existing. In any case, it breaks existing timeBase bounds (bound between Simulation instances). Especially useful for multi parameter sweeps (see _sweep).

class _parameter(value: Any = None, _bound: _parameter = None)

Bases: object

_parameter instances can be bound to each other to implement a (value) dependency between them.

There are two types of parametric bounds/relations/dependencies in this library,

1. Value of an attribute in an instance is bound to the value of the same attribute in another instance, meaning it gets its value from its bound.

2. Not the value of the attribute itself, but any change in its value is important for another object.

This class wraps (composition) the value of a parameter (an attribute) to create a hierarchical dependency required for the first case. The second case is covered by paramBoundBase.

It is intended to be used with private attributes and the corresponding properties returns the value of that attribute (which is a _parameter object).

If a _parameter is given another _parameter as its _bound, it returns the value of its _bound, while keeping its _value unchanged (which is mostly left to be None). This is the same for the bound one, which means a chain of dependency is achieved by bounding each object to another.

bounds can be broken by explicitly setting the value.

TODO update this list and add cross-references. Used in stepSize, totalTime, stepCount, initialState etc. The goal of having such dependency is that, for example, when simulating a quantum system simultaneously using more than 1 protocol, we can assign an initialState for the quantum system, and all the protocols initialState will by default be _bound to quantum systems initialState and get their value from it. If we explicitly assign an initialState to any protocol, the _bound will break for that particular protocol, which will have its own initialState, but not the others, unless they are also explicitly given an initialState. These sort of dependencies are implemented in the library and are not meant for external modifications.

This class can be replaced by a proxy class. However, this is intended to be used completely internally (private attributes + properties), this simple option should suffice.

_value: Any

the value to be wrapped

_bound: _parameter

bounded _parameter object, self is not bounded to anything when this is None or any other object that does not have a value attribute. Assigned to False when a bound is broken (by updating the value).

property value: Any

Property to get the _value of self, if bound does not have value as an attribute, else returns the value of the _bound, which should be an instance of _parameter object but can be any other object with an _value &/ _bound attribute.

Setter assigns the _value to a given input and _bound to False (meaning the bound to any other object is broken, and value is different than the default, which is None)

__firstlineno__ = 65

__static_attributes__ = ('_bound', '_value')

class stateBase(**kwargs)

Bases: computeBase

Contains attributes and methods for initialState and a boolean to determine whether to store or discard time-evolved states. Since, we can use compute to compute quantities of interest at the run-time of simulation, we don’t need to keep the states and can discard them to save memory.

NOTE : This class branches the inheritance started by paramBoundBase and extends to Simulation.

NOTE : All three attributes of this class (and all 4 of timeBase) are instances of _parameter, so they have a corresponding property.

label: str = 'stateBase'

(class attribute) class label used in default naming

_internalInstances: int = 0

(class attribute) number of instances created internally by the library

_externalInstances: int = 0

(class attribute) number of instances created explicitly by the user

_instances: int = 0

(class attribute) number of total instances = _internalInstances + _externalInstances

__initialState

This attribute is a _parameter and value stores the initialState matrix

__initialStateInput

Input used in the creation of the initialState, there are various ways to create initialState, so its value changes depending on the case. This information is kept so that it can be used in cases where a new reconstruction of initialState is required, e.g. when system dimension is swept or changed.

__delStates

This boolean determines if we delete/discard (True) time-evolved states (to save memory) and keep only the initialState and currentState of the system. By default, it is False and states will be stored in the corresponding protocols qRes.states.

_initialStateSystem

This system will be used in the initial state creation, i.e. input will be passed to this systems createState function. If this is None, it fallbacks to self.superSys, and raises error if self.superSys is also None.

_maxInput

Stores the maximum of the basis numbers passed to initial state input.

property initialStateSystem

property initialState

The initialState property returns _stateBase__initialState.value if it is not None. Otherwise, uses first element in its subSys dictionary values to create and assign its value. This assumes that, to be able to assign a state to a Simulation, it needs at least one quantum system in its subSys dictionary, and the subSys have method to create the state (_createState). This requirement, by default, is satisfied by the internally created Simulation objects that are attributes of quantum systems and protocols.

Setter sets _stateBase__initialState.value matrix for self by using the first element of subSys dictionary values.

property _initialStateInput

getter and setter of _stateBase__initialStateInput.value.

_setGetMaxInput(inps)

getResultByNameOrAlias(name)

This method exists to enrich the terminology, it just returns super().getByNameOrAlias(name), which returns the object with the given name. See getByNameOrAlias for details.

property delStates

gets and sets _stateBase__delStates.value boolean

delMatrices(_exclude=[])

This method extends delMatrices to also set the _stateBase__initialState.value to None and del the old value.

__firstlineno__ = 132

__static_attributes__ = ('__delStates', '__initialState', '__initialStateInput', '_initialStateInput', '_initialStateSystem', '_maxInput')

class timeBase(**kwargs)

Bases: stateBase

Implements 3 basic time information, namely total time of simulation (totalTime), step size for each unitary (stepSize), and number of steps (stepCount = totalTime/stepSize). Additionally, one more parameter, namely, number of samples (samples) is introduced to be used with time-dependent Hamiltonian, where a continuous parameter is discretely changed at every stepSize and more than one samples are desired during the stepSize.

These 4 attributes are all _parameter instances and protected attributes, meaning they are modified by the corresponding properties. One other functionality of property is to create flexible use of these attributes. For example, not all 3 of stepSize, totalTime, and stepCount are need to be explicitly defined, any of these two would be sufficient, since the 3rd can be calculated using the two. So, property setters&getters also covers such cases. Another flexibility ensured by the properties is when _bound are broken.

label: str = 'timeBase'

(class attribute) class label used in default naming

_internalInstances: int = 0

(class attribute) number of instances created internally by the library

_externalInstances: int = 0

(class attribute) number of instances created explicitly by the user

_instances: int = 0

(class attribute) number of total instances = _internalInstances + _externalInstances

__totalTime

_parameter storing the total time of simulation

__stepSize

_parameter storing the step size of simulation

__samples

_parameter storing number of samples in each step, by default 1.

__stepCount

_parameter storing the number of steps, i.e totalTime/stepSize.

__updated

_updated storing the two most recent time parameters which were updated (totalTime/stepSize/stepCount)

__bound

if bound to another object, meaning the _parameters of this gets their value from the others _parameters, this attribute is a reference to another. Else None.

__firstlineno__ = 291

__static_attributes__ = ('__bound', '__samples', '__stepCount', '__stepSize', '__totalTime', '__updated', '_timeBase__bound', '_timeBase__updated')

_updateUpdated(paramName)

property totalTime

gets and sets _timeBase__totalTime.value, and also sets the _timeBase__stepCount.value conditioned on that stepSize is not None. It also sets _paramUpdated to True. Additionally to these, it sets _timeBase__stepSize._value to _timeBase__stepSize._bound._value, if _timeBase__stepSize._bound is not None or False. This is introduced to provide a flexible use of these parameters, such as not forcing to define at least 2 of 3 timeBase parameters, if it already has a _bound and can obtain the second one from the _bound.

property stepCount

gets and sets _timeBase__stepCount.value. getter also try seting the totalTime if it is None. Setter also sets _timeBase__stepSize.value conditioned on that totalTime is not None. It also sets _paramUpdated to True. Additionally to these, it sets _timeBase__totalTime._value to _timeBase__totalTime._bound._value, if _timeBase__totalTime._bound is not None or False. This is introduced to provide a flexible use of these parameters, such as not forcing to define at least 2 of 3 timeBase parameters, if it already has a _bound and can obtain the second one from the _bound.

property stepSize

gets and sets _timeBase__stepSize.value, and also _timeBase__stepCount.value conditioned on that totalTime is not None. It also sets _paramUpdated to True. Additionally to these, it sets _timeBase__totalTime._value to _timeBase__totalTime._bound._value, if _timeBase__totalTime._bound is not None or False. This is introduced to provide a flexible use of these parameters, such as not forcing to define at least 2 of 3 timeBase parameters, if it already has a _bound and can obtain the second one from the _bound.

property samples

gets and sets _timeBase__samples.value and also sets _paramUpdated to True.

_copyVals(other, keys)

Method to copy the values for given attributes (as keys) from other to self.

static _boundTree(osys, tree=None)

Creates a tree of bound instances starting from the given osys. A primitive method used in debugging and to be improved.

_bound(other, params=['_stateBase__delStates', '_stateBase__initialState', '_stateBase__initialStateInput'], re=False)

This method is used internally at appropriate places to create bound between different simulation instances in the intended hierarchical order. For example, when a quantum system is added to subSys of explicitly created Simulation, The parameters of any protocol.simulation for that system will be bound to (quantum system).simulation which will be bound to explicitly created Simulation. This method creates such a bound between two Simulation objects, and it is used in appropriate places of the library. Such a bound is broken or not created at all, if a parameter is explicitly assigned for a protocol or system.

• if self _parameter attributes have bound False (meaning set a value before)

  • copies the value from other, if value in other is not None.

  • is any self _parameter bound is None, and the same value in other is not, sets it and breaks the loop

• tries bounding if bound is None

NOTE : This method is intended purely for internal uses!

Parameters:

• other (Simulation) – The other Simulation (or timeBase) class to bound the parameters of self

• re (bool, optional) – This boolean used (internally) to re-bound a simulation object to another one, by default False. So, re-calling this method to bound a simulation object to another will not work unless re=True.

• param (List[str]) – This is a list of strings for attributes (which are also _parameter objects) other than time parameters, for which the same bound will be created. The difference between param and timeBase parameters is that the latter ones has a functional dependency to each other, meaning a break in one of them should appropriately be reflected to the others.

delMatrices(_exclude=[])

This method extends delMatrices to also set the _stateBase__initialState.value to None and del the old value.