interface

alchemiscale.interface.client — client for interacting with user-facing API

class alchemiscale.interface.client.AlchemiscaleClient(api_url: str | None = None, identifier: str | None = None, key: str | None = None, cache_directory: Path | str | None = None, cache_size_limit: int = 1073741824, use_local_cache: bool = True, max_retries: int = 5, retry_base_seconds: float = 2.0, retry_max_seconds: float = 60.0, verify: bool = True)

Bases: AlchemiscaleBaseClient

Client for user interaction with API service.

action_tasks(tasks: list[ScopedKey], network: ScopedKey, weight: float | list[float] | None = None) → list[ScopedKey | None]

Action Tasks for execution via the given AlchemicalNetwork’s TaskHub.

A Task cannot be actioned:

  • to an AlchemicalNetwork in a different Scope

  • if it has any status other than ‘waiting’, ‘running’, or ‘error’

Parameters:

  • tasks – Task ScopedKeys to action for execution.

  • network – The AlchemicalNetwork ScopedKey to action the Tasks for. The Tasks will be added to the network’s associated TaskHub.

  • weight –

    Weight to be applied to the actioned Tasks. Only values between 0 and 1 are valid weights. Weights can also be provided as a list of floats with the same length as tasks.

    Setting weight to None will apply the default weight of 0.5 to newly actioned Tasks, while leaving the weights of any previously actioned Tasks unchanged. Setting weight to anything other than None will change the weights of previously actioned Tasks included in tasks.

Returns:

ScopedKeys for Tasks actioned, in the same order as given as tasks on input. If a Task couldn’t be actioned, then None will be returned in its place.

Return type:

List[Optional[ScopedKey]]

add_task_restart_patterns(network_scoped_key: ScopedKey, patterns: list[str], num_allowed_restarts: int) → ScopedKey

Add a list of Task restart patterns to an AlchemicalNetwork.

Parameters:

  • network_scoped_key – The ScopedKey for the AlchemicalNetwork to add the patterns to.

  • patterns – The regular expression strings to compare to ProtocolUnitFailure tracebacks. Matching patterns will set the Task status back to ‘waiting’.

  • num_allowed_restarts – The number of times each pattern will be able to restart each Task. When this number is exceeded, the Task is canceled from the AlchemicalNetwork and left with the error status.

Returns:

The ScopedKey of the AlchemicalNetwork the patterns were added to.

Return type:

network_scoped_key

cancel_tasks(tasks: list[ScopedKey], network: ScopedKey) → list[ScopedKey]

Cancel Tasks for execution via the given AlchemicalNetwork’s TaskHub.

A Task cannot be canceled:

  • if it is not present in the AlchemicalNetwork’s TaskHub.

Parameters:

  • tasks – Task ScopedKeys to cancel for execution.

  • network – The AlchemicalNetwork ScopedKey to cancel the Tasks for. The Tasks will be removed from the network’s associated TaskHub.

Returns:

ScopedKeys for Tasks canceled, in the same order as given as tasks on input. If a Task couldn’t be canceled, then None will be returned in its place.

Return type:

List[Optional[ScopedKey]]

check_exists(scoped_key: ScopedKey | str) → bool

Returns True if the given ScopedKey represents an object in the database.

clear_task_restart_patterns(network_scoped_key: ScopedKey) → None

Clear all restart patterns from an AlchemicalNetwork.

Parameters:

network_scoped_key – The ScopedKey of the AlchemicalNetwork to be cleared of restart patterns.

create_network(network: AlchemicalNetwork, scope: Scope, state: NetworkStateEnum | str = NetworkStateEnum.active, compress: bool | int = True, visualize: bool = True) → ScopedKey

Submit an AlchemicalNetwork to a specific Scope.

Parameters:

  • network – The AlchemicalNetwork to submit.

  • scope – The Scope in which to submit the AlchemicalNetwork. This must be a specific Scope; it must not contain wildcards.

  • state – The starting state of the AlchemicalNetwork in the database. See AlchemiscaleClient.set_network_state() for valid states.

  • compress –

    If True, compress the AlchemicalNetwork client-side before shipping to the API service. This can reduce submission time depending on the bandwidth of your connection to the API service. Set to False to submit without compressing. This is a performance optimization; it has no bearing on the result of this method call.

    Use an integer between 0 and 9 for finer control over the degree of compression; 0 means no compression, 9 means max compression. True is synonymous with level 5 compression.

  • visualize – If True, show submission progress indicator.

Returns:

The ScopedKey of the AlchemicalNetwork.

Return type:

ScopedKey

create_tasks(transformation: ScopedKey, extends: ScopedKey | None = None, count: int = 1) → list[ScopedKey]

Create Tasks for the given Transformation.

Parameters:

  • transformation – The ScopedKey of the Transformation to create Tasks for.

  • extends – The ScopedKey for the Task to use as a starting point for the Tasks created.

  • count – The number of new Tasks to create.

Returns:

A list giving the ScopedKeys of the new Tasks created.

Return type:

List[ScopedKey]

create_transformations_tasks(transformations: list[ScopedKey], extends: list[ScopedKey | None] | None = None) → list[ScopedKey]

Create Tasks for multiple Transformations.

Unlike create_tasks, this method can create Tasks for many Transformations. This method should be used instead of create_tasks whenever creating Tasks for more than one unique Transformation since it minimizes the number of API requests to the alchemiscale server.

Parameters:

  • transformations – A list of ScopedKeys of Transformations to create Tasks for. The same ScopedKey can be repeated to create multiple Tasks for the same Transformation.

  • extends – A list of ScopedKeys for the Tasks to be extended. When not None, extends must be a list of the same length as transformations. If a transformation in transformations should not extend a Task, use a None as a placeholder in the extends list.

Returns:

A list giving the ScopedKeys of the new Tasks created.

Return type:

List[ScopedKey]

Examples

Instead of looping over Transformations and calling create_tasks, make one call to create_transformations_tasks.

>>> client.create_transformations_tasks([transformation_1_sk, transformation_2_sk])

The behavior of the count keyword argument from create_tasks can be recreated by repeating the same transformation in the list while also allowing the addition of other transformtions.

>>> client.create_transformations_tasks([transformation_1_sk] * 3 + [transformation_2_sk] * 2)
get_chemicalsystem(chemicalsystem: ScopedKey | str, compress: bool = True, visualize: bool = True) → ChemicalSystem

Retrieve a ChemicalSystem given its ScopedKey.

Parameters:

  • chemicalsystem – The ScopedKey of the ChemicalSystem to retrieve.

  • compress – If True, compress the ChemicalSystem server-side before shipping it to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicator.

Returns:

The retrieved ChemicalSystem.

Return type:

ChemicalSystem

get_chemicalsystem_networks(chemicalsystem: ScopedKey) → list[ScopedKey]

List ScopedKeys for the AlchemicalNetworks associated with the given ChemicalSystem.

get_chemicalsystem_transformations(chemicalsystem: ScopedKey) → list[ScopedKey]

List ScopedKeys for the Transformations associated with the given ChemicalSystem.

get_network(network: ScopedKey | str, compress: bool = True, visualize: bool = True) → AlchemicalNetwork

Retrieve an AlchemicalNetwork given its ScopedKey.

Parameters:

  • network – The ScopedKey of the AlchemicalNetwork to retrieve.

  • compress – If True, compress the AlchemicalNetwork server-side before shipping it to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicator.

Returns:

The retrieved AlchemicalNetwork.

Return type:

AlchemicalNetwork

get_network_actioned_tasks(network: ScopedKey, task_weights: bool = False) → dict[ScopedKey, float] | list[ScopedKey]

Return all actioned Tasks for a given AlchemicalNetwork.

Parameters:

  • network – The ScopedKey for the AlchemicalNetwork to get actioned Tasks for.

  • task_weights – If True, return a dict with Task ScopedKeys as keys, Task weights on the AlchemicalNetwork as values.

Returns:

A list of Task ScopedKeys actioned on the given AlchemicalNetwork. If task_weights is True, a dict is returned with Task ScopedKeys as keys, Task weights as values.

Return type:

tasks

get_network_chemicalsystems(network: ScopedKey) → list[ScopedKey]

List ScopedKeys for the ChemicalSystems associated with the given AlchemicalNetwork.

get_network_failures(network: ScopedKey, compress: bool = True, visualize: bool = True) → dict[str, list[ProtocolDAGResult]]

Get all failed ProtocolDAGResult`s for every `Transformation in the given AlchemicalNetwork.

A dict giving the ScopedKey of each Transformation in the network as keys, a list of the ProtocolDAGResults as values, is returned.

Parameters:

  • network – The ScopedKey of the AlchemicalNetwork to retrieve results for.

  • compress – If True, compress the ProtocolDAGResults server-side before shipping them to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicators.

get_network_results(network: ScopedKey, return_protocoldagresults: bool = False, compress: bool = True, visualize: bool = True) → dict[str, ProtocolResult | None | list[ProtocolDAGResult]]

Get a ProtocolResult for every Transformation in the given AlchemicalNetwork.

A dict giving the ScopedKey of each Transformation in the network as keys, ProtocolResult as values, is returned. If no ProtocolDAGResults exist for a given Transformation, None is given for its value.

If return_protocoldagresults is True, then a list of the ProtocolDAGResults themselves is given as values instead of ProtocolResults.

Parameters:

  • network – The ScopedKey of the AlchemicalNetwork to retrieve results for.

  • return_protocoldagresults – If True, return the raw ProtocolDAGResult`s instead of returning a processed `ProtocolResult. Only successful ProtocolDAGResults are returned.

  • compress – If True, compress the ProtocolDAGResults server-side before shipping them to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicators.

get_network_state(network: ScopedKey) → str | None

Get the state of an AlchemicalNetwork.

Parameters:

network – The ScopedKey of the AlchemicalNetwork to get the state for.

Returns:

The state of the AlchemicalNetwork. If the network was not found in the database, None is returned instead.

Return type:

Optional[str]

get_network_status(network: ScopedKey, visualize: bool | None = True) → dict[str, int]

Return status counts for all Tasks associated with the given AlchemicalNetwork.

Parameters:

  • network – ScopedKey for the AlchemicalNetwork to obtain status counts for.

  • visualize – If True, print a table of status counts.

Returns:

Dict giving statuses as keys, Task counts as values.

Return type:

status_counts

get_network_strategy(network: ScopedKey) → Strategy | None

Get the Strategy for the given AlchemicalNetwork.

Parameters:

network – ScopedKey of the AlchemicalNetwork.

Returns:

Strategy object for this AlchemicalNetwork; None if no Strategy is set.

Return type:

strategy

get_network_strategy_state(network: ScopedKey) → StrategyState | None

Get the StrategyState for the given AlchemicalNetwork.

Parameters:

network – ScopedKey of the AlchemicalNetwork.

Returns:

Strategy state with execution metadata; None if no Strategy is set.

Return type:

strategy_state

get_network_strategy_status(network: ScopedKey) → str | None

Get the status of the Strategy for the given AlchemicalNetwork.

Parameters:

network – ScopedKey of the AlchemicalNetwork.

Returns:

Strategy status: “awake”, “dormant”, or “error”; None if no Strategy is set.

Return type:

status

get_network_tasks(network: ScopedKey, status: str | None = None)

List ScopedKeys for all Tasks associated with the given AlchemicalNetwork.

get_network_transformations(network: ScopedKey) → list[ScopedKey]

List ScopedKeys for Transformations associated with the given AlchemicalNetwork.

get_network_weight(network: ScopedKey) → float

Get the weight of the TaskHub associated with the given AlchemicalNetwork.

Compute services perform a weighted selection of the AlchemicalNetworks visible to them before claiming Tasks actioned on those networks. Networks with higher weight are more likely to be selected than those with lower weight, and so will generally get more compute attention over time.

A weight of 0 means the AlchemicalNetwork will not receive any compute for its actioned Tasks.

get_networks_actioned_tasks(networks: list[ScopedKey], task_weights: bool = False) → list[dict[ScopedKey, float] | list[ScopedKey]]

Get all actioned Tasks for a list of AlchemicalNetwork ScopedKeys.

Parameters:

networks – A list of AlchemicalNetwork ScopedKeys to retrieve actioned Tasks for.

Returns:

If task_weights is True, a list of dictionaries is returned with the same length as the specified network list. The keys and values of the contained dictionaries are the ScopedKeys and weights of the actioned Tasks, respectively.

If task_weights is False, only a list of actioned Task ScopedKeys is returned for each network in the specified list.

Return type:

List[Union[Dict[ScopedKey, float], List[ScopedKey]]]

get_networks_state(networks: list[ScopedKey]) → list[str | None]

Get the states for a list of AlchemicalNetworks.

Parameters:

networks – A list of ScopedKeys for the AlchemicalNetworks to get the states of.

Returns:

A list of network states, in the same order as the specified networks. If a network was not found in the database, the corresponding entry in this list is None.

Return type:

List[Optional[str]]

get_networks_status(networks: list[ScopedKey]) → list[dict[str, int]]

Get the status counts of Tasks for a list of AlchemicalNetworks.

Parameters:

networks – List of AlchemicalNetwork ScopedKeys to obtain status counts for.

Returns:

A list of dictionaries, in the same order as the provided networks, containing the Task status counts for all Tasks in each network. The dictionary keys are the statuses and the values are the number of Tasks with that status. If either no tasks exist for the Transformations in a network, or the network does not exist in the database, a empty dictionary is returned at the corresponding index.

Return type:

List[Dict[str, int]]

get_networks_weight(networks: list[ScopedKey], batch_size: int = 1000) → list[float]

Get the weight of the TaskHubs associated with the given AlchemicalNetworks.

Compute services perform a weighted selection of the AlchemicalNetworks visible to them before claiming Tasks actioned on those networks. Networks with higher weight are more likely to be selected than those with lower weight, and so will generally get more compute attention over time.

A weight of 0 means the AlchemicalNetwork will not receive any compute for its actioned Tasks.

Parameters:

networks – A list of AlchemicalNetwork ScopedKeys.

Returns:

The weights of the TaskHubs associated with the specified AlchemicalNetworks. If the network was not found in the database, then None is returned in the corresponding index.

Return type:

List[float]

get_scope_status(scope: Scope | None = None, visualize: bool | None = True, network_state: NetworkStateEnum | str | None = NetworkStateEnum.active) → dict[str, int]

Return status counts for all Tasks within the given Scope.

Parameters:

  • scope – Scope to use for querying status. Non-specific Scopes are allowed, and will give back counts for all Tasks within that this user has Scope access to. Defaults to all Scopes.

  • visualize – If True, print a table of status counts.

  • network_state – Regex expression for the network states. Nonexistent state values entered will not raise any warnings. Use None to get networks regardless of state. Defaults to the “active” state.

Returns:

Dict giving statuses as keys, Task counts as values.

Return type:

status_counts

get_scoped_key(obj: GufeTokenizable, scope: Scope) → ScopedKey

Given any gufe object and a fully-specified Scope, return corresponding ScopedKey.

This method does not check that this ScopedKey is represented in the database. It is only a convenience for properly constructing a ScopedKey from a gufe object and a Scope.

get_task_actioned_networks(task: ScopedKey, task_weights: bool = False) → dict[ScopedKey, float] | list[ScopedKey]

Return all AlchemicalNetworks the given Task is actioned on.

Parameters:

  • task – The ScopedKey for the Task to get actioned AlchemicalNetworks for.

  • task_weights – If True, return a dict with AlchemicalNetwork ScopedKeys as keys, the given Task’s weights on each AlchemicalNetwork as values.

Returns:

A list of AlchemicalNetwork ScopedKeys which action the given Task. If task_weights is True, a dict is returned with AlchemicalNetwork ScopedKeys as keys, Task weights as values.

Return type:

networks

get_task_failures(task: ScopedKey, compress: bool = True, visualize: bool = True) → list[ProtocolDAGResult]

Get failed ProtocolDAGResult`s for the given `Task.

Parameters:

  • task – The ScopedKey of the Task to retrieve failures for.

  • compress – If True, compress the ProtocolDAGResults server-side before shipping them to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicators.

get_task_networks(task: ScopedKey)

List ScopedKeys for all AlchemicalNetworks associated with the given Task.

get_task_restart_patterns(network_scoped_key: ScopedKey) → dict[str, int]

Get the Task restart patterns applied to an AlchemicalNetwork along with the number of retries allowed for each pattern.

Parameters:

network_scoped_key – The ScopedKey of the AlchemicalNetwork to query.

Returns:

A dictionary whose keys are all of the patterns applied to the AlchemicalNetwork and whose values are the number of retries each pattern will allow.

Return type:

patterns

get_task_results(task: ScopedKey, compress: bool = True, visualize: bool = True) → list[ProtocolDAGResult]

Get successful ProtocolDAGResult`s for the given `Task.

Parameters:

  • task – The ScopedKey of the Task to retrieve results for.

  • compress – If True, compress the ProtocolDAGResults server-side before shipping them to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicators.

get_task_transformation(task: ScopedKey) → ScopedKey

Get the Transformation associated with the given Task.

get_tasks_priority(tasks: list[ScopedKey], batch_size: int = 1000) → list[int]

Get the priority of multiple Tasks.

Parameters:

  • tasks – The Tasks to get the priority of.

  • batch_size – The number of Tasks to include in a single request; use to tune method call speed when requesting many priorities at once.

Returns:

The priority of each Task in the same order as given in tasks. If a given Task doesn’t exist, None will be returned in its place.

Return type:

priorities

get_tasks_status(tasks: list[ScopedKey], batch_size: int = 1000) → list[str]

Get the status of multiple Tasks.

Parameters:

  • tasks – The Tasks to get the status of.

  • batch_size – The number of Tasks to include in a single request; use to tune method call speed when requesting many statuses at once.

Returns:

The status of each Task in the same order as given in tasks. If a given Task doesn’t exist, None will be returned in its place.

Return type:

statuses

get_transformation(transformation: ScopedKey | str, compress: bool = True, visualize: bool = True) → Transformation

Retrieve a Transformation given its ScopedKey.

Parameters:

  • transformation – The ScopedKey of the Transformation to retrieve.

  • compress – If True, compress the Transformation server-side before shipping it to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicator.

Returns:

The retrieved Transformation.

Return type:

Transformation

get_transformation_chemicalsystems(transformation: ScopedKey) → list[ScopedKey]

List of ChemicalSystem ScopedKey objects associated with the given Transformation or NonTransformation.

This method returns a list of ChemicalSystem ScopedKey objects ordered by the state names, i.e. “stateA” and “stateB”. If the ScopedKey of a NonTransformation was provided, then the list will have only one element: the ScopedKey of the “system” ChemicalSystem.

Parameters:

transformation – The ScopedKey of a Transformation or NonTransformation.

get_transformation_failures(transformation: ScopedKey, compress: bool = True, visualize: bool = True) → list[ProtocolDAGResult]

Get failed ProtocolDAGResults for the given Transformation.

Parameters:

  • transformation – The ScopedKey of the Transformation to retrieve failures for.

  • compress – If True, compress the ProtocolDAGResults server-side before shipping them to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicators.

get_transformation_networks(transformation: ScopedKey) → list[ScopedKey]

List ScopedKeys for AlchemicalNetworks associated with the given Transformation.

get_transformation_results(transformation: ScopedKey, return_protocoldagresults: bool = False, compress: bool = True, visualize: bool = True) → ProtocolResult | None | list[ProtocolDAGResult]

Get a ProtocolResult for the given Transformation.

A ProtocolResult object corresponds to the Protocol used for this Transformation. This is constructed from the available ProtocolDAGResults for this Transformation via Transformation.gather. If no ProtocolDAGResults exist for this Transformation, None is returned.

If return_protocoldagresults is True, then a list of the ProtocolDAGResults themselves is returned instead.

Parameters:

  • transformation – The ScopedKey of the Transformation to retrieve results for.

  • return_protocoldagresults – If True, return the raw ProtocolDAGResult`s instead of returning a processed `ProtocolResult. Only successful ProtocolDAGResults are returned.

  • compress – If True, compress the ProtocolDAGResults server-side before shipping them to the client. This can reduce retrieval time depending on the bandwidth of your connection to the API service. Set to False to retrieve without compressing. This is a performance optimization; it has no bearing on the result of this method call.

  • visualize – If True, show retrieval progress indicators.

get_transformation_status(transformation: ScopedKey, visualize: bool | None = True) → dict[str, int]

Return status counts for all Tasks associated with the given Transformation.

Parameters:

  • transformation – ScopedKey for the Transformation to obtain status counts for.

  • visualize – If True, print a table of status counts.

Returns:

Dict giving statuses as keys, Task counts as values.

Return type:

status_counts

get_transformation_tasks(transformation: ScopedKey, extends: ScopedKey | None = None, return_as: str = 'list', status: str | None = None) → list[ScopedKey] | DiGraph

Return the Tasks associated with the given Transformation.

Parameters:

  • transformation – The ScopedKey of the Transformation to get Tasks for.

  • extends – If given, only return Tasks that extend from the given Task’s ScopedKey. This will also give any Tasks that extend from those Tasks, recursively. Using this keyword argument amounts to choosing the tree of Tasks that extend from the given Task.

  • return_as (['list', 'graph']) – If ‘list’, Tasks will be returned in no particular order. If ‘graph’, Tasks will be returned in a networkx.DiGraph, with a directed edge pointing from a given Task to the Task it extends.

query_chemicalsystems(name: str | None = None, scope: Scope | None = None) → list[ScopedKey]

Query for ChemicalSystems, optionally by name or Scope.

Calling this method with no query arguments will return ScopedKeys for all ChemicalSystems that are within the Scopes this user has access to.

query_networks(name: str | None = None, scope: Scope | None = None, state: NetworkStateEnum | str | None = NetworkStateEnum.active) → list[ScopedKey]

Query for AlchemicalNetworks, optionally by name or Scope.

Calling this method with no query arguments will return ScopedKeys for all AlchemicalNetworks that are within the Scopes this user has access to.

Parameters:

  • name (optional) – Regex expression for the network names. Defaults to a wildcard.

  • scope (optional) – A Scope to filter AlchemicalNetworks on.

  • state (optional) – Regex expression for the network states. Nonexistent state values entered will not raise any warnings. Use None to get networks regardless of state. Defaults to the “active” state.

Returns:

A list of ScopedKeys for the networks matching the query parameters.

Return type:

List[ScopedKey]

query_tasks(scope: Scope | None = None, status: str | None = None) → list[ScopedKey]

Query for Tasks, optionally by status or Scope.

Calling this method with no query arguments will return ScopedKeys for all Tasks that are within the Scopes this user has access to.

query_transformations(name: str | None = None, scope: Scope | None = None) → list[ScopedKey]

Query for Transformations, optionally by name or Scope.

Calling this method with no query arguments will return ScopedKeys for all Transformations that are within the Scopes this user has access to.

remove_task_restart_patterns(network_scoped_key: ScopedKey, patterns: list[str]) → None

Remove specific Task restart patterns from an AlchemicalNetwork.

Parameters:

  • network_scoped_key – The ScopedKey of the AlchemicalNetwork the patterns are applied to.

  • patterns – The patterns to remove from the AlchemicalNetwork.

set_network_state(network: ScopedKey, state: NetworkStateEnum | str) → ScopedKey | None

Set the state of an AlchemicalNetwork.

Parameters:

  • network – The network whose state will be updated.

  • state – The state to set the network to. Valid options include “active”, “inactive”, “invalid”, and “deleted”.

Returns:

The ScopedKey of the updated network. If the network was not found, None is returned.

Return type:

Optional[ScopedKey]

set_network_strategy(network: ScopedKey, strategy: GufeTokenizable | None, max_tasks_per_transformation: int = 3, task_scaling: str = 'exponential', mode: str = 'partial', sleep_interval: int = 3600) → ScopedKey | None

Set a Strategy for the given AlchemicalNetwork.

Parameters:

  • network – ScopedKey of the AlchemicalNetwork.

  • strategy – Strategy object (GufeTokenizable) or None to remove strategy.

  • max_tasks_per_transformation. – Maximum number of actioned Tasks allowed on a Transformation at once.

  • task_scaling – How to translate weights into Task counts: “linear” or “exponential”.

  • mode – Strategy mode: “full”, “partial”, or “disabled”.

  • sleep_interval – Wait time between iterations of the Strategy in seconds.

Returns:

ScopedKey of the Strategy that was set, or None if strategy was removed.

Return type:

ScopedKey | None

set_network_strategy_awake(network: ScopedKey) → ScopedKey | None

Set the Strategy status to ‘awake’ for the given AlchemicalNetwork.

This resets a dormant or errored strategy to active status.

Parameters:

network – ScopedKey of the AlchemicalNetwork to set Strategy ‘awake’ for.

Returns:

ScopedKey of the AlchemicalNetwork if Strategy status set to ‘awake’; None otherwise.

Return type:

ScopedKey | None

set_network_weight(network: ScopedKey, weight: float) → ScopedKey | None

Set the weight of the TaskHub associated with the given AlchemicalNetwork.

Compute services perform a weighted selection of the AlchemicalNetworks visible to them before claiming Tasks actioned on those networks. Networks with higher weight are more likely to be selected than those with lower weight, and so will generally get more compute attention over time.

A weight of 0 means the AlchemicalNetwork will not receive any compute for its actioned Tasks.

Parameters:

  • network – The ScopedKey of the AlchemicalNetwork to set the weight for.

  • weight – The weight to set for the network. This must be between 0 and 1 (inclusive). Setting the value to 0 will effectively disable compute on this network without cancelling its actioned Tasks.

set_networks_state(networks: list[ScopedKey], states: list[NetworkStateEnum | str]) → list[ScopedKey | None]

Set the state of a list of AlchemicalNetworks.

Parameters:

  • networks – The networks whose states will be updated.

  • states – The states to set the networks to, in the same order as networks. Values must be in a list of the same length as the networks parameter. Valid options include “active”, “inactive”, “invalid”, and “deleted”.

Returns:

The ScopedKeys of the updated networks. If a network was not found, None is returned at the corresponding index.

Return type:

List[Optional[ScopedKey]]

set_networks_weight(networks: list[ScopedKey], weights: list[float], batch_size: int = 1000) → list[ScopedKey | None]

Set the weights of the TaskHubs associated with the given AlchemicalNetworks.

Compute services perform a weighted selection of the AlchemicalNetworks visible to them before claiming Tasks actioned on those networks. Networks with higher weight are more likely to be selected than those with lower weight, and so will generally get more compute attention over time.

A weight of 0 means the AlchemicalNetwork will not receive any compute for its actioned Tasks.

Parameters:

  • networks – The ScopedKeys of the AlchemicalNetworks to set the weights for.

  • weight – The weights to set for the networks, in the same order. Each must be between 0 and 1 (inclusive). Setting the value to 0 will effectively disable compute on the networks without cancelling its actioned Tasks. Should be a list of the same length as networks.

Returns:

The ScopedKeys of the TaskHubs whose weight changed, in the order that the AlchemicalNetworks ScopedKeys were provided. If one of the specified networks could not be found, a None is returned at its corresponding index.

Return type:

List[Optional[ScopedKey]]

set_task_restart_patterns_allowed_restarts(network_scoped_key: ScopedKey, patterns: list[str], num_allowed_restarts: int) → None

Set the number of Task restarts that patterns are allowed to perform for the given AlchemicalNetwork.

Parameters:

  • network_scoped_key – The ScopedKey of the AlchemicalNetwork the patterns are applied to.

  • patterns – The patterns to set the number of allowed restarts for.

  • num_allowed_restarts – The new number of allowed restarts.

set_tasks_priority(tasks: list[ScopedKey], priority: int, batch_size: int = 1000) → list[ScopedKey | None]

Set the priority of multiple Tasks.

Parameters:

  • tasks – The Tasks to set the priority of.

  • priority – The priority to set for the Task. This value must be between 1 and 2**63 - 1, with lower values indicating an increased priority.

  • batch_size – The number of Tasks to include in a single request; use to tune method call speed when requesting many priorities at once.

Returns:

The ScopedKeys of the Tasks that were updated, in the same order as given in tasks. If a given Task doesn’t exist, None will be returned in its place.

Return type:

updated

set_tasks_status(tasks: list[ScopedKey], status: TaskStatusEnum | str, batch_size: int = 1000) → list[ScopedKey | None]

Set the status of one or multiple Tasks.

Task status can be set to ‘waiting’ if currently ‘error’. Status can be set to ‘invalid’ or ‘deleted’ from any other status.

Parameters:

  • tasks – The Tasks to set the status of.

  • status – The status to set the Tasks to. Can be one of ‘waiting’, ‘invalid’, or ‘deleted’.

Returns:

The ScopedKeys of the Tasks that were updated, in the same order as given in tasks. If a given Task doesn’t exist, None will be returned in its place.

Return type:

updated

exception alchemiscale.interface.client.AlchemiscaleClientError(*args, **kwargs)

Bases: AlchemiscaleBaseClientError