3. Reference

3.1. qualib/

3.1.1. log.py

class qualib.log.Log[source]

Logs timestamped and labeled informations (“info”), debug informations (“debug”), warnings (“warn”), errors (“error”), and/or custom content.

Keyword arguments **kwargs are not supported yet, but may be added in future versions.

initialize(timestamp, max_label_len=5)[source]

Parameters

timestamp (str) – Timestamp string
max_label_len (int) – Maximum label length in characters (e.g. 5 if the possible labels are DEBUG, INFO, WARN and ERROR). Log entries (prefix: message or message) are aligned according to this constant: set max_label_len to 0 to disable log entries alignment.

Returns

A logging object.

Return type

Log

debug(prefix, *lines, **kwargs)[source]

Logs a debug message.

Parameters

prefix (str) – Optional log entry prefix (set prefix to "" to log a message without a prefix).
lines (str) – Lines to log (1 argument each: use the unpack operator * to log a list of lines).

Returns

self

Return type

Log

info(prefix, *lines, **kwargs)[source]

Logs an information message.

Parameters

prefix (str) – Optional log entry prefix (set prefix to "" to log a message without a prefix).
lines (str) – Lines to log (1 argument each: use the unpack operator * to log a list of lines).

Returns

self

Return type

Log

warn(prefix, *lines, **kwargs)[source]

Logs a warning message.

Parameters

prefix (str) – Optional log entry prefix (set prefix to "" to log a message without a prefix).
lines (str) – Lines to log (1 argument each: use the unpack operator * to log a list of lines).

Returns

self

Return type

Log

error(prefix, *lines, **kwargs)[source]

Logs an error message.

Parameters

prefix (str) – Optional log entry prefix (set prefix to "" to log a message without a prefix).
lines (str) – Lines to log (1 argument each: use the unpack operator * to log a list of lines).

Returns

self

Return type

Log

exc()[source]

Logs the current exception traceback as an error message.

Returns: self
Return type: Log

log(label, prefix, *lines, **kwargs)[source]

Logs a message with given label and prefix.

Parameters

label (str) – Label of the log entry (e.g. warn).
prefix (str) – Optional log entry prefix (set prefix to "" to log a message without a prefix).
lines (str) – Lines to log (1 argument each: use the unpack operator * to log a list of lines).

Returns

self

Return type

Log

json(obj)[source]

Returns an indented string representation of an object.

Parameters: obj (list | dict) – Object to stringify.
Returns: Indented string representation of obj.
Return type: str

3.1.2. load.py

qualib.load.load_calibration_scheme(log, path)[source]

Parameters

log (qualib.log.Log) – Logging object.
path (str) – Absolute or relative path to the Python file describing the calibration sequence to run.

Returns

Parsed calibration sequence, raw calibration sequence.

Return type

Tuple[list, str]

qualib.load.load_assumptions(log, path='assumptions.py')[source]

Parameters

log (qualib.log.Log) – Logging object.
path (str) – Path to the assumptions file (assumptions.py by default).

Returns

Assumptions before any calibration.

Return type

dict

qualib.load.load_utils(log, name, prefix)[source]

Parameters

log (qualib.log.Log) – Logging object.
name (str) – Name of the calibration. The Python script to load should be named {name}_utils.py under qualib/calibrations/{name}.
prefix (str) – Prefix of the log entry (whose format will be [timestamp] [INFO] prefix: message).

Returns

Calibration class from CALIBRATION_NAME_utils.py.

Return type

Calibration

qualib.load.load_exopy_template(log, name, prefix)[source]

Parameters

log (qualib.log.Log) – Logging object.
name (str) – Name of the calibration. The Exopy template to load should be named {name}_template.meas.ini under qualib/calibrations/{name}.
prefix (str) – Prefix of the log entry (whose format will be [timestamp] [INFO] prefix: message).

Returns

Contents of the Exopy template for a given calibration name.

Return type

str

3.1.3. main.py

class qualib.main.Qualib[source]

Wrapper supclass.

retries = 0: Type: int

run(log, report, assumptions, id, name, substitutions, timestamp)[source]

Runs a single calibration with given assumptions and Exopy template.

Parameters

log (qualib.log.Log) – Logging object.
report (qualib.calibrations.default.Report) – Default report object.
assumptions (dict) – Current state of the assumptions (updated after each calibration).
id (int) – Natural number giving the rank of the calibration to run.
name (str) – Name of the calibration to run (in lowercase).
substitutions (Dict[str, str]) – Dictionary of substitutions.
timestamp (str) – Timestamp used to create the log and report files.

Return type

None

run_all(pkg_calib_scheme='', assumptions={})[source]

Runs a calibration sequence whose path is either passed:

As pkg_calib_scheme — package usage examples: Qualib().run_all('calibration_scheme.py', assumptions_dict), Qualib().run_all(calibration_scheme_list)

Or in sys.argv — CLI/module usage: python -m qualib.main calibration_scheme.py.

Parameters

pkg_calib_scheme (Union[str, list]) – Path to the Python file defining the calibration sequence to run (str) or calibration sequence to run (list).
assumptions (dict) – Optional. Custom assumptions dict.

Return type

list

3.1.4. calibrations/default.py

qualib.calibrations.default.get_diff(prev, next)[source]

Generator of diff lines between prev and next.

Parameters

prev (List[str]) – First list of lines.
next (List[str]) – Second list of lines.

Return type

Generator[str, None, None]

qualib.calibrations.default.keep_cell(src)[source]

Handles conditional cells: skips a given cell if its first line is #if condition: and condition evaluates to False.

Parameters: src (List[str]) – Lines of a given cell.
Return type: bool

qualib.calibrations.default.handle_magic_commands(log, pre, line)[source]

Filters magic commands and runs %run path_or_url ones.

Parameters

log (qualib.log.Log) – Logging object.
pre (str) – Optional log entry prefix.
line (str) – Line to process.

Returns

'' if line is a magic command or an empty string, line otherwise.

Return type

str

class qualib.calibrations.default.DefaultCalibration(log, report, assumptions, id, name, substitutions, exopy_templ, pre, timestamp)[source]

Defines the code shared between all calibrations.

Parameters

log (Log) – Logging object.
report (Report) – Default report object.
assumptions (dict) – Current state of the assumptions (updated after each calibration).
id (int) – Natural number giving the rank of the calibration to run.
name (str) – Name of the calibration to run (in lowercase).
substitutions (dict) – Dictionary of substitutions.
exopy_templ (str) – Content of the Exopy measurement template.
pre (str) – Default prefix for log entries.
timestamp (str) – Timestamp used to create the log and report files.

log

Logging object.

Type: Log

report

Default report object.

Type: Report

assumptions

Current state of the assumptions (updated after each calibration).

Type: dict

id

Natural number giving the rank of the calibration to run.

Type: int

name

Name of the calibration to run (in lowercase).

Type: str

substitutions

Dictionary of substitutions.

Type: dict

exopy_templ

Exopy measurement template for the current calibration.

Type: str

pre

Default prefix for log entries.

Type: str

timestamp

Timestamp used to create the log and report files.

Type: str

report_templ

Cells of the calibration report template.

Type: list

hdf5_path

Relative path to the HDF5 measurement file.

Type: str

results

Dictionary of results.

Type: dict

handle_substitutions(mapping={})[source]

Handles substitutions. Should be called at the end of Calibration.handle_substitutions().

Parameters: mapping (Dict[str, str]) – Dictionary of substitutions.
Return type: None

pre_process(mapping={})[source]

Handles pre-placeholders. Should be called at the end of Calibration.pre_process().

Parameters: mapping (Dict[str, str]) – Dictionary of 'PRE_PLACEHOLDER': value pairs.
Return type: None

process()[source]

Executes analysis code and updates assumptions.

Return type: None

post_process(mapping={})[source]

Handles post-placeholders. Should be called at the end of Calibration.post_process().

Parameters: mapping (Dict[str, str]) – Dictionary of 'POST_PLACEHOLDER': value pairs.
Return type: None

class qualib.calibrations.default.Report(log, filename, assumptions, calib_scheme, timestamp)[source]

Generates and updates a Jupyter notebook to report the calibrations results.

Parameters

filename (str) – Report filename.
assumptions (dict) – Dictionary of assumptions.
calib_scheme_str (str) – String representation of the calibration sequence.
timestamp (str) – Timestamp used to create the log and report files.
log (Log) –
calib_scheme (str) –

log

Logging object.

Type: Log

filename

Report filename.

Type: str

header

List of header cells.

Type: list

notebook: nbformat.v4 notebook object.

cells

List of cells in the report notebook.

Type: list

assumptions

Dictionary of assumptions.

Type: dict

assump_befr

String representation of the assumptions before the current calibration.

Type: str

assump_aftr

String representation of the assumptions after the current calibration.

Type: str

cell_aftr

Index of the cell containing the assumptions after the current calibration.

Type: int

cell_diff

Index of the cell containing the differences between the assumptions before and after the current calibration.

Type: int

update()[source]

Overwrites self.notebook and reports/report_TIMESTAMP.ipynb from the list of cells self.cells.

Return type: Report

add_calibration(calibration)[source]

Appends a calibration to the report.

Parameters: calibration – Instance of the current Calibration class.
Return type: Report

add_results(calibration)[source]

Reports results from the current calibration.

Return type: Report

add_md_cell(src)[source]

Return type: Report

add_py_cell(src)[source]

Return type: Report

ins_md_cell(pos, src)[source]

Return type: Report
Parameters: pos (int) –

ins_py_cell(pos, src)[source]

Return type: Report
Parameters: pos (int) –

3.2. qualib/calibrations/NAME/

3.2.1. NAME_utils.py

class qualib.calibrations.NAME.NAME_utils.Calibration

Inherits from, and overrides, qualib.calibrations.default.DefaultCalibration.

handle_substitutions()

pre_process()

process()

post_process()

3.3. reports/TIMESTAMP.ipynb

Each report consists in:

Calibration sequence (Report.__init__())

Assumptions before calibration sequence (Report.__init__())

Assumptions after calibration sequence (Report.add_results())

Assumptions diff (Report.add_results())

Report header (imports, utility functions) (Report.__init__())

Calibrations reports (Report.add_calibration(), Report.add_results())

3.4. logs/TIMESTAMP.log

Logs consist in timestamped and labeled lines of information (“info”), debug information (“debug”), warning (“warn”), errors (“error”) and/or custom content.