Sweep definition

Basic description of a sweep in DMT.

Sweeps are the basic element that can be fed into simulators or be retrieved from simulations or measurements. Features:

Clear syntax and definition to create a well described simulation independent of the simulator interface.

class DMT.core.sweep.Sweep(name: str, sweepdef: ~typing.List[~DMT.core.sweep_def.SweepDef | ~typing.Mapping[str, object]] | None = None, outputdef: ~typing.List[str | ~DMT.core.naming.SpecifierStr] | ~typing.Set[str | ~DMT.core.naming.SpecifierStr] | None = None, othervar: ~typing.Mapping[str, float] | None = None, SweepDefClass: ~typing.Type = <class 'DMT.core.sweep_def.SweepDef'>)[source]

Bases: object

Creates a sweep.

The following parameters need to be specified in the sweepdef or othervar parameter for every DUT, else an error is raised:

TEMPERATURE: device or simulation temperature

Parameters:

namestr

Name of the sweep. Prefix for the simulation folder for this sweep. Just for visuals, sometimes ‘VBC0’ is nice.

sweepdefList[Dict[str, Unknown] | SweepDef], optional

Definition of a sweep. The following keys MUST be specified for each subsweep: ‘var_name’,’sweep_type’. Depending on the sweep type additional keys must be specified:

‘LIN’ : The value for the key ‘value_def’ is an array [start, end, nsteps]. The values are linearly spaced with nsteps from start to end.
‘LOG’ : The value for the key ‘value_def’ is an array [start, end, nsteps]. The values are logarithmically spaced with nsteps from 10^start to 10^end.
‘CON’ : The value for the key ‘value_def’ is an array [val] or single number.
‘SYNC’: The value for the key ‘master’ is a ‘string’ with the value of the key ‘var_name’ of the master sweep. Additionally an ‘offset’ to the master sweep can be specified.

Also note that Sweep() can only sweep potentials, voltages are only swept indirectly. This is a willfull design decision. Ideally the ‘var_name’ is a SpecifierStr, but get_specifier_from_string() is called on the variable name anyway. So if a unique conversion exists var_name can be a string.

If the key ‘sweep_order’ is not explicitly specified, it is given by the sweep definitions position in the list with increasing order. Examples:

sweepdef = [
    {'var_name':specifiers.VOLTAGE+'B', 'sweep_order':1, 'sweep_type':'LIN', 'value_def':[0,1,11]},
    {'var_name':specifiers.VOLTAGE+'C', 'sweep_order':2, 'sweep_type':'CON', 'value_def':[1]},
    {'var_name':specifiers.VOLTAGE+'E', 'sweep_order':3, 'sweep_type':'CON' , 'value_def':[0]}
]

sweepdef = [ #this is equivalent to above sweepdef, now 'sweeporder' corresponds to the dict's position in the list.
    {'var_name':specifiers.VOLTAGE+'B', 'sweep_type':'LIN', 'value_def':[0,1,11]},
    {'var_name':specifiers.VOLTAGE+'C', 'sweep_type':'CON', 'value_def':[1]},
    {'var_name':specifiers.VOLTAGE+'E', 'sweep_type':'CON', 'value_def':[0]}
]
sweepdef = [
    {'var_name':specifiers.VOLTAGE+'B', 'sweep_order':1, 'sweep_type':'LIN' , 'value_def':[0,1,11]},
    {'var_name':specifiers.VOLTAGE+'C', 'sweep_order':1, 'sweep_type':'SYNC', 'master':specifiers.VOLTAGE+'B', 'offset':0.1}
    {'var_name':specifiers.VOLTAGE+'E', 'sweep_order':2, 'sweep_type':'CON' , 'value_def':[0]}
]

outputdefList[str] or Set[str] , optional

A list of the variables that shall be computed. Example: [specifiers.CURRENT+’C’,specifiers.CURRENT+’B’]

othervarDict[str, float], optional

A dict whose ‘key’:’value’ pairs specify variables that do not need to be included in the sweepdef parameter as they should be constants. Example: {TEMPERATURE:300,’w’:10}

SweepDefClassType, optional

From this class the sweep def objects are created and the SweepDefClass checks the sweep type. The user can supply subclasses of SweepDef here to allow custom sweep types.

Attributes:

sweepdefList[SweepDef]: Get the sweepdef
outputdefList[str]: Defines which quantities need to be calculated.
othervarDict[str, float]: Optional variables.
namestr: The sweep will be saved as name + hash using this string.

Methods

check_sweep()	Checks the sweep for correctness with regards to its definition and logical consistency. Also takes care of the master - sync logic.
get_hash()	Returns a hash corresponding to a Sweep object.
create_df()	Returns an prepared `DataFrame` with all columns from the sweep definitions and output variables. The sweep definition columns are already prefilled.
set_values()	Fills all the values inside the sweepdef object list.
get_temperature()	Returns the reference temperature of the sweep to simulate. Mostly used for key generation.

check_sweep()[source]

Checks a sweep for correctness.

check_sweep() has the following features:

checks the specified sweep type and converts it to a non-misunderstandable format.
corrects the sweep_order
sets offset for SYNC
checks if non-optional variables are specified
corrects the variable names according to DMT format

create_df() → DataFrame[source]

Fill the dataframe according to the sweepdefinition

Returns:

DMT.core.DataFrame: A pandas dataframe object that corresponds to the specified sweep. Values that need to be calculated are filled with numpy.nan .

get_hash() → str[source]

Returns a hash for this sweep.

Returns:

str: MD5 hash that corresponds to this sweep.

classmethod get_sweep_from_dataframe(data: ~DMT.core.data_frame.DataFrame, temperature: float | None = None, name: str = 'sweep', outputdef: ~typing.List[str] | None = None, othervar: ~typing.Dict[str, float] | None = None, SweepDefClass: ~typing.Type = <class 'DMT.core.sweep_def.SweepDef'>, decimals_potentials: int = 3, **kwargs) → Sweep[source]

Create a Sweep from a DataFrame

Parameters:

dataDataFrame: data to create a Sweep from.
temperaturefloat | None, optional: Temperature in Kelvin, if not given it must be part of othervar, by default None
namestr, optional: Name of the sweep to create, by default “sweep”
outputdefList[str] | None, optional: outputdef of the new Sweep, by default None
othervarDict[str, float] | None, optional: othervar of the new Sweep, by default None
SweepDefClassType, optional: SweepDefClass for the new sweepdefs, by default SweepDef
decimals_potentialsint, optional: Round to x number of decimals for potentials and frequencies, by default 3

Returns:

Sweep: Created sweep from the dataframe

get_temperature() → str[source]

Returns the temperature of the sweep as a string. Use this to set the key of a dut.

Returns:

str

Single temperature: “Txxx.xxK”
List of temperatures: “T(xxx.xx,yyy.yy,…)K”
Range of temperatures: “T[xxx.xx-sss.ss-yyy.yy]K”, s is the step

property othervar[source]

property outputdef[source]

set_values()[source]: Set the values of sweep according to the DMT definition.

property sweepdef[source]

Get the sweepdef

Returns:

List[SweepDef]: Saved sweepdef

DMT.core.sweep.get_sweepdef(data: DataFrame, inner_sweep_voltage: SpecifierStr | None = None, outer_sweep_voltage: SpecifierStr | None = None, col_third: SpecifierStr | None = None, decimals_potentials: int = 3) → List[Dict][source]

Given a dataframe, one inner sweep_voltage and one outer sweep voltage, this method tries to create a SweepDefinition that can be used to re-simulate the data.

Parameters:

dataDataFrame: Frame to extract the sweepdefs from
inner_sweep_voltageSpecifierStr | None, optional: A specifier that determins the inner sweep voltage, by default None
outer_sweep_voltageSpecifierStr | None, optional: A specifier that determins the inner outer voltage, by default None
outer_sweep_voltageSpecifierStr | None, optional: A voltage at a third possible contact, that is not swept but may differ from zero.
decimals_potentialsint, optional: Round the potentials to x number of decimals, by default 3

Returns:

sweepdef[{}]: A sweep definition that can be used to init a SweepDef.

Raises:

IOError: No forced potentials (or potentials at all) in the columns. Make sure all forced potentials in the columns are SpecifierStr!”
IOError: The supplied voltages do not define unambiguous sweep conditions for the data.
NotImplementedError: Either set both or no sweep specifier for now!
NotImplementedError: If both sweep voltages are set to currents