Sweep Classes (quanguru.classes.QSweep)

Contains two classes used for sweep functionalities. NOTE : Both of these classes are not intended to be directly instanciated by the user. Simulation objects has Sweep/s as their attributes, and _sweep/s are intended to be created by calling the relevant methods over Simulation.Sweep.

_sweep(**kwargs)	Implements methods and attributes to sweep the value of an attribute for some objects for a list of values.
Sweep(**kwargs)	A container class for _sweep objects and relevant methods for creating/removing and carrying multi-parameter sweeps.

Function Name	Docstrings	Unit Tests	Tutorials
_sweep	✅	❌	❌
Sweep	✅	❌	❌

class _sweep(**kwargs)

Bases: updateBase

Implements methods and attributes to sweep the value of an attribute for some objects for a list of values. The default sweep _defSweep() sweeps the value for a given attribute (a string stored in key) of objects in subSys dictionary. The list of values (stored in _sweepList) to be swept are set either directly by giving a list or the sweepMin-sweepMax-sweepStep with logSweep. Default sweep function can be replaced with any custom method by re-assigning the sweepFunction to the function reference. The default sweep method requires the index of the value from the list of values to set the next value, this index is provided by the modularSweep and useful for multi-parameter sweeps. It keeps a value fixed by re-assigning it using the same index, and the paramBoundBase and other relevant classes uses the custom setattr methods (see setAttr() and setAttrParam()) to make sure that paramUpdated boolean is not set to True for the same value. This class implements a single sweep, and multi parameter sweep is achieved by the Sweep class.

label: str = '_sweep'

(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

_updateBase__function

protected attribute pointing to a sweep function, by default _defSweep(). This attribute get&set using the sweepFunction property to replace default with a customized sweep method.

sweepMax

maximum value for the swept parameter, used with other attributes to create the sweepList

sweepMin

minimum value for the swept parameter, used with other attributes to create the sweepList

sweepStep

corresponds to the step size in a linearly spaced sweepList, or number of steps in logarithmic case, used with other attributes to create the sweepList

_sweepList

protected attribute to store a list of values for the swept parameter. Can be given a full list or be created using sweepMin-sweepMax-sweepStep values.

logSweep

boolean to create either linearly or logarithmically spaced list values (from sweepMin-sweepMax-sweepStep).

combinatorial

boolean to determine, if two different sweeps are swept simultaneously (same length of list and pair of values at the same index are swept) or a multi-parameter (combinatorial) sweep, ie fix one sweep the other & repeat.

_sweepIndex

stores the index of the value (from the _sweepList) currently being assigned by the sweep function. Used by the default methods but also useful for custom methods. It is calculated by the modular arithmetic in modularSweep and passed to here by Sweep object containing self in its subSys. It starts from -1 and the correspoding property returns _sweepIndex+1, while the runSweep() sets it to ind+1 for a given ind from modularSweep. This whole ordeal is due to make sure that python list indexing and modular arithmetic properly agrees for the sweep functionality. I feel it can be improved but will leave as it is for now.

property index

returns self._sweepIndex + 1. reason for +1 is explained in _sweepIndex. There is no setter, the value of _sweepIndex is updated by the runSweep() and is an internal process.

property sweepFunction

gets and set _updateBase__function, which should point to a Callable.

property sweepKey

gets and sets _updateBase__key, which should be string.

property sweepList

gets and sets _sweepList. Setter requires a list input, if it is not set, getter tries creating the list (and setting _sweepList) using sweepMin-sweepMax-sweepStep attributes.

static _defSweep(self)

This is the default sweep function, and it just calls the _runUpdate by feeding it the value from the sweepList at the position ind. _runUpdate function just sets the attribute (for the given key) of every subSys to a given value (val).

The modularSweep methods uses multiplication of length of sweepList/s (stored in __inds attribute of Sweep instances) as a loop range, and the current loop counter is used by the _indicesForSweep() to calculate which indices of multi _sweep is currently needed.

Parameters:

ind (int) – Index of the value from sweepList

runSweep(ind)

Wraps the _updateBase__function, so that this will be the function that is always called to run the sweeps. This is not essential and could be removed, but it kind of creates a duck-typing with Sweep class, when we might want to use a nested sweep.

__firstlineno__ = 37

__static_attributes__ = ('_sweepIndex', '_sweepList', '_updateBase__function', '_updateBase__key', 'combinatorial', 'logSweep', 'sweepMax', 'sweepMin', 'sweepStep')

class Sweep(**kwargs)

Bases: qBase

A container class for _sweep objects and relevant methods for creating/removing and carrying multi-parameter sweeps. It stores _sweep objects in its subSys dictionary, and it has two additional private attributes to store sweep lengths and their multiplications, which are used in modularSweep and by _indicesForSweep() to carry multi parameter sweeps. Instances of this class are used as attributes of Simulation objects, and those are intended to be used for _sweep creations.

label: str = 'Sweep'

Used in default naming of objects. See label.

_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

__inds

a list of sweepList length/s of multi-parameter _sweep object/s in subSys dictionary, meaning the length for simultaneously swept _sweep objects are not repeated. the values are appended to the list, if it is the first sweep to be included into subSys or combinatorial is True.

__indMultip

the multiplication of all the indices in inds. This value is used as the loop range by modularSweep.

property inds

returns _Sweep__inds and there is no setter

property indMultip

returns _Sweep__indMultip, and there is no setter

NOTE : The reason this property returns a pre-assingned value rather than calculating from the inds is to avoid calculating it over and over again, which could be avoided by checking if _Sweep__indMultip is None, but that might create other issues, such as re-running the same simulation after a change in sweepList length/s. It still can be improved, and it is possible to avoid such issues and get rid of prepare(), which is called in run methods of Simulations, by some modifications in these properties.

__firstlineno__ = 176

__static_attributes__ = ('_Sweep__indMultip', '_Sweep__inds', '__indMultip', '__inds')

property sweeps

The sweeps property wraps subSys dictionary to create new terminology, it works exactly as subSys.

removeSweep(sys)

Removes a _sweep it self, or all the _sweep objects that contain a particular sys in it. Since, it uses removeSubSys, it works exactly the same, meaning names/aliases/objects/listOfObjects can be used to remove.

If the argument sys is an _sweep object, this method calls removeSubSys (since _sweep objects are stored in subSys dictionary of Sweep objects).

Else, it calls the removeSubSys on every _sweep in its subSys dictionary (since systems are stored in subSys dictionary of _sweep objects).

createSweep(system=None, sweepKey=None, **kwargs)

Creates a instance of _sweep and assing its system and sweepKey to given system and sweepKey arguments of this method. Keyworded arguments are used to set the other attributes of the newly created _sweep object.

Parameters:

• system (Any) – Since system property setter of _sweep behaves exactly as subSys setter, this can be various things, from a single system to name/alias of the system, or from a class to a list/tuple contaning any combination of these.

• sweepKey (str) – Name of the attribute of system/s that will be swept

Returns:

The new _sweep instance.

prepare()

This method is called inside run method of Simulation object/s to update inds and indMultip attributes/properties. The reason for this a bit argued in indMultip(), but it is basically to ensure that any changes to sweepList/s or combinatorial/s are accurately used/reflected (especially on re-runs).

runSweep(indList)

called in modularSweep to run all the _sweep objects in a Sweep. indices from a given list indList are used by the runSweep method of _sweep objects, and it switches to a new index, if the combinatorial is True. This means that the _sweeps should be created in an order such that _sweep objects that run simultaneously have to be added to subSys one after the other. Also, for nested Sweeps, the indList should be a properly nested list.

static _indicesForSweep(ind, *args)

method used in modularSweep to calculate indices for each sweepList from the loop counter ìnd using the total lengths *args. It is hard to describe the exact calculation in words, but it is trivial to see from the math (TODO) which i will do later.

the loop counter can at max be \((\prod_{i = 1}^{len(args)} args[i]) - 1\), and multi-parameter sweeps loops the first sweepList while fixing the others. So, at each inp = args[0] the first list should start from zero, and the second list moves to next item, and this relation goes up in the chain, e.g. at each inp = args[0]*args[1], the index of the third need to be increased, and so on. Therefore, the current index for the first sweepList simply is the reminder of inp with args[0].