An empty model has to be created as first step.<\/p>\n\n\n\n
M3AM *m3am_NewModel(const char *label, SpaceDim dimension)<\/strong><\/code><\/pre>\n\n\n\nThe new created model is referenced throughout the reference returned by m3am_NewModel<\/code> function. The string parameter label<\/code> set the name of the model. Parameter dimension<\/code> 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.<\/p>\n\n\n\nThe following code create an empty model over a 2D space:<\/p>\n\n\n\n
#include \"magnet.h\"\n\nM3AM *myModel;\nmyModel=m3am_NewModel(\"My_Markovian_Agent_model\", 2);<\/code><\/pre>\n\n\n\nWhen 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.<\/p>\n\n\n\n
<\/p>\n\n\n\n
Error m3am_NewClass(M3AM *model, char *label, NumStates states);<\/strong><\/code><\/pre>\n\n\n\nThe m3am_NewClass<\/code> function add a new class in the model model<\/code> with the name label<\/code>. The number of states in the class is set to states<\/code>. The error code NOERR<\/code> 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:<\/p>\n\n\n\nNOERR<\/td> no error<\/td><\/tr> EMEM<\/td> memory allocation error<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
\n <\/p>\n\n\n\n
Error m3am_AddInitProb(M3AM *model, const char *class_label, NumStates s, double val);<\/strong><\/code><\/pre>\n\n\n\nm3am_AddInitProb<\/code> is used to set\/change the initial probability vector of a class by setting to val<\/code> the probability of state s<\/code>; the class is identified by name to class_label<\/code>, in a properly defined models referred by model<\/code>. 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 :<\/p>\n\n\n\nNOERR<\/td> no error<\/td><\/tr> ENOCL<\/td> the class name does not exist<\/td><\/tr> EORANGE<\/td> probability vale out of range<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
\n <\/p>\n\n\n\n
Error m3am_AddLocTr(M3AM *model, const char *class_label, NumStates r, NumStates c, Rate val);<\/strong><\/code><\/pre>\n\n\n\nm3am_AddLocTr<\/code> sets to val<\/code> the transition rate from state r<\/code> to state c<\/code> of the Markovian agents in class class_label<\/code> of the model referenced by model<\/code>. Transition rates from a state to itself are forbidden (self loops are set with AddSelfLoop<\/code>).
Returned values are as in the following :<\/p>\n\n\n\nNOERR<\/td> no error<\/td><\/tr> EXIT_FAILURE<\/td> r is equal to c<\/td><\/tr> ENOCL<\/td> class name does not exist<\/td><\/tr> EORANGE<\/td> the rate value is negative<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
\n <\/p>\n\n\n\n
Error m3am_AddSelfLoop(M3AM *model, const char *class_label, NumStates s, Rate val);<\/strong><\/code><\/pre>\n\n\n\nm3am_AddSelfLoop<\/code> adds the self loop rate associated to the state s<\/code> of Markovian agents belonging to the class class_label<\/code> in the model referenced by model<\/code>. If a self loop rate has been defined before, it will be changed to val<\/code>.
Returned values are as in the following:<\/p>\n\n\n\nNOERR<\/td> no error<\/td><\/tr> ENOCL<\/td> the class name does not exist<\/td><\/tr> EORANGE<\/td> the rate value is negative<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
\n <\/p>\n\n\n\n
Error m3am_NewMSG(M3AM *model, const char *message_label);<\/strong><\/code><\/pre>\n\n\n\nm3am_NewMSG<\/code> adds a new message with name message_label<\/code> to the model referenced by model<\/code>. If the message is already defined in the model, it will return an error code.
Returned values are as in the following:<\/p>\n\n\n\nNOERR<\/td> no error<\/td><\/tr> EMEM<\/td> memory allocation error<\/td><\/tr> ENOOP<\/td> operation not allowed; the message exists<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
\n <\/p>\n\n\n\n
Error m3am_AddMsgGenProb(M3AM *model, const char *class_label, const char *message_label, NumStates r, NumStates c, Probability val);<\/strong><\/code><\/pre>\n\n\n\nm3am_AddMsgGenProb<\/code> sets to val<\/code> the probability that a Markovian agent belonging to the class class_label<\/code> of the model referenced by model<\/code> generates a message message_label<\/code> when transiting from state r<\/code> to state c<\/code>. 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<\/code> value brakes the internal consistency, an error will be returned and the value will not bet set. If either class_label<\/code> class or message_label<\/code> message are not defined an error code is returned.
Returned values are as in the following:<\/p>\n\n\n\nNOERR<\/td> no error<\/td><\/tr> EORANGE<\/td> probability value out of range<\/td><\/tr> ENOPR<\/td> inconsistent probability value<\/td><\/tr> ENOCL<\/td> class name does not exist<\/td><\/tr> ENOMES<\/td> message name does not exist<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
\n <\/p>\n\n\n\n
Error m3am_AddMsgAccProb(M3AM *model, const char *class_label, const char *message_label, NumStates r, NumStates c, double val);<\/strong><\/code><\/pre>\n\n\n\nm3am_AddMsgAccProb<\/code> sets to val<\/code> the probability that a Markovian agent belonging to the class class_label<\/code> of the model referenced by model<\/code> has a transition from state r<\/code> to state c<\/code> due to a perceived message message_label<\/code>. A valid probability value must be used. Sum of all probabilities to have a transition from state r<\/code> due to the same message_label<\/code> cannot exceed 1.0; this latter constrain is kept internally consistent, and if the val<\/code> value brakes the internal consistency, an error will be returned and the value will not bet set. Only values for r <\/code>different from c<\/code> make sense, thus an error code will be returned if an attempt to set it is done. If either class_label<\/code> class or message_label<\/code> message are not defined an error code is returned.
Returned values are as in the following:<\/p>\n\n\n\nNOERR<\/td> no error<\/td><\/tr> EXIT_FAILURE<\/td> r is equal to c<\/td><\/tr> EORANGE<\/td> probability value out of range<\/td><\/tr> ENOPR<\/td> inconsistent probability value<\/td><\/tr> ENOCL<\/td> class name does not exist<\/td><\/tr> ENOMES<\/td> message name does not exist<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
<\/p>\n\n\n\n