# Protocol

class Protocol(apparatus: mechwolf.core.apparatus.Apparatus, name: Union[str, NoneType] = None, description: Union[str, NoneType] = None)

A set of procedures for an apparatus.

A protocol is defined as a list of procedures, atomic steps for the individual active components of an apparatus.

# Arguments

• apparatus: The apparatus for which the protocol is being defined.
• name: The name of the protocol. Defaults to "Protocol_X" where X is protocol count.
• description: A longer description of the protocol.

# Attributes

• apparatus: The apparatus for which the protocol is being defined.
• description: A longer description of the protocol.
• is_executing: Whether the protocol is executing.
• name: The name of the protocol. Defaults to "Protocol_X" where X is protocol count.
• procedures: A list of the procedures for the protocol in which each procedure is a dict.
• was_executed: Whether the protocol was executed.

# add

def add(self, component: Union[mechwolf.components.stdlib.active_component.ActiveComponent, Iterable[mechwolf.components.stdlib.active_component.ActiveComponent]], start=None, stop=None, duration=None, **kwargs)

Adds a procedure to the protocol.

# Arguments

• component_added: The component(s) for which the procedure being added. If an interable, all components will have the same parameters.
• start: The start time of the procedure relative to the start of the protocol, such as "5 seconds". May also be a datetime.timedelta. Defaults to "0 seconds", i.e. the beginning of the protocol.
• stop: The stop time of the procedure relative to the start of the protocol, such as "30 seconds". May also be a datetime.timedelta. May not be given if duration is used. duration: The duration of the procedure, such as "1 hour". May not be used if stop is used.
• **kwargs: The state of the component for the procedure.

# Raises

• TypeError: A component is not of the correct type (i.e. a Component object)
• ValueError: An error occurred when attempting to parse the kwargs.
• RuntimeError: Stop time of procedure is unable to be determined or invalid component.

# execute

def execute(self, dry_run: Union[bool, int] = False, verbosity: str = 'info', confirm: bool = False, strict: bool = True, log_file: Union[str, bool, os.PathLike, NoneType] = True, log_file_verbosity: Union[str, NoneType] = 'trace', log_file_compression: Union[str, NoneType] = None, data_file: Union[str, bool, os.PathLike, NoneType] = True) -> mechwolf.core.experiment.Experiment

Executes the procedure.

# Arguments

• confirm: Whether to bypass the manual confirmation message before execution.
• dry_run: Whether to simulate the experiment or actually perform it. Defaults to False, which means executing the protocol on real hardware. If an integer greater than zero, the dry run will execute at that many times speed.
• strict: Whether to stop execution upon encountering any errors. If False, errors will be noted but ignored.
• verbosity: The level of logging verbosity. One of "critical", "error", "warning", "success", "info", "debug", or "trace" in descending order of severity. "debug" and (especially) "trace" are not meant to be used regularly, as they generate significant amounts of usually useless information. However, these verbosity levels are useful for tracing where exactly a bug was generated, especially if no error message was thrown.
• log_file: The file to write the logs to during execution. If True, the data will be written to a file in ~/.mechwolf with the filename {experiment_id}.log.jsonl. If falsey, no logs will be written to the file.
• log_file_verbosity: How verbose the logs in file should be. By default, it is "trace", which is the most verbose logging available. If None, it will use the same level as verbosity.
• log_file_compression: Whether to compress the log file after the experiment.
• data_file: The file to write the experimental data to during execution. If True, the data will be written to a file in ~/.mechwolf with the filename {experiment_id}.data.jsonl. If falsey, no data will be written to the file.

# Returns

• An Experiment object. In a Jupyter notebook, the object yields an interactive visualization. If protocol execution fails for any reason that does not raise an error, the return type is None.

# Raises

• RuntimeError: When attempting to execute a protocol on invalid components.

# json

def json(self) -> Union[str, IPython.lib.display.Code]

Outputs the uncompiled procedures to JSON.

# Returns

• JSON of the protocol. When in Jupyter, this string is wrapped in a IPython.display.Code object for nice syntax highlighting.

# to_dict

def to_dict(self)

None

# to_list

def to_list(self)

None

# visualize

def visualize(self, legend: bool = False, width=500, renderer: str = 'notebook')

Generates a Gantt plot visualization of the protocol.

# Arguments

• legend: Whether to show a legend.
• renderer: Which renderer to use. Defaults to "notebook" but can also be "jupyterlab", or "nteract", depending on the development environment. If not in a Jupyter Notebook, this argument is ignored.
• width: The width of the Gantt chart.

# Returns

• An interactive visualization of the protocol.

# yaml

def yaml(self) -> Union[str, IPython.lib.display.Code]

Outputs the uncompiled procedures to YAML.

Internally, this is a conversion of the output of Protocol.json for the purpose of enhanced human readability.

# Returns

• YAML of the procedure list. When in Jupyter, this string is wrapped in an IPython.display.Code object for nice syntax highlighting.