Audit trails for hierarchy objects¶

ReGraph implements a framework for the version control (VC) of graph transformations in hierarchies.

The data structure VersionedHierarchy allows to store the history of transformations of a hierarchy and perform the following VC operations:

Rewrite: perform a rewriting of the hierarchy with a commit to the revision history
Branch: create a new branch (with a diverged version of the graph object)
Merge branches: merge branches
Rollback: rollback to a point in the history of transformations

Let us start this tutorial by performing necessary imports:

from regraph import NXGraph, NXHierarchy
from regraph.audit import VersionedHierarchy
from regraph.rules import Rule
from regraph import print_graph, plot_rule, plot_graph

Let us now create a small hierarchy.

hierarchy = NXHierarchy()

shapes = NXGraph()
shapes.add_nodes_from(["circle", "square"])
hierarchy.add_graph("shapes", shapes)

colors = NXGraph()
colors.add_nodes_from(["white", "black"])
hierarchy.add_graph("colors", colors)

ag = NXGraph()
ag.add_nodes_from(
    ["wc", "bc", "ws", "bs"])
hierarchy.add_graph("metamodel", ag)

nugget = NXGraph()
nugget.add_nodes_from(
    ["wc1", "wc2", "bc1", "ws1", "bs2"])
hierarchy.add_graph("data", nugget)

hierarchy.add_typing(
    "metamodel", "shapes", {
        "wc": "circle",
        "bc": "circle",
        "ws": "square",
        "bs": "square"
    })
hierarchy.add_typing(
    "metamodel", "colors", {
        "wc": "white",
        "bc": "black",
        "ws": "white",
        "bs": "black"
    })
hierarchy.add_typing(
    "data", "metamodel", {
        "wc1": "wc",
        "wc2": "wc",
        "bc1": "bc",
        "ws1": "ws",
        "bs2": "bs"
    })
hierarchy.add_typing(
    "data", "colors", {
        "wc1": "white",
        "wc2": "white",
        "bc1": "black",
        "ws1": "white",
        "bs2": "black"
    })

base = NXGraph()
base.add_nodes_from(["node"])
hierarchy.add_graph("base", base)
hierarchy.add_typing(
    "colors",
    "base", {
        "white": "node",
        "black": "node"
    })

We pass the hierarchy to the VersionedHierarchy wrapper that will take care of the version control:

>>> h = VersionedHierarchy(hierarchy)
>>> print("Branches: ", h.branches())
Branches:  ['master']
>>> print("Current branch: ", h.current_branch())
Current branch:  master

Let us create a new branch test1:

>>> h.branch("test1")

We will now rewrite our hierarchy at the current branch of the audit trail.

pattern = NXGraph()
pattern.add_nodes_from(["s"])
rule = Rule.from_transform(pattern)
rule.inject_remove_node("s")

rhs_instances, commit_id = h.rewrite(
    "shapes",
    rule, {"s": "square"},
    message="Remove square in shapes")

The rewrite method of VersionedHierarchy returns the instances of the RHS of the applied rule in different graphs and the id of the newly created commit corresponding to this rewrite.

>>> print(rhs_instances)
{'shapes': {}, 'metamodel': {}, 'data': {}, 'colors': {'ws': 'white', 'bs': 'black'}, 'base': {'bs_ws': 'node'}}
>>> print(commit_id)
5ebdb406-eee6-44b9-a2a0-005e4b5ef94f

We switch back to the master branch.

>>> h.switch_branch("master")

We will now rewrite the hierarchy corresponding to the current branch.

pattern = NXGraph()
pattern.add_nodes_from(["wc"])

rule = Rule.from_transform(pattern)
rule.inject_clone_node("wc")

_, clone_commit = h.rewrite(
    "metamodel",
    rule, {"wc": "wc"},
    message="Clone 'wc' in ag")

After running the snippet above, we obtain the following resivions history:

>>> h.print_history()
2020-01-24 14:37:14.627367 78f98e3c-2361-4d96-9737-31678d507ac6 master Initial commit
2020-01-24 14:37:14.635519 b135a358-2af2-41f8-9c66-aa392ca21660 test1 Created branch 'test1'
2020-01-24 14:37:14.646972 5ebdb406-eee6-44b9-a2a0-005e4b5ef94f test1 Remove square in shapes
2020-01-24 14:37:14.697650 4e00034e-17d5-48ed-9078-d070a0d65d03 master Clone 'wc' in ag

Let us perform another rewriting as follows:

pattern = NXGraph()
pattern.add_nodes_from(["wc1"])

rule = Rule.from_transform(pattern)
rule.inject_add_node("new_node")
rule.inject_add_edge("new_node", "wc1")

_ = h.rewrite(
    "data",
    rule, {"wc1": "wc1"},
    message="Add a new node to 'data'")

Now we merge the branch test1 in into master.

>>> h.merge_with("test1")
>>> h.print_history()
2020-01-24 14:37:14.627367 78f98e3c-2361-4d96-9737-31678d507ac6 master Initial commit
2020-01-24 14:37:14.635519 b135a358-2af2-41f8-9c66-aa392ca21660 test1 Created branch 'test1'
2020-01-24 14:37:14.646972 5ebdb406-eee6-44b9-a2a0-005e4b5ef94f test1 Remove square in shapes
2020-01-24 14:37:14.697650 4e00034e-17d5-48ed-9078-d070a0d65d03 master Clone 'wc' in ag
2020-01-24 14:37:14.728376 dc371f55-18fb-4797-ba75-8ff9217bfe65 master Add a new node to 'data'
2020-01-24 14:37:14.751670 f2239fa2-2632-4650-8b53-78f03cf2d795 master Merged branch 'test1' into 'master'

Let us now rollback to the commit clone_commit.

>>> h.rollback(clone_commit)
Created the new head for 'test1'
Created the new head for 'master'

>>> h.print_history()
2020-01-24 14:37:14.627367 78f98e3c-2361-4d96-9737-31678d507ac6 master Initial commit
2020-01-24 14:37:14.635519 b135a358-2af2-41f8-9c66-aa392ca21660 test1 Created branch 'test1'
2020-01-24 14:37:14.646972 5ebdb406-eee6-44b9-a2a0-005e4b5ef94f test1 Remove square in shapes
2020-01-24 14:37:14.697650 4e00034e-17d5-48ed-9078-d070a0d65d03 master Clone 'wc' in ag
>>> print(h.branches())
['master', 'test1']

We can see that the revision history came back to the previous state (right after the clone commit), and we still have two branches master and test1.

See more¶

Module reference: Audit trail

Audit trails for hierarchy objects¶

See more¶

ReGraph

Navigation

Related Topics