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 determiens the inner sweep voltage, by default None

outer_sweep_voltageSpecifierStr | None, optional

A specifier that determiens 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