4.1.12.1. rule/Composition¶

This page contains the core functionality for composing rules and creating rules from graphs. Note that there is both a low-level interface for constructing expressions, and an embedded mini-language for defining the expressions using normal Python operators.

4.1.12.1.1. The Embedded Rule Composition Expression Language¶

The embedded language is really a collection of proxy classes with a lot of operator overloading, thus the normal syntax and semantics of Python applies.

A rule composition expression always returns a list of rules when evaluated. The following is the grammar for the expressions.

rcExp    ::=  rcExp op rcExp
              "rcBind(" graphs ")"
              "rcId(" graphs ")"
              "rcUnbind(" graphs ")"
              rules
op       ::=  "*" opObject "*"
opObject ::=  "rcParallel"
              "rcSuper"
              "rcSuper(allowPartial=True)"
              "rcSub"
              "rcSub(allowPartial=True)"
              "rcCommon"
              "rcCommon(maximum=False, connected=True, includeEmpty=False)"

Here a graphs is any Python expression that is either a single Graph or an iterable of graphs. Similarly, rules must be either a Rule or an iterable of rules. An rcExp may additionally be an iterable of expressions. The following table links each type of expression to the objects being created.

Expression	Object
An iterable of `Rule`	`RCExpUnion`
`rcBind(graphs)`	`RCExpBind`
`rcId(graphs)`	`RCExpId`
`rcUnbind(graphs)`	`RCExpUnbind`
`rcExp` `rcParallel` `rcExp`	`RCExpComposeParallel`
`rcExp` `rcSuper` `rcExp`	`RCExpComposeSuper`
`rcExp` `rcSub` `rcExp`	`RCExpComposeSub`
`rcExp` `rcCommon` `rcExp`	`RCExpComposeCommon`

See also [AFMS-RC], [AFMS-RC-AtomMap], and [AFMS-RC-Matrix] for details on how these expressions are computed internally, and further examples of how they can be used to solve particular problems.

4.1.12.1.2. Expression Evaluator¶

class mod.RCEvaluator¶

This class can evaluate rule composition expressions. During evaluation an expression graph is recorded.

The expression graph is a directed hypergraph \((V, E)\), with each vertex representing a rule. Each edge represent all compositions calculated for a unique input. That is every edge \(e\in E\) is on the form \(((u, v), R_e)\) with \((u, v)\in V\times V\) as an ordered pair of rules and \(R_e\subseteq V\) is the set of all resulting rules found.

The graph is visualised as a bipartite graph with point-shaped vertices representing the hyperedges. The in-edges to these hyperedge vertices are labelled with 1 and 2.

__init__(self, ruleDatabase, labelSettings=LabelSettings(LabelType.String, LabelRelation.Isomorphism))¶

Parameters:

ruleDatabase – a list of isomorphic rules the evaluator will compare against.
labelSettings (LabelSettings) – the settings to use for morphisms.

Note

The caller is responsible for ensuring the given rules are unique.

ruleDatabase¶

(Read-only) The list of unique rules known by the evaluator.

Type:: list[Rule]

createdRules¶

(Read-only) The list of unique rules this evaluator has constructed.

Type:: list[Rule]

eval(exp, *, onlyUnique=True, verbosity=0)¶

Evaluates a rule composition expression. Any created rule is replaced by a rule in the database if they are isomorphic. A rule may appear multiple times in the result if multiple overlaps resulted in the same composed rule.

Parameters:

exp (RCExpExp) – the expression to evaluate.
onlyUnique (bool) – whether each composition (sub-)result may contain duplicates or not.
verbosity (int) – the level of information being printed about the evaluation. See rule::Composer::eval() for details.

Returns:

the resulting list of rules of the expression.

Return type:

list[Rule]

print()¶: Print the graph representing all expressions evaluated so far.

4.1.12.1.3. Rule Composition Expressions¶

An expression can be evaluated through the method RCEvaluator.eval(). The result of an expression is a list of rules.

class mod.RCExpUnion¶: When evaluated, return the union of the result of the sub-expressions.

class mod.RCExpBind¶: Return the singleton list with the rule \((\emptyset, \emptyset, G)\) for the given graph \(G\).

class mod.RCExpId¶: Return the singleton list with the rule \((G, G, G)\) for the given graph \(G\).

class mod.RCExpUnbind¶: Return the singleton list with the rule \((G, \emptyset, \emptyset)\) for the given graph \(G\).

class mod.RCExpExp¶: The base class for the composition of two rule \((L_1, K_1, R_1)\) and \((L_2, K_2, R_2)\).

class mod.RCExpComposeCommon¶: Compose the rules by all common subgraphs of \(R_1\) and \(L_2\), possibly limited to connected subgraphs or to the subgraphs of maximum size. By default the empty overlap is not considered, but can be enabled to be.

class mod.RCExpComposeParallel¶: Compose the rules by all common subgraphs of \(R_1\) and \(L_2\), possibly limited to connected subgraphs or to the subgraphs of maximum size.

class mod.RCExpComposeSub¶: Compose the rules by the empty graph, i.e., create a rule representing the parallel application of two input rules.

class mod.RCExpComposeSuper¶: Compose the rules such that overlapping connected components of \(R_1\) and \(L_2\) have the \(L_2\) component as a subgraph of \(R_1\). The overlap is partial if not every connected component of \(L_2\) is participating in the common subgraph.