# Manuale di &rocs;

## Introduzione

In questo capitolo daremo una panoramica delle funzionalità principali e del processo di lavoro di &rocs;. Per gli impazienti che volessero iniziare subito a usare &rocs;, suggeriamo di leggere almeno introduction-nutshell e usare scripting come riferimento nella scrittura degli algoritmi.

### Obiettivi, destinatari e processo di lavoro

&rocs; è un ambiente di sviluppo integrato per la teoria dei grafi, pensato per chiunque sia interessato a tracciare e analizzare algoritmi a grafo. Ciò include esplicitamente:

- docenti che vogliano dimostrare gli algoritmi ai loro studenti,

- studenti che vogliono vedere e capire come funziona il loro algoritmo,

- e chiunque sia interessato alle strutture di dati e agli algoritmi.

Per tutti questi utenti, &rocs; fornisce un editor per creare le strutture di dati, un potente motore di scripting per eseguire gli algoritmi, e diversi strumenti di supporto per simulazioni ed esperimenti.

Il processo di lavoro tipico con &rocs; è di cominciare creando un grafo con l'editor visuale di grafi. Lo puoi fare a mano, cioè aggiungendo elementi di dati e collegandoli, o usando uno dei generatori di strutture di dati (se disponibili per il motore di strutture di dati attualmente selezionato). I generatori di strutture di dati sono reperibili sotto Grafo Strumenti Genera grafo. Inoltre, puoi assegnare dei valori agli elementi della struttura di dati, a mano o con Grafo Strumenti Assegna valori. Infine, puoi scrivere l'algoritmo in JavaScript ed eseguirlo con la struttura di dati appena creata. Tutte le modifiche effettuate dall'algoritmo sulla struttura di dati saranno visibili direttamente sull'editor visuale di grafi.

Una schermata di &rocs;. Una schermata di &rocs;.

### &rocs; in breve

In questa sezione diamo una breve panoramica degli elementi fondamentali di &rocs;. Spieghiamo le nozioni principali delle strutture di dati, dei loro motori, e i tipi di elementi. Capire questi concetti è utile per capire come le strutture di dati possono essere create e modificate con &rocs;.

In generale &rocs; lavora con dei progetti: quando si apre &rocs;, viene creato un progetto vuoto, e lo puoi sostituire caricando o importando un altro progetto. In questo contesto, un progetto consiste di grafi e script.

#### Grafi e motori per strutture di dati

Un grafo rappresenta il contenuto di una lavagna nell'editor visuale di grafi. Un grafo può perciò contenere numerose strutture di dati tutte insieme, ma un solo motore per strutture di grafi. I motori per strutture di dati sono disponibili per numerosi tipi di grafi (grafi generali, liste collegate, strutture ad albero) e forniscono funzionalità particolari per un tipo di grafico specifico. Ad esempio il posizionamento automatico degli elementi, insiemi di icone speciali oppure un ampliamento dell'insieme delle funzioni di script da usare negli algoritmi (per i dettagli cerca nella sezione corrispondente del manuale). Si può modificare il motore delle strutture di dati di un grafo, ma questa operazione può portare ad una perdita di dati (ad esempio, gli archi di una circonferenza in un grafo generale non saranno aggiunti ad una struttura ad albero nel momento in cui si passa al motore per strutture ad albero).

I grafi costituiscono anche la base per definire i tipi di puntatori e di dati.

#### Strutture di dati

Le strutture di dati sono alla base di tutte le operazioni in &rocs;. Puoi aggiungerne una o molte ad un grafo, aggiungere elementi di dati (nodi, dati) o puntatori e modificarle attraverso l'uso di script. Affinché ciò sia possibile, ogni struttura di dati è denotata da un nome unico che permette di accedervi dagli script. A seconda del motore attualmente in uso, non è sempre possibile modificare la struttura di dati in modo arbitrario (ad esempio, gli alberi non dovrebbero mai contenere cicli). Il motore delle strutture di dati in uso è determinato dal motore delle strutture di dati associato al grafo corrispondente che contiene la struttura di dati.

#### Tipi di puntatori

Attraverso le diverse tipologie di puntatori è possibile definire diversi tipi di puntatori da usare nelle strutture di dati. In altri termini, un tipo di puntatore può essere associato ad un layout (sostanzialmente un colore) specifico ed è inoltre semplice accedere solo ai puntatori di un tipo specifico attraverso gli script. Un utilizzo tipico dei puntatori è quello di implementare meta-bordi per le strutture di dati che permettano di visualizzare le relazioni i singoli dati. Inoltre se lo script dovrà identificare tipi specifici di archi (ad esempio, alberi e archi incrociati negli algoritmi di ricerca in profondità) i tipi di puntatori possono essere un elegante strumento di implementazione.

#### Tipi di dati

In numerosi problemi relativi alle strutture di dati, un insieme di singoli dati deve essere distribuito in gruppi di diverso tipo (ad esempio nei problemi di analisi dei gruppi o di copertura). Oppure, l'insieme di dati è utile per l'esecuzione di un algoritmo che specifica il tipo di un singolo dato per esprimere un particolare tipo (ad esempio nella ricerca in ampiezza). Per questi utilizzi, è possibile definire i tipi di dati. Ogni tipo è associato ad un'icona e alcuni particolari tipi sono facilmente raggiungibili attraverso gli script.

#### Proprietà dinamiche

Ogni singolo dato o puntatore può possedere molte proprietà. Alcune di queste proprietà hanno un valore predefinito dal motore delle strutture di dati. Per estendere le proprietà dei dati e dei puntatori si possono aggiungere delle proprietà dinamiche. Ogni proprietà dinamica viene identificata attraverso il nome e può contenere qualsiasi valore ad essa associato. Il nome deve cominciare con una lettera (a-z o A-Z) e può contenere solo lettere, numeri e _. Se dovessi usare un carattere non valido nel nome della proprietà, essa non verrà modificata.

Per aggiungere una proprietà dinamica, usare le finestre Proprietà degli elementi dei dati e Proprietà dei puntatori, collocate nei menu contestuali dei rispettivi elementi o funzioni di script, come spiegato nelscripting-data-structure.

Puoi anche usare gli script. Devi solo scrivere `add_property` con il nome e il valore della proprietà. Dopodiché, puoi usare nodo/puntatore.nomeProprietà per impostare o leggere i valori.

Ecco un esempio di come usare le proprietà dinamiche con il motore di strutture di dati 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

### Esercitazione

In questa sezione verrà elaborato un progetto di esempio per esplorare alcune tra le più importanti funzioni di &rocs;. L'obbiettivo è quello di creare un grafo e uno script che illustrino un semplice algoritmo di approssimazione di fattore 2 per trattare un problema di copertura minima dei vertici. Questo problema può essere descritto come la ricerca del più piccolo sottoinsieme C di vertici in un grafo tale che ogni arco ha almeno un'estremità in C. Si tratta di un problema NP-completo e il nostro obbiettivo è quello di trovare un'approssimazione di fattore 2 attraverso la ricerca di una corrispondenza all'interno di un grafo dato (nel seguito saranno utilizzati i termini comuni degli algoritmi per grafi: un grafo è la struttura di dati, i nodi sono i singoli elementi di dati e gli archi sono i puntatori).

Il nostro obbiettivo è di visualizzare la corrispondenza tra l'accoppiamento e la copertura minima dei vertici. Per ottenere questo obbiettivo dobbiamo specificare due tipi di puntatori, uno per mostrare gli archi accoppiati e l'altro per mostrare gli archi ordinari; dobbiamo specificare inoltre due tipi di dati che useremo per distinguere i nodi contenuti in C da quello non contenuti in C.

#### Generare un grafo

Per il motore di strutture di dati Graph, &rocs; mette a disposizione uno strumento di supporto capace di generare grafi. Si trova in Grafo Strumenti Genera grafo. In questo modo si genera un grafo casuale composto di 30 nodi, 90 archi, e con seme di generazione 1 (il seme determina la casualità del grafo; partendo dallo stesso seme si riproduce lo stesso grafo). Infine, modifichiamo il nome del grafo nel pannello della struttura di dati, chiamandolo `grafo di prova`.

#### Creazione di tipi

Per aprire la finestra di dialogo delle proprietà per i tipi di dati e puntatori si usa il tasto Proprietà nella barra di selezione dei documenti. Per il tipo di dati si aggiunge un nuovo tipo chiamato C che riceve automaticamente l'identificativo `1`. Per questo tipo si seleziona l'immagine del server come icona. Successivamente si passa alla pagina relativa al tipo di puntatore, si aggiunge un nuovo puntatore chiamato corrispondente che riceve automaticamente l'identificativo `1` e si imposta il colore blu.

#### L'algoritmo

Al minimo è necessario implementare l'algoritmo di approssimazione. Per farlo si utilizza la seguente implementazione:

    var E = testgraph.list_edges(); // insieme degli archi non esaminati
    var C = new Array();            // archi accoppiati
    while (E.length
    > 0) {
        var e = E[0];        // prende il primo arco e={u,v}
        var u = e.start();
        var v = e.end();
        e.set_type(1);        // imposta l'arco come arco accoppiato
        E.shift();            // elimina l'arco e (i.e., E[0]) dalla lista degli archi
        C.push(u);            // aggiunge u a C
        C.push(v);            // aggiunge v a C

        // segna u,v come nodi di C
        u.set_type(1);
        v.set_type(1);

        // rimuova da E tutti gli archi incidenti a u o v
        var adjacent = u.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // trova l'indice
            if (index!=-1) {
                E.splice(index, 1); // elimina l'indice dopo averlo trovato
            }
        }
        var adjacent = v.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // trova l'indice
            if (index!=-1) {
                E.splice(index, 1); // elimina l'indice dopo averlo trovato
            }
        }
    }
    Console.log("Vertex Cover contains " + C.length + " nodes.");

#### Eseguire l'algoritmo

Vogliamo infine eseguire l'algoritmo. Facciamo partire l'esecuzione dal pulsante Esegui nel pannello di controllo dello script.

## L'interfaccia di &rocs;

### Elementi generali dell'interfaccia

L'interfaccia si divide in diverse parti logiche, come presentato nella schermata sotto.

Elementi grafici dell'interfaccia di &rocs;. Elementi grafici dell'interfaccia di &rocs;.

Selettore dei documenti

- In questa barra dei menu in alto devi selezionare il documento e la struttura di dati attuale. Da qui è anche possibile creare ed eliminare strutture di dati, e oltre ad accedere alle loro proprietà.

Editor visuale di grafi

- Questa è la lavagna dove le strutture di dati possono essere create e modificate. Facendo clic con il tasto destro sulla lavagna, su dati particolari o su puntatori si richiama un menu contestuale. Si possono usare gli strumenti della Barra dell'editor visuale di grafi per modificare gli elementi attraverso a lavagna dell'editor visuale di grafi.

Barra dell'editor visuale di grafi

- Questa barra fornisce tutti gli strumenti dell'editor visuale di grafi. Usa il pulsante Aggiungi elemento o Aggiungi connessione rispettivamente per creare o connettere nuovi elementi. I nuovi elementi di dati vengono aggiunti alla struttura di dati attualmente selezionata nel selettore dei documenti. Nota che sia il pulsante Aggiungi elemento che Aggiungi connessione hanno dei menu per selezionare il tipo di elementi da creare. Per maggiori dettagli si veda user-interface-toolbars.

Barra laterale

- A destra, puoi trovare la barra laterale che contiene diversi strumenti per il processo di lavoro:

  - Tipi di elemento: questo dà accesso immediato ai tipi di puntatori e dati disponibili.

  - Diario: ogni progetto ha il suo diario, che si può usare per esempio per annotarsi compiti, risultati e osservazioni.

  - Manuale: per avere accesso immediato al manuale, e attraverso questo, alla documentazione degli script, puoi aprire questo.

  - API di scripting: per avere accesso immediato alla documentazione degli script, puoi aprire questo.

Editor di script

- In questo editor di testo puoi scrivere algoritmi come spiegato in dettaglio in scripting Puoi lavorare su diversi script allo stesso tempo aprendo o creando nuove schede. Se le modifiche attuali non sono salvate, appare un simbolo a forma di dischetto sulla linguetta.

Output degli script

- Quest'area di testo mostra o informazioni di debug o l'output dello script dell'algoritmo, a seconda dell'impostazione attiva in alto. Se lo script produce un errore, viene automaticamente selezionato l'output di debug.

Controlli

- Qui trovi i controlli per l'esecuzione degli script. Puoi eseguire lo script attualmente aperto nell'editor degli script premendo Esegui. Mentre lo script è in esecuzione, è possibile interromperlo premendo il pulsante Interrompi. L'esecuzione Un passo si ferma solo attraverso determinate parole chiave (vedi scripting).

### Barre degli strumenti

Ci sono diverse barre per l'editor visuale di grafi che permettono di accedere a varie funzionalità con un solo clic. Come impostazione predefinita, sono visualizzate le seguenti barre:

- Barra principale

- Barra di allineamento

#### Barra principale

La barra principale consiste delle seguenti azioni. Fare clic su un'azione implica che il puntatore del mouse l'applica alla lavagna dell'editor visuale di grafi:

- Sposta: per selezionare gli elementi, fai clic su un'area vuota della lavagna, tieni il mouse premuto e disegna un rettangolo che contenga alcuni elementi di dati o puntatori per selezionarli, oppure fai direttamente clic su un elemento non selezionato per selezionarlo. Se fai clic su uno o più elementi selezionati, li puoi spostare tenendo il mouse premuto e spostando il mouse. È possibile spostare gli elementi selezionati anche con i tasti freccia.

- Aggiungi elemento: Facendo clic su un punto qualsiasi della lavagna dell'editor visuale di grafi si crea un nuovo dato che appartiene alla struttura dati attualmente selezionata. Tenendo premuto a lungo il tasto del mouse appare un menu attraverso il quale il tipo del dato appena creato può essere selezionato (ciò richiede l'esistenza di tipi di dati differenti).

- Aggiungi arco: fai clic su un dato, tieni il mouse premuto, e traccia una linea a un altro dato a cui il puntatore o arco punterà. Questa azione ha successo solo se il grafo attuale permette l'aggiunta di questo arco (per esempio, in un grafo non direzionale non è possibile aggiungere archi multipli tra due dati). Mantenendo la pressione del puntatore sul tasto, appare un menu da cui è possibile selezionare il tipo a cui assegnare il puntatore appena creato.

- Elimina: fai clic su un elemento per eliminarlo. Se elimini un nodo, verranno eliminati anche tutti gli archi adiacenti.

- Ingrandisci: fai clic sulla lavagna, tieni premuto il &LMB;, e traccia un rettangolo. La lavagna verrà ingrandita all'area selezionata. Puoi usare anche la rotellina del mouse per ingrandire e rimpicciolire. Un doppio clic del &LMB; ripristina la scala originale.

#### Barra di allineamento

Puoi aggiungere la barra di allineamento facoltativa. Premere un'azione di questa barra ha un effetto immediato sui nodi attualmente selezionati:

- In alto: allinea gli elementi di dati alla posizione verticale dell'elemento più in alto. Questo ha effetto solo sulle posizioni verticali.

- Al centro: allinea i dati alla posizione verticale data dal centro delle posizioni verticali di tutti i dati selezionati. Questo ha effetto solo sulle posizioni verticali.

- Base: allinea i dati alla posizione verticale del dato più in basso. Questo ha effetto solo sulle posizioni verticali.

- A sinistra: allinea i dati alla posizione orizzontale del dato più a sinistra. Questo ha effetto solo sulle posizioni orizzontali.

- Al centro: allinea i dati alla posizione orizzontale del dato più in alto. Questo ha effetto solo sulle posizioni orizzontali.

- A destra: allinea i dati alla posizione orizzontale del dato più a destra. Questo ha effetto solo sulle posizioni orizzontali.

- In cerchio: allinea i dati in un cerchio del diametro pari alla massima distanza tra i dati. I dati sono posizionati nella stessa sequenza vista dal baricentro dei dati.

- Minimizza gli incroci degli archi: riorganizza i dati selezionati per minimizzare il numero di archi che si incrociano (applica l'argoritmo Fruchterman-Reingold).

### Lavorare coi grafi

Un progetto di &rocs; contiene uno o più grafi modificabili con l'editor visuale. Inoltre, ogni documento può contenere un numero qualsiasi di strutture di dati. Qui, le strutture di dati di un documento usano tutte lo stesso motore per strutture di dati. Questa sezione spiega come passare da un documento all'altro e come crearne di nuovi.

#### La barra di selezione dei documenti

La barra di selezione dei documenti si usa per selezionare il grafo attuale e la struttura di dati attuale. Quando si usa l'editor visuale dei grafi per creare elementi di strutture di dati, questi verranno automaticamente aggiunti alla struttura di dati attuale. Inoltre, questa barra dà accesso immediato all'eliminazione o alla creazione di nuove strutture nel documento attuale.

- Nuovo: questa azione crea una nuova struttura di dati con uno schema automatico per il nome dato dal motore delle strutture di dati. La struttura creata viene aggiunta al grafo attualmente selezionato.

- Elimina: questa azione elimina la struttura di dati attualmente selezionata nel selettore di strutture di dati del documento attuale.

- Proprietà del Grafo: apre una finestra che dà accesso alle proprietà del documento oltre ai tipi di dati e puntatori del documento.

- Proprietà della Struttura di dati: apre una finestra che dà accesso alle proprietà della struttura di dati.

La barra principale. La barra di selezione dei documenti.

#### Creare e importare grafi

Per creare un nuovo grafo o aggiungerne uno al progetto attuale, usa File Nuovo progetto oppure Grafo Importa grafo. È anche possibile importare grafi da applicazioni terze (per approfondire, vedi import-export).

## Scrivere ed eseguire algoritmi in &rocs;

Internamente, &rocs; usa il motore di scripting di QtScript, un motore JavaScript specifico. È perciò richiesto che tutti gli algoritmi implementati usino JavaScript. Il funzionamento e l'uso di JavaScript non sono oggetto di questo manuale, anche se sono presenti informazioni su come accedere alle strutture di dati, agli elementi e ai puntatori delle strutture dal motore di scripting. Poiché non si usano mai le strutture di dati fondamentali, ma quelle prodotte dal motore di strutture in uso al momento, la funzionalità della struttura di dati viene estesa dal motore corrispondente, e dovresti fare riferimento alle sue funzionalità specifiche. In particolare, le i motori per strutture di dati usano dei termini comuni al loro dominio (nodi e archi nei grafi, rami e radici negli alberi, eccetera).

È importante sapere che i cambiamenti al motore di scripting vengono immediatamente riflessi sulle proprietà della lavagna nell'editor visuale di grafi. Gli script modificano quindi direttamente le strutture dati.

### Controllare l'esecuzione degli script

#### Inclusione File

Gli script possono includere altri script. In questo modo è possibile ridurre la dimensione degli script e migliorarne la leggibilità. Attraverso il menu Script Inclusioni Possibili puoi accedere ad una lista di script di esempio forniti da &rocs; che puoi includere negli script. Per includere uno script utilizza il seguente comando:

    include_script(string path);            // percorso assoluto o relativo dello script

#### Output degli script

Durante l'esecuzione di un algoritmo, gli output del debug e del programma sono mostrati nell'output di debug e degli script. Se il motore di scripting individua un errore nella sintassi dello script lo mostra anche come messaggio di debug. Tutti i messaggi del programma vengono mostrati (in grassetto) insieme all'output di debug

Si può controllare il testo mostrato nell'output dello script attraverso le seguenti funzioni:

    Console.log(string message);      // mostra il messaggio come output dello script
    Console.debug(string message);    // mostra il messaggio come output di debug

#### Controllare l'esecuzione degli script

Ci sono diversi modi di esecuzione per gli script.

Si può controllare il testo mostrato nell'output dello script attraverso le seguenti funzioni:

- Esegui: fa partire lo script e lo esegue fino al termine.

- Un passo: Esegue lo script fino al termine del primo passo. Un passo termina quando lo script richiama la funzione `interrupt()`:

      interrupt(); // termina un passo

- Debug: Esegue script in modalità debug. Lancia la finestra di dialogo di debug di QtScript.

- Stop: Ferma l'esecuzione di uno script (disponibile solo se uno script è in esecuzione).

## API del motore di scripting

Ogni motore fornisce una serie di funzioni e proprietà speciali per la struttura dati a cui si riferisce e i suoi elementi. Inoltre ogni motore fornisce le proprietà e le funzioni definite per la struttura dati di base.

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

## Riconoscimenti e licenza

&rocs;

Copyright del programma:

- Copyright 2008 di Ugo Sangiori (ugorox@gmail.com)

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

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

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

Copyright della documentazione:

- Copyright della documentazione 2009 di &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Copyright della documentazione 2009 di Tomaz Canabrava (tcanabrava@kde.org)

- Copyright della documentazione 2011-2013 di Andreas Cord-Landwehr (cordlandwehr@kde.org)

Traduzione di Francesco Nigro e Federico Zenithfederico.zenith@member.fsf.org

&underFDL; &underGPL;

## Installazione

### Come ottenere &rocs;

&install.intro.documentation;

### Compilazione e installazione

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