From de9b28520a66f50dfd7b36b0cc55dd9c74ab8beb Mon Sep 17 00:00:00 2001 From: Jean Sirmai Date: Mon, 11 Nov 2024 23:36:02 +0100 Subject: [PATCH] rtfm/intro (writing the manual) + cleaning doc --- docs/rtfm/intro 80 char | 16 +++++++-------- docs/rtfm/intro.txt | 15 +++++++++++--- include/fsm.h | 15 +++++++------- src/fsm/control.c | 22 +++++++++++---------- src/fsm/log/appendix.c | 7 +++---- src/fsm/log/manager.c | 13 +++++++----- src/fsm/log/oper.c | 23 +++++++++++---------- src/main.c | 44 ++++++++++++++++++----------------------- 8 files changed, 81 insertions(+), 74 deletions(-) diff --git a/docs/rtfm/intro 80 char b/docs/rtfm/intro 80 char index 00e0cdb..081f18d 100644 --- a/docs/rtfm/intro 80 char +++ b/docs/rtfm/intro 80 char @@ -64,7 +64,7 @@ this second model a "random walk". 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 +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 @@ -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 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). +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. 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 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. +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. ------------ diff --git a/docs/rtfm/intro.txt b/docs/rtfm/intro.txt index b42b0ea..db0ed77 100644 --- a/docs/rtfm/intro.txt +++ b/docs/rtfm/intro.txt @@ -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. 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. +------------ + +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. diff --git a/include/fsm.h b/include/fsm.h index c8cafc6..15c6782 100644 --- a/include/fsm.h +++ b/include/fsm.h @@ -1,23 +1,24 @@ /** * @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. * * --- * - * The two log structures and the two enums listed below are defined in the fsm - * header. + * The two log structures and the two enums needed by the logs are defined in + * the fsm header. * * All log functions are in dedicated files. * * The most important function: fsm_add_log() is in the file: * /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. * 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 * 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 operating normally 📜️👌️ */ 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 a cost in terms of performance 🥱️ */ -};//.😮️🧐️👀️😅️😕️😱️😦️🕳️😵‍💫️ +}; /** * A list of structures or states that may be involved in program events. diff --git a/src/fsm/control.c b/src/fsm/control.c index 27b9a8a..1f44784 100644 --- a/src/fsm/control.c +++ b/src/fsm/control.c @@ -118,10 +118,10 @@ static void fsm_structures_close() /** - * @brief fsm_init() is the first function called by main.c - * It initiates the journal and calls fsm_structures_init(). + * @brief The first function called by main(); + * 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(). * * @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 - * was opened in reverse order before handing over to main(). + * @brief The last function called by main(); + * closes all that was opened in reverse order. * - * @details It ensures the fsm state is saved: - * - preferences - * - model + * @details Ensures the fsm state is saved: + * - 'preferences' + * - 'model' * - * Then it closes the four lists: + * Then closes the four lists: * - 'measures', * - 'results', * - 'displayables results' and - * - 'preferences'. + * - 'preferences' + * . + * * and closes the journal * * @since 2024-08 diff --git a/src/fsm/log/appendix.c b/src/fsm/log/appendix.c index 4476276..067184e 100644 --- a/src/fsm/log/appendix.c +++ b/src/fsm/log/appendix.c @@ -33,8 +33,7 @@ #include "../../../include/fsm.h" /** - * remove an event; - * the removal is a pop back + * Removes an event; the removal is a pop back * * @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 * @@ -85,7 +84,7 @@ int fsm_get_log_length (fsm_log_struct jj) /** - * seek for an event + * Seek for an event * * @since 2024-09 * diff --git a/src/fsm/log/manager.c b/src/fsm/log/manager.c index 4d38b4e..6920e3b 100644 --- a/src/fsm/log/manager.c +++ b/src/fsm/log/manager.c @@ -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 - * be written in another file because the fsm_log_struct **gg_logs** it transmits - * is **static** in src/fsm/log/manager.c + * Only a relay function: calls fsm_init_log(); nothing else. + * + * 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. * @@ -127,8 +128,10 @@ void fsm_relay_init_log() /** - * This function is only a relay: it calls fsm_publish_log() and fsm_clear_log() - * and this calls couldn't be written in another file because the fsm_log_struct + * Only a relay function: calls fsm_publish_log() and fsm_clear_log(); + * 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 * * Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it. diff --git a/src/fsm/log/oper.c b/src/fsm/log/oper.c index 2de59e9..b94e662 100644 --- a/src/fsm/log/oper.c +++ b/src/fsm/log/oper.c @@ -1,12 +1,11 @@ /** * @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 init the log, add an - * event and publish the log. + * This file contains the executive functions needed to initialise the log, add + * events and publish everything. * * The log presentation is: * [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 * @@ -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 * @@ -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) * @@ -122,9 +121,9 @@ void fsm_add_log_event (fsm_log_struct *jj, #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 * diff --git a/src/main.c b/src/main.c index 51624b4..b1b574c 100644 --- a/src/main.c +++ b/src/main.c @@ -1,29 +1,6 @@ /** * @file - * Gem-graph-client main file. - * - * This file is part of Gem-graph. It contains only the main() function. - * - * @cond LICENSE - * Copyright © 2021 Libre en Communs - * Copyright © 2021-2024 Adrien Bourmault - * Copyright © 2021-2024 Jean Sirmai - * - * 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 . - * @endcond - * - * --- + * This file is part of Gem-graph; it contains only the main() function. * * The main() function * - **initialise** @@ -44,7 +21,24 @@ * * About code organization, see src/readme.dox * - * --- + * @cond LICENSE + * Copyright © 2021 Libre en Communs + * Copyright © 2021-2024 Adrien Bourmault + * Copyright © 2021-2024 Jean Sirmai + * + * 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 . + * @endcond */ #include