# Handbok &rocs;

## Inledning

I det här kapitlet ger vi en översikt av de centrala funktionerna och arbetssättet i &rocs;. För den ivrige läsaren som direkt vill börja använda &rocs; föreslår vi att läsa åtminstone introduction-nutshell och använda scripting som referens för att skriva algoritmer.

### Syfte, målgrupp och arbetsflöde

&rocs; är en integrerad utvecklingsmiljö för grafteori avsedd för alla som är intresserade av att konstruera och analysera grafalgoritmer. Det omfattar speciellt

- föreläsare som vill demonstrera algoritmer för sina studenter,

- studenter som vill förstå och se hur deras algoritmer fungerar,

- och alla som är intresserade av datastrukturer och algoritmer.

För alla dessa användare tillhandahåller &rocs; en lättanvänd datastruktureditor för att skapa datastrukturer, ett kraftfullt skriptverktyg för att utföra algoritmer, och flera hjälpverktyg för simuleringar och experiment.

Det vanliga arbetssättet när &rocs; används är att börja med att skapa en graf med den visuella grafeditorn. Det kan man antingen göra för hand, genom att lägga till dataelement och koppla ihop dem, eller genom att använda en av datastrukturgeneratorerna (om tillgänglig för det aktuella datastrukturgränssnittet) som finns under Grafdokument Verktyg Skapa graf . Dessutom kan man också tilldela värden till datastrukturens element, antingen för hand eller genom att använda Grafdokument Verktyg Tilldela värden. Till sist kan man skriva algoritmer i Javascript och utföra dem med datastrukturen som just har skapats. Alla ändringarna som görs av algoritmen syns direkt i den visuella grafeditorn.

En skärmbild av &rocs;. En skärmbild av &rocs;.

### &rocs; i ett nötskal

I det här avsnittet ger vi en kortfattad översikt av de centrala delarna av &rocs;. Vi förklarar de viktiga begreppen datastruktur, datastrukturgränssnitt och elementtyper. Kännedom om dessa koncept är användbart för att förstå hur datastrukturer kan skapas och ändras i &rocs;.

I allmänhet arbetar &rocs; med projekt: när &rocs; startas skapas ett tomt projekt och du kan ersätta det genom att läsa in eller importera ett annat projekt. Härigenom består ett projekt själva av grafdokument och skript.

#### Grafdokument och datastrukturgränssnitt

Ett grafdokument representerar innehållet på en skrivtavla i den visuella grafeditorn. Härigenom kan ett grafdokument innehålla flera datastrukturer samtidigt, men bara ett datastrukturgränssnitt. Datastrukturgränssnitt finns tillgängliga för flera olika typer av grafer (allmänna grafer, länkade listor, rotade träd) och tillhandahåller ytterligare funktionalitet för sina specifika typer av grafer. Det kan vara automatisk positionering av elementen, särskilda ikonuppsättningar eller en utökad uppsättning skriptfunktioner för användning i algoritmer (för detaljinformation titta i motsvarande avsnitt av handboken). Det är möjligt att ändra datastrukturgränssnitt i ett grafdokument, även om information kan gå förlorad (t.ex. bågarna för en cirkel i en allmän graf läggs inte till i ett träd, om du byter till gränssnittet för rotat träd).

Grafdokument utgör också basen för att definiera piltyper och datatyper.

#### Datastrukturer

Datastrukturer är basen för allt arbete i &rocs;. Du kan lägga till en eller flera sådana i ett grafdokument, och dataelement (noder, datavärden) och pilar till dem, samt ändra dem med skript. För detta har varje datastruktur sitt unika namn som den går att komma åt med från skript. På grund av valet av gränssnitt för den aktuella datastrukturen kan det hända att du inte kan ändra datastrukturen helt godtyckligt (t.ex. ska ett träd aldrig innehålla en cykel). Datastrukturgränssnittet bestäms av det gränssnitt för datastrukturer associerat med motsvarande grafdokument som innehåller datastrukturen.

#### Piltyper

Med piltyper kan du definiera olika typer av pilar som ska användas av datastrukturerna. Det betyder att en piltyp kan få en individuell layout (stort sett en färg) och det är enkelt att bara komma åt pilar av en viss typ från skript. Typiska användarfall för pilar kan vara att implementera meta-bågar i datastrukturer som åskådliggör förhållanden mellan dataelement (t.ex. åskådliggör kommunikationsbehov). Men om skript dessutom ska identifiera särskilda typer av bågar (t.ex. träd och korsande bågar i djup-först sökalgoritmer), kan piltyper vara ett elegant sätt att implementera det.

#### Datatyper

I flera datastrukturproblem ska en uppsättning dataelement delas upp i grupper av olika typer (t.ex. ett klusterproblem eller täckningsproblem). Annars är det användbart att specificera en dataelementtyp för att uttrycka en specifik sort (t.ex. bredd-först sökning) när en algoritm utförs. För sådana fall kan datatyper definieras. Varje datatyp har sin egen ikon, och dataelement av en viss typ kan enkelt kommas åt från skript.

#### Dynamiska egenskaper

Varje dataelement och pil kan ha många egenskaper. Vissa av dessa egenskaper är standardvärden från datastrukturgränssnittet. Se dokumentationen av datastrukturgränssnittet för mer information. För att lägga till fler egenskaper i dataelement och pilar kan du lägga till dynamiska egenskaper till dem. Varje dynamisk egenskap identifieras med sitt namn och kan innehålla vilket tillhörande värde som helst. Namnet måste börja med en bokstav (a-z eller A-Z) och kan bara innehålla bokstäver, siffror och '_'. Om du försöker använda ett ogiltigt tecken i egenskapsnamnet ändras inte egenskapen.

Använd dialogrutorna Dataelementegenskaper och Pilegenskaper i de sammanhangsberoende menyerna för respektive element eller skriptfunktionerna som förklaras i scripting-data-structure, för att lägga till dynamiska egenskaper.

Du kan också använda skript. Du behöver bara använda `add_property` med namn och värde på egenskapen. Därefter kan du använda node/pointer.propertyName för att ändra eller läsa av värdena.

Här är ett exempel på hur dynamiska egenskaper används med datastrukturgränssnittet "Graf".

    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

### Handledning

I det här avsnittet ska vi skapa ett exempelprojekt för att utforska några av de viktigaste funktionerna i &rocs;. Målet är att skapa en graf och ett skript som åskådliggör en enkel 2-approximativ algoritm för problemet med minimal hörntäckning. Minimal hörntäckning är problemet att hitta en delmängd av grafnoder C med minimal storlek, sådan att varje grafbåge är ansluten till minst en nod i C. Problemet är känt som NP-svårt, och vi vill åskådliggöra hur man hittar en approximation med faktorn 2 genom att hitta en motsvarighet i den givna grafen (i det följande använder vi de vanliga termerna för grafalgoritmer: grafen är datastrukturen, noder är dataelementen, bågar är pilarna).

Vårt mål är att åskådliggöra likheten mellan motsvarigheten och den minimala hörntäckningen. För att göra det behöver vi specificera två piltyper, en för att visa motsvarande bågar och en för att visa vanliga bågar, samt två datatyper som vi använder för att skilja på noder som ingår i C och de som inte ingår i C.

#### Skapa en graf

&rocs; levereras med ett hjälpverktyg för datastrukturgränssnittet Graf som kan skapa grafer. Vi går till Grafdokument Verktyg Skapa graf. Där skapar vi en Slumpmässig graf med 30 noder, 90 bågar och fröet 1 (fröet är startfrö för den slumpmässiga grafgenereringen, används samma frö flera gånger erhålles samma och upprepningsbara grafer). Till sist ändrar vi grafnamnet i datastrukturpanelen och kallar grafen `testgraf`.

#### Skapa typer

Vi använder knapparna Egenskaper på dokumentväljarraden för att visa egenskapsdialogrutan för data- och piltyper i det aktuella grafdokumentet. I datatyperna lägger vi till en ny typ som heter "C", som automatiskt för identifieraren `1`. Vi väljer serverbilden som ikon för typen. Dessutom byter vi till piltypsidan och lägger till en ny piltyp som kallas "match". Den får automatiskt identifieraren `1`, och vi ställer in färgen till blå.

#### Algoritmen

Till sist måste vi implementera approximationsalgoritmen. Vi använder följande implementering för den:

    var E = testgraph.list_edges(); // mängden obehandlade bågar
    var C = new Array();            // matchande bågar
    while (E.length
    > 0) {
        var e = E[0];        // vi tar första bågen e={u,v}
        var u = e.start();
        var v = e.end();
        e.set_type(1);        // ställ in bågen till en matchande båge
        E.shift();            // ta bort e (dvs. E[0]) från listan av bågar
        C.push(u);            // lägg till u i C
        C.push(v);            // lägg till v i C

        // markera u,v som noder i C
        u.set_type(1);
        v.set_type(1);

        // ta bort alla bågar från E som ansluter till u eller v
        var adjacent = u.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // hitta index
            if (index!=-1) {
                E.splice(index, 1); // ta bort om redan hittad
            }
        }
        var adjacent = v.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // hitta index
            if (index!=-1) {
                E.splice(index, 1); // ta bort om redan hittad
            }
        }
    }
    Console.log("Vertex Cover contains " + C.length + " nodes.");

#### Utför algoritmen

Till sist vill vi utföra algoritmen. För att göra det kan vi starta körningen med knappen Kör i skriptpanelen.

## &rocs; användargränssnitt

### Allmänna delar i användargränssnittet

Användargränssnittet är uppdelat i flera logiska delar som framgår av skärmbilden nedan.

Grafiska element i &rocs; användargränssnitt. Grafiska element i &rocs; användargränssnitt.

Dokumentväljare

- Det aktuella dokumentet och datastrukturen måste väljas med den här menyraden längst upp. Att skapa eller ta bort datastrukturer samt att komma åt datastrukturers egenskaper är också möjligt här.

Visuell grafeditor

- Detta är skrivtavlan där datastrukturer kan skapas och ändras. Högerklicka på skrivtavlan, på dataelement eller på pilar för att visa sammanhangsberoende menyer. Du kan använda verktygen från den visuella grafeditorns verktygsrad för att ändra elementen på den visuella grafeditorns skrivtavla.

Den visuella grafeditorns verktygsrad

- Denna verktygsrad tillhandahåller alla verktyg för den visuella grafeditorn.Använd knappen Lägg till element eller Lägg till anslutning för att skapa nya dataelement och lägga till dataelement respektive pilar. Nya dataelement läggs till i datastrukturen som för närvarande är markerad i Dokumentväljaren. Observera att både Lägg till element och Lägg till anslutning har sammanhangsberoende menyer för val av data- och piltyp för de nya elementen som ska skapas. För detaljerad information, se user-interface-toolbars.

Sidorad

- Till höger finns sidoraden som tillhandahåller flera verktyg för arbetsflödet:

  - Elementtyper: Denna grafiska komponent ger direktåtkomst till de tillgängliga pil- och datatyper.

  - Journal: Varje projekt har sin egen journal som t.ex. kan användas för anteckningar om uppgifter, resultat eller observationer.

  - Handbok: Den här grafiska komponenten kan användas för att direkt komma åt handboken och därmed skriptdokumentationen.

  - Programmeringsgränssnittet för skript: Den här grafiska komponenten kan användas för att direkt komma åt handboken och därmed skriptdokumentationen.

Skripteditor

- I texteditorn kan algoritmer skrivas som förklaras i detalj i scripting. Det går att arbeta med flera skriptdokument samtidigt genom att använda flera flikar. Skivsymbolen på en flik visas om skriptet innehåller osparade ändringar.

Skriptutmatning

- I det här textområdet visas antingen felsökningsinformation eller skriptutmatning från algoritmer, beroende på val av utmatningsinställning längst upp i den grafiska komponenten. Om ett fel uppstår i skriptet, väljes automatiskt felsökningsutmatning.

Styrning

- Här hittar man hur körning av algoritmerna styrs. Skriptet som för närvarande är öppet i skripteditorn kan köras med genom att klicka på Kör. Medan skriptet körs, är det möjligt att stoppa det genom att klicka på knappen Stopp. Observera att körning med Ett steg bara stoppar vid specifika nyckelord (se scripting).

### Verktygsrader

Det finns olika verktygsrader för den visuella grafeditorn som gör det möjligt att komma åt funktioner med bara ett klick. Med standardinställningen visas följande verktygsrader:

- Huvudverktygsrad

- Justeringsverktygsrad

#### Huvudverktygsrad

Huvudverktygsraden innehåller följande åtgärder. Att klicka på en åtgärd leder till att muspekaren utför den åtgärden på den visuella grafeditorns skrivtavla:

- Flytta: För att markera element, klicka antingen på en oanvänd plats på skrivtavlan, håll musknappen nedtryckt och rita en rektangel som innehåller några noder och/eller bågar för att markera dessa element, eller klicka annars direkt på ett omarkerat element för att markera det. Om du klickar på ett markerat element, eller en uppsättning markerade element, kan de flyttas omkring genom att hålla musknappen nedtryckt och flytta omkring musen. Det är också möjligt att flytta markerade element med piltangenterna.

- Lägg till element: Klicka på ett godtyckligt ställe på den visuella grafeditorns skrivtavla för att skapa ett nytt dataelement som hör till datastrukturen som för närvarande är markerad. Genom att hålla muspekaren nedtryckt visas en meny där datatypen för det nyskapade dataelementen kan väljas (bara om olika datatyper finns).

- Lägg till anslutning: Klicka på ett dataelement, håll musknappen nedtryckt och rita en linje till ett annat dataelement, dit pilen/bågen ska peka. Åtgärden lyckas bara om den aktuella grafen tillåter att bågen läggs till (i en oriktad graf får t.ex. inte mer än en båge läggas till mellan två dataelement). Genom att hålla muspekaren nedtryckt, dyker en meny upp där piltypen för de nyskapade pilarna kan väljas (bara om olika piltyper finns).

- Ta bort: Klicka på ett element för att ta bort det. Om du tar bort en nod, tas också alla intilliggande bågar bort.

- Zooma: Klicka på skrivtavlan, håll vänster musknapp nertryckt, och rita på så sätt en rektangel. Skrivtavlan zoomas till det markerade området. Använd också mushjulet för att zooma in eller ut. Ett dubbelklick med musens vänsterknapp återställer ursprunglig zoomnivå.

#### Justeringsverktygsrad

Det går att lägga till en valfri justeringsverktygsrad. Genom att klicka på ett alternativ i verktygsraden erhålls direkt en effekt på noderna som för närvarande är markerade:

- Upp: Justera dataelementen längs den vertikala positionen av det översta dataelementet. Detta påverkar bara vertikala positioner.

- Mitt: Justera dataelementen längs den vertikala positionen som anges av centrum för alla markerade noders vertikala position. Detta påverkar bara vertikala positioner.

- Bas: Justera dataelementen längs den vertikala positionen av det understa dataelementet. Detta påverkar bara vertikala positioner.

- Vänster: Justera dataelementen längs den horisontella positionen för dataelementet längst åt vänster. Detta påverkar bara horisontella positioner.

- Mitt: Justera dataelementen längs den horisontella positionen för dataelementet längst upp. Detta påverkar bara horisontella positioner.

- Höger: Justera dataelementen längs den horisontella positionen för dataelementet längst åt höger. Detta påverkar bara horisontella positioner.

- Cirkel: Justerar dataelementen längs en cirkel vars diameter är lika med den maximala avståndet mellan dataelementen. Dataelementen placeras i samma följd som ges av hur dessa dataelement ser ut från sin tyngdpunkt.

- Minimera korsande bågar: Arrangera om markerade dataelement för att minimera antal korsande anslutningar (applicerar Fruchterman-Reingold-algoritmen).

### Arbeta med grafdokument

Ett projekt i &rocs; innehåller ett eller flera grafdokument som kan redigeras med den visuella grafeditorn. Dessutom kan varje dokument innehålla ett godtyckligt antal datastrukturer. Här använder datastrukturer i ett dokument alla samma datastrukturgränssnitt. Det här avsnittet förklarar hur man byter mellan dokument och hur man skapar nya.

#### Dokumentväljarraden

Dokumentväljarraden används för att välja det aktuella grafdokumentet och dessutom den aktuella datastrukturen. Att använda det visuella grafeditorverktyget för att skapa datastrukturelement lägger automatiskt till de nyskapade elementen i den aktuella datastrukturen. Dessutom ger raden direktåtkomst för att ta bort befintliga eller skapa nya datastrukturer inne i det aktuella dokumentet.

- Ny: Åtgärden skapar en ny datastruktur med användning av ett automatiskt namngivningsmönster given av datastrukturens gränssnitt. Den skapade datastrukturen läggs till i grafdokumentet som för närvarande är valt.

- Ta bort: Åtgärden tar bort datastrukturen som för närvarande är markerad i datastrukturväljaren för det aktuella dokumentet.

- Egenskaper för Grafdokument: Öppna en dialogruta som ger tillgång till dokumentegenskaperna samt data- och piltyperna i dokumentet.

- Egenskaper för Datastruktur: Öppna en dialogruta som ger tillgång till datastrukturens egenskaper.

Huvudverktygsraden. Dokumentväljarraden

#### Skapa och Importera grafdokument

För att skapa ett nytt grafdokument, eller lägga till ett befintligt dokument i projektet, använd Arkiv Nytt projekt eller Grafdokument Importera graf. Du kan också importera grafdokument från tredjepartsprogram (för mer om detta, se import-export).

## Skriva och utföra algoritmer i &rocs;

Internt använder &rocs; skriptgränssnittet QtScript, som är ett specifikt Javascript-gränssnitt. Det innebär att alla algoritmer du implementerar måste använda Javascript. Hur Javascript fungerar och hur man skriver kod för Javascript täcks inte av den här handboken, men vi beskriver hur du kommer åt datastrukturer, dataelement och pilar i dina datastrukturer via skriptgränssnittet. Eftersom du aldrig använder det grundläggande datastrukturobjektet, utan ett som tillhandahålls av det aktuella datastrukturgränssnittet, utökas datastrukturens funktionalitet av motsvarande gränssnitt, och du måste ta en titt på den specialiserade funktionaliteten. I synnerhet, använder datastrukturgränssnitt vanlig terminologi från sin domän (noder och bågar för grafer, löv och rot för träd, etc.).

Det är viktigt att känna till att ändringarna som görs av skriptgränssnittet direkt reflekteras i egenskaperna på den visuella grafeditorns skrivtavla. Sålunda ändrar skripten verkligen själva datastrukturerna.

### Styra körning av skript

#### Inkludera filer

Skriptdokument kan inkludera andra skript. Det kan vara användbart för att minska storleken på skriptdokumenten och förbättra läsbarheten. Genom att använda Skriptdokument Möjliga deklarationsfiler får du en lista över de skriptfiler som levererades med &rocs; som kan inkluderas. Du kan inkludera en skriptfil med följande kommando:

    include_script(string path);            // relativ eller absolut sökvägtill skriptfilen

#### Skriptutmatning

När en algoritm körs visas felsöknings- och programutdata i felsöknings- och skriptutmatning. Om skriptgränssnittet upptäcker ett syntaxfel i skriptet visas även det felet som ett felsökningsmeddelande. Observera att alla programmeddelanden också visas i felsökningsutmatningen (med fetstil).

Du kan bestämma vilken text som visas i skriptutmatningen med följande funktioner:

        Console.log(string message);              // visar meddelandet som skriptutdata
        Console.debug(string message);            // visar meddelandet som felsökningsutdata

#### Styr körning av skript

Det finns olika sätt att köra skripten.

Du kan bestämma vilken text som visas i skriptutmatningen med följande funktioner:

- Kör: Kör skriptet till det är klart.

- Ett steg: Kör skript tills ett steg avslutas. Ett steg avslutas när skriptet anropar funktionen `interrupt()`:

      interrupt();    // avslutar ett steg

- Felsökning: Kör skript i felsökningsläge. Detta öppnar QtScripts felsökningsdialogruta.

- Stoppa: Stoppa körning av skript (bara tillgängligt om ett skript körs).

## Programmeringsgränssnittet för skripthantering

Varje gränssnitt tillhandahåller en särskild uppsättning funktioner och egenskaper för sina datastrukturer och deras element. Men varje gränssnitt tillhandahåller också egenskaperna och funktionerna som har definierats för basdatastrukturen.

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

## Tack till och licens

&rocs;

Program Copyright:

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

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

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

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

Dokumentation Copyright:

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

- Dokumentation copyright 2009 Tomaz Canabrava (tcanabrava SNABELA kde.org)

- Dokumentation copyright 2011-2013 Andreas Cord-Landwehr (cordlandwehr SNABELA kde.org)

Översättning Stefan Asserhäll stefan.asserhall@bredband.net

&underFDL; &underGPL;

## Installation

### Hur man skaffar &rocs;

&install.intro.documentation;

### Kompilering och installation

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