DECTRIS reference

class libertem_live.detectors.dectris.DectrisAcquisition(conn: DectrisDetectorConnection, nav_shape: tuple[int, ...] | None = None, frames_per_partition: int = 128, pending_aq: DectrisPendingAcquisition | None = None, controller: DectrisActiveController | None = None, hooks: Hooks | None = None)[source]

Acquisition from a DECTRIS detector. Use libertem_live.api.LiveContext.make_acquisition() to instantiate this class!

Examples

>>> with ctx.make_connection('dectris').open(
...     api_host='127.0.0.1',
...     api_port=DCU_API_PORT,
...     data_host='127.0.0.1',
...     data_port=DCU_DATA_PORT,
... ) as conn:
...     aq = ctx.make_acquisition(
...         conn=conn,
...         nav_shape=(128, 128),
...     )

Parameters:

conn – An existing DectrisDetectorConnection instance
nav_shape – The navigation shape as a tuple, for example (height, width) for a 2D STEM scan.
frames_per_partition – A tunable for configuring the feedback rate - more frames per partition means slower feedback, but less computational overhead. Might need to be tuned to adapt to the dwell time.
pending_aq – A pending acquisition in passive mode, obtained from DectrisDetectorConnection.wait_for_acquisition(). If this is not provided, it’s assumed that the detector should be actively armed and triggered.
controller – A DectrisActiveController instance, which can be obtained from DectrisDetectorConnection.get_active_controller(). You can pass additional parameters to DectrisDetectorConnection.get_active_controller() in order to change detector settings. If no controller is passed in, and pending_aq is also not given, then the acquisition will be started in active mode, leaving all detector settings unchanged.
hooks – Acquisition hooks to react to certain events

property array_backends: Sequence[Literal['numpy', 'numpy.matrix', 'cuda', 'cupy', 'sparse.COO', 'sparse.GCXS', 'sparse.DOK', 'scipy.sparse.coo_matrix', 'scipy.sparse.csr_matrix', 'scipy.sparse.csc_matrix', 'scipy.sparse.coo_array', 'scipy.sparse.csr_array', 'scipy.sparse.csc_array', 'cupyx.scipy.sparse.coo_matrix', 'cupyx.scipy.sparse.csr_matrix', 'cupyx.scipy.sparse.csc_matrix']]

The array backends the dataset can return data as.

Defaults to only NumPy arrays

New in version 0.11.0.

property dtype: The “native” data type (either one matching the data on disk, or one that is closest)

get_api_client() → DEigerClient[source]: Get an API client, which can be used to configure the detector.

get_detector_config() → DetectorConfig[source]: Get (very limited subset of) detector configuration

property shape: The shape of the DataSet, as it makes sense for the application domain (for example, 4D for pixelated STEM)

class libertem_live.detectors.dectris.DectrisConnectionBuilder[source]

Builder class that can construct DectrisDetectorConnection instances.

Use the open() method to create a connection.

open(api_host: str, api_port: int, data_host: str, data_port: int, buffer_size: int = 2048, bytes_per_frame: int | None = None, frame_stack_size: int = 24, huge_pages: bool = False) → DectrisDetectorConnection[source]

Connect to a DECTRIS DCU, both for detector configuration and for accessing the data stream.

Parameters:

api_host – The hostname or IP address of the DECTRIS DCU for the REST API
api_port – The port of the REST API
data_host – The hostname or IP address of the DECTRIS DCU for the zeromq data stream
data_port – The zeromq port to use
buffer_size – The total receive buffer in MiB that is used to stream data to worker processes.
bytes_per_frame –
Roughtly how many bytes should be reserved per frame

If this is None, a rough guess will be calculated from the detector size. You can check the bytes_per_frame property to see if the guess matches reality, and adjust this parameter if it doesn’t.
frame_stack_size – How many frames should be stacked together and put into a shared memory slot? If this is chosen too small, it might cause slowdowns because of having to handle many small objects; if it is chosen too large, it again may be slower due to having to split frame stacks more often in boundary conditions. When in doubt, leave this value at it’s default.
huge_pages –
Set to True to allocate shared memory in huge pages. This can improve performance by reducing the page fault cost. Currently only available on Linux. Enabling this requires reserving huge pages, either at system start, or before connecting.

For example, to reserve 10000 huge pages, you can run:

echo 10000 | sudo tee /proc/sys/vm/nr_hugepages

See also the hugeadm utility, especially hugeadm --explain can be useful to check your configuration.

class libertem_live.detectors.dectris.DectrisDetectorConnection(api_host: str, api_port: int, data_host: str, data_port: int, buffer_size: int = 2048, bytes_per_frame: int | None = None, frame_stack_size: int = 24, huge_pages: bool = False)[source]

Connection to a DECTRIS DCU, both for detector configuration and for accessing the data stream.

Please see libertem_live.detectors.dectris.DectrisConnectionBuilder for a description of the parameters, and use libertem_live.api.LiveContext.make_connection() to create a connection.

Examples

>>> from libertem_live.api import LiveContext
>>> with LiveContext() as ctx, ctx.make_connection('dectris').open(
...     api_host='127.0.0.1',
...     api_port=DCU_API_PORT,
...     data_host='127.0.0.1',
...     data_port=DCU_DATA_PORT,
... ) as conn:
...     print("connected!")
connected!

close()[source]

Close the connection. It’s important to call this function once you don’t need the connection anymore, as an open connection might interfere with other software using the detector.

If possible, use this object as a context manager instead, using a with-statement.

Create a controller object that knows about the detector settings to apply when the acquisition starts.

Any settings left out or set to None will be left unchanged.

In general, please consult your detector manual for details!

Parameters:

trigger_mode – One of ‘exte’, ‘inte’, ‘exts’, ‘ints’, as defined in the manual.
count_time – Exposure time per image in seconds
frame_time – The interval between start of image acquisitions in seconds. Must be greater than or equal to count_time.
roi_mode –
Configure ROI mode. Set to the string ‘disabled’ to disable ROI mode. The allowed values depend on the detector.

For example, for ARINA, to bin to frames of 96x96, set roi_mode to ‘merge2x2’.

For QUADRO and other supported detectors, to select a subset of lines as active, set roi_mode to ‘lines’. Then, additionally set roi_y_size to one of the supported values.
roi_bit_depth – For QUADRO, this can be either 8 or 16. Setting to 8 bit is required to reach the highest frame rates.
roi_y_size –
Select a subset of lines. For QUADRO, this has to be between 2 and 256, inclusive. Note that the image size is then two times this value, plus two pixels, for example if you select 64 lines, it will result in images with 130 pixels height and the full width.

Starting with DECTRIS software version “release-2022.1”, this is the total height instead, so any even number between 4 and 512, inclusive.
enable_file_writing – Enable file writing on the DCU. If set to False, explicitly disable file writing.
compression – The type of compression to enable. Can be, for example, ‘bslz4’, or ‘lz4’.
name_pattern – If given, the name pattern is set to the given string. Only set if file writing is enabled.
nimages_per_file – If file writing is enabled, split the written files such that at maximum this number of images are saved per file. The default is not to split into multiple files.
enable_corrections – Let LiberTEM automatically correct defect pixels, downloading the pixel mask from the detector configuration.
mask_to_zero –
When set to True, the bad pixels that are configured in the detector software are set to zero instead of MAX_INT. This is using the detector-internal correction facilities, not those of LiberTEM.

Needs a current version of the DECTRIS software to work correctly (at least “release-2022.1.2”).

wait_for_acquisition(timeout: float | None = None) → DectrisPendingAcquisition | None[source]

Wait for at most timeout seconds for an acquisition to start. This does not perform any triggering itself and expects something external to arm and trigger the acquisition.

Once the detector is armed, this function returns a PendingAcquisition, which can be converted to a full Acquisition object using libertem_live.api.LiveContext.make_acquisition().

The function returns None on timeout.

Parameters:: timeout – Timeout in seconds. If None, wait indefinitely.

Examples

>>> with ctx.make_connection('dectris').open(
...     api_host='127.0.0.1',
...     api_port=DCU_API_PORT,
...     data_host='127.0.0.1',
...     data_port=DCU_DATA_PORT,
... ) as conn:
...     # NOTE: this is the part that is usually done by an external software,
...     # but we include it here to have a running example:
...     ec = conn.get_api_client()
...     arm_response = ec.sendDetectorCommand('arm')
...
...     pending_aq = conn.wait_for_acquisition(timeout=1)
...     assert pending_aq is not None, "timeout"
...
...     aq = ctx.make_acquisition(
...         conn=conn,
...         nav_shape=(32, 32),
...         pending_aq=pending_aq,
...     )
...     ctx.run_udf(dataset=aq, udf=SumUDF())
{'intensity': ...}

class libertem_live.detectors.dectris.DectrisPendingAcquisition(detector_config: libertem_dectris.DetectorConfig, series: int)[source]

property nimages: int: The total number of images that are expected for this acquisition