Merge pull request #106 from jcrozum/succession-api-and-docs

SuccessionDiagram api improvements and docs

balm/_sd_algorithms/compute_attractor_seeds.py

@@ -30,7 +30,7 @@ def compute_attractor_seeds(
  if balm.succession_diagram.DEBUG:
  print(f"[{node_id}] Start computing attractor seeds.")
 
- node_space = sd.node_space(node_id)
+ node_space = sd.node_data(node_id)["space"]
 
  if len(node_space) == sd.network.variable_count():
  # This node is a fixed-point.
@@ -39,8 +39,8 @@ def compute_attractor_seeds(
  # Compute the list of child spaces if the node is expanded. Otherwise
  # "pretend" that there are no children.
  child_spaces = []
- if sd.node_is_expanded(node_id):
- child_spaces = [sd.node_space(s) for s in sd.node_successors(node_id)]
+ if sd.node_data(node_id)["expanded"]:
+ child_spaces = [sd.node_data(s)["space"] for s in sd.node_successors(node_id)]
 
  # Fix everything in the NFVS to zero, as long as
  # it isn't already fixed by our `node_space`.

balm/_sd_algorithms/expand_attractor_seeds.py

@@ -47,7 +47,7 @@ def expand_attractor_seeds(sd: SuccessionDiagram, size_limit: int | None = None)
 
  # Retrieve the stable motifs of children that are already expanded.
  expanded_children = [
- x for x in sd.node_successors(node) if sd.node_is_expanded(x)
+ x for x in sd.node_successors(node) if sd.node_data(x)["expanded"]
  ]
  expanded_motifs = [
  sd.edge_stable_motif(node, child) for child in expanded_children
@@ -61,15 +61,15 @@ def expand_attractor_seeds(sd: SuccessionDiagram, size_limit: int | None = None)
  # and continue to the next one.
  successors.pop()
  continue
- if sd.node_is_expanded(successors[-1]):
+ if sd.node_data(successors[-1])["expanded"]:
  # The next node to explore is expanded (by some previous procedure)
  # but not "seen" in this search yet. We need to visit this node
  # regardless of other conditions
  break
  # Now, we need to asses if the next successor has some candidate states which
  # are not covered by the already expanded children.
 
- successor_space = sd.node_space(successors[-1])
+ successor_space = sd.node_data(successors[-1])["space"]
  retained_set = make_retained_set(
  sd.symbolic, sd.node_nfvs(node), successor_space
  )

balm/_sd_algorithms/expand_minimal_spaces.py

@@ -34,7 +34,7 @@ def expand_minimal_spaces(sd: SuccessionDiagram, size_limit: int | None = None)
  successors = sorted(successors, reverse=True) # For determinism!
  # (reversed because we explore the list from the back)
 
- node_space = sd.node_space(node)
+ node_space = sd.node_data(node)["space"]
 
  # Remove all immediate successors that are already visited or those who
  # do not cover any new minimal trap space.
@@ -52,7 +52,7 @@ def expand_minimal_spaces(sd: SuccessionDiagram, size_limit: int | None = None)
  # of this node is already in the succession diagram.
  if len(successors) == 0:
  if sd.node_is_minimal(node):
- minimal_traps.remove(sd.node_space(node))
+ minimal_traps.remove(sd.node_data(node)["space"])
  continue
 
  # At this point, we know that `s` is not visited and it contains

balm/_sd_algorithms/expand_to_target.py

@@ -25,7 +25,7 @@ def expand_to_target(
 
  while len(current_level) > 0:
  for node in current_level:
- node_space = sd.node_space(node)
+ node_space = sd.node_data(node)["space"]
 
  if intersect(node_space, target) is None:
  # If `node_space` does not intersect with `target`, it is not relevant

balm/control.py

@@ -58,7 +58,7 @@ def __init__(
  Example
  -------
  >>> import balm
- >>> sd = balm.SuccessionDiagram.from_bnet(
+ >>> sd = balm.SuccessionDiagram.from_rules(
  ... \"\"\"
  ... A, B & C
  ... B, A & C
@@ -87,7 +87,7 @@ def __init__(
  self._control: list[ControlOverrides] = []
  for c in control:
  cs = sorted(map(lambda x: sorted(x.items()), c))
- self._control.append(list(map(dict, cs)))
+ self._control.append(list(map(dict, cs))) # type: ignore
 
  self._strategy = strategy
  self._succession = succession
@@ -198,7 +198,7 @@ def succession_control(
  -------
  >>> import balm
  >>> from balm.control import succession_control
- >>> sd = balm.SuccessionDiagram.from_bnet(
+ >>> sd = balm.SuccessionDiagram.from_rules(
  ... \"\"\"
  ... S, S
  ... A, S | B
@@ -237,7 +237,7 @@ def succession_control(
  -------
  >>> import balm
  >>> from balm.control import succession_control
- >>> sd = balm.SuccessionDiagram.from_bnet(
+ >>> sd = balm.SuccessionDiagram.from_rules(
  ... \"\"\"
  ... S, S
  ... A, S | B
@@ -335,7 +335,7 @@ def successions_to_target(
  )
 
  for s in succession_diagram.node_ids():
- fixed_vars = succession_diagram.node_space(s)
+ fixed_vars = succession_diagram.node_data(s)["space"]
  if not is_subspace(fixed_vars, target):
  continue
 

balm/drivers.py

@@ -40,7 +40,7 @@ def find_single_node_LDOIs(
  Example
  _______
  >>> import balm
- >>> sd = balm.SuccessionDiagram.from_bnet('A, A\\nB, A')
+ >>> sd = balm.SuccessionDiagram.from_rules('A, A\\nB, A')
  >>> ldois = balm.drivers.find_single_node_LDOIs(sd.network)
  >>> for k in sorted(ldois):
  ... print(f'{k} ==> {sorted(ldois[k].items())}')
@@ -107,7 +107,7 @@ def find_single_drivers(
  Example
  -------
  >>> import balm
- >>> sd = balm.SuccessionDiagram.from_bnet('A, A\\nB, A')
+ >>> sd = balm.SuccessionDiagram.from_rules('A, A\\nB, A')
  >>> drivers = balm.drivers.find_single_drivers({'B': 0}, sd.network)
  >>> sorted(list(drivers))
  [('A', 0), ('B', 0)]

balm/interaction_graph_utils.py

@@ -96,7 +96,7 @@ def feedback_vertex_set(
  --------
  >>> import balm
  >>> from balm.interaction_graph_utils import feedback_vertex_set
- >>> sd = balm.SuccessionDiagram.from_bnet(\"\"\"
+ >>> sd = balm.SuccessionDiagram.from_rules(\"\"\"
  ... A, B
  ... B, A
  ... C, D

balm/motif_avoidant.py

@@ -1,5 +1,5 @@
 """
- A module responsible for detecting motif-avoidant attractors within terminal restriction space.
+A module responsible for detecting motif-avoidant attractors within terminal restriction space.
 """
 
 from __future__ import annotations
@@ -103,13 +103,16 @@ def detect_motif_avoidant_attractors(
  """
  Compute a sub-list of `candidates` which correspond to motif-avoidant
  attractors. Other method inputs:
- - `graph` and `petri_net` represent the model in which the property
- should be checked.
- - `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).
- - `max_iterations` specifies how much time should be spent on the "simpler"
- preprocessing before applying a more complete method.
+
+ `graph` and `petri_net` represent the model in which the property
+ should be checked.
+
+ `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).
+
+ `max_iterations` specifies how much time should be spent on the "simpler"
+ preprocessing before applying a more complete method.
  """
  if ensure_subspace is None:
  ensure_subspace = {}