# Manual do &rocs;

Tomaz
Canabrava
tomaz.canabrava@gmail.com
Andreas
Cord-Landwehr
cordlandwehr@kde.org
Marcus
Gama

    marcus.gama@gmail.com

Tradução
André Marcelo
Alvarenga

    alvarenga@kde.org

Tradução
23/10/2021
KDE Gear 21.08
&FDLNotice;

&rocs; é uma ferramenta da teoria dos grafos.

KDE
kdeedu
matemática
matemática
grafos
nó
aresta
Rocs

## Introdução

Neste capítulo apresentaremos as funcionalidades e fluxos de trabalho básicos. As partes mais importantes são e , que, em conjunto, permitem que novos usuários possam começar a usar o &rocs;.

### Objetivos, público-alvo e funcionamento

O &rocs; é uma ferramenta da Teoria dos Grafos para todos os interessados no desenho e estudo de algoritmos de grafos. Em particular, estes são

- os professores, que poderão demonstrar algoritmos aos seus alunos,

- os alunos e pesquisadores, que queiram ver como funcionam os seus algoritmos e

- todos que estejam interessados em estruturas de dados e algoritmos.

Para todos eles, o &rocs; oferece um editor gráfico fácil de usar para criar grafos, um mecanismo de criação de scripts poderoso para executar algoritmos e diversas ferramentas para ajudar nas simulações, experiências e exportações de grafos. A forma típica de usar o &rocs; é criar um grafo, seja à mão (&ie;, arrastando nós e arestas para o quadro) ou usando um dos geradores de grafos. Os algoritmos de grafos poderão então ser implementados e executados no grafo criado, assim como todas as alterações feitas pelo algoritmo, serão visíveis imediatamente no editor do grafo.

Uma captura de tela do &rocs;.
Uma captura de tela do &rocs;.

### O &rocs; em resumo

Cada sessão do &rocs; é um projeto: Ao abrir o &rocs;, um projeto vazio será criado e ao carregar algum projeto existente, ele se tornará o projeto atual. Um projeto é composto de documentos de grafos, scripts/algoritmos e registro.

#### Documentos de grafo

Um documento de grafo representa o conteúdo de um quadro no editor de grafos. Contém informações sobre os tipos de nós e arestas definidos pelo usuário, suas propriedades e os nós e arestas já criados. Isto é, o &rocs; compreende o conjunto de todos os nós e arestas de um documento de grafo para formar um grafo (não necessariamente conectado). Tudo o que pertence ao documento de grafo fica acessível pelo mecanismo de criação de scripts através do objeto global ``Document``.

#### Tipos de borda

Em alguns cenários, os grafos consistem em diversos tipos de arestas (&eg;, um grafo não-direcional mais as arestas da árvore calculadas por um algoritmo de pesquisa primeiro-em-largura) que deverá ser tratado e apresentado de forma diferente. Para isso, além de um tipo de aresta padrão, você poderá definir outros tipos de arestas arbitrários. Cada tipo de aresta tem a sua própria representação visual, propriedades dinâmicas e pode ser definido como direcionado ou não-direcionado. A interface de criação de scripts oferece métodos de conveniência para acessar de forma específica apenas as arestas de determinados tipos.

#### Tipos de nós

De forma análoga aos tipos de arestas, você poderá definir diferentes tipos de nós de um grafo (&eg;, para indicar algumas regras especiais aos nós). Cada tipo de nó tem sua própria representação visual e propriedades dinâmicas.

#### Propriedades

Cada elemento (nó ou aresta) pode ter propriedades. Essas propriedades devem ser configuradas no tipo de nó ou aresta correspondente. As propriedades são identificadas e acessadas pelos seus nomes e poderão conter qualquer valor. Para criar novas propriedades ou alterar as existentes, use a barra lateral Tipos de elementos e o botão Propriedades para abrir a janela de propriedades.

Você também pode usar o mecanismo de criação de scripts para acessar as propriedades registradas e alterar os seus valores. No exemplo a seguir, assume-se que a propriedade peso está registrada para o tipo de aresta padrão.

    var nos = Document.nodes()
    for (var i = 0; i < nos.length; ++i){
        nos[i].peso = i;
    }
    for (var i = 0; i < nos.length; ++i){
        Console.log("peso do nó " + i + ": " + nos[i].peso);
    }

### Tutorial

Nesta seção criaremos um projeto de exemplo para explorar algumas das funções mais importantes do &rocs;. O objetivo é criar um grafo e um script que ilustre um algoritmo de 2 aproximações para o problema da cobertura mínima de vértices. Esse problema consiste em encontrar um subconjunto de nós do grafo C com um tamanho mínimo, de modo que cada aresta do grafo esteja conectada a pelo menos um nó do C. Este problema é conhecido por ser NP-difícil e queremos ilustrar como encontrar uma aproximação com um fator 2 computando uma correspondência no grafo dado.

Nosso objetivo é visualizar o relacionamento da ocorrência e da cobertura mínima de vértices. Para tal, queremos mostrar dois tipos de arestas, um para mostrar as arestas correspondentes e outro para mostrar as normais, assim como dois tipos de nós que usamos para distinguir os nós contidos em C e os não-contidos.

#### Gerando o grafo

Para criação do grafo, usamos o gerador de grafos padrão oferecido pelo &rocs;. Ele pode ser encontrado no menu principal em Documento do grafo Ferramentas Gerar o grafo. Aí, selecionamos um Grafo aleatório com 30 nós, 90 arestas e com uma raiz 1 (a raiz é o valor de referência inicial para o gerador de grafos aleatórios; a utilização da mesma raiz várias vezes origina grafos iguais).

#### Criação dos tipos de elementos

Usamos os Tipos de elementos e criamos um segundo tipo de nó, assim como um segundo tipo de aresta. Para os novos tipos, abrimos a janela de propriedades, usando os respectivos botões de Propriedades e definimos os IDs como `2`. Além disso, mudamos as cores dos elementos desses dois novos tipos (para distingui-los dos tipos padrão). Finalmente, definimos todos os tipos de arestas como sendo bidirecionais e os IDs dos tipos padrão como `1`.

#### O Algoritmo

Por último, temos de implementar o algoritmo de aproximação. Para isso, iremos usar a seguinte implementação:

    for (var i=0; i < Document.nodes.length; i++) {
        Document.nodes[i].type = 1;
    }
    for (var i=0; i < Document.edges.length; i++) {
        Document.edges[i].type = 1;
    }

    var E = Document.edges(); // define o conjunto de arestas não processadas
    var C = new Array();      // arestas correspondentes
    while (E.length
    > 0) {
        var e = E[0];         // escolhemos primeiro a aresta e={u,v}
        var u = e.from();
        var v = e.to();
        e.type = 2;           // define a aresta como sendo correspondente
        E.shift();            // remove a 'e' (i.e., E[0]) da lista de arestas
        C.push(u);            // adiciona a 'u' ao C
        C.push(v);            // adiciona a 'v' ao C

        // marcar o u,v como nós no C
        u.type = 2;
        v.type = 2;

        // remove do E todas as arestas que incidem em 'u' ou 'v'
        var adjacente = u.edges();
        for (var i=0; i < adjacente.length; i++) {
            var indice = E.indexOf(adjacente[i]); // localiza o índice
            if (indice != -1) {
                E.splice(indice, 1); // remove se já tiver encontrado
            }
        }
        var adjacente = v.edges();
        for (var i=0; i < adjacente.length; i++) {
            var indice = E.indexOf(adjacente[i]); // descobrir o índice
            if (indice != -1) {
                E.splice(indice, 1); // remover se já tiver encontrado
            }
        }
    }
    Console.log("A cobertura de vértices contém " + C.length + " nós.");

#### Executar o Algoritmo

O algoritmo pode ser executado com o botão Executar no painel de controle de scripts.

## A interface do usuário do &rocs;

### Elementos principais da interface do usuário

A interface do usuário está dividida em várias partes lógicas, como aparece na imagem abaixo.

Elementos gráficos da interface do &rocs;.
Elementos gráficos da interface do &rocs;.

Editor de grafos

  O editor oferece um quadro onde os nós e arestas podem ser colocados. Ao clicar duas vezes em qualquer um dos elementos, será aberto um menu de propriedades correspondente. Você pode usar as ferramentas das abas da barra lateral para criar e modificar os grafos.

  Ferramentas disponíveis:

  - No canto superior esquerdo da caixa, você encontrará os seguintes ícones de ação. Clicar em uma ação significa que o ponteiro do mouse aplica essa ação no quadro branco do editor de grafos:

    - Selecionar e mover: Para selecionar os elementos, você poderá clicar no espaço em branco do quadro, manter o mouse pressionado e desenhar um retângulo que contenha alguns elementos de dados e/ou arestas para selecionar estes elementos ou então clicar diretamente em um elemento não selecionado para escolher esse elemento. Se clicar em um elemento ou conjunto de elementos selecionados, você poderá mover estes elementos em conjunto. A movimentação dos elementos selecionados também é possível com as teclas direcionais.

    - Adicionar nó: Clique em uma posição arbitrária no quadro do editor do grafo para criar um novo elemento de dados que pertença ao grafo selecionado na estrutura de dados. Mantendo o ponteiro do mouse pressionado no botão, um menu mostra a quais tipos de dados o novo elemento de dados criados pode pertencer (somente se existirem diferentes tipos de dados).

    - Criar aresta: Clique em um elemento de dado, mantenha o mouse pressionado e desenhe uma linha para outro elemento de dado, apontando a aresta nessa direção. Esta ação só será bem-sucedida se o grafo atual permitir adicionar esta aresta (&eg;, em um grafo não-direcionado, você não poderá adicionar várias arestas entre dois elementos de dado). Mantendo o ponteiro do mouse pressionado no botão, um menu mostra qual o tipo das novas arestas criadas pode ser selecionado (somente se existirem diferentes tipos de aresta).

    - Excluir elemento: Clique em um elemento para excluí-lo. Se excluir um nó, todas as arestas adjacentes serão também excluídas.

Barra lateral

  À direita, você poderá encontrar a barra lateral que oferece diversas ferramentas para o seu fluxo de trabalho:

  - Tipos de elementos: Este widget fornece acesso direto para os tipos de arestas e nós disponíveis.

  - Diário: Cada projeto tem o seu próprio diário que pode ser usado para, &eg;, notas das tarefas, resultados ou observações.

  - API de criação de scripts: Para obter acesso direto à documentação do script, você poderá abrir este widget.

Editor de script

  Neste editor de texto você pode criar os algoritmos como explicado em detalhes em . Você poderá trabalhar com vários documentos de script ao mesmo tempo usando diversas abas.

Resultado do programa:

  Esta área de texto poderá apresentar as informações de depuração ou o resultado do script para o seu algoritmo, dependendo da configuração no topo deste elemento. Se o script emitir um erro, o resultado de depuração é automaticamente apresentado.

Controles

  Aqui você encontra os controles para executar scripts. Você pode executar o script que está aberto no editor de scripts pressionando o botão Executar. Enquanto o script estiver em execução, é possível interromper a execução pressionando o botão Parar.

## Criação de scripts

### Executando algoritmos no &rocs;

O &rocs; usa internamente o mecanismo &javascript; do QtScript. Isso significa que todos os algoritmos que implementarem deverão usar &javascript;. Nos seguintes pontos, explicaremos como acessar e modificar os elementos de um documento de grafo a partir do mecanismo de criação de scripts. É importante apontar que as alterações feitas pelo mecanismo de criação de scripts são diretamente refletidas nas propriedades dos elementos do editor de grafos.

#### Controle da execução dos scripts

Existem diferentes modo de execução para seus algoritmos:

- Executar: Executa o script até ele terminar.

- Parar: Interrompe a execução do script (só está disponível enquanto um script estiver em execução).

#### Resultado do programa

Durante a execução de um algoritmo, o resultado do programa e da depuração é exibido no Resultado do script & depuração. Se o motor de script detecta um erro de sintaxe em seu script, o erro é também exibido como uma mensagem de depuração. Observe que todas as mensagens do programa são também exibidas na saída de depuração (exibida em texto em negrito).

Você pode controlar o texto que é exibido no resultado do script com as seguintes funções:

    Console.log(string mensagem);    // exibe a mensagem como resultado do script
        Console.debug(string mensagem);  // exibe a mensagem como resultado da depuração
        Console.error(string message);          // exibe a mensagem como resultado do erro

#### API do mecanismo de criação de scripts

Cada uma das diferentes partes do &rocs; oferece um elemento estático que pode ser acessado pelo mecanismo de criação de scripts. São elas:

- ``Document`` para o documento do grafo

- ``Console`` para a saída do registro do console

Para uso explícito da API e para referência dos métodos, consulte a ajuda incorporada na barra lateral do &rocs;.

## Importar e exportar

### Compartilhar projetos do &rocs;

Os projetos do &rocs; podem ser importados e exportados como arquivos `.tar.gz`. Estes arquivos podem ser usados para compartilhar projetos. A importação e exportação pode ser feita com o Documento do grafo Importar grafo... e Documento do grafo Exportar grafo como..., respectivamente.

#### Importar e exportar documentos de grafo

O &rocs; atualmente suporta a importação e exportação para os seguintes formatos de arquivos:

- Arquivos &DOT;, também conhecidos como arquivos Graphviz

- Arquivos GML

- Arquivos no formato Trivial Graph

- Formato de Linguagem de Formatação Keyhole

##### Formato de Arquivo Trivial Graph

O Formato Trivial Graph (TGF, sigla em inglês) é um formato de arquivo simples baseado em texto para descrever gráficos. O arquivo TGF consiste de uma lista de definições de nó, o mapa de IDs dos nós para rótulos, seguido de uma lista de arestas. Neste formato, somente é possível ter um rótulo por nó e um valor por aresta. O &rocs; interpreta os gráficos importados como gráficos não direcionados. Os gráficos exportados conterão duas arestas por conexão se as conexões forem bidirecionais.

###### Especificação do formato

- O arquivo inicia com uma lista de nós (um nó por linha), seguida de uma linha com somente o caractere #, seguida pela lista de arestas (uma aresta por linha).

- Um nó consiste de um inteiro (identificador), seguido por um espaço, seguido por um string arbitrário.

- Uma aresta consiste de dois inteiros (identificadores) separados por um espaço, seguida por um espaço, seguida por um string arbitrário. É considerado que a aresta aponta do primeiro para o segundo identificador.

###### Exemplo

    1 nó inicial
    2 transmissor
    3 fundo
    #
    1 2 azul
    2 1 vermelho
    2 3 verde

##### Linguagem &DOT; / Formato do Arquivo de Grafos do Graphviz

&DOT; é uma linguagem descritiva em texto simples que permite tanto uma representação legível para os usuários dos grafos, assim como um processamento eficiente pelos programas de formatação de grafos. O &DOT; é o formato de arquivo padrão do pacote de visualização de grafos Graphviz, mas também é largamente usado por outras ferramentas de grafos. As extensões usuais para os nomes de arquivos da linguagem &DOT; são `.gv` e `.dot`.

###### Funcionalidades não suportadas

O &rocs; consegue processar todos os arquivos de grafos que tenham um grafo definido de acordo com a especificação da linguagem &DOT; https://graphviz.org/doc/info/lang.html. O suporte das funcionalidades da linguagem é completo, apesar das seguintes exceções:

- subgrafo: Devido à falta da funcionalidade do conceito de subgrafos no &rocs;, os subgrafos só são importados como um conjunto de elementos de dados e ligações. Especialmente, as ligações de e para subgrafos não são importadas.

- Atributos em &HTML; e &XML;: Os atributos (como as legendas) que contenham uma sintaxe em &HTML; ou &XML; são lidos sem qualquer alteração. Especialmente, não são lidos os ajustes de estilos e tipos de letra destes atributos.

###### Exemplo

    digraph meuGrafo {
        a -> b -> c;
        b -> d;
    }

## Layout do grafo

### Layout automática de grafos no &rocs;

O &rocs; pode criar grafos automaticamente. A ferramenta de layout de grafos do &rocs; pode ser encontrada no menu principal em Documento do Grafo Ferramentas Layout do Grafo. Existem dois algoritmos de layout diferentes que podem ser aplicados: Layout baseado em força e Layout de árvore radial. Para aplicar um deles, selecione a aba correspondente da ferramenta de layout de gráficos, escolha os parâmetros desejados e execute o algoritmo pressionando o botão OK. Detalhes específicos de cada um dos algoritmos de layout são fornecidos nas próximas seções.

#### Layout baseado na força

O Layout baseado em força pode ser aplicado a qualquer grafo. Intuitivamente, este algoritmo simula as forças que atuam em cada nó. Existem forças repulsivas entre pares de nós e forças de atração entre pares de nós que são vizinhos. A magnitude dessas forças pode ser especificada movendo os controles deslizantes correspondentes na interface do usuário.

Captura de tela da aba de Layout baseado em força da ferramenta de layout gráfico do &rocs;.
Captura de tela da aba de Layout baseado em força da ferramenta de layout gráfico do &rocs;.

Outro parâmetro que pode ser controlado é o fator de área. Este parâmetro controla como os nós são distribuídos. Layouts gerados com valores altos de fator de área tendem a ter grandes distâncias entre os nós.

##### Layout de árvore radial

O layout de árvore radial só pode ser aplicado a árvores. Qualquer tentativa de aplicar este algoritmo de layout a outros tipos de grafo produzirá uma mensagem de erro. Os parâmetros para o layout de árvore radial podem ser selecionados usando a interface de usuário fornecida.

Captura de tela da aba de Layout de árvore radial da ferramenta de layout gráfico do &rocs;.
Captura de tela da aba de Layout de árvore radial da ferramenta de layout gráfico do &rocs;.

O parâmetro de tipo de árvore seleciona entre um layout de árvore livre e um layout de árvore enraizada. Em um layout de árvore livre, os nós são colocados livremente, sem nenhuma hierarquia aparente entre eles. Em um layout de árvore enraizada, o nó raiz é colocado no topo e as subárvores são dispostas abaixo dele, dando a ideia de uma hierarquia entre os nós.

O parâmetro centro/raiz define qual nó será usado como raiz para o layout de árvore enraizada ou como centro para o layout de árvore livre. O centro de um layout de árvore livre é o primeiro nó a ser posicionado pelo algoritmo. Todos os outros nós são posicionados em círculos centrados no nó central. Um centro/raiz pode ser selecionado automaticamente pelo algoritmo de layout.

O parâmetro de separação de nós controla a distância entre os nós. Aumentar o valor desse parâmetro fará com que a distância entre os nós aumente. Da mesma forma, diminuir o valor desse parâmetro fará com que a distância entre os nós diminua.

## Créditos e Licença

&rocs;

Direitos autorais do programa:

- Direitos autorais 2008 Ugo Sangiori (ugorox AT gmail.com)

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

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

- Direitos autorais 2011-2015 Andreas Cord-Landwehr (cordlandwehr AT kde.org)

Direitos autorais da documentação:

- Direitos autorais da documentação 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Direitos autorais da documentação 2009 Tomaz Canabrava (tcanabrava AT kde.org)

- Direitos autorais da documentação 2011-2015 Andreas Cord-Landwehr (cordlandwehr AT kde.org)

Tradução de Marcus Gama marcus.gama@gmail.com e André Marcelo Alvarenga alvarenga@kde.org

&underFDL; &underGPL;

&documentation.index;