gem-graph/gem-graph-client
gem-graph
/
gem-graph-client
3
0
Fork 0
Code Issues 14 Pull Requests Projects Releases Activity

rtfm/intro (writing the manual) + cleaning doc

This commit is contained in:
Jean Sirmai 2024-11-11 23:36:02 +01:00
parent c9edba046c
commit 2a739928fb
Signed by: jean
GPG Key ID: FB3115C340E057E3
8 changed files with 81 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/rtfm/intro 80 char
View File

@ -64,7 +64,7 @@ this second model a "random walk".
The second model (the random walk) had one state (the arrow) and two rules The second model (the random walk) had one state (the arrow) and two rules
(forward/backward). Now here's a model with two states and two rules: (forward/backward). Now here's a model with two states and two rules:
the pendulum. This time, the arrow can be drawn either tilted forwards or tilted the "pendulum". This time, the arrow can be drawn either tilted forwards or tilted
backwards (these are the two possible states) and the two rules switch the drawn backwards (these are the two possible states) and the two rules switch the drawn
arrow from one state to the other or vice versa. In the file, the states are (here) arrow from one state to the other or vice versa. In the file, the states are (here)
and the rules (here). The pendulum does not change place, but alternates between and the rules (here). The pendulum does not change place, but alternates between
@ -86,8 +86,8 @@ The next example shows how the same rule can be applied to a multitude of states
The rule is the same as that used in the first model: an arrow can only be moved The rule is the same as that used in the first model: an arrow can only be moved
one square forward, but this time you have to check that the square forward is one square forward, but this time you have to check that the square forward is
free. If it isn't, the arrow won't move. Once the rule has been modified in this free. If it isn't, the arrow won't move. Once the rule has been modified in this
way, it can be applied to a multitude of arrows distributed randomly in space way (see how), it can be applied to a multitude of arrows distributed randomly in space
(see details here). (see more details here).
When you set the model in motion, you will see all these small lines moving from When you set the model in motion, you will see all these small lines moving from
left to right. A single rule is responsible for all these movements. left to right. A single rule is responsible for all these movements.
For a small fee, we can apply the two rules of the 'random walk' model to all the For a small fee, we can apply the two rules of the 'random walk' model to all the
@ -121,11 +121,11 @@ limitations are.
The main difference between gem-graph models and agent-based models is that The main difference between gem-graph models and agent-based models is that
gem-graph deals with situations, not agents. In a situation where several agents gem-graph deals with situations, not agents. In a situation where several agents
are interacting and each agent could apply a different rule, gem-graph considers are interacting and each agent could apply a different rule, gem-graph considers
and processes the situation. Not the agents. Whatever the state - the new and processes the situation. Not the agents. Whatever the new situation that
situation - that results from his action, his decision-making process will have results from his action, his decision-making process will have been simple and
been simple and straightforward. It will therefore be easy to modify and control. straightforward. It will therefore be easy to modify and control. And the
And the diversity of possible new situations will be far greater than that diversity of possible new situations will be far greater than that offered by
offered by agent-based models. agent-based models.
------------ ------------

15
docs/rtfm/intro.txt
View File

@ -16,7 +16,7 @@ To improve this model, it is possible to give the arrow the ability to move in t
------------ ------------
The second model (the random walk) had one state (the arrow) and two rules (forward/backward). Now here's a model with two states and two rules: the pendulum. This time, the arrow can be drawn either tilted forwards or tilted backwards (these are the two possible states) and the two rules switch the drawn arrow from one state to the other or vice versa. In the file, the states are (here) and the rules (here). The pendulum does not change place, but alternates between left and right. Like the previous ones, you can slow down the programme so that you can observe the movements. The second model (the random walk) had one state (the arrow) and two rules (forward/backward). Now here's a model with two states and two rules: the "pendulum". This time, the arrow can be drawn either tilted forwards or tilted backwards (these are the two possible states) and the two rules switch the drawn arrow from one state to the other or vice versa. In the file, the states are (here) and the rules (here). The pendulum does not change place, but alternates between left and right. Like the previous ones, you can slow down the programme so that you can observe the movements.
------------ ------------
@ -24,7 +24,7 @@ Once you know how to write a state and a rule, you can write thousands of them:
------------ ------------
The next example shows how the same rule can be applied to a multitude of states. The rule is the same as that used in the first model: an arrow can only be moved one square forward, but this time you have to check that the square forward is free. If it isn't, the arrow won't move. Once the rule has been modified in this way, it can be applied to a multitude of arrows distributed randomly in space (see details here). The next example shows how the same rule can be applied to a multitude of states. The rule is the same as that used in the first model: an arrow can only be moved one square forward, but this time you have to check that the square forward is free. If it isn't, the arrow won't move. Once the rule has been modified in this way (see how), it can be applied to a multitude of arrows distributed randomly in space (see more details here).
When you set the model in motion, you will see all these small lines moving from left to right. A single rule is responsible for all these movements. When you set the model in motion, you will see all these small lines moving from left to right. A single rule is responsible for all these movements.
For a small fee, we can apply the two rules of the 'random walk' model to all the arrows distributed in this space, and they will then all behave in the same way, sometimes moving forwards, sometimes backwards. For a small fee, we can apply the two rules of the 'random walk' model to all the arrows distributed in this space, and they will then all behave in the same way, sometimes moving forwards, sometimes backwards.
@ -39,7 +39,7 @@ The last example in this series, because it shows a multitude of diverse and sim
------------ ------------
The main difference between gem-graph models and agent-based models is that gem-graph deals with situations, not agents. In a situation where several agents are interacting and each agent could apply a different rule, gem-graph considers and processes the situation. Not the agents. Whatever the state - the new situation - that results from his action, his decision-making process will have been simple and straightforward. It will therefore be easy to modify and control. And the diversity of possible new situations will be far greater than that offered by agent-based models. The main difference between gem-graph models and agent-based models is that gem-graph deals with situations, not agents. In a situation where several agents are interacting and each agent could apply a different rule, gem-graph considers and processes the situation. Not the agents. Whatever the new situation that results from his action, his decision-making process will have been simple and straightforward. It will therefore be easy to modify and control. And the diversity of possible new situations will be far greater than that offered by agent-based models.
------------ ------------
@ -49,3 +49,12 @@ The comparison between gem-graphs and cellular automata first comes up against a
How can gem-graph be used to analyse and control the complexity of what it represents and sets in motion? This chapter introduces the gem-graph mechanism. How can gem-graph be used to analyse and control the complexity of what it represents and sets in motion? This chapter introduces the gem-graph mechanism.
------------
Gem-graph can reproduce the behavior of any cellular automata. Whatever the state of the cellular automaton space at a given time (n), this state can be considered as a gem-graph state and a rule can be written to transform it into the next state (n+1).
The difference with the cellular automaton is that this rule is not generated by a "micro-rule" applied cell by cell to the entire state (n). This rule must be written by hand and its writing requires knowledge of state (n+1).
Writing all the rules that describe all the transformations that have occurred when a cellular automaton describes a trajectory (a story) is certainly tedious, but it is always possible. And the number of possible histories that gem-graph rules can describe is limited only by the size of the space and the number of symbols it contains.
If a set of "micro-rules", each applied cell by cell to the entire state (n) of a cellular automaton, can produce all the possible states that the gem-graph can describe, the two representations can be considered to be equivalent in power.

15
include/fsm.h
View File

@ -1,23 +1,24 @@
/** /**
* @file * @file
* This file is part of Gem-graph; Client fsm (finite state machine) header. * This file is part of Gem-graph; it is the client fsm (finite state machine)
* header.
* *
* @see readme.docs and this text below. * @see readme.docs and this text below.
* *
* --- * ---
* *
* The two log structures and the two enums listed below are defined in the fsm * The two log structures and the two enums needed by the logs are defined in
* header. * the fsm header.
* *
* All log functions are in dedicated files. * All log functions are in dedicated files.
* *
* The most important function: fsm_add_log() is in the file: * The most important function: fsm_add_log() is in the file:
* /src/fsm/log/manager.c * /src/fsm/log/manager.c
* *
* This file contains the declaration of the log with the static attribute, * This file contains the declaration of the log with the **static** attribute,
* which forces all the functions that read or write it to be in it. * which forces all the functions that read or write it to be in it.
* Forcing all functions that read or write to the log to be grouped together * Forcing all functions that read or write to the log to be grouped together
* help to prevent uncontrolled operations. * helps to prevent uncontrolled operations.
* *
* All events sent to the log must pass through this function, which allows them * All events sent to the log must pass through this function, which allows them
* to be filtered before being published in the log. * to be filtered before being published in the log.
@ -115,10 +116,10 @@ enum fsm_enum_log_severity {
INFO, /**< (or MESSAGE) a significant event occurs while the system is INFO, /**< (or MESSAGE) a significant event occurs while the system is
operating normally 📜️👌️ */ operating normally 📜️👌️ */
DEBUG, /**< a description of system states in sufficient detail to give DEBUG, /**< a description of system states in sufficient detail to give
developers clues as to the cause of an error 🪳️👀️🧐️ */ developers clues as to the cause of an error 🪳️🧐️ */
TRACE /**< provides a systematic overview of code execution but comes at TRACE /**< provides a systematic overview of code execution but comes at
a cost in terms of performance 🥱️ */ a cost in terms of performance 🥱️ */
};//.😮️🧐️👀️😅️😕️😱️😦️🕳️😵‍💫️ };
/** /**
* A list of structures or states that may be involved in program events. * A list of structures or states that may be involved in program events.

22
src/fsm/control.c
View File

@ -118,10 +118,10 @@ static void fsm_structures_close()
/** /**
* @brief fsm_init() is the first function called by main.c * @brief The first function called by main();
* It initiates the journal and calls fsm_structures_init(). * initiates the journal and calls fsm_structures_init().
* *
* It uses the relay function fsm_relay_init_log() in src/fsm/log/manager.c to * Uses the relay function fsm_relay_init_log() in src/fsm/log/manager.c to
* reach the fsm_init_log(). * reach the fsm_init_log().
* *
* @since 2024-08 * @since 2024-08
@ -152,18 +152,20 @@ void fsm_init (const char *initial_info_from_main)
} }
/** /**
* @brief fsm_close() is the last function called by main.c It closes all that * @brief The last function called by main();
* was opened in reverse order before handing over to main(). * closes all that was opened in reverse order.
* *
* @details It ensures the fsm state is saved: * @details Ensures the fsm state is saved:
* - preferences * - 'preferences'
* - model * - 'model'
* *
* Then it closes the four lists: * Then closes the four lists:
* - 'measures', * - 'measures',
* - 'results', * - 'results',
* - 'displayables results' and * - 'displayables results' and
* - 'preferences'. * - 'preferences'
* .
*
* and closes the journal * and closes the journal
* *
* @since 2024-08 * @since 2024-08

7
src/fsm/log/appendix.c
View File

@ -33,8 +33,7 @@
#include "../../../include/fsm.h" #include "../../../include/fsm.h"
/** /**
* remove an event; * Removes an event; the removal is a pop back
* the removal is a pop back
* *
* @since 2024-09 * @since 2024-09
* *
@ -64,7 +63,7 @@ long fsm_remove_log (fsm_log_struct *jj,
/** /**
* get log length * Gets the log length
* *
* @since 2024-09 * @since 2024-09
* *
@ -85,7 +84,7 @@ int fsm_get_log_length (fsm_log_struct jj)
/** /**
* seek for an event * Seek for an event
* *
* @since 2024-09 * @since 2024-09
* *

13
src/fsm/log/manager.c
View File

@ -106,9 +106,10 @@ void fsm_add_log (int severity,
/** /**
* This function is only a relay: it calls fsm_init_log() and this call couldn't * Only a relay function: calls fsm_init_log(); nothing else.
* be written in another file because the fsm_log_struct **gg_logs** it transmits *
* is **static** in src/fsm/log/manager.c * This call couldn't be written in another file because the fsm_log_struct
* **gg_logs** it transmits is **static** in src/fsm/log/manager.c
* *
* Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it. * Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.
* *
@ -127,8 +128,10 @@ void fsm_relay_init_log()
/** /**
* This function is only a relay: it calls fsm_publish_log() and fsm_clear_log() * Only a relay function: calls fsm_publish_log() and fsm_clear_log();
* and this calls couldn't be written in another file because the fsm_log_struct * nothing else.
*
* These calls couldn't be written in another file because the fsm_log_struct
* **gg_logs** they transmit is **static** in src/fsm/log/manager.c * **gg_logs** they transmit is **static** in src/fsm/log/manager.c
* *
* Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it. * Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.

23
src/fsm/log/oper.c
View File

@ -1,12 +1,11 @@
/** /**
* @file * @file
* *
* This file is part of Gem-graph. * This file is part of Gem-graph;
* the log stores chronologically all the events during a run.
* *
* The log (journal) stores chronologically the events during a session. * This file contains the executive functions needed to initialise the log, add
* * events and publish everything.
* This file contains the executive functions needed to init the log, add an
* event and publish the log.
* *
* The log presentation is: * The log presentation is:
* [date - rank - source file - source function - value] * [date - rank - source file - source function - value]
@ -44,9 +43,9 @@
/** /**
* init the log: a double chained list * Inits the log: a double chained list.
* *
* first and last records are set to NULL * First and last records are set to NULL
* *
* @since 2024-09 * @since 2024-09
* *
@ -60,7 +59,7 @@ void fsm_init_log (fsm_log_struct *jj)
/** /**
* removes all the log content and free each unit * Deletes all the contents of the log and frees each unit.
* *
* @since 2024-09 * @since 2024-09
* *
@ -82,9 +81,9 @@ void fsm_clear_log (fsm_log_struct *jj)
/** /**
* add an event * Adds a log unit (an event) to the list.
* *
* *new_unit = malloc (sizeof(fsm_log_unit_struct)); * *new_unit = malloc (sizeof (fsm_log_unit_struct));
* *
* warn: is never free (as new log units are never removed) * warn: is never free (as new log units are never removed)
* *
@ -122,9 +121,9 @@ void fsm_add_log_event (fsm_log_struct *jj,
#define LOG_MAX_LENGTH 255 /**< arbitrary */ #define LOG_MAX_LENGTH 255 /**< arbitrary */
/** /**
* publish all the logs chronologically (using the g_lib function: g_message) * Publishes all the logs chronologically (using the g_lib function: g_message)
* *
* today, simply printed in the console; TODO: print in a file * Today, simply printed in the console; TODO: print in a file
* *
* @since 2024-09 * @since 2024-09
* *

44
src/main.c
View File

@ -1,29 +1,6 @@
/** /**
* @file * @file
* Gem-graph-client main file. * This file is part of Gem-graph; it contains only the main() function.
*
* This file is part of Gem-graph. It contains only the main() function.
*
* @cond LICENSE
* Copyright © 2021 Libre en Communs <contact@a-lec.org>
* Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
* Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU Affero General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option) any
* later version.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
* details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
* @endcond
*
* ---
* *
* The main() function * The main() function
* - **initialise** * - **initialise**
@ -44,7 +21,24 @@
* *
* About code organization, see src/readme.dox * About code organization, see src/readme.dox
* *
* --- * @cond LICENSE
* Copyright © 2021 Libre en Communs <contact@a-lec.org>
* Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
* Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
*
* This program is free software: you can redistribute it and/or modify it under
* the terms of the GNU Affero General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option) any
* later version.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
* details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
* @endcond
*/ */
#include <gtk-4.0/gtk/gtk.h> #include <gtk-4.0/gtk/gtk.h>