diff --git a/docs/conf.py b/docs/conf.py index bf6c0c3..d8b416c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,12 +13,14 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.autodoc'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - +intersphinx_mapping = { + "gufe": ("https://gufe.openfree.energy/en/stable", None), +} # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/docs/getting_started.rst b/docs/getting_started.rst index ce035cf..212d0f1 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -21,7 +21,7 @@ Verify the installation was successful in a Python interpreter 3. Quick-start example ~~~~~~~~~~~~~~~~~~~~~~ -You can calculate transformation weights for an ``AlchemicalNetwork``, ``alchem_network`` by calling a strategy's ``propose`` method. +You can calculate transformation weights for an :external+gufe:py:class:`~gufe.network.AlchemicalNetwork`, ``alchem_network`` by calling a strategy's ``propose`` method. .. code:: python @@ -36,10 +36,10 @@ You can calculate transformation weights for an ``AlchemicalNetwork``, ``alchem_ strategy_result: StrategyResult = strategy.propose(alchem_network, previous_results) -This returns a ``StrategyResult`` object, which is a mapping between the transformations in an ``AlchemicalNetwork`` and the weights determined by the strategy. -``None`` weights are a terminating case: a transformation with a ``None`` weight won't be proposed again and a ``StrategyResult`` with only ``None`` weights is "complete". +This returns a :py:class:`~stratocaster.base.strategy.StrategyResult` object, which is a mapping between the transformations in an :external+gufe:py:class:`~gufe.network.AlchemicalNetwork` and the weights determined by the strategy. +``None`` weights are a terminating case: a transformation with a ``None`` weight won't be proposed again and a :py:class:`~stratocaster.base.strategy.StrategyResult` with only ``None`` weights is "complete". -Calls to ``propose`` are deterministic and guaranteed to reach a terminating condition if the resulting weights are used to update the ``ProtocolResult`` objects in ``previous_results``. +Calls to ``propose`` are deterministic and guaranteed to reach a terminating condition if the resulting weights are used to update the :external+gufe:py:class:`~gufe.protocols.protocol.ProtocolResult` objects in ``previous_results``. See the :ref:`user guide` for an example of this process. Other resources diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 37c908a..efd61ba 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -3,11 +3,12 @@ User Guide ========== -A ``Strategy`` is an algorithm that assists in traversing the execution path of transformations within ``gufe`` ``AlchemicalNetwork`` objects. +A :py:class:`~stratocaster.base.strategy.Strategy` is an algorithm that assists in traversing the execution path of transformations within ``gufe`` :external+gufe:py:class:`~gufe.network.AlchemicalNetwork` objects. It removes the burden for an individual or execution engine to determine which transformations in a network must be performed and how important one transformation is relative to another given results that have already been collected. For instance, transformations with many previously calculated repeats might have a lower priority compared to transformations that haven't been performed at all. -This prioritization is encoded by transformation weights, which are presented for an ``AlchemicalNetwork`` given a set of previously computed results. +This prioritization is encoded by transformation weights, which are presented for an :external+gufe:py:class:`~gufe.network.AlchemicalNetwork` given a set of previously computed results. As results are accumulated, the strategy must eventually reach a terminating condition where no weights are presented. + Valid strategies are deterministic, i.e. networks with a fixed set of previous results always return the same weights. While the details of selecting and running a transformation from the weights is out of scope for ``stratocaster``, the following code demonstrates where a strategy might fit in an iterative execution workflow. @@ -16,19 +17,19 @@ While the details of selecting and running a transformation from the weights is A ``None`` weight for a transformation means the transformation should not be performed again as more results are added. This differs from a zero weight, which could mean the transformation will eventually be proposed again with more results. Note that before ``resolve`` (which returns a normalized set of weights) is called, the magnitudes of the weights are arbitrary and may reflect the underlying logic behind the specific strategy implementation. -For example, the ``ConnectivityStrategy`` weights are, before correcting for repeated calculations, the average number of connections of the transformations' end states. -Therefore, the pre-normalization weights directly report properties of the many subgraphs in the ``AlchemicalNetwork``. +For example, the :py:class:`~stratocaster.strategies.ConnectivityStrategy` weights are, before correcting for repeated calculations, the average number of connections of the transformations' end states. +Therefore, the pre-normalization weights directly report properties of the many subgraphs in the :py:class:`~gufe.network.AlchemicalNetwork`. Defining a new ``Strategy`` --------------------------- -A new ``Strategy`` implementation requires definitions of a new ``Strategy`` subclass along with a ``StrategySettings`` subclass specific to the new strategy. +A new :py:class:`~stratocaster.base.strategy.Strategy` implementation requires definitions of a new :py:class:`~stratocaster.base.strategy.Strategy` subclass along with a :py:class:`~stratocaster.base.models.StrategySettings` subclass specific to the new strategy. -The new ``StrategySettings`` is the mechanism by which a user will alter behavior of the new ``Strategy``. -As such, it should define the relevant variables on which the ``Strategy`` will depend. +The new ``StrategySettings`` is the mechanism by which a user will alter behavior of the new :py:class:`~stratocaster.base.strategy.Strategy`. +As such, it should define the relevant variables on which the :py:class:`~stratocaster.base.strategy.Strategy` will depend. In the below example, we include only a ``max_runs`` setting, which is usually enough to guarantee that the strategy reaches a termination condition. -The new ``Strategy`` implementation involves three main steps: 1) linking the strategy to its settings class, 2) defining the ``_default_settings`` class method, and 3) defining the ``_propose`` method. +The new :py:class:`~stratocaster.base.strategy.Strategy` implementation involves three main steps: 1) linking the strategy to its settings class, 2) defining the ``_default_settings`` class method, and 3) defining the ``_propose`` method. .. literalinclude:: ./code/newstrat.py @@ -36,7 +37,7 @@ A definition of ``_settings_cls`` provides a guardrail by preventing a user of y Defining ``_default_settings`` allows a user to get the default settings through ``MyCustomStrategy.default_settings()``. If your settings provide an exhaustive set of default options, simply return an instance of your settings without providing hard-coded keyword arguments. -Lastly, the ``_propose`` method implementation determines the results of a strategy prediction based on the ``AlchemicalNetwork``, prior results from executing ``Transformation`` protocols, and your settings. -This method should be deterministic: repeated proposals given the same set of results will yield the same ``StrategyResult``. +Lastly, the ``_propose`` method implementation determines the results of a strategy prediction based on the :external+gufe:py:class:`~gufe.network.AlchemicalNetwork`, prior results from executing :external+gufe:py:class:`~gufe.transformations.transformation.Transformation` protocols, and your settings. +This method should be deterministic: repeated proposals given the same set of results will yield the same :py:class:`~stratocaster.base.StrategyResult`. It should also have a clear termination condition. -If results are accumulated as a result of the recommendations provided by the strategy, the ``StrategyResult`` will eventually return ``None`` weights for all transformations in the network. +If results are accumulated as a result of the recommendations provided by the strategy, the :py:class:`~stratocaster.base.StrategyResult` will eventually return ``None`` weights for all transformations in the network.