TMPL Application Programming Interface

The core TMPL classes TestManager, Measurement and SetupClasses are all created from abstract class defintions. These are like “templates” that provide most of the underlying functionality, with only a few methods that need to be defined by the user.

TestManager classes

TestManager classes are defined from the AbstractTestManager class and require the user to define the methods: define_measurements and define_setup_conditions. Optionally a define_services method can also be defined. The main methods that the user will encounter are documented below:

class tmpl.AbstractTestManager(resources={}, **kwargs)

Test manager class template definition

TestManagers are responsible for running measurements over multiple conditions and collecting up all the data.

Measurements are implemented as classes that inherit from AbstractMeasurement. Setup conditions are classes based on AbstractSetupConditions.

Measurements and setup conditions are held in dictionaries that are class properties:

  • self.meas : contains all available measurements for this test

  • self.conditions : all conditions classes for this test

Initialise test sequence manager object

Parameters:

  • resources (dict, optional) – Dictionary of objects, e.g. instrument drivers, required by the measurements, by default {}

  • config (dict, optional) – Configuration settings dictionary. Can be used to store settings and options for measurements. These should be ‘standard’ python variable types, like strings, numbers, lists and dicts. Values entered in this dict will OVERWRITE anything with the same name in the self.config property of Measurement and SetupConditions classes.

run(*arg, **kwargs)

Run full test over all or specified conditions [Mandatory function]

Parameters:

conditions (list of dict, optional) –

list of dict of conditions, by default None Conditions are specified as key value pairs e.g.

conditions = [dict(temperature_degC=34,humidity=50)]

conditions = [{‘temperature_degC’:34,’humidity’:50}]

conditions = [{‘temperature_degC’:40,’humidity’:50}]

conditions = [

{‘temperature_degC’:25,’humidity’:50},

{‘temperature_degC’:40,’wavelength_nm’:1560},

]

Raises:

ValueError – If supplied conditions are the wrong format

add_setup_condition(cond_class, cond_name='')

Add setup conditions This takes a class (not an instance) and creates an instance from it that is populated with resources

Examples

class Temperature():

…

testseq.add_setup_condition(Temperature)

Parameters:

  • cond_class (class reference) – Reference to the class i.e. the class name in code

  • cond_name (str) – Name to be used to reference setup condition. This will appear as a key in the self.conditions dict and also as a coordinate in ds_results. If nothing is specified then the class name is used.

add_measurement(meas_class, meas_name='', run_state=None)

Add measurement class This takes a class (not an instance) and creates an instance from it that is populated with resources

Examples

class VoltageSweep():

…

testseq.add_measurement(VoltageSweep)

Parameters:

  • meas_class (class reference) – Reference to the class i.e. the class name in code

  • meas_name (str) – Name to be used to reference measuremEnt. This will appear as a key in the self.meas dict. If nothing is specified then the class name is used.

  • run_state (str or list of str or dict) –

    Specify which state this measurement should run in. The options are:

    • str : Name of state [‘startup’,’teardown’,’main’]

    • list : List of states, same names as for str

    • dictThis is primarily for the ‘setup’ and ‘after’ states

      where a condition needs to be specified. Here the format would be

      {‘setup’:’<Condition name>’}

      or

      {‘after’:’<Condition name>’}

to_markdown(filename=None, exclude_cond=['Iteration'], exclude_meas=['Timestamp'])

Generate a markdown file containing a description of the test sequence.

Creates a description of the test sequence from the docstrings of all setup conditions and measurements.

Can be returned as a string or written to a file

Parameters:

  • filename (str, optional) – path/filename to file where markdown is to be written, If None then the markdown will be returned as a string by default None

  • exclude_cond (list of str) – A list of condition names to exclude from markdown file

  • exclude_meas (list of str) – A list of measurement names to exclude from markdwon file

Returns:

If no filename was given a string is returned with markdown text Otherwise None

Return type:

str or None

abstract define_setup_conditions()

Define setup condition classes to be used for this test.

All that is required is to add SetupCondition classes using the add_setup_condition() method as shown below:

Example usage

def define_setup_conditions(self):
    self.add_setup_condition(TemperatureConditions)
    self.add_setup_condition(HumidityConditions)
Return type:

None

abstract define_measurements()

Define measurement classes to be used for this test.

All that is required is to add Measurement classes using the add_measurement() method as shown below:

Example usage

def define_measurements(self):
    self.add_measurement(TurnOn)
    self.add_measurement(Stabilise)
    self.add_measurement(VoltageSweeper)
    self.add_measurement(TurnOff)
Return type:

None

save(filename, format='json')

Save ds_results dataset

Parameters:

  • filename (str) – Full path/filename

  • format (str, optional) –

    File format to save in, by default ‘json’ Options are:

    • ’json’

    • ’excel’

Raises:

ValueError – If file format is not supported

load(filename)

Load data into self.ds_results If the self object is a measurement or conditions class then it will only take data that is usually generated by those classes.

If the self object is a test manager class it will load the data into its self.ds_results property and also distribute the data amongst its measurement/conditions classes.

The net effect should be to recreate all the self.ds_results datasets that existed when the file was saved.

Parameters:

filename (str) – full path/filename to data file

Raises:

  • FileNotFoundError – Data file could not be found

  • ValueError – Data file is not a .json file

  • ValueError – No data for this object could be found in the file

Measurement classes

Measurement classes are defined from the AbstractMeasurement class. They have one mandatory method that must be defined by the user: meas_sequence, plus two optional methods initialise and process.

class tmpl.AbstractMeasurement(resources={}, **kwargs)

Measurement class This class contains the measurement code. At a minimum it should define the ‘meas_sequence()’ method and the ‘enable’ property.

Example usage

Create measurement

>>> meas = MyMeasurement(resources)

Enable/disable measurement

>>> meas.enable = True # Measurement will run by default
>>> meas.run()

>>> meas.enable = False # Measurement will not run
>>> meas.run()  # Nothing happends

Results are returned in an xarray Dataset

>>> meas.ds_results

Initialise measurement

param resources:

Dictionary like object that contains ‘resources’. These can be instrument objects, station objects, testboard objects etc. The key should be the name of the resource e.g. for a station and testboard class resources = {‘station’:station, ‘testboard’:tb}

These can be extracted out in the initialise() method, if desired, to make them class properties.

type resources:

dict like

param run_condition:

Specifiy the name of the condition where this measurement is run. e.g. if the measurement should be run every time the condition ‘temperature’ is set then run_condition=’temperature’. The name must correspond to a key in the TestManager objects ‘conditions’ property.

type run_condition:

str (optional)

initialise()

Custom initialisation function. Put any custom properties and definitions in here. This function will be run automatically when an object is instantiated.

Example use could be to extract out contents of resources to properties e.g.

self.station = self.resources[‘station’] self.tb = self.resources[‘testboard’]

run(*arg, **kwargs)

Run measurement sequence at specified conditions This method will run the sequence inside a try/except block to catch errors. Error messages will be reported in self.last_error

Parameters:

conditions (dict, optional) –

Dict of current setup conditions Conditions are specified as key value pairs e.g.

conditions = dict(temperature_degC=34,humidity=50) conditions = {‘temperature_degC’:34,’humidity’:50}

The value of each item in the conditions dict is treated as one value. The Measurement class does not actually set the conditions it just uses them to set coordinates in the ds_results Dataset.

by default cond = {‘default’:0}, this allows the measurement to be run without specifiying any conditions. All data in self.ds_results will have a coordinate called ‘default’, which can be removed later if necessary.

Returns:

True if sequence executed successfully, False if error occurred

Return type:

bool

Raises:

NotImplementedError – [description]

abstract meas_sequence()

Define the sequence of measurements that are executed by the run() method. This is a mandatory method that all classes must define. The user is free to put anything in this method.

property ds_results_global

Access global dataset of test manager

Returns:

Returns the test manager ds_results dataset

Return type:

xarray Dataset

store_data_var(name, data_values, coords=[])

Store data into a data variable in self.ds_results Creates a new data variable or overwrites existing data. The new data variable also has all the current conditions appended to it.

Parameters:

  • name (str) – Name of new data variable. No spaces, ascii only

  • data_values (list or array) – Array of data to be added to data variable The dimensions of the array needs to be consistent with the coordinates being requested.

  • coords (list or dict, optional) – List of coordinates for this data variable, usually added by the store_coords() method, e.g. [‘sweep_voltage’] by default [] Can also be a dict if a specific coordinate value is being requested e.g. {‘Resistor’:’R1’} If some coordinates need specific values and others do not then they can be mixed in the dict by setting the value to None for those that do not have a value e.g. {‘Resistor’:’R1’,’sweep_voltage’:None}

store_coords(name, values)

Add a new coordinate to self.ds_results or overwrite and existing one

Parameters:

  • name (str) – Name of new coordinate, no spaces, ascii

  • values (list or array) – 1D list or array of values for this coordinate

save(filename, format='json')

Save ds_results dataset

Parameters:

  • filename (str) – Full path/filename

  • format (str, optional) –

    File format to save in, by default ‘json’ Options are:

    • ’json’

    • ’excel’

Raises:

ValueError – If file format is not supported

load(filename)

Load data into self.ds_results If the self object is a measurement or conditions class then it will only take data that is usually generated by those classes.

If the self object is a test manager class it will load the data into its self.ds_results property and also distribute the data amongst its measurement/conditions classes.

The net effect should be to recreate all the self.ds_results datasets that existed when the file was saved.

Parameters:

filename (str) – full path/filename to data file

Raises:

  • FileNotFoundError – Data file could not be found

  • ValueError – Data file is not a .json file

  • ValueError – No data for this object could be found in the file

SetupCondition classes

SetupCondition classes are defined from AbstractSetupCondition class. They require the user to define two properties: setpoint and actual.

class tmpl.AbstractSetupConditions(resources, **kwargs)

Setup conditions class This class sets up conditions like temperature, wavelength etc. Conditions that are not changing quickly. A measurement will be run under one combination of setup conditions.

Example usage

Create Setup conditions

>>> cond = MySetupConditions(station,uut,values=[1,2,3])

Enable/disable conditions

>>> cond.enable = True # condition will be set by default
>>> cond.set(value)

>>> cond.enable = False # Measurement will not run
>>> cond.set(value)  # Nothing happends

State of conditions are returned by

>>> cond.setpoint
>>> cond.actual

Return list of values

>>> cond.values

Initialise measurement

param station:

Class that contains instrumentation for the station

type station:

station class

param uut:

Class object that allows measurements of the unit under test

type uut:

any

param values:

List of allowed values for the setpoints.

type values:

list

property ds_results_global

Access global dataset of test manager

Returns:

Returns the test manager ds_results dataset

Return type:

xarray Dataset

initialise()

Custom initialisation function. Put any custom properties and definitions in here. This function will be run automatically when an object is instantiated.

Example use could be to extract out contents of resources to properties e.g.

self.station = self.resources[‘station’] self.tb = self.resources[‘testboard’]

abstract property setpoint

Get/Set the condition setpoint

e.g.

>>> cond_temperature_degC.setpoint = 25

>>> cond_temperature_degC.setpoint

25

Raises:

NotImplementedError – If user has not defined this property in SetupCondition class

abstract property actual

Get the actual condition value Read only value

e.g.

>>> cond_temperature_degC.setpoint = 25

>>> cond_temperature_degC.actual

25.2

Raises:

NotImplementedError – If user has not defined this property in SetupCondition class