Functions
None	_print_conda_warnings ()

Union[List[Union[Callable[..., Any], str]], NoReturn]	get_protocols (Union[List[Union[Callable[..., Any], str]], Callable[..., Any], Optional[str]] protocols=None, Optional[str] input_file=None, Optional[str] scorefile=None, Optional[str] decoy_name=None)

Union[Dict[str, Any], NoReturn]	get_instance_kwargs (Optional[str] input_file=None, Optional[str] scorefile=None, Optional[str] decoy_name=None)

Optional[NoReturn]	recreate_environment (Optional[str] environment_name=None, Optional[str] input_file=None, Optional[str] scorefile=None, Optional[str] decoy_name=None, Optional[int] timeout=None)

Union[P, NoReturn]	reserve_scores (P func)

Optional[NoReturn]	reproduce (Optional[str] input_file=None, Optional[str] scorefile=None, Optional[str] decoy_name=None, Any protocols=None, Optional[distributed.client.Client] client=None, Optional[List[distributed.client.Client]] clients=None, Optional[Union[Pose, PackedPose]] input_packed_pose=None, Optional[Dict[Any, Any]] instance_kwargs=None, Optional[List[int]] clients_indices=None, Optional[Dict[Any, Any]] resources=None)

Optional[NoReturn]	produce (**Any kwargs)

Variables
string	__author__ = "Jason C. Klima"

	P = TypeVar("P", bound=Callable[..., Any])

Function Documentation

◆ _print_conda_warnings()

None pyrosetta.distributed.cluster.tools._print_conda_warnings ( )

private

Print warning message if Anaconda or Miniconda are not installed and we are
not in an active conda environment on the client.

References pyrosetta.distributed.cluster.converter_tasks.get_yml(), and print().

◆ get_instance_kwargs()

Union[Dict[str, Any], NoReturn] pyrosetta.distributed.cluster.tools.get_instance_kwargs	(	Optional[str]	input_file = `None`,
		Optional[str]	scorefile = `None`,
		Optional[str]	decoy_name = `None`
	)

Given an input file that was written by PyRosettaCluster, or a scorefile
and a decoy name that was written by PyRosettaCluster, return the PyRosettaCluster
instance kwargs needed to reproduce the decoy using PyRosettaCluster.

Args:
    input_file: A `str` object specifying the path to the '.pdb' or '.pdb.bz2'
        file from which to extract PyRosettaCluster instance kwargs. If input_file
        is provided, then ignore the 'scorefile' and 'decoy_name' argument parameters.
        Default: None
    scorefile: A `str` object specifying the path to the JSON-formatted scorefile
        from which to extract PyRosettaCluster instance kwargs. If 'scorefile'
        is provided, 'decoy_name' must also be provided. In order to use a scorefile,
        it must contain full simulation records from the original production
        run; i.e., the attribute 'simulation_records_in_scorefile' was set to True.
        Default: None
    decoy_name: A `str` object specifying the decoy name for which to extract
        PyRosettaCluster instance kwargs. If 'decoy_name' is provided, 'scorefile'
        must also be provided.
        Default: None

Returns:
    A `dict` object of PyRosettaCluster instance kwargs.

References basic::database.open(), pyrosetta.distributed.cluster.converter_tasks.parse_decoy_name(), pyrosetta.distributed.cluster.converter_tasks.parse_input_file_to_instance_kwargs(), and pyrosetta.distributed.cluster.converter_tasks.parse_scorefile().

Referenced by pyrosetta.distributed.cluster.tools.recreate_environment(), and pyrosetta.distributed.cluster.tools.reproduce().

◆ get_protocols()

Union[List[Union[Callable[..., Any], str]], NoReturn] pyrosetta.distributed.cluster.tools.get_protocols	(	Union[ List[Union[Callable[..., Any], str]], Callable[..., Any], Optional[str] ]	protocols = `None`,
		Optional[str]	input_file = `None`,
		Optional[str]	scorefile = `None`,
		Optional[str]	decoy_name = `None`
	)

Given an 'input_file' that was written by PyRosettaCluster, or a full 'scorefile'
and a 'decoy_name' that was written by PyRosettaCluster, if 'protocols' is provided
then validate the 'protocols' against those in the 'input_file' or 'scorefile',
otherwise if 'protocols' is `NoneType` then attempt to return the PyRosettaCluster
protocols from the current scope matching the protocol names in the 'input_file'
or 'scorefile'.

Args:
    protocols: An iterable of `str` objects specifying the names of user-provided
        PyRosetta protocols to validate or return.
        Default: None
    input_file: A `str` object specifying the path to the '.pdb' or '.pdb.bz2'
        file from which to extract PyRosettaCluster instance kwargs. If input_file
        is provided, then ignore the scorefile and decoy_name argument parameters.
        Default: None
    scorefile: A `str` object specifying the path to the JSON-formatted scorefile
        from which to extract PyRosettaCluster instance kwargs. If 'scorefile'
        is provided, 'decoy_name' must also be provided. In order to use a scorefile,
        it must contain full simulation records from the original production
        run; i.e., the attribute 'simulation_records_in_scorefile' was set to True.
        Default: None
    decoy_name: A `str` object specifying the decoy name for which to extract
        PyRosettaCluster instance kwargs. If decoy_name is provided, scorefile
        must also be provided.
        Default: None

Returns:
    A `list` of user-defined PyRosetta protocol names from the 'input_file' or 'scorefile'.
    If `protocols` is None, then attempt to return the PyRosettaCluster protocols
    from the current scope matching the protocol names in the 'input_file' or 'scorefile'.

References pyrosetta.distributed.cluster.converters._parse_protocols(), pyrosetta.distributed.cluster.converter_tasks.get_protocols_list_of_str(), ObjexxFCL.len(), and range.

Referenced by pyrosetta.distributed.cluster.tools.reproduce().

◆ produce()

Optional[NoReturn] pyrosetta.distributed.cluster.tools.produce ( **Any kwargs )

PyRosettaCluster.distribute shim requiring the 'protocols' keyword argument and optionally
any PyRosettaCluster keyword arguments or the 'clients_indices' keyword argument when using
the 'clients' keyword argument.

Args:
    **kwargs: See PyRosettaCluster docstring. The keyword arguments must also include
        'protocols', an iterable object of function or generator objects specifying
        an ordered sequence of user-defined PyRosetta protocols to execute for
        the simulation (see PyRosettaCluster.distribute docstring). The keyword arguments
        may also optionally include 'clients_indices' (see PyRosettaCluster.distribute
        docstring).

Returns:
    None

Referenced by pyrosetta.tests.distributed.cluster.test_smoke.MultipleClientsTest.test_clients(), pyrosetta.tests.distributed.cluster.test_smoke.ResourcesTest.test_resources(), pyrosetta.tests.distributed.cluster.test_smoke.ResourcesTest.test_resources_clients(), and pyrosetta.tests.distributed.cluster.test_smoke.SmokeTest.test_smoke().

◆ recreate_environment()

Optional[NoReturn] pyrosetta.distributed.cluster.tools.recreate_environment	(	Optional[str]	environment_name = `None`,
		Optional[str]	input_file = `None`,
		Optional[str]	scorefile = `None`,
		Optional[str]	decoy_name = `None`,
		Optional[int]	timeout = `None`
	)

Given an input file that was written by PyRosettaCluster, or a scorefile
and a decoy name that was written by PyRosettaCluster, recreate the conda
environment that was used to generate the decoy with a new environment name.

Args:
    environment_name: A `str` object specifying the new name of the conda environment
        to recreate.
        Default: 'PyRosettaCluster_' + datetime.now().strftime("%Y.%m.%d.%H.%M.%S.%f")
    input_file: A `str` object specifying the path to the '.pdb' or '.pdb.bz2'
        file from which to extract PyRosettaCluster instance kwargs. If input_file
        is provided, then ignore the 'scorefile' and 'decoy_name' argument parameters.
        Default: None
    scorefile: A `str` object specifying the path to the JSON-formatted scorefile
        from which to extract PyRosettaCluster instance kwargs. If 'scorefile'
        is provided, 'decoy_name' must also be provided. In order to use a scorefile,
        it must contain full simulation records from the original production
        run; i.e., the attribute 'simulation_records_in_scorefile' was set to True.
        Default: None
    decoy_name: A `str` object specifying the decoy name for which to extract
        PyRosettaCluster instance kwargs. If 'decoy_name' is provided, 'scorefile'
        must also be provided.
        Default: None
    timeout: An `int` object specifying the timeout in seconds before exiting the subprocess.
        Default: None

Returns:
    None

References pyrosetta.distributed.cluster.tools.get_instance_kwargs(), basic::database.open(), and detail.strftime().

◆ reproduce()

Optional[NoReturn] pyrosetta.distributed.cluster.tools.reproduce	(	Optional[str]	input_file = `None`,
		Optional[str]	scorefile = `None`,
		Optional[str]	decoy_name = `None`,
		Any	protocols = `None`,
		Optional[distributed.client.Client]	client = `None`,
		Optional[List[distributed.client.Client]]	clients = `None`,
		Optional[Union[Pose, PackedPose]]	input_packed_pose = `None`,
		Optional[Dict[Any, Any]]	instance_kwargs = `None`,
		Optional[List[int]]	clients_indices = `None`,
		Optional[Dict[Any, Any]]	resources = `None`
	)

Given an input file that was written by PyRosettaCluster (or a full scorefile
and a decoy name that was written by PyRosettaCluster) and any additional
PyRosettaCluster instance kwargs, run the reproduction simulation for the
given decoy with a new instance of PyRosettaCluster.

Args:
input_file: A `str` object specifying the path to the '.pdb' or '.pdb.bz2'
file from which to extract PyRosettaCluster instance kwargs. If 'input_file'
is provided, then ignore the 'scorefile' and 'decoy_name' argument parameters.
Default: None
scorefile: A `str` object specifying the path to the JSON-formatted scorefile
from which to extract PyRosettaCluster instance kwargs. If 'scorefile'
is provided, 'decoy_name' must also be provided. In order to use a scorefile,
it must contain full simulation records from the original production
run; i.e., the attribute 'simulation_records_in_scorefile' was set to True.
Default: None
decoy_name: A `str` object specifying the decoy name for which to extract
PyRosettaCluster instance kwargs. If decoy_name is provided, scorefile
must also be provided.
Default: None
protocols: An optional iterable object of function or generator objects specifying
an ordered sequence of user-defined PyRosetta protocols to execute for
the reproduction. This argument only needs to be provided if the user-defined
PyRosetta protocols are not defined with the same scope as in the original
production run.
Default: None
client: An optional initialized dask `distributed.client.Client` object to be used as
the dask client interface to the local or remote compute cluster. If `None`,
then PyRosettaCluster initializes its own dask client based on the settings
from the original production run. Deprecated by the `clients` attribute, but
supported for legacy purposes.
Default: None
clients: A `list` or `tuple` object of initialized dask `distributed.client.Client`
objects to be used as the dask client interface(s) to the local or remote compute
cluster(s). If `None`, then PyRosettaCluster initializes its own dask client based
on the settings from the original production run. Optionally used in
combination with the `clients_indices` attribute.
Default: None
input_packed_pose: An optional input `PackedPose` object that is accessible via
the first argument of the first user-defined PyRosetta protocol.
Default: None
instance_kwargs: An optional `dict` object of valid PyRosettaCluster attributes
which will override any PyRosettaCluster attributes that were used to generate
the original decoy.
Default: None
clients_indices: An optional `list` or `tuple` object of `int` objects, where each `int` object represents
a zero-based index corresponding to the initialized dask `distributed.client.Client` object(s) passed
to the `PyRosettaCluster(clients=...)` class attribute. If not `None`, then the length of the
`clients_indices` object must equal the number of protocols passed to the `PyRosettaCluster().distribute`
method.
Default: None
resources: An optional `list` or `tuple` object of `dict` objects, where each `dict` object represents
an abstract, arbitrary resource to constrain which dask workers run the user-defined PyRosetta protocols.
If `None`, then do not impose resource constaints on any protocols. If not `None`, then the length
of the `resources` object must equal the number of protocols passed to the `PyRosettaCluster().distribute`
method, such that each resource specified indicates the unique resource constraints for the protocol at the
corresponding index of the protocols passed to `PyRosettaCluster().distribute`. Note that this feature is only
useful when one passes in their own instantiated client(s) with dask workers set up with various resource
constraints. If dask workers were not instantiated to satisfy the specified resource constraints, protocols
will hang indefinitely because the dask scheduler is waiting for workers that meet the specified resource
constraints so that it can schedule these protocols. Unless workers were created with these resource tags
applied, the protocols will not run. See https://distributed.dask.org/en/latest/resources.html for more
information.
Default: None

Returns:
None

References pyrosetta.distributed.cluster.tools.get_instance_kwargs(), pyrosetta.distributed.cluster.tools.get_protocols(), pyrosetta.distributed.cluster.converter_tasks.parse_client(), and pyrosetta.distributed.cluster.converter_tasks.parse_instance_kwargs().

Referenced by pyrosetta.tests.distributed.cluster.test_reproducibility.TestReproducibilityMulti.test_reproducibility_from_reproduce().

◆ reserve_scores()

Union[P, NoReturn] pyrosetta.distributed.cluster.tools.reserve_scores ( P func )

Use this as a Python decorator of any user-provided PyRosetta protocol.
If any scoreterms and values are present in the input `packed_pose`, then if
they are deleted during execution of the decorated user-provided PyRosetta
protocol, then append those scoreterms and values back into the pose.scores
dictionary after execution. If any scoreterms and values are present in the
input `packed_pose` and also present in the returned or yielded output `Pose`
or `PackedPose` objects, then do not append the original scoreterms and values
back into the pose.scores dictionary after execution (that is, keep the outputted
scoreterms and values in the pose.scores dictionary). Any new scoreterms and
values acquired in the decorated user-provided PyRosetta protocol will never
be overwritten. This allows users to maintain scoreterms and values acquired
in earlier user-defined PyRosetta protocols if needing to execute Rosetta
Movers that happen to delete scores from pose objects.

For example:

@reserve_scores
def my_pyrosetta_protocol(packed_pose, **kwargs):
    from pyrosetta import MyMover
    MyMover().apply(packed_pose.pose)
    return pose

Args:
    A user-provided PyRosetta function.

Returns:
    The output from the user-provided PyRosetta function, reserving the scores.

References pyrosetta.distributed.cluster.converter_tasks.reserve_scores_in_results().

Variable Documentation

◆ author

string pyrosetta.distributed.cluster.tools.__author__ = "Jason C. Klima"