# Gem-graph Client

## Procédure de développement (Bonnes pratiques)

###   Une seule branche par fonctionnalité : dev/<fonctionnalité>

    git fetch origin                                     // récupère les branches sur le remote (git.a-lec.org)
    git switch devel                                     // car on part toujours de la branche devel
    git branch dev/<fonctionnalité>
    git switch dev/<fonctionnalité>
    git push --set-upstream origin dev/<fonctionnalité>  // dit au serveur que la branche existe
    
    [...]

Une fois fonctionnalité terminée et push accompli, ouvrir une merge request à
l'aide du lien fourni par git push
    

### Lors du travail sur une branche (les [...] du premier point)

Pour chaque session de travail : 
       
    git pull
    [...]
    git commit -am "WIP: <message>"
    git push
    
Une fois terminée la fonctionnalité et s'il y a un objectif de version :

    git tag -a vM.m.p -m "Fonctionnalité terminée"
    git commit -am "Fonctionnalité terminée"
    git push

## Objectifs de développement

A gem-graph client can be used to:

- create or edit a gem-graph model
- control a run of a gem-graph model by a gem-graph server
- get and study the results of such a run

---

In order to execute these functions, it must be able to manage:

inputs / outputs

    - load and save models
    - use xml schemas to check the validity of models 
    - connect to an instance of gem-graph server
    - dialog with this instance
    
a GUI able to:

    - render and edit the model
        - states
        - objects types
        - tags and references
        - transitions (edition 'de novo' or starting from a state copy)
        - transitions trees
        - users trees
    
    - control a run using commands: 
        - run / stop
        - speed up / slow down
        - do / undo / redo
        - predefine run duration, sampling frequency and nature
        - predefine interruption parameters 
                (according to server performances and/or model results)
        - preselect the search algorithm in the conditions tree 

    - monitor performances of the server
        
    - view and analyse the results of a run
        - history
        - phase diagrams (structures / fluxes)
        - statistics
        - errors
        
    - facilitate usage of the software
        - preferences
        - context info
        - help

---

Definitions (see also: gem graph README and gem graph server README) 

1) XML Schema

- According to the model xml schema,
    a gem-graph model must include at least the following data groups:

    + identity (name, owner, creation date, version, references,...)
    + parameters (about simulation and space: dimension, size x y z,...)
    + objects: each object is a connex graph drawn as a set of arrows
    + savestates: each state (objects, situations, tags) is drawn as a set of arrows
    + transitions: each transition is defined as two sets of arrows
    + conditions: that are specified as nodes in a tree (see below)
    

2) Automaton rewriting a geometric graph

- A gem-graph is a geometric graph = a graph whose nodes have coordinates in a space.
- A gem-graph model describes an automaton that can rewrite a gem-graph.
- An automaton that can rewrite a gem-graph has to define states and transitions.

- States belong to a unique global space in which all the transitions occur.
- Each transition rewrites a part of the global space. This part is called the local space.

- States are drawn in spaces (global or local) using arrows.
- States can be combinations of objects, situations and/or tags.
- Objects and tags are connex graphs (i.e. graphs whose nodes are all connected).
- A situation describes the relative positions of several objects in the global space.
- A tag is a part of an object or situation which encodes a human readable text (annotation, ref, value,...).

- Several connex graphs can be used to describe the same object.
- An instance of the class object groups all these graphs plus some comments or values.

- Transitions are defined by an initial and a final local states.
- The initial state of a transition can be evaluated by a set of conditions.
- Each condition is defined as the association of:

	+ a location (space unit (x, y, z) and site number)
	+ an arrow number (or weight) as several arrows can be stacked at the same location


- All the conditions can be ordered in a single tree: the 'tree of conditions' (see below).
- In the XML model file, in order to write and read this tree, 
        each condition has a node identifier (node_id) and a parent.


3) Data structures

- Arrows are represented (encoded) by numbers in sites.
- In each space units is a finite number of sites.
- The site 0 always points towards its own space unit.
- Each other site points towards a neighbouring (not necessarily adjacent) state unit.
- Each site of each space unit can 'contain' 0 or n arrows.
- The set of states of all the sites of all the space units defines a space state.

- A condition is satisfied if both following quantities are equal:
    + the number of arrows (or weights) specified by the condition
    + the number of arrows present in the space at the same location specified by the condition.


- When conditions are evaluated by the automaton, these two values are compared.
- These evaluations are done by threads (workers) managed by the scheduler of the server.

- A transition rule associates several conditions to several assignments.
- An assignment instruction assigns a number (n) of arrows to a site of a space unit of the global space.

- The conditions of a transition rule must all be satisfied for this rule to be applied.

- Several transition rules can have conditions that read the same site.
- As all the transition rules share at least one common conditions on the local space origin,
        all the conditions of all the transition rules can be ordered as a single conditions tree.
- In this conditions tree, each condition is a node and each set of assignments is a leave.
- The root of this tree is the condition on the local space origin.
- The other conditions are met by following a predefined path through all the locations of the local space.
- This path is determined by the user according to the design and performances of the model.
- In the XML model file, in order to write and read the conditions tree, each condition has a node identifier and a parent.


4) Algorithms

- The search of a transition rule in the conditions tree is done by the threads of the scheduler (see gem-graph-server README)
- The result of these searches can be:
    + success (the founded rule is applied)
    + failure (there is no rule for this situation; the local situation is returned to the client)
    + error

- The rules and the conditions tree are designed by the client and executed by the server scheduler threads.
  It is the responsability of the user to manage:
    + conditions deficit, conflicts and redundancy
    + rules deficit, conflicts and redundancy
    + optimisation of the conditions tree by design of an adequate path through all the locations of the local space
    + approximations of objects, situations and phenomena


5) Meta-edition (future)

- As mentionned above, several connex graphs can be used to describe the same object.
- An instance of the class object, called a meta-object, then groups all these graphs plus some comments or values.

- In future versions, the client should provide tools in order to help model designers to edit 
    + objects from meta-objects. (vectorisation)
    + transitions from meta-transitions. (AI ?)


NB Adequate data structures should describe these meta-transitions and meta-objets.


---