evedata.scan.boundaries.scan module

High-level Python object representation of SCML file contents.

This module provides a high-level representation of the contents of an SCML file. Being a high-level, user-facing object representation, technically speaking this module is a facade. The corresponding resource (persistence-layer-facing interface) would be the scml module.

Overview

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

../../../_images/evedata.scan.boundaries.scan.svg

Fig. 44 Class hierarchy of the scan.boundaries.scan module, providing the facades for the scan and setup descriptions. Currently, the basic idea is to inherit from the File interface. The difference between the load() and extract() methods: While load() loads a file from the file system, extract() extracts the SCML from the user block of a given HDF5 file.

When loading an SCML/XML file, the SCML class is called to read the actual XML, and afterwards, the contents are mapped to the entities defined in the entities subpackage.

Key aspects

The key characteristics of the module are:

  • Stable interface to SCML files, regardless of their version.

    • Some features may only be available for newer SCML versions, though.

  • Access to the complete relevant information contained in an SCML file.

Usage

Loading the scan description contained in an eveH5 data file of a measurement may be as simple as:

from evedata.scan.boundaries.scan import Scan

scan = Scan()
scan.extract(filename="my_measurement_file.h5")

Internals: What happens when reading an SCML file?

…

Module documentation

class evedata.scan.boundaries.scan.File

Bases: object

Interface class for SCML files.

There are two distinct XML files following the SCML schema definition, represented by the Scan and Station classes. The Scan class contains the scan description and information on all devices directly used in scan modules, while the Station class represents the XML file loaded by the engine when executing a scan that contains information on all devices available for a given measurement station. Both, Scan and Station, share a lot of functionality that is available from and defined in this interface.

version

Schema version of the SCML file.

Type:

str

Examples

Being an interface, this class is not meant to be used directly, but only by using one of the classes implementing it: Scan and Station.

load(filename='')

Load contents of an SCML file.

Parameters:

filename (str) – Name of the file to load.

class evedata.scan.boundaries.scan.Scan

Bases: File, File

High-level Python object representation of a scan description.

This class serves as facade to the entire evedata.scan subpackage and provides a rather high-level representation of the contents of the scan description stored in an individual SCML file.

version

Schema version of the SCML file represented by this class.

Type:

str

location

Name of the measurement station the scan was executed at.

Type:

str

scan

Representation of all information available for the scan.

Type:

evedata.scan.entities.scan.Scan

Raises:

exception – Short description when and why raised

Examples

Loading the scan description contained in an eveH5 data file of a measurement may be as simple as:

scan = Scan()
scan.extract(filename="my_measurement_file.h5")

If you are ever in the situation to load a separate SCML file, this is possible as well:

scan = Scan()
scan.load(filename="my_scan_description.scml")

In most cases, however, you need not be concerned with loading the SCML file at all, as the EveFile and Measurement classes will take care of that for you.

extract(filename='')

Extract SCML from the user part of an eveH5 file.

Parameters:

filename (str) – Name of the file to load.

A short description of the way the scan description (SCML) is contained in eveH5 files:

  • Generally, the SCML is located at the beginning of the file, therefore interpreted by HDF5 as “user data”.

  • The first eight bytes of an eveH5 file containing the SCML read “EVEcSCML”.

  • The next four bytes are the length of the compressed SCML file (encoded as big-endian unsigned integer, “!L”).

  • The next four bytes are the length of the uncompressed SCML file (encoded as big-endian unsigned integer, “!L”) - an information that is not needed here.

  • The next (length compressed SCML file) bytes are the ZIP-compressed contents of the actual SCML file.

  • As a user data block in HDF5 files needs to be 2^n bytes long, the remaining space to the next power of 2 is padded with zeros.

load(filename='')

Load contents of an SCML file.

Parameters:

filename (str) – Name of the file to load.