Commit 90aa4741 authored by VIGNET Pierre's avatar VIGNET Pierre

[doc] Fix main sphinx warnings...

parent a77fad40
......@@ -352,7 +352,7 @@ def queries_2_common_graph(output_dir, model_file, path,
Create a GraphML formated file containing a unique representation of **all**
trajectories corresponding to all solutions in each complete MAC files
(*mac_complete files).
(\*mac_complete files).
This is a function to visualize paths taken by the solver from the boundaries
to the entities of interest.
......
......@@ -253,22 +253,22 @@ def get_solutions_graph_data(G, info, centralities):
Doc::
https://networkx.github.io/documentation/networkx-1.10/reference/algorithms.component.html
https://networkx.github.io/documentation/stable/reference/algorithms/shortest_paths.html
average_shortest_path_length
https://networkx.github.io/documentation/stable/reference/algorithms/generated/networkx.algorithms.shortest_paths.generic.average_shortest_path_length.html#networkx.algorithms.shortest_paths.generic.average_shortest_path_length
weakly_connected_component_subgraphs
https://networkx.github.io/documentation/networkx-1.10/reference/generated/networkx.algorithms.components.weakly_connected.weakly_connected_component_subgraphs.html#networkx.algorithms.components.weakly_connected.weakly_connected_component_subgraphs
Measures
https://networkx.github.io/documentation/stable/reference/algorithms/index.html
https://networkx.github.io/documentation/networkx-1.10/reference/algorithms.component.html
https://networkx.github.io/documentation/stable/reference/algorithms/shortest_paths.html
average_shortest_path_length
https://networkx.github.io/documentation/stable/reference/algorithms/generated/networkx.algorithms.shortest_paths.generic.average_shortest_path_length.html#networkx.algorithms.shortest_paths.generic.average_shortest_path_length
weakly_connected_component_subgraphs
https://networkx.github.io/documentation/networkx-1.10/reference/generated/networkx.algorithms.components.weakly_connected.weakly_connected_component_subgraphs.html#networkx.algorithms.components.weakly_connected.weakly_connected_component_subgraphs
Measures
https://networkx.github.io/documentation/stable/reference/algorithms/index.html
By default the following information are added::
- graph_nodes: Number of nodes
- graph_edges: Number of edges
- graph_nodes_places: Number of biological places/entities.
The graph is a false bipartite graph, we remove the subset of transitions
in order to have the real count of biological places/entities.
The graph is a false bipartite graph, we remove the subset of transitions
in order to have the real count of biological places/entities.
If centralities is True, the folliwing information are added to the a new
key named "centralities"::
......
......@@ -43,6 +43,7 @@
Collection of widgets for properties checking
Classes:
- :class:`ChartChecker`: GUI interface for query checking
- :class:`QueryCheckingForm`: Main form of ChartChecker Window
- :class:`SolutionWindow`: Show solutions found by the solver
......@@ -930,10 +931,11 @@ class PropertyVisitor(object):
Retain only subnodes if they are in a binary expression linked by a logical "and".
Because:
- not (a or b) is valid only if a and b are False;
thus we don't care of a and b
thus we don't care of a and b
- not (a and b) is valid only if a or b are True, or if a and b are False;
thus a and b can be True alternately and it is sufficient for us.
thus a and b can be True alternately and it is sufficient for us.
"""
# print("not node:", str(node))
root = self.root
......
......@@ -227,10 +227,11 @@ class SearchManager(object):
def on_extract(self, widget):
"""Extract nodes environment
- Get selected nodes
- Get all transitions of interest:
- ori and ext nodes are concerned
- ori or ext are concerned and the second node is a Start/Trap node
- ori and ext nodes are concerned
- ori or ext are concerned and the second node is a Start/Trap node
"""
if not self.model:
return
......
......@@ -43,12 +43,12 @@ Main views for the Cadbiom gui
Classes available and inheritance hierarchy:
gtk.DrawingArea
ChartView: Used by the graph editor window/page of charter
NavView: overview widget
gtk.DrawingArea:
:class:`ChartView`: Used by the graph editor window/page of charter
:class:`NavView`: overview widget
gtk.Frame
ChartPage: Graph editor window/page of charter
gtk.Frame:
:class:`ChartPage`: Graph editor window/page of charter
"""
import gtk
......@@ -58,18 +58,18 @@ class ChartView(gtk.DrawingArea):
.. note:: Also instanciated by the overview widget.
.. note:: DrawingArea can capture key-press-events::
.. note:: DrawingArea can capture key-press-events:
- add gtk.gdk.KEY_PRESS_MASK mask to event
- be sure that the DrawingArea has the focus by using grab_focus() on
mouse events.
mouse events.
.. TODO:: Optimize events handling::
.. TODO:: Optimize events handling:
- on_motion_notify: Mouse over the widget, causing multiple calls to
find_element() of the top node.
find_element() of the top node.
- on_expose_event: When the window is covered/partially covered;
all the pixmap is redrawn.
all the pixmap is redrawn.
"""
def __init__(self, width, height, drawing_style, controler, model):
......
......@@ -55,7 +55,7 @@ def logger(name=LOGGER_NAME, logfilename=None):
Equivalent of logging.getLogger() call.
:Example:
:Example::
cm.logger(name=__name__)
......@@ -89,6 +89,7 @@ _logger.addHandler(stream_handler)
def log_level(level):
"""Set terminal/file log level to given one.
.. note:: Don't forget the propagation system of messages:
From logger to handlers. Handlers receive log messages only if
the main logger doesn't filter them.
......
......@@ -171,12 +171,14 @@ class CLDynSys(object):
/!\ Should not be used after adding the clauses by GT2Clauses (?)
:Examples:
:Examples::
{'PGK_cGMP_active': ('state', 0), ...}
{'input_place': ('input', 0), ...}
{'A': ('state', 0), ...}
:Completed by MCLTranslator with add_free_clock():
:Completed by MCLTranslator with add_free_clock()::
{"_h_0000": ('clock', -1)}
:param report: Reporter for error reporting.
......@@ -197,9 +199,10 @@ class CLDynSys(object):
Added from MCLTranslator.
:param place_clocks: Dictionary of clocks as keys and places as values.
Association between a clock and an inductive place:
clock h -> [place P, ...] where P is a place preceding free clock h
`clock h -> [place P, ...]` where P is a place preceding free clock h.
:Example::
:Example:
{"_h_2772": ["BTG2_gene", ...]}
:param inputs: Other inputs
......@@ -229,15 +232,14 @@ class CLDynSys(object):
Added to base_var_set
Auxiliary variables: They are named by adding a value incremented at their end.
Added to base_var_set
Ex: "_lit00000"
Ex: `"_lit00000"`
Free clock variables: Their names are preserved from the model.
Added to base_var_set
Added to free_clocks
Added to the dict symb_tab:
Ex: {"_h_0000": ('clock', -1)}
Added to the dict symb_tab: Ex: `{"_h_0000": ('clock', -1)}`
Place clocks:
Added to place_clocks:
Ex: {"_h_2772": ["BTG2_gene", ...]}
Added to place_clocks::
Ex: `{"_h_2772": ["BTG2_gene", ...]}`
Input variables: Their names are "supposed to be" preserved from the model.
Added to base_var_set
Added to inputs (May be added multiple times ?)
......@@ -269,9 +271,11 @@ class CLDynSys(object):
self.lit_compt = 0 # for auxiliary variables generation
def add_var(self, name):
"""add a logical variable to the dynamic system
@param name: the name of the variable (string)
All entities of the model are added here
"""Add a logical variable to the dynamic system
All entities of the model are added here
:param name: the name of the variable (string)
"""
if name in self.base_var_set:
return
......@@ -290,9 +294,13 @@ class CLDynSys(object):
def add_free_clock(self, hname):
"""add a free clock variable
@param hname: the name of the clock variable (string)
:param hname: the name of the clock variable (string)
Free clocks are associated to the value ('clock', -1) in self.symb_tab
ex: {"_h_0000": ('clock', -1)}
:Example::
{"_h_0000": ('clock', -1)}
"""
if hname in self.base_var_set:
......@@ -318,7 +326,7 @@ class CLDynSys(object):
def add_clause(self, clause):
"""add a clause constraint
PS: How to debug a clause:
PS: How to debug a clause::
cla_str = str(clause)
if "_h_0" in cla_str or "A" in cla_str: print(cla_str)
......
......@@ -45,9 +45,10 @@ Main class to perform dynamic analysis of Cadbiom chart models.
Discrete event system simulation is a standard simulation scheme which consists
in the repetition of the following actions until some halting condition
is satisfied:
- Find the current events and inputs (including free events)
- Find the state variables subject to change
- Perform the state evolution
- Find the current events and inputs (including free events)
- Find the state variables subject to change
- Perform the state evolution
## Here you will find a global view of the process of dynamic analysis
......@@ -84,14 +85,12 @@ __mac_exhaustive_search:
Pour bannir les solutions 2 choix se présentent:
- Soit les joindre par des "and" logiques et contraindre chaque solution
par un "non".
Ex: Pour 2 solutions [(A, B), (B, C)]:
not((A and B) or (B and C))
par un "non".
Ex: Pour 2 solutions `[(A, B), (B, C)]`: `not((A and B) or (B and C))`
- Soit conserver les valeurs de chaque ensemble de places frontière sous
forme de clauses constituées de valeurs numériques.
Ex: Pour 2 solutions [(A, B), (B, C)]:
[[-1, -2], [-2, -3]]
forme de clauses constituées de valeurs numériques.
Ex: Pour 2 solutions `[(A, B), (B, C)]`: `[[-1, -2], [-2, -3]]`
La deuxième solution est nettement plus performante car elle permet de
s'affranchir du travail de parsing réalisé par l'intervention d'une grammaire,
......@@ -576,42 +575,47 @@ class MCLAnalyser(object):
"""Compute active frontier places and timings
Compute the set of frontier place names which must be activated for
implying query satisfaction and returned it as a list of FrontierSolution.
implying query satisfaction and returned it as a list of `FrontierSolution`.
Quiet deprecated but referenced by:
gt_gui/chart_checker/chart_checker_controler
cadbiom_cmd/solution_search.py very old code for debug purpose
self.mac_inhibitor_search
- `gt_gui/chart_checker/chart_checker_controler`
- `cadbiom_cmd/solution_search.py` very old code for debug purpose
:meth:`mac_inhibitor_search`
In models of signal propagation, we are more interested in frontier solutions.
So the current method is better adapted: sq_frontier_solutions()
than sq_solutions() which returns RawSolutions.
So the current method is better adapted than :meth:`sq_solutions`
which returns `RawSolutions`.
This function is a wrapper of sq_solutions().
This function is a wrapper of :meth:`sq_solutions`.
The class FrontierSolution provides objects wrapping a symbolic
The class `FrontierSolution` provides objects wrapping a symbolic
representation of frontier values and timing from a raw solution.
- The main attributes are activated_frontier which is a set of
(string) names of frontier places which are activated in the solution.
(string) names of frontier places which are activated in the solution.
- The second important attribute is ic_sequence, a list of strings
which describes the successive activated inputs and free events in
the solution.
which describes the successive activated inputs and free events in
the solution.
If events h2, h5 and input in3 are activated at step k in the solution,
then the kth element of the list is “% h2 h5 in3”.
This format is understood by the Cadbiom simulator.
@warning: no frontier places are initialized to False
.. warning:: no frontier places are initialized to False
@param query: MCLSimpleQuery
@param max_step: int - Number of steps allowed in the unfolding;
:param query: Query
:param max_step: int - Number of steps allowed in the unfolding;
the horizon on which the properties must be satisfied
@param max_sol: max number of wanted solutions.
@return: List of FrontierSolutions built from RawSolutions from the solver.
:param max_sol: max number of wanted solutions.
:type query: MCLSimpleQuery
:type max_step: <int>
:type max_sol: <int>
:return: List of FrontierSolutions built from RawSolutions from the solver.
So, lists of lists of frontier place names which must be activated
for implying query satisfaction
for implying query satisfaction.
:rtype: <list <FrontierSolution>>
"""
vvars = self.unfolder.frontier_values
......@@ -832,10 +836,10 @@ class MCLAnalyser(object):
.. note:: __mac_exhaustive_search() returns DimacsFrontierSols
@param query: MCLSimpleQuery
@param max_step: int - Number of steps allowed in the unfolding;
:param query: MCLSimpleQuery
:param max_step: int - Number of steps allowed in the unfolding;
the horizon on which the properties must be satisfied
@return: <generator <FrontierSolution>>
:return: <generator <FrontierSolution>>
"""
## TODO: convert start_property in dim_start !! => eviter la recompilation des propriétés
# Get <generator <DimacsFrontierSol>>
......
......@@ -55,11 +55,11 @@ class MCLSimpleQuery(object):
Object containing 2 main types of attributes describing properties:
- Attributes in text format: These are logical formulas that are humanly
readable.
Ex: start_prop, inv_prop, final_prop, variant_prop
readable.
Ex: `start_prop, inv_prop, final_prop, variant_prop`
- Attributes in DIMACS format: These are logical formulas encoded in
the form of clauses containing numerical values.
Ex: dim_start, dim_inv, dim_final, dim_variant
the form of clauses containing numerical values.
Ex: `dim_start, dim_inv, dim_final, dim_variant`
Textual properties of query are compiled into numeric clauses in the unfolder
with init_forward_unfolding(), just at the beginning of squery_is_satisfied()
......@@ -72,15 +72,18 @@ class MCLSimpleQuery(object):
:param final_prop: final property; logical formulas
:param variant_prop: list of logical formulas from ic_sequence.
It's the trajectory of events of a solution.
:Example:
:Example::
['', 'h2 and h2', '', 'h2']
:param dim_start: start property in DIMACS form - optional
:param dim_inv: invariant property in DIMACS form - optional
:param dim_final: final property in DIMACS form - optional
:param dim_variant: list of lists of dimacs clauses
:Example:
:Example::
[[[16], [16]], [[22], [22]]]
:param steps_before_check: Number of shifts before testing the
final property - optional
......@@ -304,13 +307,13 @@ class MCLSimpleQuery(object):
- start, invariant and final properties are merged.
- If both queries have variant properties, they must be on the same horizon
(number of steps).
(number of steps).
- steps before reach is set to zero.
- dim properties are also merged: dim_start, dim_inv, dim_final
@param query: a MCLSimpleQuery
@raise MCLException: if the queries have variant properties on
different horizons.
:param query: a MCLSimpleQuery
:raises: `MCLException` If the queries have variant properties with
different horizons (nb of steps).
"""
# merge of start properties
if not self.start_prop:
......
......@@ -41,14 +41,14 @@
##
"""Classes used to store solver answers.
RawSolution:
:class:`RawSolution`:
Contain a solution got from SAT solver with all variable parameters
from the unfolder.
DimacsFrontierSol:
:class:`DimacsFrontierSol`:
A numerical representation of *frontier values and timings* from a raw solution.
FrontierSolution:
:class:`FrontierSolution`:
Provides is a wrapper for a symbolic
representation (human readable) of activated frontiers defined in
RawSolution and DimacsFrontierSol objects.
......@@ -431,15 +431,16 @@ class FrontierSolution(object):
RawSolution and DimacsFrontierSol objects.
Attributes:
- The main attributes are activated_frontier which is a set of
(string) names of frontier places which are activated in the solution.
(string) names of frontier places which are activated in the solution.
- The second important attribute is ic_sequence, a list of strings
which describes the successive activated inputs and free events in
the solution.
which describes the successive activated inputs and free events in
the solution.
- current_step is the number of steps used during the unfolding that made
the solution.
the solution.
If events h2, h5 and input in3 are activated at step k in the solution,
then the kth element of the list is “% h2 h5 in3”.
......@@ -449,10 +450,10 @@ class FrontierSolution(object):
:type ic_sequence: <list <str>>
:type current_step: <int>
..TODO::
.. TODO::
- Faire une super classe dont héritent RawSolution et DimacsFrontierSol
pour éviter la duplication de code et le stockage d'attributs qu'on
connait déjà dans les types de plus bas niveaux...
pour éviter la duplication de code et le stockage d'attributs qu'on
connait déjà dans les types de plus bas niveaux...
- ... Ou détecter le type d'objet dans le constructeur => ducktyping
- renommer l'attr activated_frontier en activated_frontiers
"""
......@@ -671,12 +672,14 @@ class DimacsFrontierSol(object):
Dimacs solution.
This attribute is precomputed because it is used intensively and
multiple times for each object in:
MCLAnalyser.less_activated_solution
MCLAnalyser.__prune_frontier_solution
MCLAnalyser.__mac_exhaustive_search
- MCLAnalyser.less_activated_solution
- MCLAnalyser.__prune_frontier_solution
- MCLAnalyser.__mac_exhaustive_search
:param activated_frontier_values: Values of activated frontier places
in the current Dimacs solution.
Convenient attribute used:
- by FrontierSolution.from_dimacs_front_sol()
- to accelerate the call of self.nb_activated_frontiers
- as a criterion of uniqueness, to do set operations
......
......@@ -487,7 +487,8 @@ def test_init_unfolder(feed_mclanalyser):
def test_init_forward_unfolding_solution_1_text(feed_mclanalyser, textual_properties):
"""
Query:
Query::
start, invariant, final: ("M", "L", "C")
No solution (because inhibitor M is activated)
"""
......@@ -507,7 +508,8 @@ def test_init_forward_unfolding_solution_1_text(feed_mclanalyser, textual_proper
def test_init_forward_unfolding_solution_1_dimacs(feed_mclanalyser, numeric_properties):
"""
Query:
Query::
dim_start, dim_inv, dim_final = [[13]], [[12]], [[3]]
DIMACS equiv of: start, invariant, final: ("M", "L", "C"):
No solution (because inhibitor M is activated)
......@@ -544,7 +546,8 @@ def test_init_forward_unfolding_solution_1_dimacs(feed_mclanalyser, numeric_prop
def test_init_forward_unfolding_solution_2_text(feed_mclanalyser, textual_properties):
"""
Query:
Query::
start, invariant, final: ("", "L", "C and K")
Solution: D E F I L
"""
......@@ -567,7 +570,8 @@ def test_init_forward_unfolding_solution_2_text(feed_mclanalyser, textual_proper
def test_init_forward_unfolding_solution_2_dimacs(feed_mclanalyser, numeric_properties):
"""
Query:
Query::
dim_start, dim_inv, dim_final = [], [[12]], [[3, -47], [11, -47], [-3, -11, 47], [47]]
DIMACS equiv of: start, invariant, final: ("", "L", "C and K")
Solution: D E F I L
......@@ -590,7 +594,8 @@ def test_init_forward_unfolding_solution_2_dimacs(feed_mclanalyser, numeric_prop
def test_init_forward_unfolding_solution_3(feed_mclanalyser, textual_properties, numeric_properties):
"""
Query:
Query::
start, invariant, final: Union of textual and DIMACS properties:
("", "L", "C and K") => [], [[12]], [[3, -47], [11, -47], [-3, -11, 47], [47]]
[[13]], [[12]], [[3]] <= ("M", "L", "C")
......@@ -629,7 +634,8 @@ def test_init_forward_unfolding_solution_3(feed_mclanalyser, textual_properties,
def test_init_forward_unfolding_solution_4(feed_mclanalyser, textual_properties):
"""
Query:
Query::
start, invariant, final: ("", "", "C")
Solutions: D E F L, D E F I
"""
......@@ -656,7 +662,8 @@ def init_forward_unfolding_solution_1(mcla, dimacs_check=True):
- Test first part of init_forward_unfolding: init of constraints
- Test second part of init_forward_unfolding: shift of initialized constraints
Query:
Query::
start, invariant, final: ("M", "L", "C")
No solution (because inhibitor M is activated)
......@@ -783,7 +790,8 @@ def init_forward_unfolding_solution_2(mcla):
- Test first part of init_forward_unfolding: init of constraints
- Test second part of init_forward_unfolding: shift of initialized constraints
Query:
Query::
start, invariant, final: ("", "L", "C and K")
Solution: D E F I L
"""
......@@ -893,7 +901,8 @@ def init_forward_unfolding_solution_3(mcla, dimacs_check=True):
- Test first part of init_forward_unfolding: init of constraints
- Test second part of init_forward_unfolding: shift of initialized constraints
Query:
Query::
start, invariant, final: Union of textual and DIMACS properties:
("", "L", "C and K") => [], [[12]], [[3, -47], [11, -47], [-3, -11, 47], [47]]
[[13]], [[12]], [[3]] <= ("M", "L", "C")
......@@ -956,7 +965,8 @@ def init_forward_unfolding_solution_4(mcla):
- Test first part of init_forward_unfolding: init of constraints
- Test second part of init_forward_unfolding: shift of initialized constraints
Query:
Query::
start, invariant, final: ("", "", "C")
Solutions: F E L D, D E F I
"""
......@@ -992,7 +1002,8 @@ def init_forward_unfolding_solution_4(mcla):
def test_init_forward_unfolding_solution_5(feed_mclanalyser):
"""Test variant_prop, dim_variant attributes of a query and their solutions
Query:
Query::
variant text: ["_h4 and _h2 and _h3", "_h5", "_h_0"]
variant DIMACS: [[[18], [16], [17]], [[19]], [[22]]]
Solution: D E I (not D E F I)
......
......@@ -248,8 +248,7 @@ class TestMCLAnaLyzer(unittest.TestCase):
self.assert_(not res, 'Error in C3 and C4')
def test_delay1_w_ic(self):
"""
simple delay computation with clock sequence
"""Simple delay computation with clock sequence
First test: f_prop = "C4"
# old solver
......@@ -297,17 +296,18 @@ class TestMCLAnaLyzer(unittest.TestCase):
.. note:: Debugging of solutions - help:
for i, sol in enumerate(lsol, 1):
print("Sol", i)
# [[], [], [], []]
print(sol.extract_act_input_clock_seq())
# [[....], [....], [....], [....]]
print(x.unflatten())
.. code-block:: python
# Convert literal values to str, display only activated ones (val > 0)
for step in sol.unflatten():
print([sol.unfolder.get_var_name(val) for val in step
if val > 0])
for i, sol in enumerate(lsol, 1):
print("Sol", i)
# [[], [], [], []]
print(sol.extract_act_input_clock_seq())
# [[....], [....], [....], [....]]
print(x.unflatten())
# Convert literal values to str, display only activated ones (val > 0)
for step in sol.unflatten():
print([sol.unfolder.get_var_name(val) for val in step if val > 0])
"""
def debug_solutions(lsol):
......
......@@ -38,24 +38,24 @@
##
"""Visitors for guarded transition model analysis
Visitors::
Visitors:
- :class:`TableVisitor`: used to collect action and place declarations of a model
- :class:`FrontierVisitor`: Simple frontier computation for editor
- :class:`IndirectFlowGraphBuilder`: build a networkx indirect graph of transitions
(for debugging only)
(for debugging only)
- :class:`DirectFlowGraphBuilder`: build a networkx graph of transitions
(for tests only)
(for tests only)
- :class:`EstimExpVisitor`: Partial Evaluator of event and condition expressions
(subset of sig expressions)
(subset of sig expressions)
- :class:`SigExpIdCollectVisitor`: Collect idents in a sig expression
.. note:: 2 more visitors are kept elsewhere for practical reasons and for now at:
- :meth:`cadbiom.models.clause_constraints.mcl.CLUnfolder.PropertyVisitor`
(involve Clause and Literals).
- :meth:`cadbiom.models.clause_constraints.mcl.CLUnfolder.PropertyVisitor`
(involve Clause and Literals).
- :meth:`cadbiom_gui.gt_gui.chart_checker.chart_checker_controler.PropertyVisitor`
(used to get mandatory nodes in conditions of transitions)
(used to get mandatory nodes in conditions of transitions)
"""
......
......@@ -126,22 +126,25 @@ class StaticAnalyzer(object):
def get_gene_places(self):
"""Return gene places