7.6 KiB

Raw Permalink Blame History

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)

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)

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.

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.

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

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.