An empty model has to be created as first step.
M3AM *m3am_NewModel(const char *label, SpaceDim dimension)The new created model is referenced throughout the reference returned by m3am_NewModel function. The string parameter label set the name of the model. Parameter dimension sets the space dimension of the space where the agents in the model will be deployed. The function returns a pointer to be used for referencing the model in all the other functions.
The following code create an empty model over a 2D space:
#include "magnet.h"
M3AM *myModel;
myModel=m3am_NewModel("My_Markovian_Agent_model", 2);When a new M3AM model has been instantiated all the other objects have to be created into the model. The following functions are used to this aim.
Error m3am_NewClass(M3AM *model, char *label, NumStates states);The m3am_NewClass function add a new class in the model model with the name label. The number of states in the class is set to states. The error code NOERR is returned if the class is correctly created otherwise it evaluates to one of the codes in the error code table.
Probability of state 0 is set to 1.0 and the probabilities of all the other states are set to 0.0 when the class is created. The probability vector in the class is assumed the initial probability vector of Markovian agents belonging to the class.
Returned values are as in the following:
| NOERR | no error |
| EMEM | memory allocation error |
Error m3am_AddInitProb(M3AM *model, const char *class_label, NumStates s, double val);m3am_AddInitProb is used to set/change the initial probability vector of a class by setting to val the probability of state s; the class is identified by name to class_label, in a properly defined models referred by model. It is user responsibility to guarantee that of all the values in the vector sum to 1.0
Returned values are as in the following :
| NOERR | no error |
| ENOCL | the class name does not exist |
| EORANGE | probability vale out of range |
Error m3am_AddLocTr(M3AM *model, const char *class_label, NumStates r, NumStates c, Rate val);m3am_AddLocTr sets to val the transition rate from state r to state c of the Markovian agents in class class_label of the model referenced by model. Transition rates from a state to itself are forbidden (self loops are set with AddSelfLoop).
Returned values are as in the following :
| NOERR | no error |
| EXIT_FAILURE | r is equal to c |
| ENOCL | class name does not exist |
| EORANGE | the rate value is negative |
Error m3am_AddSelfLoop(M3AM *model, const char *class_label, NumStates s, Rate val);m3am_AddSelfLoop adds the self loop rate associated to the state s of Markovian agents belonging to the class class_label in the model referenced by model. If a self loop rate has been defined before, it will be changed to val.
Returned values are as in the following:
| NOERR | no error |
| ENOCL | the class name does not exist |
| EORANGE | the rate value is negative |
Error m3am_NewMSG(M3AM *model, const char *message_label);m3am_NewMSG adds a new message with name message_label to the model referenced by model. If the message is already defined in the model, it will return an error code.
Returned values are as in the following:
| NOERR | no error |
| EMEM | memory allocation error |
| ENOOP | operation not allowed; the message exists |
Error m3am_AddMsgGenProb(M3AM *model, const char *class_label, const char *message_label, NumStates r, NumStates c, Probability val);m3am_AddMsgGenProb sets to val the probability that a Markovian agent belonging to the class class_label of the model referenced by model generates a message message_label when transiting from state r to state c. A valid probability value must be used. Probability values to generate messages when a Markovian agents outgoes from a state cannot exceed 1.0; this latter constrain is kept internally consistent, and if the val value brakes the internal consistency, an error will be returned and the value will not bet set. If either class_label class or message_label message are not defined an error code is returned.
Returned values are as in the following:
| NOERR | no error |
| EORANGE | probability value out of range |
| ENOPR | inconsistent probability value |
| ENOCL | class name does not exist |
| ENOMES | message name does not exist |
Error m3am_AddMsgAccProb(M3AM *model, const char *class_label, const char *message_label, NumStates r, NumStates c, double val);m3am_AddMsgAccProb sets to val the probability that a Markovian agent belonging to the class class_label of the model referenced by model has a transition from state r to state c due to a perceived message message_label. A valid probability value must be used. Sum of all probabilities to have a transition from state r due to the same message_label cannot exceed 1.0; this latter constrain is kept internally consistent, and if the val value brakes the internal consistency, an error will be returned and the value will not bet set. Only values for r different from c make sense, thus an error code will be returned if an attempt to set it is done. If either class_label class or message_label message are not defined an error code is returned.
Returned values are as in the following:
| NOERR | no error |
| EXIT_FAILURE | r is equal to c |
| EORANGE | probability value out of range |
| ENOPR | inconsistent probability value |
| ENOCL | class name does not exist |
| ENOMES | message name does not exist |