Differences

This shows you the differences between two versions of the page.

--- groimp-platform:extents [2024/12/16 17:58] – [Extent index] gaetan
+++ groimp-platform:extents [2025/01/14 15:29] (current) – gaetan
@@ Line 1: / Line 1: @@
 ====== Graph Extents ======
-A special feature of the graph management is the manipulation of [[https://javadoc.grogra.de/graph/de/grogra/graph/impl/Extent.html|extents]]. For each used node class in the graph, there exists an Extent which collects all nodes of this class and also has a link to the extent of its superclass and to the extents of its subclasses. This feature is currently used within the RGG plug-in for a fast processing of queries which specify node type patterns like in the rule ''F(x) == > F(2*x);''. Instead of having to scan the whole graph for nodes of class F, the corresponding extent is used together with its sub-extents to directly iterate over all nodes of class F.
+A special feature of the graph management is the manipulation of [[https://javadoc.grogra.de/graph/de/grogra/graph/impl/Extent.html|extents]]. For each used node class in the graph, there exists an Extent which collects all nodes of this class and also has a link to the extent of its superclass and to the extents of its subclasses. This feature is currently used within the RGG plug-in for a fast processing of queries which specify node type patterns like in the rule ''F(x) %%==>%% F(2*x);''. Instead of having to scan the whole graph for nodes of class F, the corresponding extent is used together with its sub-extents to directly iterate over all nodes of class F.
@@ Line 10: / Line 10: @@
 Then, for each new type of Node added in the graph, an extent is created and linked to its direct super class. The type of Node is described by its [[https://javadoc.grogra.de/graph/de/grogra/graph/impl/Node.NType.html|NType]]. The NType is an internal class defined by each Node. In java it is usually created with the [[dev-guide:automatic-code-enhancement|code enhancer]] to ensure that all the required attributes for the persistence management are created. In RGG, the NType is automatically created for all ''modules''.
 If a Node is added to the graph and it extends several level of Nodes, an extent for each intermediate NTypes is created.
+[[https://javadoc.grogra.de/graph/de/grogra/graph/impl/Extent.html|Extent]] implements the following methods:
+  * getType(): return the type of the node of this extent.
+  * getSubExtents(): return the list of extents whose type is a sub type.
+  * getFirstNode(): return the first element added to this extent.
+  * getNextNode(): return the next element in the chain.
+  * getTotalSize(): return the size of the extent including the size of its sub extent.
+=== Example ===
 E.g. in the following: (the init method is simplified, and we assume that there are not other nodes in the graph)
@@ Line 26: / Line 36: @@
   * one for B of size 0
   * one for C of size 1
-[[https://javadoc.grogra.de/graph/de/grogra/graph/impl/Extent.html|Extent]] implements the following methods:
-  * getType(): return the type of the node of this extent.
-  * getSubExtents(): return the list of extents whose type is a sub type.
-  * getFirstNode(): return the first element added to this extent.
-  * getNextNode(): return the next element in the chain.
-  * getTotalSize(): return the size of the extent including the size of its sub extent.
@@ Line 40: / Line 41: @@
 ===== Extent index =====
-An extent collects its nodes not by a single list, but by a number of (doubly linked) lists. Currently, eight lists are used, but this can easily be changed. This feature is used to partition the extents.
+An extent collects its nodes not by a single list, but by a number of (doubly linked) lists. Currently, eight lists are used, but this can easily be changed. This feature is used to partition the extents. The eight lists are called the extent indexes.
-The extent indexes are defined from 0 to 7. By default most nodes added to the graph are added with the index 0. There are two exceptions:
+The extent indexes are defined from 0 to 7. By default most nodes added to the graph are added with the index 0. There are two exceptions (by default. You can manually set index of Node):
   - //meta objects//: Nodes of the meta graph. Added at index 7.
-  - //GUI inserted objects//: Nodes inserted from the GUI. Added at index 6.
+  - //GUI inserted objects//: Nodes inserted from the GUI. Added at index 6 (since GroIMP 2.1.5, they where added to index 7 before).
 The most common example of extent index is the //meta-graph//. Each project in GroIMP includes a //meta-graph// with at least one node per compiled file in the project. Yet, these Nodes are not returned by default in XL queries. The reason is that, they were added to an invisible (by default) extent index.
@@ Line 52: / Line 53: @@
 An index is visible, if it is included in the queries. A Node can be added in the scene with a geometrical representation, and still be in an invisible index. By default only the 7th first indexes are visible (0 to 6). The last index (7) is not visible.
-It is possible to change the index visibility in a project with the method: ''setVisibleIndex(int )'' on the RGGGraph.
+It is possible to change the index visibility in a project with the method: ''setVisibleExtents(int )'' on the RGGGraph.
-For instance, let's consider the following method in an empty project. Notice that we set the visible extent value to 1;
+=== Example ===
+For instance, let's consider the following method in an empty project. Notice that we set the visible extent value to 1:
 <code java>
@@ Line 84: / Line 88: @@
   * the nodes from the meta graph: the compiled version of the files: Model, and parameters.
+Notice that:
+  * Once the setVisibleExtents is called. The value remains until a new value is set.
+  * setVisibleExtents use as parameter the decimal value of a binary number of 8 values where each 1 mean that the index is visible, the 0 to 7 index visibility are defined from left to right. E.g. to have all indexes visible, we use 11111111 (eight 1), which is equal in decimal to 255. To have all indexes visible except for the 1rst one, we use 11111110 (=254). The default value is 01111111 (=127).
 ===== Extent in XL queries =====
+=== Graph complexity ===
-For instance the following graph, where //RGGRoot// extends //Node//, and //Model.A// extends //Node//:
+Extent are used in RGG for queries that involve Node types. E.g. the query ''F +> Node /> Model.A %%==>%%;'' will be resolved by: looping over the Extent of //F//, finding the edges that matches to the Extent of //Node//, ...
-<uml>
+Such a query will **not** visit the graph. It will loop over the extents data. Thus, the complexity of the graph //might// not affect the query.
-@startuml
-(Model.A) as a1
+Speed up queries by using more specific Node type: As the query loop over the extents content, ''( (*Node*))'' will loop over all nodes in the graph, while ''( (*Model.A*))'' only on the Extent Model.A and its sub extent. Each edge condition add a level of complexity. For instance: ''[Node Node Node %%==>%%;]'' has a complexity of n³ (n being the number of Node).
-(Model.A) as a2
-(Node) --> (RGGRoot)
-(RGGRoot) --> a1
+=== Indexes ===
-(RGGRoot) --> a2
-@enduml
+Additionally, the extent non visible indexes are not included in the query. Thus, nodes whose extent index is not visible will not add any complexity to the query.
-</uml>
+=== Examples ===
+The following code will create a chain of 8 cylinders, then stop growing.
+<code java>
+module A(int i) extends F {
+{setExtentIndex(i);}
+}
+static int i = 0;
+{de.grogra.rgg.model.Runtime.INSTANCE.currentGraph().setVisibleExtents(127);}
+public void init()[ Axiom ==> A(i); ]
+public void run() [ a:A(x), (x==i) ==> a A(++i); ]
+</code>
-GroIMP creates three extents, one for each type: Node, RGGRoot, and Model.A.
+Indeed, the last F added as an extent index of 7, thus not visible (setVisibleExtents(127) means 0 to 6 visible). In this case, the query search for F that have a extent index of 7, but the index is not visible, thus, not used in the query.
-Extents work as linked list.