Syntax (#21)

* Modified description: more abstract

* Updated example folder

* Fix file names

* Change proper name of areas

* Change vocabulary in main file

* Change vocabulary in test files

README.md

@@ -35,9 +35,9 @@
 
 **GRAPE** (GRAph Parallel Environment) is a Python package that takes advantage of **Graph Theory** into a *High Performance Computing* (HPC) environment to develope a screening tool aimed at studying the effect of different kinds of perturbations in interconnected systems, such as industrial plants.
 
-The tool allows to represent the dependencies between components and predict the state of health and the residual functionality of degradable systems after a casualty, suggesting the proper reconfiguration strategies to mitigate the damage. The results obtained from the graph analysis can be therefore used to improve topology, robustness, and resilience profile of industrial facilities against domino effect propagation.
+The package represents the dependencies between graph elements and predicts the effects of a perturbation. The results obtained from the graph analysis can be therefore used to improve the robustness, and resilience profile of industrial facilities against domino effect propagation.
 
-In particular, the components contribution to the cascade effects resulting from adverse events can be evaluated through centrality and efficiency measures, highlighting the plants major criticalities, vulnerabilities and potential weak points.
+In particular, the contribution to the cascade effects resulting from adverse events can be evaluated through centrality and efficiency measures, highlighting the plants major criticalities, vulnerabilities and potential weak points.
 
 Considering that the most computationally expensive parts of the program involve the calculation of shortest paths, parallelization of shortest path computation in large unweighted graphs was integrated in the program. This was done taking advantage of the Python modules multiprocessing and threading. Two different sequential algorithms for the solution of the shortest path problem have been parallelized including a Single Source Shortest Path (SSSP) algorythm for sparse graphs and an All Pairs Shortest Path one (APSP) for dense graphs.
 

examples/Room_damage/README.md → examples/Area_perturbation/README.md

@@ -2,100 +2,100 @@
 
 The input for the graph construction currently 
 consists of text files reflecting the hierarchy of
-the plant components and their features.
+the plant elements and their features.
 In the text input files each line corresponds 
-to a node/component description. 
+to a node/element description. 
 The same line reports the name of the predecessor 
-of a particular node/component, 
+of a particular node/element, 
 the relationship between them, and the list of 
-node’s attributes (room in which the component is 
+node’s attributes (area in which the element is 
 present, perturbation resistance, etc.).
 In this way each line corresponds to an edge
-connecting a component to its parent component.
+connecting a element to its parent element.
 
 Each line should contain the following info:
-- component id (**Mark**)
-- parent of the component id (**father_mark**)
+- element id (**Mark**)
+- parent of the element id (**father_mark**)
 - parent-child relationship 
 (**father_cond**: *AND*, *OR*, *SINGLE*, *ORPHAN*. It is an edge attribute.)
-- type of component 
-(**Description**: *isolation_A*, *isolation_B* are isolating components 
+- type of element 
+(**Description**: *isolation_A*, *isolation_B* are isolating elements 
 with opposite behaviour. It is a node attribute.)
-- state of the isolating component 
+- state of the isolating element 
 (**InitStatus**: *1*, *0*. It is a node attribute.)
-- room in which the component is located 
+- area in which the element is located 
 (**Area**. It is a node attribute.)
-- component external perturbation resistance 
+- element external perturbation resistance 
 (**PerturbationResistant**: *1*, *0*. It is a node attribute.)
-- source - target components 
+- source - target elements 
 (**From_to**: *SOURCE* or *TARGET*. It is a node attribute.)
 
-The hierarchy of the components explains how commodities
-flow from one component to another component
+The hierarchy of the elements explains how commodities
+flow from one element to another element
 and from one system to another system. 
 In fact, if the input is properly formatted, with this
 simple digraph model it is possible to represent and 
 integrate different interconnected plants
 in a unique graph without losing information about 
 their peculiarities. 
 
-In the graph, the nodes represent the system components 
+In the graph, the nodes represent the system elements 
 while the edges connecting the nodes harbor the logic 
-relations (edge attributes) existing between the components 
+relations (edge attributes) existing between the elements 
 (*ORPHAN*, *SINGLE*, *AND*, and *OR*).
 - An **ORPHAN** edge is the edge of a node without predecessors.
 - A **SINGLE** edge connects a node to its only one predecessor.
-- An **AND** edge indicates that the node/component 
+- An **AND** edge indicates that the node/element 
 has more than one predecessor. All the predecessors are 
-necessary for the functioning of that component.
-- An **OR** edge indicates that the node/component has 
+necessary for the functioning of that element.
+- An **OR** edge indicates that the node/element has 
 more than one predecessor. Just one of the node’s 
 predecessors should be active to guarantee the functioning 
-of the component.
+of the element.
 For this reason, correct input formatting 
 is one of the most important steps of the analysis.
 
 ## Example
 
 In the cartoon is represented the example input file `TOY_graph.csv `.
-In this file are present 19 nodes/components connected by
+In this file are present 19 nodes/elements connected by
 direct edges that reflect the hierarchy of the system 
 in a parent-child fashion.
 
-The nodes are disributed in adjacent rooms.
+The nodes are disributed in adjacent areas.
 
-In room1 are present 5 nodes: 1, 2, 3, 4 and 5.
+In area1 are present 5 nodes: 1, 2, 3, 4 and 5.
 
-In room2 are present nodes: 11, 19, 12, 13, 14 and 18.
+In area2 are present nodes: 11, 19, 12, 13, 14 and 18.
 
-In room3 are present nodes: 15, 9, 16, 17 and 10.
+In area3 are present nodes: 15, 9, 16, 17 and 10.
 
-In room4 are present nodes: 6, 7 and 8.
+In area4 are present nodes: 6, 7 and 8.
 
-A damage of one or multiple components in one room
-may exceed the room boundaries and propagate
+A perturbation of one or multiple elements in one area
+may exceed the area boundaries and propagate
 to other systems connected to it, located in other
-rooms. 
+areas. 
 
 Nodes 1, 2, 3, 4, 5 are perturbation resistant nodes 
 ("PerturbationResistant" field = "1").
 These nodes will not be affected by the simulated
 perturbation.
 
-Nodes 2 and 3 are isolating components ("Description field" =
-"isolation_A"). In the figure, damaging node 1 would result 
+Nodes 2 and 3 are isolating elements ("Description field" =
+"isolation_A"). In the figure, perturbing node 1 would result 
 in the breakage of all the nodes present in the graph except 
-node 15 in absence of isolating components. On the other hand, 
-isolating components 2 and 3 would stop the damage propagation
+node 15 in absence of isolating elements. On the other hand, 
+isolating elements 2 and 3 would stop the perturbation propagation
 cascade to node 1.
 
 !["TOY graph"](TOY_graph.png )
 
-### Simulate a damage in room 'room1' 
+### Simulate a perturbation in area 'area1' 
 
 1. In file `general_graph.py`:
 
-* Uncomment  `g.simulate_multi_room_perturbation(['room1']) `.
+* Uncomment  `g.simulate_multi_area_perturbation(['area1']) `.
 
 * Uncomment  `g.check_input_with_gephi() `.
 
@@ -106,23 +106,23 @@ cascade to node 1.
 
 # Output description:
 
-### room_perturbation.csv
+### area_perturbation.csv
 
-In this table is listed the new status of the components 
-(active, not-active) and the rooms in which the components 
+In this table is listed the new status of the elements 
+(active, not-active) and the areas in which the elements 
 are located (affected, not affected) as well as the new status
-of components that have been operated to stop the 
-propagation of the damage or to open new paths
+of elements that have been operated to stop the 
+propagation of the perturbation or to open new paths
 in case of unavailabilty of the default ones. 
 The efficiency (*nodal efficiency*, *local efficiency*, *global efficiency*)
 and closeness indices (*closeness_centrality*, *betweenness_centrality*, 
 *indegree_centrality*) are then recalculated.
 
-### service_paths_multi_room_perturbation.csv
+### service_paths_multi_area_perturbation.csv
 
 In this table are reported the paths (all paths and shortest paths), if any, 
-that connect source and target components.
-Paths are calculated before and after damaging one or multiple components.
+that connect source and target elements.
+Paths are calculated before and after perturbing one or multiple elements.
 
 ### general_code_output.log
 

examples/Area_perturbation/input_file/TOY_graph.csv

@@ -0,0 +1,30 @@
+,"Mark","Father_cond","Father_mark","Area","PerturbationResistant","InitStatus","Description","From_to"
+,"1","ORPHAN","NULL","area1","1",,,
+,"2","SINGLE","1","area1","1","1","isolation_A",
+,"3","SINGLE","1","area1","1","1","isolation_A",
+,"4","SINGLE","2","area1","1",,,
+,"5","SINGLE","3","area1","1",,,
+,"6","SINGLE","4","area4","0",,,
+,"6","SINGLE","7","area4","0",,,
+,"7","SINGLE","6","area4","0",,,
+,"8","SINGLE","6","area4","0",,,
+,"6","SINGLE","8","area4","0",,,
+,"9","OR","8","area3","0",,,"SOURCE"
+,"9","OR","15","area3","0",,,"SOURCE"
+,"15","ORPHAN","NULL","area3","0",,,
+,"16","SINGLE","9","area3","0",,,
+,"16","SINGLE","17","area3","0",,,
+,"17","SINGLE","16","area3","0",,,
+,"10","SINGLE","17","area3","0",,,
+,"11","AND","10","area2","0",,,
+,"11","AND","5","area2","0",,,
+,"19","SINGLE","11","area2","0",,,
+,"19","SINGLE","12","area2","0",,,
+,"19","SINGLE","14","area2","0",,,
+,"12","SINGLE","19","area2","0",,,
+,"12","SINGLE","13","area2","0",,,
+,"13","SINGLE","14","area2","0",,,
+,"13","SINGLE","12","area2","0",,,
+,"14","SINGLE","19","area2","0",,,
+,"14","SINGLE","13","area2","0",,,
+,"18","SINGLE","14","area2","0",,,"TARGET"

examples/Room_damage/output_files/room_perturbation.csv → examples/Area_perturbation/output_files/area_perturbation.csv

@@ -1,20 +1,20 @@
-Mark,Description,InitStatus,IntermediateStatus,FinalStatus,Mark_Status,PerturbationResistant,Room,Status_Room,closeness_centrality,betweenness_centrality,indegree_centrality,original_local_eff,final_local_eff,original_global_eff,final_global_eff,original_avg_global_eff,final_avg_global_eff
-1,,, , ,ACTIVE,1,room1,DAMAGED,0,0.0,0,0.17437369729036395,0.17437369729036395,0.3213624338624339,0.3213624338624339,0.17591917504198207,0.17591917504198207
-2,isolation_A,1, , ,ACTIVE,1,room1,DAMAGED,0.05555555555555555,0.05161290322580645,0.05555555555555555,0.20222663139329808,0.20222663139329808,0.19689554272887605,0.19689554272887605,0.17591917504198207,0.17591917504198207
-3,isolation_A,1, , ,ACTIVE,1,room1,DAMAGED,0.05555555555555555,0.04516129032258064,0.05555555555555555,0.14814814814814814,0.14814814814814814,0.15185185185185185,0.15185185185185185,0.17591917504198207,0.17591917504198207
-4,,, , ,ACTIVE,1,room1,DAMAGED,0.07407407407407407,0.12903225806451613,0.05555555555555555,0.22583774250440916,0.22583774250440916,0.20222663139329808,0.20222663139329808,0.17591917504198207,0.17591917504198207
-5,,, , ,ACTIVE,1,room1,DAMAGED,0.07407407407407407,0.07741935483870968,0.05555555555555555,0.14814814814814817,0.14814814814814817,0.14814814814814814,0.14814814814814814,0.17591917504198207,0.17591917504198207
-6,,, , ,ACTIVE,0,room4,AVAILABLE,0.1736111111111111,0.2709677419354839,0.16666666666666666,0.21182760141093476,0.21182760141093476,0.22583774250440916,0.22583774250440916,0.17591917504198207,0.17591917504198207
-7,,, , ,ACTIVE,0,room4,AVAILABLE,0.11574074074074076,0.0,0.05555555555555555,0.22583774250440916,0.22583774250440916,0.1744488536155203,0.1744488536155203,0.17591917504198207,0.17591917504198207
-8,,, , ,ACTIVE,0,room4,AVAILABLE,0.11574074074074076,0.2838709677419355,0.05555555555555555,0.1935405643738977,0.1935405643738977,0.24920634920634926,0.24920634920634926,0.17591917504198207,0.17591917504198207
-9,,, , ,ACTIVE,0,room3,AVAILABLE,0.14327485380116958,0.36774193548387096,0.1111111111111111,0.15648148148148147,0.15648148148148147,0.16124338624338622,0.16124338624338622,0.17591917504198207,0.17591917504198207
-15,,, , ,ACTIVE,0,room3,AVAILABLE,0,0.0,0,0.16124338624338622,0.16124338624338622,0.16587301587301584,0.16587301587301584,0.17591917504198207,0.17591917504198207
-16,,, , ,ACTIVE,0,room3,AVAILABLE,0.16071428571428573,0.3741935483870968,0.1111111111111111,0.20740740740740743,0.20740740740740743,0.15648148148148147,0.15648148148148147,0.17591917504198207,0.17591917504198207
-17,,, , ,ACTIVE,0,room3,AVAILABLE,0.125,0.36774193548387096,0.05555555555555555,0.1523148148148148,0.1523148148148148,0.20740740740740743,0.20740740740740743,0.17591917504198207,0.17591917504198207
-10,,, , ,ACTIVE,0,room3,AVAILABLE,0.12077294685990338,0.34838709677419355,0.05555555555555555,0.14814814814814817,0.14814814814814817,0.14814814814814814,0.14814814814814814,0.17591917504198207,0.17591917504198207
-11,,, , ,ACTIVE,0,room2,AVAILABLE,0.17386831275720163,0.41935483870967744,0.1111111111111111,0.16666666666666666,0.16666666666666666,0.14814814814814817,0.14814814814814817,0.17591917504198207,0.17591917504198207
-19,,, , ,ACTIVE,0,room2,AVAILABLE,0.22299382716049382,0.38064516129032255,0.16666666666666666,0.17592592592592593,0.17592592592592593,0.16666666666666666,0.16666666666666666,0.17591917504198207,0.17591917504198207
-12,,, , ,ACTIVE,0,room2,AVAILABLE,0.1866925064599483,0.1032258064516129,0.1111111111111111,0.16666666666666666,0.16666666666666666,0.1574074074074074,0.1574074074074074,0.17591917504198207,0.17591917504198207
-14,,, , ,ACTIVE,0,room2,AVAILABLE,0.1866925064599483,0.10967741935483871,0.1111111111111111,0.1111111111111111,0.1111111111111111,0.19444444444444445,0.19444444444444445,0.17591917504198207,0.17591917504198207
-13,,, , ,ACTIVE,0,room2,AVAILABLE,0.16055555555555556,0.0,0.1111111111111111,0.17592592592592593,0.17592592592592593,0.16666666666666666,0.16666666666666666,0.17591917504198207,0.17591917504198207
-18,,, , ,ACTIVE,0,room2,AVAILABLE,0.17307692307692307,0.0,0.05555555555555555,0,0,0.0,0.0,0.17591917504198207,0.17591917504198207
+Mark,Description,InitStatus,IntermediateStatus,FinalStatus,Mark_Status,PerturbationResistant,Area,Status_Area,closeness_centrality,betweenness_centrality,indegree_centrality,original_local_eff,final_local_eff,original_global_eff,final_global_eff,original_avg_global_eff,final_avg_global_eff
+1,,, , ,ACTIVE,1,area1,DAMAGED,0,0.0,0,0.17437369729036395,0.17437369729036395,0.3213624338624339,0.3213624338624339,0.17591917504198207,0.17591917504198207
+2,isolation_A,1, , ,ACTIVE,1,area1,DAMAGED,0.05555555555555555,0.05161290322580645,0.05555555555555555,0.20222663139329808,0.20222663139329808,0.19689554272887605,0.19689554272887605,0.17591917504198207,0.17591917504198207
+3,isolation_A,1, , ,ACTIVE,1,area1,DAMAGED,0.05555555555555555,0.04516129032258064,0.05555555555555555,0.14814814814814814,0.14814814814814814,0.15185185185185185,0.15185185185185185,0.17591917504198207,0.17591917504198207
+4,,, , ,ACTIVE,1,area1,DAMAGED,0.07407407407407407,0.12903225806451613,0.05555555555555555,0.22583774250440916,0.22583774250440916,0.20222663139329808,0.20222663139329808,0.17591917504198207,0.17591917504198207
+5,,, , ,ACTIVE,1,area1,DAMAGED,0.07407407407407407,0.07741935483870968,0.05555555555555555,0.14814814814814817,0.14814814814814817,0.14814814814814814,0.14814814814814814,0.17591917504198207,0.17591917504198207
+6,,, , ,ACTIVE,0,area4,AVAILABLE,0.1736111111111111,0.2709677419354839,0.16666666666666666,0.21182760141093476,0.21182760141093476,0.22583774250440916,0.22583774250440916,0.17591917504198207,0.17591917504198207
+7,,, , ,ACTIVE,0,area4,AVAILABLE,0.11574074074074076,0.0,0.05555555555555555,0.22583774250440916,0.22583774250440916,0.1744488536155203,0.1744488536155203,0.17591917504198207,0.17591917504198207
+8,,, , ,ACTIVE,0,area4,AVAILABLE,0.11574074074074076,0.2838709677419355,0.05555555555555555,0.1935405643738977,0.1935405643738977,0.24920634920634926,0.24920634920634926,0.17591917504198207,0.17591917504198207
+9,,, , ,ACTIVE,0,area3,AVAILABLE,0.14327485380116958,0.36774193548387096,0.1111111111111111,0.15648148148148147,0.15648148148148147,0.16124338624338622,0.16124338624338622,0.17591917504198207,0.17591917504198207
+15,,, , ,ACTIVE,0,area3,AVAILABLE,0,0.0,0,0.16124338624338622,0.16124338624338622,0.16587301587301584,0.16587301587301584,0.17591917504198207,0.17591917504198207
+16,,, , ,ACTIVE,0,area3,AVAILABLE,0.16071428571428573,0.3741935483870968,0.1111111111111111,0.20740740740740743,0.20740740740740743,0.15648148148148147,0.15648148148148147,0.17591917504198207,0.17591917504198207
+17,,, , ,ACTIVE,0,area3,AVAILABLE,0.125,0.36774193548387096,0.05555555555555555,0.1523148148148148,0.1523148148148148,0.20740740740740743,0.20740740740740743,0.17591917504198207,0.17591917504198207
+10,,, , ,ACTIVE,0,area3,AVAILABLE,0.12077294685990338,0.34838709677419355,0.05555555555555555,0.14814814814814817,0.14814814814814817,0.14814814814814814,0.14814814814814814,0.17591917504198207,0.17591917504198207
+11,,, , ,ACTIVE,0,area2,AVAILABLE,0.17386831275720163,0.41935483870967744,0.1111111111111111,0.16666666666666666,0.16666666666666666,0.14814814814814817,0.14814814814814817,0.17591917504198207,0.17591917504198207
+19,,, , ,ACTIVE,0,area2,AVAILABLE,0.22299382716049382,0.38064516129032255,0.16666666666666666,0.17592592592592593,0.17592592592592593,0.16666666666666666,0.16666666666666666,0.17591917504198207,0.17591917504198207
+12,,, , ,ACTIVE,0,area2,AVAILABLE,0.1866925064599483,0.1032258064516129,0.1111111111111111,0.16666666666666666,0.16666666666666666,0.1574074074074074,0.1574074074074074,0.17591917504198207,0.17591917504198207
+14,,, , ,ACTIVE,0,area2,AVAILABLE,0.1866925064599483,0.10967741935483871,0.1111111111111111,0.1111111111111111,0.1111111111111111,0.19444444444444445,0.19444444444444445,0.17591917504198207,0.17591917504198207
+13,,, , ,ACTIVE,0,area2,AVAILABLE,0.16055555555555556,0.0,0.1111111111111111,0.17592592592592593,0.17592592592592593,0.16666666666666666,0.16666666666666666,0.17591917504198207,0.17591917504198207
+18,,, , ,ACTIVE,0,area2,AVAILABLE,0.17307692307692307,0.0,0.05555555555555555,0,0,0.0,0.0,0.17591917504198207,0.17591917504198207

examples/Area_perturbation/output_files/check_import_nodes.csv

@@ -0,0 +1,20 @@
+Mark,Description,InitStatus,PerturbationResistant,Area
+1,,,1,area1
+2,isolation_A,1,1,area1
+3,isolation_A,1,1,area1
+4,,,1,area1
+5,,,1,area1
+6,,,0,area4
+7,,,0,area4
+8,,,0,area4
+9,,,0,area3
+15,,,0,area3
+16,,,0,area3
+17,,,0,area3
+10,,,0,area3
+11,,,0,area2
+19,,,0,area2
+12,,,0,area2
+14,,,0,area2
+13,,,0,area2
+18,,,0,area2

examples/Component_damage/output_files/service_paths_component_damage.csv → examples/Area_perturbation/output_files/service_paths_multi_area_perturbation.csv

@@ -1,2 +1,2 @@
-from,to,final_simple_path,final_shortest_path,final_shortest_path_length,final_pair_efficiency,room,ids,original_simple path,original_shortest_path_length,original_pair_efficiency,original_shortest_path
-9,18,"[['9', '16', '17', '10', '11', '19', '12', '13', '14', '18'], ['9', '16', '17', '10', '11', '19', '14', '18']]","['9', '16', '17', '10', '11', '19', '14', '18']",7,0.14285714285714285,room3,918,"[['9', '16', '17', '10', '11', '19', '12', '13', '14', '18'], ['9', '16', '17', '10', '11', '19', '14', '18']]",7,0.14285714285714285,"['9', '16', '17', '10', '11', '19', '14', '18']"
+from,to,final_simple_path,final_shortest_path,final_shortest_path_length,final_pair_efficiency,area,ids,original_simple path,original_shortest_path_length,original_pair_efficiency,original_shortest_path
+9,18,"[['9', '16', '17', '10', '11', '19', '12', '13', '14', '18'], ['9', '16', '17', '10', '11', '19', '14', '18']]","['9', '16', '17', '10', '11', '19', '14', '18']",7,0.14285714285714285,area3,918,"[['9', '16', '17', '10', '11', '19', '12', '13', '14', '18'], ['9', '16', '17', '10', '11', '19', '14', '18']]",7,0.14285714285714285,"['9', '16', '17', '10', '11', '19', '14', '18']"