evedata.scan.boundaries.scml module

Low-level Python object representation of SCML file contents.

Contents

This module provides a low-level representation of the contents of an SCML file that can be mapped to the Scan and Station interfaces. Being a low-level object representation, technically speaking this module is a resource. The corresponding facade (user-facing interface) would be the scan module.

Overview

A first overview of the classes implemented in this module and their hierarchy is given in the UML diagram below.

TBD

Key aspects

Despite being a low-level interface to SCML files, the scml module provides a series of abstractions and special behaviour summarised below:

• …

Usage

SCML files are XML files following a particular XML Schema Definition (XSD) and contain potentially a scan definition and definitions for devices (detectors, motors, devices).

SCML files can exist either as files in the file system, or can be loaded as text from other places, e.g. the user block of an eveH5 HDF5 file. Hence, there are two distinct methods for loading the contents of an SCML file.

In case of a file in the file system, use the load() method:

scml = SCML()
scml.load(filename="my_scml_file.scml")

In case of an SCML file read from, e.g., the user block of an eveH5 HDF5 file, the contents of the SCML file will typically be contained in a variable – in our case scml_contents:

scml = SCML()
scml.from_string(xml=scml_contents)

In both cases, the root attribute will be set to the root element of the SCML file read. Afterwards, you can access the other attributes, scan, scan_modules, detectors, motors, and devices as needed, to further process the contents of the SCML file.

Module documentation

class evedata.scan.boundaries.scml.SCML

Bases: object

Representation of an SCML file.

SCML files are XML files following a distinct schema and can contain descriptions of a scan performed by the engine as well as a list of devices (detectors, motors, devices), either those actually used in a scan or those of the entire measurement station.

Currently, to read the SCML file, the xml.etree.ElementTree module gets used. Furthermore, the attributes scan, scan_modules, detectors, motors, and devices contain crucial parts of the SCML, simplifying further processing and mapping of the SCML contents to Python objects from the scan.entities subpackage.

root

Root element of the SCML file read.

Type:

xml.etree.ElementTree.Element

version

Schema version of the SCML file loaded.

The reason behind directly mapping this information here is to allow the VersionMapperFactory to return the correct VersionMapper object.

Type:

str

Examples

SCML files are XML files following a particular XML Schema Definition (XSD) and contain potentially a scan definition and definitions for devices (detectors, motors, devices).

SCML files can exist either as files in the file system, or can be loaded as text from other places, e.g. the user block of an eveH5 HDF5 file. Hence, there are two distinct methods for loading the contents of an SCML file.

In case of a file in the file system, use the load() method:

scml = SCML()
scml.load(filename="my_scml_file.scml")

In case of an SCML file read from, e.g., the user block of an eveH5 HDF5 file, the contents of the SCML file will typically be contained in a variable – in our case scml_contents:

scml = SCML()
scml.from_string(xml=scml_contents)

In both cases, the root attribute will be set to the root element of the SCML file read. Afterwards, you can access the other attributes, scan, scan_modules, detectors, motors, and devices as needed, to further process the contents of the SCML file.

property scan

Scan block of the SCML file.

Note that not every SCML/XML file necessarily contains a scan block. Those XML files describing the devices (detectors, motors, devices) available at a measurement station do not contain a scan block.

Returns:

scan – Scan element of the SCML file.

Return type:

xml.etree.ElementTree.Element

property scan_modules

Scan modules contained in the scan block of the SCML file.

Note that not every SCML/XML file necessarily contains a scan block. Those XML files describing the devices (detectors, motors, devices) available at a measurement station do not contain a scan block.

Returns:

modules – Scan modules of the SCML file.

Each element in the list is an xml.etree.ElementTree.Element object.

Empty list if no SCML has been read or no scan modules could be found in the SCML file.

Return type:

list

property detectors

Detectors defined in the SCML file.

In case of an SCML file with a scan block, only those detectors actively used in the scan are contained. In case of an SCML/XML file describing the measurement station, all detectors defined and potentially available at this measurement station are contained.

Returns:

detectors – Detectors defined in the SCML file.

Each element in the list is an xml.etree.ElementTree.Element object.

Empty list if no SCML has been read or no detectors could be found in the SCML file.

Return type:

list

property motors

Motors defined in the SCML file.

In case of an SCML file with a scan block, only those motors actively used in the scan are contained. In case of an SCML/XML file describing the measurement station, all motors defined and potentially available at this measurement station are contained.

Returns:

motors – Motors defined in the SCML file.

Each element in the list is an xml.etree.ElementTree.Element object.

Empty list if no SCML has been read or no motors could be found in the SCML file.

Return type:

list

property devices

Devices defined in the SCML file.

In case of an SCML file with a scan block, only those devices actively used in the scan are contained. In case of an SCML/XML file describing the measurement station, all devices defined and potentially available at this measurement station are contained.

Returns:

devices – Devices defined in the SCML file.

Each element in the list is an xml.etree.ElementTree.Element object.

Empty list if no SCML has been read or no devices could be found in the SCML file.

Return type:

list

load(filename='')

Load SCML file and parse contents.

The root element is set to the document root of the SCML file read.

Parameters:

filename (str) – Name (path) of the SCML file

from_string(xml='')

Load SCML file from string and parse contents.

The root element is set to the document root of the SCML file read.

Parameters:

xml (str) – String representation of an SCML file.

Raises:

ValueError – Raised if no XML string is provided.