gufe.protocols.protocolunit

The ProtocolUnit class should be subclassed for all units to be used as part of a ProtocolDAG.

Classes

Context(scratch, shared[, stderr, stdout])

Data class for passing around execution context components to ProtocolUnit._execute.

ProtocolUnit(*[, name])

A unit of work within a ProtocolDAG.

ProtocolUnitFailure(*[, name, stderr, ...])

Failed result of a single ProtocolUnit execution.

ProtocolUnitResult(*[, name, stderr, ...])

Successful result of a single ProtocolUnit execution.
class gufe.protocols.protocolunit.Context(scratch: Path, shared: Path, stderr: Path | None = None, stdout: Path | None = None)

Data class for passing around execution context components to ProtocolUnit._execute.

scratch: Path
shared: Path
stderr: Path | None = None
stdout: Path | None = None
class gufe.protocols.protocolunit.ProtocolUnitResult(*, name: str | None = None, source_key: GufeKey, inputs: dict[str, Any], outputs: dict[str, Any], stderr: dict[str, bytes] | None = None, stdout: dict[str, bytes] | None = None, start_time: datetime.datetime | None = None, end_time: datetime.datetime | None = None)

Successful result of a single ProtocolUnit execution.

Parameters:

  • name (Optional[str]) – Name of the ProtocolUnit that produced this ProtocolUnitResult.

  • source_key (GufeKey) – Key of the ProtocolUnit that produced this ProtocolUnitResult

  • inputs (Dict[str, Any]) – Inputs to the ProtocolUnit that produced this ProtocolUnitResult. Includes any ProtocolUnitResult`s this `ProtocolUnitResult is dependent on.

  • outputs (Dict[str, Any]) – Outputs from the ProtocolUnit._execute that generated this ProtocolUnitResult.

  • stderr (dict[str, bytes] | None) – stderr output captured during execution of the ProtocolUnit. The keys are the filenames given to the captured output and the values are the bytes contained within those files after execution.

  • stdout (dict[str, bytes] | None) – stdout output captured during execution of the ProtocolUnit. The keys are the filenames given to the captured output and the values are the bytes contained within those files after execution.

  • start_time (datetime.datetime) – The start and end time for executing this Unit

  • end_time (datetime.datetime) – The start and end time for executing this Unit

property name
property source_key
property inputs
property outputs
property stderr
property stdout
property dependencies: list[ProtocolUnitResult]

All results that this result was dependent on

static ok() → bool
property start_time: datetime | None

The time execution of this Unit began

property end_time: datetime | None

The time at which execution of this Unit finished

class gufe.protocols.protocolunit.ProtocolUnitFailure(*, name=None, source_key, inputs, outputs, stderr: dict[str, bytes] | None = None, stdout: dict[str, bytes] | None = None, _key=None, exception, traceback, start_time: datetime.datetime | None = None, end_time: datetime.datetime | None = None)

Failed result of a single ProtocolUnit execution.

Parameters:

  • name (Optional[str]) – Name of the ProtocolUnit that produced this ProtocolUnitResult.

  • source_key (GufeKey) – Key of the ProtocolUnit that produced this ProtocolUnitResult

  • inputs (Dict[str, Any]) – Inputs to the ProtocolUnit that produced this ProtocolUnitResult. Includes any ProtocolUnitResult this ProtocolUnitResult was dependent on.

  • outputs (Dict[str, Any]) – Outputs from the ProtocolUnit._execute that generated this ProtocolUnitResult.

  • stderr (dict[str, bytes] | None) – stderr output captured during execution of the ProtocolUnit. The keys are the filenames given to the captured output and the values are the bytes contained within those files after execution.

  • stdout (dict[str, bytes] | None) – stdout output captured during execution of the ProtocolUnit. The keys are the filenames given to the captured output and the values are the bytes contained within those files after execution.

  • exception (Tuple[str, Tuple[Any, ...]]) – A tuple giving details on the exception raised during ProtocolUnit execution. The first element gives the type of exception raised; the second element is a tuple giving the exception’s args values.

  • traceback (str) – The traceback given by the exception.

property exception: tuple[str, tuple[Any, ...]]
property traceback: str
static ok() → bool
property dependencies: list[ProtocolUnitResult]

All results that this result was dependent on

property end_time: datetime | None

The time at which execution of this Unit finished

property inputs
property name
property outputs
property source_key
property start_time: datetime | None

The time execution of this Unit began

property stderr
property stdout
class gufe.protocols.protocolunit.ProtocolUnit(*, name: str | None = None, **inputs)

A unit of work within a ProtocolDAG.

Create an instance of a ProtocolUnit.

Parameters:

  • name (str) – Custom name to give this

  • **inputs – Keyword arguments, which can include other ProtocolUnit`s on which this `ProtocolUnit is dependent. Should be either gufe objects or JSON-serializables.

property name: str | None

Optional name for the ProtocolUnit.

property inputs: dict[str, Any]

Inputs to the ProtocolUnit.

Includes any ProtocolUnit instances this ProtocolUnit depends on.

property dependencies: list[ProtocolUnit]

All units that this unit is dependent on (parents)

execute(*, context: Context, raise_error: bool = False, **inputs) → ProtocolUnitResult | ProtocolUnitFailure

Given ProtocolUnitResult s from dependencies, execute this ProtocolUnit.

Parameters:

  • context (Context) – Execution context for this ProtocolUnit; includes e.g. shared and scratch Path s.

  • raise_error (bool) – If True, raise any errors instead of catching and returning a ProtocolUnitFailure default False

  • **inputs – Keyword arguments giving the named inputs to _execute. These can include ProtocolUnitResult objects from ProtocolUnit objects this unit is dependent on.