Gem-graph/architecture.md

# Gem-graph Architecture

- Le [serveur](https://gitlab.os-k.eu/gem-graph-team/gem-graph-server) est la partie dont l'exécution est rythmée par le calcul du modèle. Il comporte:

   - l'interface cli (command line interface) qui gère le serveur sur la machine où il est exécuté, ou à distance via le client (prévoir les traductions, la gestion du vocabulaire)

   - le scheduler qui coordonne le calcul du modèle en initiant et terminant le superviseur et les threads de calcul

   - le superviseur qui: 

      - maintient l'historique et effectue des mesures

      - effectue un test d'intégrité et renvoie son résultat au scheduler
         (pour détecter des états chaotiques, boucles infinies, répartitions déséquilibrées entre threads de calcul,...)
      
   - les threads de calcul

- Le [client](https://gitlab.os-k.eu/gem-graph-team/gem-graph-client) est la partie dont l'exécution est rythmée par l'utilisateur:

     - l'initiation / la terminaison / l'interface OS

     - les entrées / sorties / contrôles d'erreurs associés

     - le contrôle par l'utilisateur du déroulement du calcul effectué par le serveur

        - interface serveur > user (quel est l'état du modèle ? comment fonctionne l'automate ?)
        
        - user > interface serveur (stop, slow / speed, undo / redo, modify the nb of threads or the algorithm...)

     - la gestion des vues (conformité à une view_type)

     - les éditions

        - des états 

        - des règles de transition

        - des arbres de règles

     - interprétation des mesures des états du modèle et de son histoire

     - les traductions, la gestion du vocabulaire

     - des aides/facilités/présentation (textes, vues, liens) vers :

        - le contexte théorique, la bibliographie

        - principes / justifications / limites du modèle

        - licence, droits, auteurs, informations pratiques

        - outils de présentation

---

Le centre de calcul (serveur) est un automate qui effectue des transitions locales sur un état global

Les modifications successives de cet état global décrivent sa trajectoire dans son espace de phase

Chaque transition locale est calculée indépendamment, en mode asynchrone, par un thread de calcul

Tous les threads de calcul appliquent les mêmes règles selon le même algorithme

Un processus principal (scheduler) initie et termine ces threads 

Il garantit la cohérence de l'état global et valide l'ensemble du calcul ou l'interrompt en cas d'erreur
Il est seul à avoir accès à l'état global et à la liste des threads de calcul
Il n'a pas accès aux règles de transition
Il assure également (ou délègue) les fonctions de communications avec les modules périphériques

Il exécute un cycle qui comporte deux étapes principales:

 - recherche aléatoire d'un espace local

 - si trouvé:

    - arrêt de cette recherche 

    - préemption de cet espace local 

    - initiation d'un nouveau thread de calcul auquel est attibué cet espace local

 - sinon arrêt de cette recherche en un temps fini
    
 - recherche des threads de calcul en fin d'exécution 
   (ces threads se signalent dans une liste; leur temps de calcul est aléatoire)

 - si trouvé(s):

    - arrêt de cette recherche 

    - mise à jour de l'état global (insertion du ou des états locaux calculés)

    - terminaison des threads de calcul concernés et libération des verrous associés

 - sinon arrêt de cette recherche en un temps fini
 
 - stimule le superviseur qui effectue : mesures / recueil des commandes / retour d'information
 
 - s'arrête s'il le superviseur renvoie une alerte d'intégrité

---

chaque thread de calcul applique à un état local différent les mêmes règles de transition selon le même algorithme

il retourne un nouvel état local ou lève une exception

l'espace local est défini par un centre, une orientation et un rayon

(il peut être approché par un carré, un hexagone, un cube, ou toute autre forme le contenant)

optimisation : le centre est une cellule contenant au moins une flèche

L'algorithme de calcul de l'état local suit parallèlement un chemin partant du centre de l'espace local et un chemin allant de la racine de l'arbre des règles vers l'une des feuilles et il compare, à chaque itération: 

 - le nombre de flèches présentes dans chaque site

 - au nombre de flèches requis pour que la condition qui s'applique à ce site soit satisfaite
 (un parcours séquentiel ou aléatoire des règles est possible mais donnerait des résultats différents)
 
Ce chemin parcourt l'ensemble de tous les sites de toutes les cellules de l'espace local dans un ordre prédéfini

Ce parcours est optimisé de façon à maximiser la probabilité d'intersection entre:

 - les sites occupés dans l'état local

 - les sites définis par les règles de transition

Pour pouvoir effectuer ce parcours, il faut que les coordonnées (locales) des conditions et des actions des règles soient préalablement superposées aux coordonnées globales (calculées d'après l'origine et l'orientation) de l'espace local

le parcours s'interrompt dès qu'une condition est fausse: ceci veut dire qu'aucune règle ne décrit cet espace local (to do: renvoyer à l'utilisateur un message : "pas de règle s'appliquant à cet espace local")

sinon, il se termine lorque toutes les conditions d'une règle ont été satisfaites: la région de l'espace global auquel cet espace local est superposé peut être modifié selon les indications de cette règle

---

le nombre de calculs pouvant être effectués en parallèle dépend donc:

 - du rapport entre l'étendue de l'espace local et celui de l'espace global

 - du temps de parcours moyen des règles
 (si l'on néglige les opérations d'initiation et de terminaison des threads de calcul 
 et les opérations de communication de la boucle principale avec son environnement)

---

Le processus principal (scheduler) peut donc être un serveur pour les threads de calcul

L'interface ligne de commande doit également intercepter les demandes des utilisateurs et les déléguer a des threads ou processus dédiés