Minor documentation updates.

balm/control.py

@@ -1,3 +1,8 @@
+"""
+This module implementes methods for permanent target control of Boolean networks
+based on the structure of a succession diagram.
+"""
+
 from __future__ import annotations
 
 from itertools import combinations, product
@@ -25,7 +30,7 @@ def __init__(
         which returns a list of `Intervention` objects. Manipulating the
         contents of these objects is only recommended for advanced use cases.
         Typically, it is sufficient to print this object to see a human-readable
-        an explanation of how to interpret the intervention.
+        explanation of how to interpret the intervention.
 
         Note that two interventions are considered to be equal if they act on the same succession with
         equal controls applied to each subspace in the succession. Thus, two
@@ -142,12 +147,12 @@ def __str__(self):
         )
         if self.strategy == "internal":
             return succession_string + " and then\n".join(
-                f"({' or '.join(map(str,motif_control))})"
+                f"({' or '.join(map(str, motif_control))})"
                 for motif_control in self.control
             )
         elif self.strategy == "all":
             return succession_string + " temporarily, and then\n".join(
-                f"({' or '.join(map(str,motif_control))})"
+                f"({' or '.join(map(str, motif_control))})"
                 for motif_control in self.control
             )
         else:
@@ -174,7 +179,7 @@ def succession_control(
         The target subspace.
     strategy : str, optional
         The searching strategy to use to look for driver nodes. Options are
-        'internal' (default), 'all'.
+        'internal' (default) and 'all'.
     max_drivers_per_succession_node: int | None = None,
         The maximum number of drivers that will be tested for a succession
         diagram node. If `None`, then a number of drivers up to the size of the
@@ -382,11 +387,11 @@ def drivers_of_succession(
         A list of sequentially nested trap spaces that specify the target.
     strategy: str
         The searching strategy to use to look for driver nodes. Options are
-        'internal' (default), 'all'.
+        'internal' (default) and 'all'.
     max_drivers_per_succession_node: int | None = None,
         The maximum number of drivers that will be tested for a succession
         diagram node. If `None`, then a number of drivers up to the size of the
-        succession diagram node's stable motif will be tested
+        succession diagram node's stable motif will be tested.
     forbidden_drivers: set[str] | None
         A set of forbidden drivers that will not be overridden for control. If
         `None`, then all nodes are candidates for control.
@@ -449,13 +454,13 @@ def find_drivers(
         The trap space we want to find drivers for.
     strategy: str
         The searching strategy to use to look for driver nodes. Options are
-        'internal' (default), 'all'.
+        'internal' (default) and 'all'.
     assume_fixed: dict[str,int] | None
         A dictionary of fixed variables that should be assumed to be fixed.
     max_drivers_per_succession_node: int | None = None,
         The maximum number of drivers that will be tested for a succession
         diagram node. If `None`, then a number of drivers up to the size of the
-        succession diagram node's stable motif will be tested
+        succession diagram node's stable motif will be tested.
     forbidden_drivers: set[str] | None
         A set of forbidden drivers that will not be overridden for control. If
         `None`, then all nodes are candidates for control.
@@ -522,8 +527,8 @@ def controls_are_equal(a: ControlOverrides, b: ControlOverrides) -> bool:
     objects are equal.
 
     Two `ControlOverrides` objects are equal if they contain the same
-    :class:`BooleanSpace<balm.types.BooleanSpace>` objects, without respect to
-    order.
+    :class:`BooleanSpace<balm.types.BooleanSpace>` objects, regardless of their
+    ordering.
 
     Parameters
     ----------

balm/drivers.py

@@ -1,3 +1,7 @@
+"""
+A module which provides functions for processing the stable motif driver nodes of a Boolean network.
+"""
+
 from __future__ import annotations
 
 from biodivine_aeon import AsynchronousGraph, BooleanNetwork
@@ -40,7 +44,10 @@ def find_single_node_LDOIs(
     Example
     _______
     >>> import balm
-    >>> sd = balm.SuccessionDiagram.from_rules('A, A\\nB, A')
+    >>> sd = balm.SuccessionDiagram.from_rules(\"\"\"
+    >>>     A, A
+    >>>     B, A
+    >>> \"\"\")
     >>> ldois = balm.drivers.find_single_node_LDOIs(sd.network)
     >>> for k in sorted(ldois):
     ...     print(f'{k} ==> {sorted(ldois[k].items())}')

balm/interaction_graph_utils.py

@@ -1,3 +1,8 @@
+"""
+A utility module which provides several methods for manipulating the influence graph
+of a Boolean network.
+"""
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Literal
@@ -79,7 +84,8 @@ def feedback_vertex_set(
         Must be `"positive"`, `"negative"`, or `None` (default). If
         `"positive"`, only cycles with an even number of negative edges are
         considered. If `"negative"`, only cycles with an odd number of negative
-        edges are considered. Otherwise, all cycles are considered.
+        edges are considered. Edges with no monotonicity are counted as both
+        positive and negative. Otherwise, all cycles are considered.
     subgraph : Sequence[str  |  VariableId] | None, optional
         A list of network variables (either string names or AEON `VariableId`
         objects are fine). If given, the result is the FVS of the sub-graph induced by
@@ -118,8 +124,8 @@ def feedback_vertex_set(
 def cleanup_network(network: BooleanNetwork) -> BooleanNetwork:
     """
     Prepare a `BooleanNetwork` object for use in a `SuccessionDiagram`. This
-    mainly and fixes any static constraints to ensure that they are actually
-    correct.
+    mainly ensures that the network does not use parameters and fixes all static
+    constraints to ensure that they are actually correct.
 
     Parameters
     ----------

balm/motif_avoidant.py

@@ -1,5 +1,6 @@
 """
-A module responsible for detecting motif-avoidant attractors within terminal restriction space.
+A module which provides utility methods for detecting motif-avoidant attractors
+within a terminal restriction space.
 """
 
 from __future__ import annotations
@@ -32,25 +33,32 @@ def make_retained_set(
     child_spaces: list[BooleanSpace] | None = None,
 ) -> BooleanSpace:
     """
-    Calculate the retained set.
+    Calculate the retained set for a given `space`.
 
     The retained set is technically a space-like object that describes the
     variables which have to be fixed in order for the network to lose all
     complex attractors. However, note that this really means changing the update
-    functions. I.e. this is not a trap space that only contains fixed-points,
-    but a description of how the network must be modified to eliminate complex
-    attractors.
+    functions. This is not a trap space that only contains fixed-points,
+    but a description of how the network must be modified to eliminate
+    all complex attractors in the given `space`.
 
-    Finally, the construction guarantees that any complex attractor of the old
-    network will manifest as at least one fixed-point in the new network.
+    The construction guarantees that any complex attractor of the old
+    network will manifest as at least one fixed-point in the new network. But this
+    network modification is not implemented here. This method only generates
+    the necessary list of variables and values.
+
+    Finally, note that the method uses a heuristic to select values
+    that should lead to the least amount of fixed-points in
+    the modified network.
 
     Parameters
     ----------
     graph : AsynchronousGraph
         The symbolic update functions stored as an `AsynchronousGraph` object
         from the `biodivine_aeon` library.
     nfvs : list[str]
-        The list of fixed variables in the current NFVS.
+        The list of variables in the NFVS that is valid for a network
+        restricted to the given `space`.
     space : BooleanSpace
         A :class:`BooleanSpace<balm.types.BooleanSpace>` object describing the
         current trap space.
@@ -122,20 +130,22 @@ def detect_motif_avoidant_attractors(
     is_in_an_mts: bool = False,
 ) -> list[BooleanSpace]:
     """
-    Determine which candidate seed states correspond to motif-avoidant attractors.
-
-    Compute a sub-list of `candidates` which correspond to motif-avoidant
-    attractors. Other method inputs:
+    Determine which seed states from the `candidates` list map to true
+    motif-avoidant attractors.
 
-    `graph` and `petri_net` represent the model in which the property
-    should be checked.
+    Assumes that all attractors in the `terminal_restriction_space` are
+    covered by at least one state in `candidates`. Eliminates all states
+    from `candidates` that are provably not in an attractor, or that correspond
+    to an attractor that is already covered by some other candidate.
 
-    `terminal_restriction_space` is a symbolic set of states which contains
-    all motif avoidant attractors (i.e. if a candidate state can leave this
-    set, the candidate cannot be an attractor).
+    The method consists of two steps: initial pruning, and exact reachability
+    analysis. As such, the result is always complete. However, some of the
+    parameters can be used to adjust the initial pruning step.
 
-    `max_iterations` specifies how much time should be spent on the simpler
-    preprocessing before applying a more complete method.
+    If `is_in_an_mts` is set, the method assumes the `candidates` are members
+    of a minimal trap space. In such case, a different simulation algorithm
+    is used for initial pruning. Furthermore, `max_iterations` can be used to
+    to limit the time spent on the initial pruning step.
 
     Parameters
     ----------
@@ -149,14 +159,14 @@ def detect_motif_avoidant_attractors(
         describing the candidate seed states.
     terminal_restriction_space : Bdd
         A symbolic set of states which contains all motif avoidant attractors
-        (i.e. if a candidate state can leave this set, the candidate cannot be
-        an attractor).
+        in question (i.e. if a candidate state can leave this set, the candidate
+        cannot be an attractor).
     max_iterations : int
         Specifies how much time should be spent on the simpler preprocessing methods.
     is_in_an_mts : bool, optional
-        By default `False`. If `True`, the the we assume that the candidates lie
+        By default `False`. If `True`, then we assume that the candidates lie
         within a minimal trap space, enabling certain optimizations. If
-        incorrectly set to `True`, correct behaviour is not guaranteed.
+        incorrectly set to `True`, the result is undefined.
 
     Returns
     -------

balm/petri_net_translation.py

@@ -116,7 +116,7 @@ def variable_to_place(variable: str, positive: bool) -> str:
 
 def place_to_variable(place: str) -> tuple[str, bool]:
     """
-    Extract the variable name and state from a Peteri net place name.
+    Extract the variable name and state from a Petri net place name.
 
     Parameters
     ----------
@@ -200,9 +200,9 @@ def restrict_petrinet_to_subspace(
     Creates a copy of the given Petri net, but with the variables given in
     `sub_space` fixed to their respective values.
 
-    Note that this completely eliminates the constant variables from the {etri
+    Note that this completely eliminates the constant variables from the Petri
     net, but it does not perform any further constant propagation or
-    percolation. Variables that are fixed in the sub_space but do not exist in
+    percolation. Variables that are fixed in the `sub_space` but do not exist in
     the Petri net are ignored.
 
     Parameters
@@ -261,7 +261,7 @@ def network_to_petrinet(
     """
     Convert a Boolean network to a Petri net.
 
-    Converts a `BooleanNetwork` to a `DiGraph` representing a Petri net encoding
+    Converts a `biodivine_aeon.BooleanNetwork` to a `DiGraph` representing a Petri net encoding
     of the original network. For details about the encoding, see module
     description.
 
@@ -270,7 +270,7 @@ def network_to_petrinet(
 
     The operation uses translation through `biodivine_aeon.Bdd` to generate a
     disjunctive normal form of the network's update functions. This is
-    facilitated by `biodivine_aeon.SymbolicContext`. If such context already
+    facilitated by `biodivine_aeon.SymbolicContext`. If a suitable context already
     exists, it can be provided as the second argument. Otherwise it will be
     created.
 

balm/space_utils.py

@@ -2,7 +2,8 @@
 Some basic utility operations on spaces (partial assignments of BN variables).
 
 Each space is represented as a dictionary with a subset of variable names as
-keys and values `0`/`1` assigned to fixed variables.
+keys and values `0`/`1` assigned to fixed variables. See also
+:class:`BooleanSpace<balm.types.BooleanSpace>`.
 """
 
 from __future__ import annotations
@@ -85,6 +86,9 @@ def dnf_function_is_true(dnf: list[BooleanSpace], state: BooleanSpace) -> bool:
     """
     Checks if a DNF function evaluates to `1` for the given state (or space).
 
+    The DNF function is represented as a list of spaces, such that each space represents
+    exactly one DNF clause.
+
     Parameters
     ----------
     dnf : list[BooleanSpace]
@@ -110,9 +114,9 @@ def remove_state_from_dnf(
     dnf: list[BooleanSpace], state: BooleanSpace
 ) -> list[BooleanSpace]:
     """
-    Removes all conjunctions that are True in the state.
+    Removes all clauses (conjunctions) that are `True` in the given `state` from a DNF function.
 
-    Returns a modified copy (i.e., it does not modify the original list).
+    The result is a new list (i.e., it does not modify the original list).
 
     Parameters
     ----------
@@ -203,7 +207,7 @@ def percolate_space(
     Percolates a space through a Boolean network.
 
     Takes a symbolic `AsynchronousGraph` and a `BooleanSpace`. It then percolates
-    any values that are effectively constant with the `network` assuming the variables
+    any values that are effectively constant within the `network` assuming the variables
     from `space` are fixed accordingly.
 
     If the argument is a trap space, then the result is a subspace of the
@@ -377,11 +381,12 @@ def restrict_expression(
         The space to restrict to.
     symbolic_context : BddVariableSet | SymbolicContext | None
         An optional symbolic context to use to perform the percolation. If not given,
-        a temporary one will be created. If given, it can be either a
-        `biodivine_aeon.SymbolicContext` or a `biodivine_aeon.BddVariableSet`.
-        If the former is given, it is converted to the latter. The context is
-        used to ensure compatibility between BDDs by ensuring that the same
-        variable names and ordering are used.
+        a temporary one will be created.
+
+        This is a `biodivine_aeon.BddVariableSet` or a `biodivine_aeon.SymbolicContext`
+        (which is automatically converted to `biodivine_aeon.BddVariableSet`).
+        The context object ensures compatibility between BDDs by
+        maintaining a shared collection of variable names and their ordering.
 
     Returns
     -------
@@ -410,7 +415,7 @@ def expression_to_space_list(
     symbolic_context: BddVariableSet | SymbolicContext | None = None,
 ) -> list[BooleanSpace]:
     """
-    Convert a Boolean expression to a list of subspaces on which it is true.
+    Convert a Boolean expression to a list of subspaces for which it is true.
 
     Equivalent to a disjunctive normal form. Convert a `BooleanExpression` to a
     list of subspaces whose union represents an equivalent set of the network
@@ -429,11 +434,12 @@ def expression_to_space_list(
         The expression to convert.
     symbolic_context : BddVariableSet | SymbolicContext | None
         An optional symbolic context to use to perform the percolation. If not given,
-        a temporary one will be created. If given, it can be either a
-        `biodivine_aeon.SymbolicContext` or a `biodivine_aeon.BddVariableSet`.
-        If the former is given, it is converted to the latter. The context is
-        used to ensure compatibility between BDDs by ensuring that the same
-        variable names and ordering are used.
+        a temporary one will be created.
+
+        This is a `biodivine_aeon.BddVariableSet` or a `biodivine_aeon.SymbolicContext`
+        (which is automatically converted to `biodivine_aeon.BddVariableSet`).
+        The context object ensures compatibility between BDDs by
+        maintaining a shared collection of variable names and their ordering.
 
     Returns
     -------

balm/succession_diagram.py

@@ -76,7 +76,7 @@ class SuccessionDiagram:
     threshold, we find a feedback vertex set (without consideration of cycle
     sign) for reachability preprocessing. There is a trade-off between the speed
     gains from a smaller node set to consider and the cost of determining which
-    FVS nodes only intersect negative cycles to find an NFVS subset. Typcially,
+    FVS nodes only intersect negative cycles to find an NFVS subset. Typically,
     for smaller networks, the trade-off is in favor of computing a smaller NFVS.
     """
 
@@ -103,7 +103,7 @@ def __init__(self, network: BooleanNetwork):
 
         self.petri_net: nx.DiGraph = network_to_petrinet(network)
         """
-        The Petri net representation of the network.
+        The Petri net representation of the network (see :mod:`petri_net_translation<balm.petri_net_translation>`).
         """
 
         if DEBUG:
@@ -306,7 +306,7 @@ def node_ids(self) -> Iterator[int]:
 
     def stub_ids(self) -> Iterator[int]:
         """
-        Iterator over all node IDs that are currently not expanded.
+        Iterator over all node IDs that are currently *not* expanded.
         """
         for i in range(len(self)):
             if not self.node_data(i)["expanded"]:
@@ -430,8 +430,8 @@ def node_data(self, node_id: int) -> NodeData:
         Returns a `NodeData` object with the following attributes:
 
         - `depth`: The depth of the node.
-        - `attractors`: The attractors of the node.
-        - `petri_net`: The Petri net representation of the node.
+        - `attractors`: The attractors of the node (if computed).
+        - `petri_net`: The Petri net representation of the node (if computed).
         - `space`: The sub-space of the node.
         - `expanded`: Whether the node is expanded or not.