lightlab.laboratory.state module

This module contains classes responsible to maintain a record of the current state of the lab.

Users typically just have to import the variable lab.

Warning

Developers: do not import lab anywhere inside the lightlab package. This will cause the deserialization of the JSON file before the definition of the classes of the objects serialized. If you want to make use of the variable lab, import it like this:

import lightlab.laboratory.state as labstate

# developer code
device = function_that_returns_device()
bench = labstate.lab.findBenchFromInstrument(device)

Summary

Classes:

LabState

Represents the set of objects and connections present in lab, with the ability to safely save and load to and from a .json file.

Functions:

hash_sha256	Returns the hash of string encoded via the SHA-256 algorithm from hashlib
init_module
patch_labstate	This takes the loaded JSON version of labstate (old_lab) and applies a patch to the current version of labstate.
timestamp_string	Returns timestamp in iso format (e.g.

Data:

can_write	bool(x) -> bool
lab

Reference

timestamp_string()

Returns timestamp in iso format (e.g. 2018-03-25T18:30:55.328389)

hash_sha256(string)

Returns the hash of string encoded via the SHA-256 algorithm from hashlib

class LabState(filename=None)

Bases: lightlab.laboratory.Hashable

Represents the set of objects and connections present in lab, with the ability to safely save and load to and from a .json file.

instruments_dict

Dictionary of instruments, concatenated from lab.instruments.

hosts = None

list(Host) list of hosts

benches = None

list(Bench) list of benches

connections = None

list(dict(str -> str)) list of connections

devices = None

list(Device) list of devices

instruments = None

list(Instrument) list of instruments

updateHost(*hosts)

Updates hosts in the hosts list.

Checks the number of instrumentation_servers. There should be exactly one.

Parameters:

* (Host) – hosts

Raises:

• RuntimeError – Raised if duplicate names are found.
• TypeError – Raised if host is not of type Host

updateBench(*benches)

Updates benches in the benches list.

Parameters:

* (Bench) – benches

Raises:

• RuntimeError – Raised if duplicate names are found.
• TypeError – Raised if bench is not of type Bench

deleteInstrumentFromName(name)

Deletes an instrument by their name.

Example:

lab.deleteInstrumentFromName("Keithley2")

Parameters:name (str) – Instrument name

insertInstrument(instrument)

Inserts instrument in labstate.

Parameters:

instrument (Instrument) – instrument to insert.

Raises:

• RuntimeError – Raised if duplicate names are found.
• TypeError – Raised if instrument is not of type Instrument

insertDevice(device)

Inserts device in labstate.

Parameters:

device (Device) – device to insert.

Raises:

• RuntimeError – Raised if duplicate names are found.
• TypeError – Raised if device is not of type Device

updateConnections(*connections)

Updates connections between instruments and devices.

A connection is a tuple with a pair of one-entry dictionaries, as such:

conn = ({instr1: port1}, {instr2: port2})

The code assumes that there can only be one connection per port. This method performs the following action:

1. verifies that port is one of instr.ports. Otherwise raises

   a RuntimeError.

2. deletes any connection in lab.connections that has

   either {instr1: port1} or {instr1: port1}, and logs the deleted connection as a warning.

3. adds new connection

Parameters:connections (tuple(dict)) – connection to update

devices_dict

Dictionary of devices, concatenated from lab.devices.

Access with devices_dict[device.name]

Todo

Logs a warning if duplicate is found.

findBenchFromInstrument(instrument)

Returns the bench that contains the instrument.

This obviously assumes that one instrument can only be present in one bench.

findBenchFromDevice(device)

Returns the bench that contains the device.

This obviously assumes that one device can only be present in one bench.

findHostFromInstrument(instrument)

Returns the host that contains the instrument.

This obviously assumes that one instrument can only be present in one host.

classmethod loadState(filename=None, validateHash=True)

Loads a LabState object from a file.

It loads and instantiates a copy of every object serialized with lab.saveState(filename). The objects are saved with jsonpickle, and must be hashable and contain no C-object references. For convenience, lab objects are inherited from :class:`lightlab.laboratory.Hashable.

By default, the sha256 hash is verified at import time to prevent instantiating objects from a corrupted file.

A file version is also compared to the code version. If a new version of this class is present, but your json file is older, a RuntimeWarning is issued.

Todo

When importing older json files, know what to do to upgrade it without bugs.

Parameters:

• filename (str or Path) – file to load from.
• validateHash (bool) – whether to check the hash, default True.

Raises:

• RuntimeWarning – if file version is older than lightlab.
• RuntimeError – if file version is newer than lightlab.
• JSONDecodeError – if there is any problem decoding the .json file.
• JSONDecodeError – if the hash file inside the .json file does not match the computed hash during import.
• OSError – if there is any problem loading the file.

filename

Filename used to serialize labstate.

saveState(fname=None, save_backup=True)

Saves the current lab, together with all its dependencies, to a JSON file.

But first, it checks whether the file has the same hash as the previously loaded one. If file is not found, skip this check.

If the labstate was created from scratch, save with _saveState().

Parameters:

• fname (str or Path) – file path to save
• save_backup (bool) – saves a backup just in case, defaults to True.

Raises:

OSError – if there is any problem saving the file.

init_module(module)

patch_labstate(from_version, old_lab)

This takes the loaded JSON version of labstate (old_lab) and applies a patch to the current version of labstate.