Getting Started

Discover what Bigraph Framework is all about and learn the core concepts behind it.

Creating a Bigraph

At the moment, Bigraph Framework supports only pure bigraphs and kind bigraphs.

Signature

To create a bigraph, a so-called signature must be created first. Technically, it defines the syntax of a bigraph and determines what types (i.e., controls of a bigraphs) we can create in the following.

To create a signature, we begin by spawning a signature builder that is internally provided by a pure factory. All further operations will use the same factory in the current execution context. The first step is to create a signature builder by using the appropriate factory method. Here, BigraphFactory#pureSignatureBuilder():

tip

Note that all examples use a static import of the BigraphFactory class' operations:

import static org.bigraphs.framework.core.factory.BigraphFactory.*;

This makes access to its operations more convenient.

import static org.bigraphs.framework.core.factory.BigraphFactory.*;

void getting_started_guide() throws InvalidConnectionException, IncompatibleSignatureException, IncompatibleInterfaceException { 
	DynamicSignatureBuilder signatureBuilder = pureSignatureBuilder();
	DefaultDynamicSignature signature = signatureBuilder.newControl().identifier("User").arity(1).status(ControlStatus.ATOMIC).assign().newControl(StringTypedName.of("Computer"), FiniteOrdinal.ofInteger(2)).assign().create();
}

As mentioned above, the signature specifies the syntax of a bigraph we are going to create in the following. The resulting signature contains two controls: a User with an arity of 1, and a Computer with an arity of 2. The arity specifies how many connections a control can have. The semantic meaning of the term "connection" is left open here - it can represent anything, for example, an ethernet link or an association relationship between elements.

tip

A more compact form for creating controls is the following:

signatureBuilder.addControl("User", 1, ControlStatus.ATOMIC)

The control is instantly added to the signature. Contrary, using #newControl() returns a control instance that can be used for other purposes.

Bigraph Builder

Now we are able to instantiate a pure bigraph builder instance. It allows us to build our bigraph by adding child nodes and connections among them. The signature above determines which kind of nodes we can add to the bigraph (our syntax). Therefore, we have to supply the previously created signature to the pureBuilder() method.

void getting_started_guide() throws InvalidConnectionException, IncompatibleSignatureException, IncompatibleInterfaceException { 
	// ...
	PureBigraphBuilder<DefaultDynamicSignature> builder = pureBuilder(signature);
	builder.createRoot().addChild("User", "login").addChild("Computer", "login");
	PureBigraph bigraph = builder.createRoot().addChild("User", "login").addChild("Computer", "login").createBigraph();
}

The example shows how to add two nodes ("User" and "Computer") under the same root (we do it twice) and how to link all to the same outer name with the label "login". The bigraph is illustrated below.

info

Note that the method addChild will throw an InvalidConnectionException if the node cannot be connected to the outer name (because of its arity specified by the signature).

tip

See Visualization on how to export a bigraph as graphics file.

Elementary Bigraphs

Let us now examine how more trivial bigraphs can be created which are termed elementary bigraphs. Essentially, there are two categories: Placings and Linkings. They do not contain any node, thus, they are node-free bigraphs.

info

Elementary bigraphs are essential building blocks in the theory and fundamental to define the normal form of bigraphs.

Elementary bigraphs allow to build more complex bigraphs easily. We show how to create a concrete placing and linking, before we use them for composition later in the next section.

info

Even if elementary bigraphs usually do not take a signature, it must be provided. This is due to technical reasons with respect to the bigraphical metamodel that is used internally. Refer to the project Bigraph Metamodel for more details.

The next code example shows how we can create a so-called merge_n (i.e., a placing where n sites are located under one root) and an identity link graph (i.e., inner and outer interfaces of the link graph are connected), which can also be regarded as a bijective substitution in bigraph-jargon.

void getting_started_guide() throws InvalidConnectionException, IncompatibleSignatureException, IncompatibleInterfaceException { 
	// ...
	Placings<DefaultDynamicSignature> placings = purePlacings(signature);
	Placings<DefaultDynamicSignature>.Merge merge = placings.merge(2);
	Linkings<DefaultDynamicSignature> linkings = pureLinkings(signature);
	Linkings<DefaultDynamicSignature>.Identity login = linkings.identity(StringTypedName.of("login"));
}

The factory provides the method #purePlacings() to create a placings builder. With it we create a merge, a join, or a barren to mention a few. By passing the integer 2 as argument, a merge with two sites is created. Further, we create an identity link graph with the name "login".

The two elementary bigraphs merge and identity are depicted below.

Placing: Merge	Linking: Identity

Composition of Bigraphs

Bigraphs may be composed by using special operators. This allows us to modularize bigraphs by constructing sub-structures separately from each other and compose them later to build a larger bigraph.

To equip a bigraph with operators we simply pass it to the static method #ops() provided by the BigraphFactory class.

void getting_started_guide() throws InvalidConnectionException, IncompatibleSignatureException, IncompatibleInterfaceException { 
	// ...
	BigraphComposite<DefaultDynamicSignature> composed = BigraphFactory.ops(merge).parallelProduct(login).compose(bigraph);
}

The code above describes a composition that merges the two roots of the previously created bigraph under one root node with index 0 and under one root indexed 1. At the same time we keep the links so that all nodes are kept connected via the link graph.

info

Note that composition may throw the following two exceptions IncompatibleSignatureException and IncompatibleInterfaceException if the signatures are not the same or the interfaces are not compatible.

Some operators are explained in Composition. For a full account consult JavaDoc of the BigraphComposite interface.

tip

As seen before, bigraphs can be constructed by an operator approach (composition and product). Note that the bigraph builder also supports the creation of hierarchies that can be later combined to build a larger bigraph easily. Example:

PureBigraphBuilder<DefaultDynamicSignature>.Hierarchy h1 = pureBuilder(sig).hierarchy("A");
pureBuilder(sig).createRoot().addChild(h1);

Hierarchies can separately created and extended. Finally, they can be added as a child node as usually at any point in the bigraph.

Linkings between nodes within different hierarchies shall be established using inner or outer names.

Conclusion

This page explored some of the basic features of Bigraph Framework on how to create signatures, bigraphs, elementary bigraphs and how to compose them to form larger ones.