# The &rocs; Handbook

## Introduction

In this chapter we provide an overview of the core features and the workflow of &rocs;. For the eager reader, who wants to start using &rocs; immediately, we suggest to read at least introduction-nutshell and using scripting as a reference when writing algorithms.

### Goals, Target Audience and Workflow

&rocs; is a Graph Theory IDE for everybody interested in designing and analyzing graph algorithms. This explicitly includes

- lecturers, who want to demonstrate algorithms to their students,

- students, who want to understand and see how their algorithm perform,

- and everybody, who is interested in data structures and algorithms.

For all these users, &rocs; provides an easy to use data structure editor for creating the data structures, a powerful scripting engine to execute algorithms, and several helper tools for your simulations and experiments.

The typical workflow when using &rocs; is to start by creating a graph with the visual graph editor. You can do this either by hand, this is adding data elements and connect them, or by using one of the data structure generators (if available for the currently selected data structure backend). Data structure generators can be found at Graph Document Tools Generate Graph. Further, you can assign values to the data structure elements, either by hand or using Graph Document Tools Assign Values. Finally, you can write your algorithm in JavaScript and execute it with the just created data structure. All changes that your algorithm perform at the data structure will be directly visible at the visual graph editor.

A Screenshot of &rocs;. A Screenshot of &rocs;.

### &rocs; in a Nutshell

In this section we provide a compact overview of the core elements of &rocs;. We explain the important notions of data structures, data structure backends, and element types. Understanding of these concepts is useful to understand how data structures can be created and modified in &rocs;.

In general &rocs; works with projects: when opening &rocs; an empty project is created and you can replace it by loading or importing another project. Hereby, a project itself consists of graph documents and scripts.

#### Graph Documents and Data Structure Backends

A graph document represents the content of a whiteboard in the visual graph editor. Hereby, a graph document can contain several data structures at once, but only one data structure backends. Data structure backends are present for several graph types (general graphs, linked lists, rooted trees) and provide for their specific graph types additional functionality. That can be automatic positioning of the elements, special icon sets, or an extended set of script functions for use in your algorithms. (for details look at the corresponding handbook section). It is possible to change the data structure backend of a graph document, though information can be lost (e.g., edges of a circle in a general graph won't be added to a tree, if you switch to the rooted tree backend).

Graph documents form also the base for defining pointer types and data types.

#### Data Structures

Data structures are the base of all work in &rocs;. You can add one or several of them to a graph document, add data elements (nodes, datums) and pointers to them, and modify them by scripts. For this, each data structure has its unique name by which it can be accessed from your scripts. Due to your choice of the current data structure backend it can happen that you cannot modify the data structures arbitrarily (e.g., a tree should never contain a cycle). The data structure backend is determined by the data structure backend associated with the corresponding graph document that contains the data structure.

#### Pointer Types

By pointer types you can define different types of pointers to be used in your data structures. This is, a pointer type can get an individual layout (essentially a color) and it is easy to access only pointers of a specific type from your scripts. Typical use cases for pointers can be to implement meta-edges at your data structures that visualize relationships between data elements (e.g., visualize communication interests). But also, if your scripts shall identify specific kinds of edges (e.g., tree and cross edges at the depth first search algorithm), pointer types can be an elegant way to implement that.

#### Data Types

In several data structure problems, a set of data elements should be parted into groups of different types (e.g., clustering problems or covering problems). Or it is useful for the execution of an algorithm to specify a data element type to express a specific type (e.g., breath first search). For such use cases you can define data types. Each data type has its own icon and data types of some type can easily be accessed from your scripts.

#### Dynamic Properties

Every data element and pointer can have many properties. Some of these properties are default from data structure backend. See the documentation of the data structure backend for more details. To add further properties to the data elements and pointers, you can add dynamic properties to them. Each dynamic property is identified by its name and can contain any value associated with it. The name must start with a letter (a-z or A-Z) and can contain only letters, numbers and '_'. If you try to use any invalid character in the property name, the property will not be changed.

To add dynamic properties, use the Data Element Properties and Pointer Properties dialogs from the context menus of the respective elements or the script functions as explained in scripting-data-structure.

You can also use the scripts. You just need to use the `add_property` with the name and value of your property. After that, you can use node/pointer.propertyName to set/get the values.

Here is an example of how to use dynamic properties with data structure backend "Graph".

    nodes = myGraph.list_nodes()
    for (var i = 0; i < nodes.length; ++i ){
        nodes[i].add_property("MyProperty", 0)
    }
    nodes[0].MyProperty = 2
    nodes[1].MyProperty = nodes[0].MyProperty + 2

### Tutorial

In this section we want to create an example project to explore some of the most important functions of &rocs;. The goal is to create a graph and a script that illustrates a simple 2-approximate algorithm for the minimum vertex cover problem. The minimum vertex cover problem is the problem to find a subset of graph nodes C of minimal size such that each graph edge is connected to at least one node in C. This problem is known to be NP-hard and we want to illustrate how to find an approximation of factor 2 by finding a matching in the given graph (in the following we use the common terms for graph algorithms: graph is the data structure, nodes are the data elements, edges are the pointers).

Our goal is to visualize the correspondence of the matching and the minimum vertex cover. For this, we want to specify two pointer types, one to display matching edges and one type to display ordinary edges, as well as two data types that we use to distinguish nodes contained in C and those not contained in C.

#### Generate a Graph

For the data structure backend Graph, &rocs; ships a helper tool that can generate graphs. We go to Graph Document Tools Generate Graph. There we generate a Random Graph with 30 nodes, 90 edges, and with seed 1 (the seed is the starting seed for the random graph generator; using the same seed multiple times results in same and reproducible graphs). Finally, we modify the graph name at the data structure panel and call the graph `testgraph`.

#### Create Types

We use the Properties buttons at the Document Selector bar to open the properties dialog for data and pointer types of the current graph document. For the data types we add a new type called "C", which automatically gets ID `1`. For this type we select the server picture as icon. Furthermore, we switch to the pointer type page and add a new pointer type called "matching". This gets automatically ID `1` and we set the color to blue.

#### The Algorithm

At last we have to implement the approximation algorithm. For this we use the following implementation:

    var E = testgraph.list_edges(); // set of unprocessed edges
    var C = new Array();            // matching edges
    while (E.length > 0) {
        var e = E[0];        // we take first edge e={u,v}
        var u = e.start();
        var v = e.end();
        e.set_type(1);        // set edge to be a matching edge
        E.shift();            // remove e (i.e., E[0]) from edge list
        C.push(u);            // add u to C
        C.push(v);            // add v to C

        // mark u,v as nodes in C
        u.set_type(1);
        v.set_type(1);

        // remove from E all edges incident to u or v
        var adjacent = u.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // find the index
            if (index!=-1) {
                E.splice(index, 1); // remove it if really found
            }
        }
        var adjacent = v.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // find the index
            if (index!=-1) {
                E.splice(index, 1); // remove it if really found
            }
        }
    }
    Console.log("Vertex Cover contains " + C.length + " nodes.");

#### Execute the Algorithm

Finally we want to execute the algorithm. For this we can start the execution by the Run button at the script control panel.

## The &rocs; User Interface

### General Elements of the User Interface

The user interface is divided into several logical parts as presented at the screenshot below.

&GUI; elements of the &rocs; interface. &GUI; elements of the &rocs; interface.

Document Selector

- At this top menubar you must select the current document and data structure. Creating and deleting of data structures as well as access to data structure properties is also possible there.

Visual Graph Editor

- This is the whiteboard at which data structures can be created and modified. Right click at the whiteboard, at data elements, or at pointers to open context menus. You can use the tools from the Visual Graph Editor Toolbar to modify the elements at the visual graph editor whiteboard.

Visual Graph Editor Toolbar

- This toolbar provides all tools for the visual graph editor. Use the Add Element or Add Connection buttons to create new elements or to connect elements, respectively. New data elements are added to the data structure that is currently selected at the Document Selector bar. Note that Add Element and Add Connection buttons both have menus to select the type of which the created elements shall be. For details see user-interface-toolbars.

Side Bar

- At the right, you can find the side bar that provides several tools for your workflow:

  - Element Types: This widget gives you direct access to the available pointer and data types.

  - Journal: Each project has its own journal that can be used to, ⪚ note tasks, results, or observations.

  - Handbook: To get direct access to the handbook and by this to the script documentation, you can open this widget.

  - Scripting API: To get direct access to the script documentation, you can open this widget.

Script Editor

- In this text editor you can write algorithms as explained in detail in scripting. You can work on several script documents simultaneously by using several tabs. The disk symbol at a tab appears if the script contains unsaved changes.

Script Output

- This text area either shows debug information or the script output of your algorithm, depending on the toggled setting at the top of this widget. If the script throws an error, automatically the debug output is presented.

Controls

- Here you can find the controls for executing scripts. You can execute the script that is currently open at the script editor by pressing Run. While the script is executed, it is possible to stop execution by pressing the Stop button. Note that the One Step execution only stops at specific keywords (see scripting).

### Toolbars

There are different toolbars for the visual graph editor that allow you to access features by only one click. Per default, the following toolbars are shown:

- Main Toolbar

- Alignment Toolbar

#### Main Toolbar

The Main Toolbar consists of the following actions. Clicking at an action means that your mouse pointer applies this action at the visual graph editor whiteboard:

- Move: To select elements, either click at unused space at the whiteboard, keep the mouse pressed and draw a rectangle that contains some data elements and/or pointers to select these elements or otherwise directly click at an unselected element to select this element. If you click at a selected element or a set of selected elements, respectively, by keeping the mouse pressed and moving around you can move these elements. Moving selected elements is also possible with the arrow keys.

- Add Element: Click at an arbitrary position at the visual graph editor whiteboard to create a new data element that belongs to the currently selected data structure. By keeping the mouse pointer pressed at the button, a menu shows up at which the data type of the new created data elements can be selected (only if different data types exist).

- Add Connection: Click at one data element, keep the mouse pressed and draw a line to another data element to which the pointer/edge shall point. This action is only successful if the current graph allows to add this edge (⪚, in an undirected graph you are not allowed to add multiple edges between two data elements). By keeping the mouse pointer pressed at the button, a menu shows up at which the pointer type of the new created pointers can be selected (only if different pointer types exist).

- Delete: Click at an element to delete it. If you delete a node, all adjacent edges are also deleted.

- Zoom: Click at the whiteboard, keep the &LMB; pressed, and by this draw a rectangle. The whiteboard will be zoomed to the selected area. Using the mousewheel to zoom in or out as well. A double click with the &LMB; restores the original zoom.

#### Alignment Toolbar

You can add the optional Alignment Toolbar. Pressing an action at this toolbar has direct effect to the currently selected nodes:

- Top: Align the data elements at the vertical position of the top-most data element. This only affects the vertical positions.

- Center: Align the data elements at the vertical position given by the center of all selected data elements vertical positions. This only affects the vertical positions.

- Base: Align the data elements at the vertical position of the bottom-most data element. This only affects the vertical positions.

- Left: Align the data elements at the horizontal position of the left-most data element. This only affects the horizontal positions.

- Center: Align the data elements at the horizontal position of the top-most data element. This only affects the horizontal positions.

- Right: Align the data elements at the horizontal position of the right-most data element. This only affects the horizontal positions.

- Circle: Aligns the data elements at a circle of diameter equals to the maximal distance of the data elements. The data elements are positioned in the same sequence as given by view from the center of gravity of these data elements.

- Minimize Crossing Edges: Rearrange the selected data elements to minimize the number of crossing connections (application of the Fruchterman-Reingold algorithm).

### Working with Graph Documents

A &rocs; project contains one or multiple graph documents that can be edited with the visual graph editor. Further, each document can contain an arbitrary number of data structures. Here, data structures of a document all use the same data structure backend. This section will explain how to switch between documents and how to create new ones.

#### The Document Selector Bar

The document selector bar is used to select the current graph document and further the current data structure. Using the visual graph editor tools to create data structures elements will automatically add those newly created elements to the current data structure. Also, this bar gives direct access to delete existing or create new data structures within the current document.

- New: This action creates a new data structure using an automatic naming pattern given by the data structure backend. The created data structure is added to the currently selected graph document.

- Delete: This action deletes the data structure that is currently selected in the data structure selector for the current document.

- Properties for Graph Document: Open a dialog that gives access to the document properties as well as the data and pointer types of the document.

- Properties for Data Structure: Open a dialog that gives access to the data structure properties.

The Main Toolbar. The Document Selector Bar.

#### Create and Import Graph Documents

To create a new graph document or to add an existing one to the project, use File New Project or Graph Document Import Graph. You can also import graph documents from third party applications (for this, see import-export).

## Writing and Executing Algorithms in &rocs;

&rocs; internally uses the QtScript scripting engine, which is a specific JavaScript engine. This means, all algorithms that you implement must use JavaScript. How JavaScript works and how to write JavaScript code is not covered in this handbook, though we explain how to access data structures, data elements and pointers of your data structures from the scripting engine. Since you never use the basic data structure object but one that is provided by the currently used data structure backend, the functionality of the data structure is extended by the corresponding backend and you should have a look at the specialized functionality. Especially, data structure backends use the common terms from their domain (nodes and edges in graphs, leafs and roots in trees, etc.)

It is important to know that changes done by the scripting engine are directly reflected at the properties at the visual graph editor whiteboard. Hence, the scripts actually modify the data structures.

### Controlling the Script Execution

#### Include Files

Your script documents can include other scripts. This can be useful to reduce the size of script documents and improve readability. Using Script Document Possible Includes you get a list of script files already shipped with &rocs; that could be included. You can include a script file with the following command:

        include_script(string path);            // relative or absolute path to script file

#### Script Output

During the execution of an algorithm, debug and program output is displayed in the Debug & Script Output. If the scripting engine detects a syntax error in your script, the error is also displayed as debug message. Note that all program messages are also displayed at the debug output (displayed as bold text).

You can control the text that is displayed at the script output by the following functions:

        Console.log(string message);            // displays the message as script output
        Console.debug(string message);          // displays the message as debug output

#### Control Script Execution

There are different execution modes for your scripts.

You can control the text that is displayed at the script output by the following functions:

- Run: Execute the script until it finishes.

- One Step: Execute script until one step ends. A step ends when the script calls the function `interrupt()`:

              interrupt();    // ends a step

- Debug: Execute script in debug mode. This opens the QtScript debug dialog.

- Stop: Stop script execution (only available if a script is executing).

## Scripting Engine API

Every backend provides a special set of functions and properties for its data structures and their elements. But also every backend provides the properties and functions that are defined for the base data structure.

&apiDatastructure; &apiGraphstructure; &apiLinkedListstructure; &apiRootedTreestructure; &apiConsole;
&chapterImportExport;

## Credits and License

&rocs;

Program Copyright:

- Copyright 2008 Ugo Sangiori (ugorox AT gmail.com)

- Copyright 2008-2012 Tomaz Canabrava (tcanabrava AT kde.org)

- Copyright 2008-2012 Wagner Reck (wagner.reck AT gmail.com)

- Copyright 2011-2013 Andreas Cord-Landwehr (cordlandwehr AT kde.org)

Documentation Copyright:

- Documentation copyright 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Documentation copyright 2009 Tomaz Canabrava (tcanabrava AT kde.org)

- Documentation copyright 2011-2013 Andreas Cord-Landwehr (cordlandwehr AT kde.org)

&underFDL; &underGPL;

## Installation

### How to obtain &rocs;

&install.intro.documentation;

### Compilation and installation

&install.compile.documentation;
&documentation.index;