nomad_camels.bluesky_handling package

Submodules

nomad_camels.bluesky_handling.EpicsFieldSignal module

nomad_camels.bluesky_handling.TriggerEpicsSignalRO module

class nomad_camels.bluesky_handling.TriggerEpicsSignalRO.TriggerEpicsSignalRO(read_pv, *, timeout=10, string=False, name=None, no_mdel=False, **kwargs)

Bases: EpicsSignalRO

Subclass that implements a simple ‘timed’ reading when called via bluesky’s ‘trigger_and_read’. Note that each PV that shall be read via this class also needs a second PV with the same name+:trig. That PV should provide a FLNK to the original PV.

callback_method(**kwargs)

If there is a status object from the trigger-method, it will be set to finished.

Parameters:

**kwargs

subscriptions: ClassVar[FrozenSet[str]] = frozenset({'meta', 'value'})
trigger()

Returns a status object that will be set to finished, when the PV-value is updated. Sets the trigger-PV to 1, thus triggering the process of the original PV.

nomad_camels.bluesky_handling.builder_helper_functions module

This module provides functions that are often used when building a protocol. It is not inside the protocol_builder module, since these functions are also called by the classes of the single protocol-steps.

nomad_camels.bluesky_handling.builder_helper_functions.flyer_creator(flyer_data, func_name='create_flyers')

Creates the create_flyers function for the protocol if asynchronous acquisition is used.

Parameters:

  • flyer_data (list[dict]) – A list of dictionaries with all information for the flyers.

  • func_name (str) – (Default value = ‘create_flyers’) The name of the function in the protocol-script.

Returns:

The string containing the function for the protocol-script.

Return type:

flyer_string

nomad_camels.bluesky_handling.builder_helper_functions.get_plot_add_string(name, stream, subprotocol=False, n_tabs=1)

This function generates the necessary lines for the “steps_add_main” function in the protocol-script to open the plots of a sub-step of the protocol.

Parameters:

  • name (str) – The name of the calling protocol-step.

  • stream (str) – The bluesky-stream on which the plots should react.

  • subprotocol – (Default value = False) If True, the create_plots function will be called from the subprotocol’s module.

Returns:

The string to be added.

Return type:

add_main_string

nomad_camels.bluesky_handling.builder_helper_functions.plot_creator(plot_data, func_name='create_plots', multi_stream=False, plot_is_box=False, box_names='', skip_box=True)

Creates the create_plots function for the protocol.

Parameters:

  • plot_data (list[Plot_Info]) – A list of Plot_Info objects with all information for the plots.

  • func_name (str) – (Default value = ‘create_plots’) The name of the function in the protocol-script.

  • multi_stream – (Default value = False) Passes the multi_stream keyword to the plot-widgets. This is used if the plot should not only react to the stream that’s specified exactly.

Returns:

  • plot_string – The string containing the function for the protocol-script.

  • plotting – True if there actually was a plot. Otherwise the function will not be created in the script at all.

nomad_camels.bluesky_handling.custom_function_signal module

class nomad_camels.bluesky_handling.custom_function_signal.Custom_Function_Signal(name, value=0.0, timestamp=None, parent=None, labels=None, kind='hinted', tolerance=None, rtolerance=None, metadata=None, cl=None, attr_name='', put_function=None, read_function=None, trigger_function=None, retry_on_error=0, error_retry_function=None, force_sequential=None)

Bases: Signal

A custom signal class that extends ophyd’s Signal by allowing the user to specify custom functions that are executed when putting, reading, or triggering the signal.

put_function

Function called when the signal’s put() method is invoked.

Type:

callable

read_function

Function called when the signal’s get() method is invoked.

Type:

callable

trigger_function

Function called when the signal’s trigger() method is invoked.

Type:

callable

retry_on_error

Number of retry attempts in case of failure when calling custom functions.

Type:

int

error_retry_function

Optional function to be called if a custom function raises an error.

Type:

callable

force_sequential

Flag to force sequential execution; if True, operations may wait for the parent.

Type:

bool

describe()

Return a description of the signal with a custom source identifier.

Returns:

A dictionary describing the signal, with the ‘source’ set to “Custom Function”.

Return type:

dict

get(**kwargs)

Read the value from the signal. If a read_function is defined, it is used to obtain the value. The function is retried upon error based on the retry_on_error setting.

This method updates the internal _readback attribute and notifies subscribers of the change.

Returns:

The value obtained from the parent get() method.

put(value, *, timestamp=None, force=False, metadata=None, **kwargs)

Write a value to the signal. If a put_function is defined, it is called to process the value. The function is retried upon error based on the retry_on_error setting.

This method first checks if a put_function is provided and if it needs the instance reference. If the put_function’s first parameter is named “_self_instance”, the instance (self) is passed. Otherwise, the function is executed without the instance.

Parameters:

  • value – The value to be written to the signal.

  • timestamp (optional) – Timestamp for the put operation.

  • force (bool, optional) – Force the put operation even if the value is the same. Defaults to False.

  • metadata (optional) – Additional metadata for the put operation.

  • **kwargs – Additional keyword arguments.

Returns:

None

read_configuration()

Read the current configuration of the signal.

If _readback is already set, that value is used; otherwise, get() is called. The returned configuration is a dictionary with the signal’s name as the key and a dictionary containing the value and timestamp.

Returns:

A dictionary in the format {signal_name: {“value”: value, “timestamp”: timestamp}}.

Return type:

dict

subscriptions: ClassVar[FrozenSet[str]] = frozenset({'meta', 'value'})
trigger()

Trigger the signal. If a trigger_function is defined, it is executed with retries upon failure.

Returns:

The result of the parent trigger() method.

class nomad_camels.bluesky_handling.custom_function_signal.Custom_Function_SignalRO(name, value=0.0, timestamp=None, parent=None, labels=None, kind='hinted', tolerance=None, rtolerance=None, metadata=None, cl=None, attr_name='', read_function=None, trigger_function=None, retry_on_error=0, error_retry_function=None, force_sequential=None)

Bases: SignalRO

A custom read-only signal class that extends ophyd’s SignalRO by allowing the user to specify functions that are executed when reading or triggering the signal.

read_function

Function called when the signal’s get() method is invoked.

Type:

callable

trigger_function

Function called when the signal’s trigger() method is invoked.

Type:

callable

retry_on_error

Number of retry attempts in case of failure when calling custom functions.

Type:

int

error_retry_function

Optional function to be called if a custom function raises an error.

Type:

callable

force_sequential

Flag to force sequential execution; if True, operations may wait for the parent.

Type:

bool

describe()

Return a description of the read-only signal with a custom source identifier.

Returns:

A dictionary describing the signal, with the ‘source’ set to “Custom Function”.

Return type:

dict

get(**kwargs)

Read the value from the read-only signal. If a read_function is defined, it is used to obtain the value. The function is retried upon error based on the retry_on_error setting.

The internal _readback attribute is updated and subscribers are notified of the change.

Returns:

The value obtained from the parent get() method.

read_configuration()

Read the current configuration of the read-only signal.

If _readback is set and the signal is not a configuration signal with an associated read_function, the existing value is used; otherwise, get() is called to obtain the value. The returned configuration is a dictionary with the signal’s name as the key and a dictionary containing the value and timestamp.

Returns:

A dictionary in the format {signal_name: {“value”: value, “timestamp”: timestamp}}.

Return type:

dict

subscriptions: ClassVar[FrozenSet[str]] = frozenset({'meta', 'value'})
trigger()

Trigger the read-only signal. If a trigger_function is defined, it is executed with retries upon failure.

Returns:

The result of the parent trigger() method.

class nomad_camels.bluesky_handling.custom_function_signal.Sequential_Device(force_sequential=False, currently_reading=False, *args, **kwargs)

Bases: Device

A custom device class that supports sequential operations. It provides flags to force sequential execution and to indicate whether a reading operation is in progress.

component_names = ()
subscriptions: ClassVar[FrozenSet[str]] = frozenset({'acq_done'})
nomad_camels.bluesky_handling.custom_function_signal.retry_function(func, retries: int, *args, error_retry_function=None, parent=None, **kwargs)

Attempt to execute a function multiple times until it succeeds or the maximum number of retries is reached.

If a parent object is provided and it is currently reading (i.e., parent.currently_reading is True), the function waits until the parent is no longer reading before executing.

Parameters:

  • func (callable) – The function to be executed.

  • retries (int) – Maximum number of retries upon failure.

  • *args – Variable length argument list for the function.

  • error_retry_function (callable, optional) – Function to call when an error occurs. Defaults to None.

  • parent (object, optional) – An object (e.g., an instrument) that may enforce sequential access. Defaults to None.

  • **kwargs – Arbitrary keyword arguments for the function.

Returns:

The result of the function call if successful.

Raises:

Exception – If the function fails after the specified number of retries, an exception is raised with details of the last and first encountered exceptions.

nomad_camels.bluesky_handling.evaluation_helper module

class nomad_camels.bluesky_handling.evaluation_helper.Evaluator(*args, namespace=None, **kwargs)

Bases: CallbackBase

This class can be used to evaluate strings with names known in bluesky at any point, as well inside the run itself. It provides methods to evaluate strings and update the namespace dynamically.

eval(eval_str: str, do_not_reraise=False)

Evaluates the string within the given namespace. Checks if the namespace is up to date before evaluating.

Parameters:

  • eval_str (str) – The string to be evaluated.

  • do_not_reraise (bool, optional) – If True, exceptions are not re-raised, and NaN is returned instead.

Returns:

The evaluated value.

Return type:

Value

eval_string(eval_str: str) → str

Evaluates the given string through the provided namespace to another string. The string is split at quotation marks and the parts of the string are tried to be evaluated. If that is not possible, they are just added back to the string as is. Checks if the namespace is up to date before evaluating.

Parameters:

eval_str (str) – The string to be evaluated.

Returns:

The evaluated string.

Return type:

str

Raises:

ValueError – If there is a bigger problem during evaluation.

event(doc)

Overwrites the event method to add the variable ‘time’ to the namespace and update the last_update attribute for checking before evaluation. See bluesky’s documentation for more information.

Parameters:

doc (dict) – The event document provided by bluesky.

is_to_date(t: float) → bool

Compares whether the given t is the same as the Evaluator’s last_update.

Parameters:

t (float) – The time to compare with the last update time.

Returns:

True if the given time is the same as the last update time, False otherwise.

Return type:

bool

start(doc)

Overwrites the start method to add the variable ‘StartTime’ to the namespace. See bluesky’s documentation for more information.

Parameters:

doc (dict) – The start document provided by bluesky.

update_namespace()

Updates the namespace with the add_namespace dictionary. Since this is exactly the given namespace from __init__, it can be easily updated from outside the class. Also, the variable ‘ElapsedTime’ is added to the namespace.

This method ensures that the namespace is always up-to-date with the latest additions and changes.

nomad_camels.bluesky_handling.evaluation_helper.get_eval(eval_str: str, namespace: dict, evaluator: Evaluator = None)

Evaluates the given string within the given namespace. Most functionality is taken from bluesky.utils.call_or_eval_one.

Parameters:

  • eval_str (str) – The string to be evaluated.

  • namespace (dict) – The namespace in which to evaluate the string.

  • evaluator (Evaluator, optional) – The Evaluator instance to use for tracking raised exceptions.

Returns:

The evaluated value.

Return type:

Value

Raises:

ValueError – If the string cannot be found in the namespace or evaluated as a Python expression.

nomad_camels.bluesky_handling.flyer_interface module

Module for Asynchronous Data Acquisition from Detectors

This module provides classes for managing asynchronous data collection from multiple detectors using a threaded approach. The primary class is CAMELS_Flyer.

class nomad_camels.bluesky_handling.flyer_interface.CAMELS_Flyer(name, detectors, read_time, can_fail, **kwargs)

Bases: object

Class that provides asynchronous acquisition during the run of protocol.

Parameters:

  • name (str) – Name of the flyer and its data stream.

  • detectors (list) – List of the detectors to be used for data collection.

  • read_time (float) – Time interval (in seconds) between each reading.

  • can_fail (list[bool]) – If true, a failed reading of the detector does not throw an error and a NaN value is used instead.

  • **kwargs (dict) – Additional keyword arguments (not in use).

name

Flyer name.

Type:

str

detectors

List of detectors.

Type:

list

can_fail

Fail flag for each detector.

Type:

list or bool

read_time

Read interval in seconds.

Type:

float

mutex

Mutex for thread-safe operations.

Type:

QMutex

_data

Deque to store collected data events.

Type:

deque

_completion_status

Status of the data collection process.

Type:

DeviceStatus or None

flyer_thread

Thread that performs the periodic reading from detectors.

Type:

Flyer_Thread

collect()

Retrieve the collected data events in a thread-safe manner. Clears the data deque.

Yields:

list – List of collected data events.

complete()

Stop the data collection process.

Raises:

RuntimeError – If no collection is currently in progress.

Returns:

Status object indicating the completion status of the data collection.

Return type:

DeviceStatus

describe_collect()

Generate a description of the detectors for data collection.

Returns:

Dictionary with flyer name as key and aggregated detector descriptions as value.

Return type:

dict

kickoff()

Start the data collection process.

Raises:

RuntimeError – If a collection is already in progress.

Returns:

Status object indicating that the kickoff is complete.

Return type:

DeviceStatus

propagate_exceptions(ex)

Raise an exception from the flyer thread in the main thread.

class nomad_camels.bluesky_handling.flyer_interface.Flyer_Thread(parent=None, detectors=None, can_fail=None, read_time=1, flyer_name='camels_flyer', data_object=None, mutex=None)

Bases: QThread

Thread class for periodically reading data asynchronously during a protocol.

Parameters:

  • parent (QObject, optional) – Parent object (default is None).

  • detectors (list, optional) – List of detectors to trigger and read from (default is None, giving an empty list).

  • can_fail (list[bool], optional) – Flag for each detector indicating if a failed reading should be ignored (default None defaults to all False).

  • read_time (float, optional) – Time interval (in seconds) between each read (default is 1).

  • flyer_name (str, optional) – Name identifier for the flyer, which also names the resulting data stream (default is “camels_flyer”).

  • data_object (deque, optional) – Deque to store the collected events (default is None).

  • mutex (QMutex, optional) – Mutex for ensuring thread-safe operations (default is None).

timer

Timer to schedule periodic readings.

Type:

QTimer or None

keep_running

Flag to control the continuous operation of the thread.

Type:

bool

mutex

Mutex for synchronizing access to shared data.

Type:

QMutex

_currently_reading

Flag indicating if a read operation is currently in progress.

Type:

bool

exception_signal
run()

Run the thread event loop with a timer that periodically triggers data reading.

staticMetaObject = PySide6.QtCore.QMetaObject("Flyer_Thread" inherits "QThread": Methods:   #12 type=Signal, signature=exception_signal(PyObject), parameters=PyObject )

nomad_camels.bluesky_handling.helper_functions module

Functions to be used in protocols.

The functions in this module may be used inside a protocol. It is much simpler to use these than writing them as a string into the protocol-file.

class nomad_camels.bluesky_handling.helper_functions.BoxHelper

Bases: QWidget

Helper-class to start the execution of Prompts and other boxes from within the protocol.

executor
staticMetaObject = PySide6.QtCore.QMetaObject("BoxHelper" inherits "QWidget": Methods:   #33 type=Signal, signature=executor() )
class nomad_camels.bluesky_handling.helper_functions.Commenting_Box(parent=None)

Bases: QWidget

A widget to add comments to the protocol.

closeEvent(self, event: PySide6.QtGui.QCloseEvent, /) → None
closing
finish_comment()

Sets the flag _is_finished to True.

get_metadata()

Get the text of the comment.

staticMetaObject = PySide6.QtCore.QMetaObject("Commenting_Box" inherits "QWidget": Methods:   #33 type=Signal, signature=closing() )
class nomad_camels.bluesky_handling.helper_functions.Prompt_Box(icon='', text='', title='', parent=None, abortable=False)

Bases: QMessageBox

A subclass of QMessageBox that is used in the prompt-step. The protocol is paused until self.done_flag is True.

Parameters:

  • icon (str) – If ‘Error’, the QMessagebox.Critical icon is displayed, if ‘Warning’, then QMessagebox.Warning is used, otherwise QMessagebox.Information.

  • text (str) – The text to be displayed by the prompt.

  • title (str) – The window-title of the prompt.

abort_action()

If the abort button is clicked, the protocol is stopped.

set_done()

Sets self.done_flag to True.

start_execution()

Sets self.done_flag to False and starts self.exec().

staticMetaObject = PySide6.QtCore.QMetaObject("Prompt_Box" inherits "QMessageBox": )
class nomad_camels.bluesky_handling.helper_functions.TimestampTextEdit(parent=None)

Bases: QTextEdit

insertTimestamp()

Inserts the current timestamp followed by a space at the current cursor position. The timestamp is in ISO 8601 format (e.g. “2025-02-05T14:30:00”).

keyPressEvent(self, e: PySide6.QtGui.QKeyEvent, /) → None
staticMetaObject = PySide6.QtCore.QMetaObject("TimestampTextEdit" inherits "QTextEdit": )
class nomad_camels.bluesky_handling.helper_functions.Value_Box(text='', title='', variables=None, channels=None, free_variables=False, free_channels=False, parent=None, devs=None, comboboxes=None)

Bases: QDialog

Dialog to set variables or channels at runtime of a protocol.

Parameters:

  • text (str) – A text to be displayed with the box.

  • title (str) – The window title of the box.

  • variables (list, default: None) – The variables that should be set by the user. A QLineEdit will be provided for each of the variables.

  • channels (list, default: None) – The channels that should be set by the user. A QLineEdit will be provided for each of the channels.

  • free_variables (bool, default: False) – Whether the user is allowed to freely set any variables.

  • free_channels (bool, default: False) – Whether the user is allowed to freely set any channels.

  • devs (dict, default: None) – Dictionary of the available devices. Only needed, if free_channels is True, to provide the available channels.

accept() → None

Reads all the values to be set to channels / variables and saves them in self.set_channels and self.set_variables respectively, then sets self.done_flag to True, allowing the protocol to go on and accepts the dialog.

reject() → None

Sets self.done_flag to True, allowing the protocol to go on before rejecting the dialog.

start_execution()

Sets self.done_flag to False and starts self.exec().

staticMetaObject = PySide6.QtCore.QMetaObject("Value_Box" inherits "QDialog": )
class nomad_camels.bluesky_handling.helper_functions.Value_Setter(parent=None)

Bases: QWidget

A widget to set a value and a wait-time for a waiting bar.

hide_signal
set_signal
set_start_time(start_time)

Set the start time for the waiting bar.

set_wait_time(wait_time)

Set the wait time for the waiting bar.

staticMetaObject = PySide6.QtCore.QMetaObject("Value_Setter" inherits "QWidget": Methods:   #33 type=Signal, signature=set_signal(double), parameters=double   #34 type=Signal, signature=hide_signal() )
update_timer()

Update the timer of the waiting bar.

class nomad_camels.bluesky_handling.helper_functions.Waiting_Bar(parent=None, title='', skipable=True, with_timer=False, display_bar=True, plot=None)

Bases: QWidget

A widget to show a waiting bar.

Used in the wait step with a progress bar or also to wait for a condition and display the list plot of the condition.

Parameters:

  • parent (QWidget) – The parent widget.

  • title (str) – The title of the waiting bar.

  • skipable (bool) – (Default value = True) Whether the waiting bar can be skipped and shows a skip button.

  • with_timer (bool) – (Default value = False) Whether the waiting bar has a timer.

  • display_bar (bool) – (Default value = True) Whether the waiting bar should be displayed.

  • plot (QWidget, optional) – A plot to be displayed together with the waiting bar.

setValue(value)

Set the value of the progress bar.

skipping()

Set the skip flag to True and hide the waiting bar.

start_execution()

Sets self.done_flag to False and starts self.exec().

staticMetaObject = PySide6.QtCore.QMetaObject("Waiting_Bar" inherits "QWidget": )
nomad_camels.bluesky_handling.helper_functions.clear_plots(plots, stream='primary')

Clears all given plots if they correspond to the given stream.

Parameters:

  • plots (list) – List of the plots to be cleared.

  • stream (str) – (Default value = ‘primary’) The stream to which the plots that should be cleared correspond.

nomad_camels.bluesky_handling.helper_functions.create_venv_run_file_delete_venv(packages, script_to_run)

Create a virtual environment, install the specified packages in it, run the specified Python script, and then delete the virtual environment.

nomad_camels.bluesky_handling.helper_functions.evaluate_python_file_output(stdout, namespace)

Evaluates the stdout of a Python file execution and writes the returned key value pairs to the namespace, so CAMELS can access their values

nomad_camels.bluesky_handling.helper_functions.export_function(runs, save_path, do_export, new_file_each=True, export_csv=False, export_json=False, plot_data=None, do_nexus_output=True)

Export the given runs to the given path.

Parameters:

  • runs (list[databroker.core.BlueskyRun]) – The runs to be exported.

  • save_path (str) – The path where the files should be saved.

  • do_export (bool) – Whether the runs should be exported.

  • new_file_each (bool, optional) – (Default value = True) Whether a new file should be created for each run. If True, the files are padded with the start-time of the run. Ignored if do_export is False.

  • export_csv (bool, optional) – (Default value = False) Whether the data should be exported to a csv file.

  • export_json (bool, optional) – (Default value = False) Whether the metadata should be exported to a json file.

  • plot_data (dict, optional) – (Default value = None) The data to be plotted.

nomad_camels.bluesky_handling.helper_functions.get_channels(dev)

Goes through the components of the given ophyd device and returns all that are not read-only and not config.

Parameters:

dev (ophyd.Device) – The device that is checked for output channels.

Returns:

channels – The keys are the channels in CAMELS-style. The values are [dev.name, <name_of_the_component>].

Return type:

dict

nomad_camels.bluesky_handling.helper_functions.get_fit_results(fits, namespace, yielding=False, stream='primary')

Updates and reads all the fits that correspond to the given stream and resets the fits in the end.

Parameters:

  • fits (dict) – Dictionary of all the fits to take into account.

  • namespace (dict) – Namespace dictionary where to write the fit results.

  • yielding (bool, optional) – (Default value = False) If True, the fits will be triggered and updated.

  • stream (str, optional) – (Default value = ‘primary’) The stream on which the regarded fits should run. Only the fits which have stream_name equal to stream will be used.

nomad_camels.bluesky_handling.helper_functions.get_inner_range(start, stop, points, sweep_mode, endpoint, use_distance=False, distance=nan)

Used for get_range, to make the split up ranges if doing a hysteresis sweep.

Parameters:

  • start (float, str) – The starting position for the sweep / loop.

  • stop (float, str) – The end position for the sweep / loop.

  • points (float, str) – The number of points in the range. If using min_val / max_val, points is the distance between those two.

  • sweep_mode (str) – (Default value = ‘linear’) The type how the distance between the points is calculated. If ‘linear’, they are equidistant, if ‘logarithmic’, the points between log(start) and log(stop) are equidistant, if ‘exponential’, between exp(start) and exp(stop), otherwise they are equidistant between 1/start and 1/stop.

  • endpoint (bool) – (Default value = True) Whether to include the endpoint into the range.

Return type:

An array of the calculated range.

nomad_camels.bluesky_handling.helper_functions.get_newest_file(directory)

Return the newest ‘.nxs’ or ‘.h5’ file in the specified directory, if one exists.

This function searches the given directory for files ending with the ‘.nxs’ or ‘.h5’ extension and returns the one with the most recent modification time.

If the input ‘directory’ is a file, its parent directory is used for the search. If no ‘.nxs’ or ‘.h5’ files are found, the function returns None.

Parameters:

directory (str) – The directory to search for ‘.nxs’ files. If a file path is provided, the search is performed in the file’s parent directory.

Returns:

The full path to the newest ‘.nxs’ file found in the directory, or None if no such file exists.

Return type:

str or None

nomad_camels.bluesky_handling.helper_functions.get_opyd_and_py_file_contents(classname, md, device_name)

Reads the content of the .py and _opyd.py driver files of the given instrument and adds them to the metadata dictionary. If the files are not found, it adds a corresponding message to the dictionary.

Parameters:

  • classname (class or function) – The class or function whose associated files’ contents are to be read.

  • md (dict) – The metadata dictionary where the content of the files should be added.

  • device_name (str) – The name of the device associated with the classname.

Returns:

md – The updated metadata dictionary with the content of the files added or with a message indicating that the file was not found.

Return type:

dict

Raises:

FileNotFoundError – If the .py or _opyd.py files associated with the classname are not found.

nomad_camels.bluesky_handling.helper_functions.get_range(evaluator, start, stop, points: int, min_val=nan, max_val=nan, loop_type='start - stop', sweep_mode='linear', endpoint=True, distance=nan, use_distance=False)

Helper function for steps like sweeps and the for loop.

Using the evaluator, it creates the range of iterations given the other values.

Parameters:

  • evaluator (Evaluator) – Used to evaluate the given expressions (start, stop, points, min_val, max_val).

  • start (float, str) – The starting position for the sweep / loop.

  • stop (float, str) – The end position for the sweep / loop.

  • points (int, str) – The number of points in the range. If using min_val / max_val, points is the distance between those two.

  • min_val (float, str) – (Default value = np.nan) Minimum value of the loop / sweep. Useful for hysteresis-sweeps.

  • max_val (float, str) – (Default value = np.nan) Minimum value of the loop / sweep. Useful for hysteresis-sweeps.

  • loop_type (str) – (Default value = ‘start - stop’) Possible values: ‘start - stop’, ignoring min_val and max_val ‘start - min - max - stop’ going to minimum first, then maximum ‘start - max - min - stop’, or anything not-specified.

  • sweep_mode (str) – (Default value = ‘linear’) The type how the distance between the points is calculated. If ‘linear’, they are equidistant, if ‘logarithmic’, the points between log(start) and log(stop) are equidistant, if ‘exponential’, between exp(start) and exp(stop), otherwise they are equidistant between 1/start and 1/stop.

  • endpoint (bool) – (Default value = True) Whether to include the endpoint into the range.

  • distance (float, str) – (Default value = np.nan) The distance between the points.

  • use_distance (bool) – (Default value = False) If True, the distance is used to calculate the range.

Return type:

An array of the calculated range.

nomad_camels.bluesky_handling.helper_functions.gradient_descent(max_iterations, threshold, w_init, func_text, evaluator, set_channel, read_channels, min_step, max_step, min_val, max_val, stream_name='gradient_descent', learning_rate=0.05, momentum=0.8, max_step_for_diff=None)

Helper function for the gradient descent protocol-step. It follows a simple gradient descent algorithm to find an optimum.

Parameters:

  • max_iterations (int) – The maximum number of iterations until the algorithm should stop if it did not arrive at the threshold yet.

  • threshold (float) – If the difference between two measurements is smaller than this threshold, the algorithm recognizes the value as the optimum and stops.

  • w_init (float) – The initial set-value from where the algorithm should start.

  • func_text (str) – This string is evaluated by the given evaluator to give the target function.

  • evaluator (Evaluator) – Used to evaluate the read values.

  • set_channel (ophyd.Signal) – The channel which is used for the optimization.

  • read_channels (list) – A list of all the channels which are read for the optimization.

  • min_step (float) – The minimum step size.

  • max_step (float) – The maximum step size.

  • min_val (float) – The minimum value that should be given to the set_channel.

  • max_val (float) – The maximum value that should be given to the set_channel.

  • stream_name (str) – (Default value = ‘gradient_descent’) The bluesky stream in which everything should run.

  • learning_rate (float) – (Default value = 0.05) A weight for the learning of the gradient descent. The next shift delta_w is calculated as: delta_w = -learning_rate * <current_gradient> + momentum * <last_delta_w>

  • momentum (float) – (Default value = 0.8) A momentum to keep up the last direction. The next shift delta_w is calculated as: delta_w = -learning_rate * <current_gradient> + momentum * <last_delta_w>

  • max_step_for_diff (float, None) – If none, max_step_for_diff = 10 * min_step Only if the last step was smaller than max_step_for_diff, the algorithm breaks if the threshold is reached.

Returns:

  • w_history – The history of values of set_channel

  • f_history – The history of evaluated values

nomad_camels.bluesky_handling.helper_functions.make_recoursive_plot_list_of_sub_steps(sub_dict, plot_list=None)
nomad_camels.bluesky_handling.helper_functions.read_wo_trigger(devices, grp=None, stream='primary', skip_on_exception=None)

Used if not reading by trigger_and_read, but splitting both. This function only reads, without triggering.

Parameters:

  • devices (list[ophyd.Device]) – List of the devices that should be read.

  • grp (string (or any hashable object), optional) – identifier used by ‘wait’; None by default

  • stream (string, optional) – event stream name, a convenient human-friendly identifier; default name is ‘primary’

Returns:

ret – The readings of the devices.

Return type:

dict

nomad_camels.bluesky_handling.helper_functions.saving_function(name, start_doc, path, new_file_each=True, plot_data=None, do_nexus_output=True)

Create a Serializer and return it.

The serializer is from the suitcase.nomad_camels_hdf5 module and used to save the data during a run.

Parameters:

  • name (str) – The name of the file.

  • start_doc (dict) – The start document of the run.

  • path (str) – The path where the file should be saved.

  • new_file_each (bool, optional) – (Default value = True) Whether a new file should be created for each run. If True, the files are padded with the start-time of the run.

  • plot_data (dict, optional) – (Default value = None) The data to be plotted.

Returns:

  • serializers (list) – The serializers to be used.

  • resources (list) – The resources to be used. In this case, an empty list.

nomad_camels.bluesky_handling.helper_functions.simplify_configs_dict(configs)

Returns a simplified version of the given dictionary configs by returning confs[key] = configs[key][‘value’].

Parameters:

configs (dict) – The dictionary to be simplified.

Returns:

confs – The simplified dictionary.

Return type:

dict

nomad_camels.bluesky_handling.helper_functions.trigger_and_read(devices, name='primary', skip_on_exception=None)
nomad_camels.bluesky_handling.helper_functions.trigger_multi(devices, grp=None)

Trigger multiple devices.

Parameters:

  • devices (list[ophyd.Device]) – List of the devices that should be triggered.

  • grp (string (or any hashable object), optional) – identifier used by ‘wait’; None by default

nomad_camels.bluesky_handling.loop_step_functions_api_call module

nomad_camels.bluesky_handling.loop_step_functions_api_call.evaluate_message_body(message_body, eva)

This function evaluates the values of the message_body items if the value is empty. This allows you to use variables and values that are obtained during the script execution.

nomad_camels.bluesky_handling.loop_step_functions_api_call.execute_camels_api_call(host: str, port: str, api_type: str, message_body: dict, authentication_type: str, authentication_string: str, selected_camels_function_index: int, camels_function_parameters: dict)

This function executes the CAMELS API call and returns the results.

nomad_camels.bluesky_handling.loop_step_functions_api_call.execute_generic_api_call(host: str, port: str, api_type: str, api_url: str, http_method: str, message_body: dict, authentication_type: str, authentication_string: str, http_parameters: dict)

This function executes the generic API call and returns the results.

nomad_camels.bluesky_handling.loop_step_functions_api_call.get_available_camels_api_functions(host, port, camels_function_parameters)

This function gets all the available CAMELS API functions.

nomad_camels.bluesky_handling.loop_step_functions_api_call.save_API_response_to_variable(response, namespace, protocol_step_name)

This function saves the API response to the namespace. This allows you to use the response values in the script and following protocol steps.

nomad_camels.bluesky_handling.make_catalog module

nomad_camels.bluesky_handling.make_catalog.make_yml(datapath, catalog_name='CAMELS_CATALOG', ask_restart=False)

Creates the yml file for the databroker (where it is looking for them) to configure a simple catalog for measurements with CAMELS.

Parameters:

  • datapath (str, path) – The path where the measurement data of the catalog should be saved to.

  • catalog_name (str) – (Default value = ‘CAMELS_CATALOG’) The name, the catalog should have.

nomad_camels.bluesky_handling.protocol_builder module

This module provides the functionalities needed for CAMELS to produce a running python script for its protocols.

The overview of the protocol-file looks like this:

  • import sys

  • add path_to_camels, path_to_camels/nomad_camels, path to instruments to path

  • standard_string

  • variable_string

  • device_import_string

  • plot-string

  • outer protocol string (things like plots from single steps)

  • plan-string (including the inner plan, w/o start/stop and the outer)

  • add-main-string (protocol or step specific things that should be done in the main function)

  • standard_run_string

  • further metadata (user / sample, file)

  • standard_start_string

  • set up databroker and progress bar

  • devices_string

  • standard_start_string2

  • save_string

  • final_string

  • standard_start_string3

giving shortly:

  • imports/variables…

  • def protocol_plan_inner

  • def protocol_plan

  • def create_plots

  • def steps_add_main (plots of steps, etc.)

  • def uid_collector

  • def run_protocol_main

  • def main

  • if __name__ == “__main__”

With the call chain as follows:

  • if –> main

  • main –> create_plots, steps_add_main, run_protocol_main

  • run_protocol_main –> uid_collector, protocol_plan

  • protocol_plan –> protocol_plan_inner

nomad_camels.bluesky_handling.protocol_builder.build_from_path(path, save_path='test', catalog='CAMELS_CATALOG', userdata=None, sampledata=None)

Creating the runable python file from a given protocol.

Parameters:

  • path (str, path) – The path to the protocol that should be built.

  • save_path (str, path) – (Default value = ‘test’) The path, where the data should be saved to.

  • catalog (str) – (Default value = ‘CAMELS_CATALOG’) The name of the databroker catalog that should be used.

  • userdata (dict, None) – (Default value = None) Metadata that describes the user.

  • sampledata (dict, None) – (Default value = None) Metadata that describes the sample.

nomad_camels.bluesky_handling.protocol_builder.build_protocol(protocol, file_path, save_path='test', catalog='CAMELS_CATALOG', userdata=None, sampledata=None)

Creating the runable python file from a given protocol.

Parameters:

  • protocol (main_classes.protocol_class.Measurement_Protocol) – The protocol that provides the information for the python file.

  • file_path (str, path) – The path, where the file should be saved.

  • save_path (str, path) – (Default value = ‘test’) The path, where the data should be saved to. Does NOT have a file ending. Depends on the export settings. If no NeXus export is selected uses .h5 otherwise .nxs

  • catalog (str) – (Default value = ‘CAMELS_CATALOG’) The name of the databroker catalog that should be used.

  • userdata (dict, None) – (Default value = None) Metadata that describes the user.

  • sampledata (dict, None) – (Default value = None) Metadata that describes the sample.

nomad_camels.bluesky_handling.protocol_builder.import_protocol_string(protocol_path, n_tabs=0)

Imports the subprotocol as <protocol_name>_mod.

nomad_camels.bluesky_handling.protocol_builder.make_plots_string_of_protocol(protocol_path, use_own_plots=True, data_output='sub-stream', n_tabs=1, name=None)

Creates the string to add the plots of the protocol to the main protocol.

Parameters:

  • protocol_path (str) – The path to the protocol that should be built.

  • name (str) – The name of the subprotocol. Only passed if it is a subprotocol.

Returns:

plot_string – The string that adds the plots of the protocol to the main protocol.

Return type:

str

nomad_camels.bluesky_handling.protocol_builder.sub_protocol_string(protocol_path, n_tabs=1, variables_in=None, variables_out=None, data_output='sub-stream', new_stream=None)

Overwrites the signal for the progressbar and the number of steps in the subprotocol’s module. Evaluates the input variables, then writes them into the subprotocol’s namespace and starts the subprotocol’s _plan_inner function. Afterwards the output variables are written to the main namespace.

nomad_camels.bluesky_handling.protocol_builder.user_sample_string(userdata, sampledata)

Returns the string adding userdata and sampledata to the md.

Parameters:

  • userdata (dict) – data on the user

  • sampledata (dict) – data on the sample

Returns:

u_s_string – the string containing the data and adding it to the metadata

Return type:

str

nomad_camels.bluesky_handling.run_engine_overwrite module

class nomad_camels.bluesky_handling.run_engine_overwrite.RunEngineOverwrite(md=None, *, loop=None, preprocessors=None, context_managers=None, md_validator=None, md_normalizer=None, scan_id_source=<function default_scan_id_source>, during_task=None, call_returns_result=False)

Bases: RunEngine

nomad_camels.bluesky_handling.run_engine_overwrite.get_nan_value(value)

nomad_camels.bluesky_handling.variable_reading module

class nomad_camels.bluesky_handling.variable_reading.Variable_Signal(name, value=None, timestamp=None, parent=None, labels=None, kind='normal', tolerance=None, rtolerance=None, metadata=None, cl=None, attr_name='', variables_dict=None)

Bases: SignalRO

describe()

Provide schema and meta-data for read()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns:

data_keys – The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

Return type:

OrderedDict

get()

The readback value

subscriptions: ClassVar[FrozenSet[str]] = frozenset({'meta', 'value'})

nomad_camels.bluesky_handling.visa_signal module

class nomad_camels.bluesky_handling.visa_signal.VISA_Device(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, resource_name='', read_termination='\r\n', write_termination='\r\n', baud_rate=9600, timeout=2000, retry_on_error=0, retry_on_timeout=False, **kwargs)

Bases: Device

Subclasses ophyd’s Device class. Automatically opens the specified VISA resource.

Parameters:

  • resource_name (str) – The name of the VISA-resource.

  • read_termination (str) – (Default = ‘rn’) The line termination for reading from the instrument.

  • write_termination (str) – (Default = ‘rn’) The line termination for writing to the instrument.

  • baud_rate (int) – (Default = 9600) The communication baud rate.

  • retry_on_error (int) – (Default = 0) The number of times the reading / setting should be tried again if there is an error (e.g. a VISA-IO-error). It is handed to all components that do not have a retry_on_error already defined.

component_names = ()
subscriptions: ClassVar[FrozenSet[str]] = frozenset({'acq_done'})
class nomad_camels.bluesky_handling.visa_signal.VISA_Signal(name, value=0.0, timestamp=None, parent=None, labels=None, kind='hinted', tolerance=None, rtolerance=None, metadata=None, cl=None, attr_name='', write=None, parse=None, parse_return_type=None, retry_on_error=0, write_delay=0, retry_on_timeout=False)

Bases: Signal

change_instrument(resource_name)

Changes the visa_instrument to the one with the given resource_name.

Parameters:

resource_name (str) – Name of the new instrument to be used.

describe()

Adding “VISA” as the source for the description.

put(value, *, timestamp=None, force=False, metadata=None, **kwargs)

Overwrites ophyd.Signal.put. The value is converted to a string, using self.write. If self.parse is not None, a query instead of a simple write is being performed, in that case, the value given to super().put is the returned value from the query.

subscriptions: ClassVar[FrozenSet[str]] = frozenset({'meta', 'value'})
class nomad_camels.bluesky_handling.visa_signal.VISA_Signal_RO(name, value=0.0, timestamp=None, parent=None, labels=None, kind='hinted', tolerance=None, rtolerance=None, metadata=None, cl=None, attr_name='', query='', parse=None, parse_return_type='float', retry_on_error=0, write_delay=0, retry_on_timeout=False)

Bases: SignalRO

describe()

Adding “VISA” as the source for the description.

get()

Overwrites ophyd.SignalRO.get, performing a query to the instrument. The returned string is parsed regarding self.parse and converted to the datatype specified by self.parse_return_type.

subscriptions: ClassVar[FrozenSet[str]] = frozenset({'meta', 'value'})
nomad_camels.bluesky_handling.visa_signal.close_resources()

Goes through all the opened resources and closes them.

nomad_camels.bluesky_handling.visa_signal.list_resources()

Gives the results of ResourceManager.list_resources.

nomad_camels.bluesky_handling.visa_signal.retry_query_or_write(write_text, visa_instrument, retries, just_write=False, write_delay=0, retry_on_timeout=False)
nomad_camels.bluesky_handling.visa_signal.single_query_or_write(write_text, visa_instrument, just_write=False)

nomad_camels.bluesky_handling.watchdogs module

class nomad_camels.bluesky_handling.watchdogs.Watchdog(channels=None, condition='', execute_at_condition='', read_periodic=False, read_timer=10, active=True, name='watchdog')

Bases: QObject

add_device(device_name, ophyd_device)

Subscribes the respective channels corresponding to the device

callback(value, **kwargs)
condition_met
get_definition()
get_device_list()

Goes through the cannels and returns a list of all needed devices

read()
remove_device(device_name, ophyd_device)

Unsubscribes the respective channels corresponding to the device

staticMetaObject = PySide6.QtCore.QMetaObject("Watchdog" inherits "QObject": Methods:   #4 type=Signal, signature=condition_met(QObject*), parameters=QObject* )
update_settings()
class nomad_camels.bluesky_handling.watchdogs.Watchdog_Definer(parent=None)

Bases: QDialog

accept(self, /) → None
staticMetaObject = PySide6.QtCore.QMetaObject("Watchdog_Definer" inherits "QDialog": )
update_watchdog_view()
update_watchdogs()
class nomad_camels.bluesky_handling.watchdogs.Watchdog_View(parent=None, watchdogs=None)

Bases: QWidget

get_data()
read_check_changed()
staticMetaObject = PySide6.QtCore.QMetaObject("Watchdog_View" inherits "QWidget": )
update_watchdog(watchdog_name)

Module contents