Changes for 1.15 (2013-05-27) Backward-incompatible changes. * New implementation of functionality of STL `map' and `multimap' templates introduces a change, according to which when calling function `qsmm_map_erase' to remove a key-value pair from a map, the key should be destroyed after calling that function, not before. It is because function `qsmm_map_erase' might call a key comparison function for the key of a key-value pair being removed and that key must be a valid object. * New implementation of functionality of STL `multimap' template does not provide storing key-value pairs with the same key in order, in which they were added to a multimap. Added support for large actors that choose output signals quickly when the number of those signals is large. * Added field `large_desc_p' to structure `qsmm_actor_desc_s'. This field, if not 0, indicates that a large actor should be created and specifies additional parameters of that actor. Function `qsmm_actor_create' will return QSMM_ERR_INVAL if (large_desc_p!=0 && use_flat_storage!=0) or if large_desc_p!=0 and parameters specified in *large_desc_p are invalid. * Function `qsmm_get_actor_sig_action' can be (and normally should be) called for a large actor without prior calling function `qsmm_actor_calc_action_prob'. There is no means to pass a specific range of signals to which a generated output signal should belong. Values of arguments `sig_beg' and `sig_end' of function `qsmm_get_actor_sig_action' are only checked that they include the whole range of output signals of the large actor. If they do not include that range, then QSMM_ERR_INVAL will be returned. The use of different ranges of allowed output signals can be implemented in your programs with the help of functions `qsmm_actor_profile_add', `qsmm_actor_permut_add', and `qsmm_set_actor_ngram_profile'. * Function `qsmm_actor_calc_action_prob' can now calculate probabilities of output signals of a large actor. However, the function should not be called too often for actors of that type, because it is slow. When you need to generate an output signal by a large actor, you may call function `qsmm_get_actor_sig_action' without prior calling function `qsmm_actor_calc_action_prob'. * Functions `qsmm_get_actor_sig_weight', `qsmm_set_actor_sig_weight', `qsmm_get_actor_spur_time', and `qsmm_set_actor_spur_time' will return QSMM_ERR_NOSYS when are called for a large actor. * Added function `qsmm_get_actor_large_model' that returns the handle of multinode model of a large actor or 0 when the actor is not the large one. * For a large actor, functions `qsmm_actor_spur_delta', `qsmm_get_actor_spur', `qsmm_get_actor_spur_weight', `qsmm_set_actor_spur_weight', `qsmm_get_actor_spur_perception', and `qsmm_set_actor_spur_perception' support calls with argument `spur_type' equal to -1, in which case they retrieve or modify parameters that correspond to automatic spur of a small actor associated with the large actor. * When creating a large actor, function `qsmm_actor_create' will return error code QSMM_ERR_BIGMDL if a multinode model upon which the actor is based is too complicated. * Added function `qsmm_actor_remove_ngram' that removes information from actor's memory about specific action choice n-gram. The function performs operation, which could be performed in previous package releases by function `qsmm_storage_remove_state' for actor's storage, but function `qsmm_actor_remove_ngram' also works with large actors. * Added function `qsmm_actor_enum_ngrams' that enumerates action choice state n-grams with specifed prefix, information on which is stored in actor's memory. The function performs operation, which could be performed in previous package releases by function `qsmm_storage_enum_states' for actor's storage, but function `qsmm_actor_enum_ngrams' also works with large actors. The function takes an argument of new type `qsmm_enum_ngrams_callback_func_t'. For smaller memory footprint when using a large actor, to allow creating flat storage for n-grams of lengths greater than 2 and when input and output signals do not interleave in the event history, for smaller memory footprint of flat storage, there was introduced a possibility to specify precise ranges of signals in action choice state n-grams of actors. * Added field `range_sig_p' to structure `qsmm_actor_desc_s'. That field describes ranges of signals in action choice state n-grams. If range_sig_p==0, then it will be assumed that every signal of action choice state n-gram has an allowed range from 0 to `nsig' (exclusive), where `nsig' is the total number of signals of the actor. Function `qsmm_actor_create' will return QSMM_ERR_INVAL if range_sig_p!=0 and (range_sig_p[i].first>range_sig_p[i].second || range_sig_p[i].second>=nsig) for some valid `i'. * Added function `qsmm_get_actor_range_sig' that returns a read-only array of ranges of signals in action choice state n-grams of an actor. This function never returns 0. * Added field `range_sig_in_p' to structure `qsmm_actpair_desc_s'. This field describes ranges of signals in signal sequences passed to function `qsmm_actpair_in', excluding the first signal of sequence if field `nnode' of that structure has a value greater than 1. If range_sig_in_p==0, then it will be assumed that every signal has an allowed range from 0 to a value of field `nsig_in' (exclusive) of that structure. Function `qsmm_actpair_create' will return QSMM_ERR_INVAL if range_sig_in_p!=0 and (range_sig_in_p[i].first>range_sig_in_p[i].second || range_sig_in_p[i].second>=nsig_in) for some valid `i'. * Added field `range_sig_env_la_p' to structure `qsmm_desc_s'. That field describes ranges of signals in the look-ahead signal segment of multinode model. If range_sig_env_la_p==0, then it will be assumed that every signal of the look-ahead signal segment has an allowed range from 0 to a value of field `nsig_ngram_env_la' (exclusive) of that structure. Function `qsmm_create' will return QSMM_ERR_INVAL if range_sig_env_la_p!=0 and (range_sig_env_la_p[i].first>range_sig_env_la_p[i].second || range_sig_env_la_p[i].second>=nsig_ngram_env_la) for some valid `i'. * Function `qsmm_actor_reg_sig_in' will return QSMM_ERR_NGRAM if the contents of current action choice state n-gram contradicts with a value of field `range_sig_p' of structure `qsmm_actor_desc_s' specified when creating the actor. * Function `qsmm_actpair_in' will return QSMM_ERR_INVAL if the contents of input signal sequence contradicts with a value of field `range_sig_in_p' of structure `qsmm_actpair_desc_s' specified when creating the actor pair. * Function `qsmm_set_la_sig' will raise QSMM_ERR_INVAL if a look-ahead signal does not belong to a range specified using field `range_sig_env_la_p' of structure `qsmm_desc_s' when creating the multinode model. To support using various n-ary trees by a large actor to quickly choose output signals, there has been introduced the concept of a pool of ordered lists of probabilities for output signals and a pool of permutations for output signals. An ordered list of probabilities for output signals corresponds to a Huffman tree, which can be large enough and therefore consume considerable amount of memory. To reduce the amount of memory needed, the same Huffman tree may represent more than one probability profile when those profiles are actually different reorderings of the same ordered list of probabilities of tree leaves. These reorderings are called permutations of output signals. That is, a probability profile is represented by an ordered list of probabilities and a permutation, using which that list can be converted to a list of profile probabilities of output signals of the actor. * The concept of a pool of ordered lists of probabilities for output signals and a pool of permutations for output signals is supported not only for large actors, but also for small ones. * Added field `profile_pool_sz' to structure `qsmm_actor_desc_s'. That field specifies the maximum number of ordered output signal probabilities lists, which can be loaded into an actor. Function `qsmm_actor_create' will return QSMM_ERR_INVAL if the value of this field is negative or if the actor is large and the number of possible action choice state n-grams plus the value of this field plus 1 exceeds INT_MAX. * Added function `qsmm_get_actor_profile_pool_sz' that retrieves a value of field `profile_pool_sz' of structure `qsmm_actor_desc_s' specified when creating the actor. * Added error code QSMM_ERR_MPROF, which indicates that a new ordered probabilities list is to be registered, but there is no room in the pool for that. Added field `mprof' to union `qsmm_except_u'. That field hands over the size of the pool when error QSMM_ERR_MPROF is raised during execution of a multinode model API function. * Added function `qsmm_actor_profile_add', which returns an index of ordered probabilities list and an index of output signals permutation that correspond to a list of probabilities of output signals of an actor. The function can return error QSMM_ERR_MPROF. * Added function `qsmm_actor_permut_add' that adds a permutation of actor's output signals to the pool and returns the index of a newly added permutation, or returns the index of an existing permutation if it is already contained in the pool. * Added functions `qsmm_get_actor_ngram_profile' and `qsmm_set_actor_ngram_profile' for retrieving and setting up a correspondence between an action choice state n-gram and a preloaded probability profile represented by an index of ordered probabilities list and an index of output signals permutation. * A preloaded probability profile specified for an action choice n-gram of a small actor using function `qsmm_set_actor_ngram_profile' will be implicitly loaded by function `qsmm_actor_calc_action_prob' in an internal array, which holds weights of output signals of the actor and which can be accessed by functions `qsmm_get_actor_sig_weight' and `qsmm_set_actor_sig_weight'. Flat storage now supports n-grams of arbitrary length and arbitrary contents. Main memory for the storage is allocated on the basis of the number of possible n-grams that can be held in the storage, which is calculated using a value of field `range_sig_p' of structure `qsmm_actor_desc_s' specified when creating the actor. * Added field `use_flat_storage' to structure `qsmm_actor_desc_s'. That field specifies whether flat storage should be used by the actor. The field can be set to a non-zero value disregarding of the n-gram length and whether input and output signals interleave in the event history. Field `use_flat_storage' (of structure `qsmm_actor_sig_spec_in_out_s'), to which those limitations were pertinent, is now deprecated. * Field `use_flat_storage' of structure `qsmm_actpair_desc_s' can now be set to a non-zero value disregarding of n-gram length. * Added field `use_flat_storage' to structure `qsmm_desc_s'. That field specifies whether flat storage should be used by an actor pair, which corresponds to the multinode model. * Flat storage now supports retrieving and setting redirection functions using calls to `qsmm_get_storage_state_stats_redir', `qsmm_set_storage_state_stats_redir', `qsmm_get_storage_cycle_stats_redir', `qsmm_set_storage_cycle_stats_redir', `qsmm_get_storage_cycle_next_redir', `qsmm_set_storage_cycle_next_redir'. * Flat storage now supports state enumeration using function `qsmm_storage_enum_states', state removal using function `qsmm_storage_remove_state', and retrieving the next type of cycles, which start at specified state, using function `qsmm_get_storage_cycle_next'. * Main memory for flat storage is now allocated upon creating the storage, not upon the first write operation to the storage. * Function `qsmm_actor_create' will now return QSMM_ERR_INVAL if flat storage is used and the number of possible action choice state n-grams exceeds INT_MAX. Additional changes for actor. * Function `qsmm_get_actor_last_discrete_cycle_period' was renamed to `qsmm_get_actor_discrete_cycle_period_last'. The deprecated old function is still available via an alias. * Added function `qsmm_get_actor_discrete_cycle_period_mean' that returns the mean discrete cycle period of an actor. The function could be called, e.g. from a user-supplied function specified using a call to `qsmm_set_actor_relprob_helper' (see below). * Added field `compat' to structure `qsmm_actor_desc_s'. That field specifies a compatibility level of algorithms used by an actor. If the field has value 1, then the mean discrete cycle period will be additionally multiplied by a value returned by function `qsmm_get_actor_naction_per_evt' (and possibly by 2) when calculating a relative probability of output signal choice, and a simpler formula for automatic spur increment will be used. Setting value of field `compat' to 1 is recommended for your new programs. Function `qsmm_actor_create' will return QSMM_ERR_INVAL if the value of this field is not 0 and 1. * Added function `qsmm_get_actor_compat' that returns a value of field `compat' of structure `qsmm_actor_desc_s' specified when creating the actor. * Added functions `qsmm_get_actor_relprob_type' and `qsmm_set_actor_relprob_type' for retrieving and setting the type of a function that returns a relative probability of output signal choice. Possible types: QSMM_RELPROB_BUILTIN1 - utilize the standard function; QSMM_RELPROB_BUILTIN2 - utilize the alternative function; QSMM_RELPROB_USER1 - utilize a user-defined helper function, to which a cycle period is passed, which returns a multiplier for the exponent of relative probability of output signal choice. * Added functions `qsmm_get_actor_relprob_helper' and `qsmm_set_actor_relprob_helper' for retrieving and setting a pointer to a helper function, which is used when calculating the relative probability of output signal choice, and for retrieving and setting a user parameter of that function. The helper function will be used when the type of a function, which returns a relative probability of output signal choice, is set to QSMM_RELPROB_USER1. * Functions `qsmm_get_actor_discrete_cycle_period_mlt' and `qsmm_set_actor_discrete_cycle_period_mlt' are now deprecated. If you need to use a discrete cycle period multiplier or change the formula, which gives a relative probability of output signal choice, in some other way, then set the type of a function, which returns a relative probability of output signal choice, to QSMM_RELPROB_USER1, and specify a necessary helper function using a call to `qsmm_set_actor_relprob_helper'. * Added function `qsmm_get_actor_nsig' that returns the total number of signals of an actor. * Added function `qsmm_get_actor_nsig_out' that returns the number of output signals of an actor. * Function `qsmm_get_actor_discrete_time' is now allowed to return negative values. * Functions `qsmm_actor_reg_sig_in', `qsmm_actor_reg_sig_action', `qsmm_actor_calc_action_prob', `qsmm_get_actor_profile_nsig_ctrl', and `qsmm_get_actor_sig_action' (when is called for a large actor) will now return QSMM_ERR_NGRAM if the actor window contains an invalid action choice state n-gram. Additional changes for actor pair. * Added field `compat' to structure `qsmm_actpair_desc_s'. That field specifies a compatibility level of algorithms used by actors, which comprise the actor pair. Additionally, if the field has value 1, then the actor pair will multiply a discrete cycle period of the opposite actor of the actor pair by 2*qsmm_get_actor_naction_per_evt( actor_opposite). Setting value of field `compat' to 1 is recommended for your new programs. Function `qsmm_actpair_create' will return QSMM_ERR_INVAL if the value of this field is not 0 and 1. * Added field `is_large_env' to structure `qsmm_actpair_desc_s'. The field, if not 0, specifies that a large actor should be created for the environment state identification engine. It is only allowed when field `use_flat_storage' is equal to 0 and field `compat' is equal to 1. Otherwise, function `qsmm_actpair_create' will return QSMM_ERR_INVAL. * The value of field `nspur' of structure `qsmm_actpair_desc_s' passed to function `qsmm_actpair_create' can now be equal to 1, which means that the environment state identification engine shall use only one spur type, which is normally automatic spur, and an engine, which produces optimal actions on the basis of current environment states, shall not use spur at all (this makes sense when the latter engine generates actions deterministically). * Added field `profile_pool_env_sz' to structure `qsmm_actpair_desc_s'. That field specifies the size of a pool of ordered probabilities lists used by the environment state identification engine. Function `qsmm_actpair_create' will return QSMM_ERR_INVAL if the value of the field is negative. * Function `qsmm_set_actpair_work_nsig_out' can now set the working number of output signals equal to 1. * Function `qsmm_set_actpair_work_nstate' will return QSMM_ERR_NOSYS if the environment state identification engine is a large actor. * Function `qsmm_actpair_spur_delta' supports a call with argument `spur_type' equal to -1 when the environment state identification engine is represented by a large actor, in which case the function increments the value of automatic spur of a small actor associated with the large actor. * Function `qsmm_get_actpair_cycle_period_mlt_opt' is now deprecated. The current standpoint is that a discrete cycle period multiplier of an actor, which produces optimal actions on the basis of current environment states, should not be modified outside of the actor pair. Additional changes for multinode model. * Fixed a bug in passing a user parameter to an event handler function of C function node class via argument `qsmm_param_p' on events QSMM_EVT_ENT_INIT, QSMM_EVT_ENT_DONE, QSMM_EVT_ENGINE_INIT, and QSMM_EVT_ENGINE_DONE. * The type of argument `desc_p' of function `qsmm_create' was changed from (struct qsmm_desc_s *) to (const struct qsmm_desc_s *). * Added field `compat' to structure `qsmm_desc_s'. That field specifies a compatibility level of algorithms used by the actor pair. Additionally, if the field has value 1, then the multinode model engine will not reset to 1 a discrete cycle period multiplier of an actor, which produces optimal actions on the basis of current environment states, when that actor is used independently of the actor pair. Setting value of field `compat' to 1 is recommended for your new programs. Function `qsmm_create' will return QSMM_ERR_INVAL if the value of this field is not 0 and 1. * Added field `is_determ_opt' to structure `qsmm_desc_s'. If that field has a non-zero value, then the action emission matrix of every node will be restricted to define only deterministic action choices. In this mode the value of field `nspur' can be equal to 1; additionally, when loading assembler programs into nodes, states are assumed to begin just before user and mixed type instructions, and there is no need to mark the states by `stt' instructions. Setting field `is_determ_opt' to a non-zero value is only allowed when field `dont_use_instr_class_weights' (see below) also has a non-zero value; otherwise, function `qsmm_create' will return QSMM_ERR_INVAL. * Function `qsmm_reg_program' will raise QSMM_ERR_NOSYS when is called for a multinode model created with field `is_determ_opt' of structure `qsmm_desc_s' set to a non-zero value. * Added field `is_large_env' to structure `qsmm_desc_s'. If that field has a non-zero value, then a large actor will be created for the environment state identification engine of actor pair. It is only allowed when field `is_determ_opt' also has a non-zero value, field `use_flat_storage' is equal to 0, and field `compat' is equal to 1. Otherwise, function `qsmm_create' will return QSMM_ERR_INVAL. * Added field `profile_pool_env_sz' to structure `qsmm_desc_s'. That field specifies the size of a pool of ordered probabilities lists used by the environment state identification engine of actor pair. Function `qsmm_create' will return QSMM_ERR_INVAL if the value of the field is negative. * Added field `rng' to structure `qsmm_desc_s'. That field specifies a random number generator to use for the model. If the field has zero value, then default preudorandom number generator will be allocated by function `qsmm_create' and destroyed upon model destruction. * Function `qsmm_spur_delta' supports a call with argument `spur_type' equal to -1 when the environment state identification engine is represented by a large actor, in which case the function increments the value of automatic spur of a small actor associated with the large actor. * Added field `dont_use_instr_class_weights' to structure `qsmm_desc_s'. If this field has a non-zero value, then the multinode model engine will not set weights of output signals of the actor pair equal to instruction classes weights that can be specified for a node. This makes the multinode model to execute faster, especially when a sparse probability profile is specified for the action emission matrix of a node, and the number of instruction classes in the instruction class set of the node is large. * Added function `qsmm_get_use_instr_class_weights' that will return a positive value if field `dont_use_instr_class_weights' of structure `qsmm_desc_s' has zero value when creating a multinode model, and will return 0 otherwise. * Functions `qsmm_set_instr_meta_class_weight', `qsmm_get_instr_class_weight', `qsmm_set_instr_class_weight', `qsmm_get_instr_class_weight_by_name_f', and `qsmm_set_instr_class_weight_by_name_f' will raise QSMM_ERR_NOSYS when are called for a multinode model created with field `dont_use_instr_class_weights' of structure `qsmm_desc_s' set to a non-zero value. * Instruction class sets are now allowed to contain only one instruction class. The description of error QSMM_ERR_NOIC has been changed accordingly. * Function `qsmm_node_create' now supports calls with argument `node' equal to -1, in which case the function tries to find an unused identifier for a new node. Upon successful completion, the function now returns the identifier of created node. * Added error code QSMM_ERR_MNODE, which indicates that an unused identifier for a new node cannot be found by function `qsmm_node_create'. Added field `mnode', which corresponds to this error, to union `qsmm_except_u'; that field hands over information on the maximum allowed number of nodes in the model. * Added field `instr_param_str_p' to structure `qsmm_except_outcome_s' that corresponds to error code QSMM_ERR_OUTCOME. The field contains a textual representation of parameters of an instruction for which an invalid outcome was set. Field `instr_meta_class_name' of this structure now correctly hands over the name of meta-class of that instruction. * Function `qsmm_node_unload' can now be called for a node that belongs to a C function node class, in which case the function unloads statistics from storage of an actor that produces optimal actions on the basis of current environment states. * Added function `qsmm_node_destroy' for dynamic node destruction. * Functions `qsmm_reg_var_prob', `qsmm_node_var_realize', `qsmm_get_node_var_prob', and `qsmm_set_node_var_prob' will raise QSMM_ERR_NOSYS if a large actor is used for the environment state identification engine of the actor pair. * Error code QSMM_ERR_PROFNOLD was replaced with QSMM_ERR_NOPROF. Error code QSMM_ERR_NOPROF means that a node does not have a probability profile loaded using function `qsmm_node_asm', cloned using function `qsmm_node_profile_clone', or set using function `qsmm_set_node_profile_source'. Added field `noprof' to union `qsmm_except_u'. This field should be used instead of field `profnold' which is now marked as deprecated one. * Function `qsmm_node_call_default' will return QSMM_ERR_NOPROF if a non-zero value is specified in field `is_determ_opt' of structure `qsmm_desc_s' when creating the multinode model, the node belongs to a node class represented by an instruction class set, but does not have a probability profile loaded. * Function `qsmm_get_eh_instr_class_set_name' now correctly returns the name of an instruction class set when is called from the event handler function of the instruction class set. * Events QSMM_EVT_ENGINE_DONE are sent to entities in order, reverse to the order in which events QSMM_EVT_ENGINE_INIT were sent. Events QSMM_EVT_ENGINE_INIT are sent to entities in alphabetical order of entity names. Events QSMM_EVT_ENGINE_DONE are sent to entities in reverse alphabetical order of entity names. * Added field `prob_prec' to structures `qsmm_dump_mat_goto_desc_s' and `qsmm_dump_mat_action_desc_s' that specifies the number of digits after a decimal point to print for probabilities. A positive value corresponds to fixed-point notation. A negative value corresponds to exponential notation, and the number of digits is equal to the absolute value of the field. Zero value specifies the default mode. * Function `qsmm_mat_goto_dump' now dumps names of instruction classes that correspond to actions. If node states have names assigned to them by arguments of `stt' instructions, then now those state names will be dumped after state indices. * Function `qsmm_mat_action_dump', when possible, dumps names of instruction classes that correspond to actions and dumps names assigned to node states by arguments of `stt' instructions. * Functions `qsmm_mat_goto_dump' and `qsmm_mat_action_dump' now dump information in aligned fields. Fields of the same type have equal lengths. * Functions `qsmm_get_ptr' and `qsmm_set_ptr' now support arbitrary pointer indices, because pointer values are now stored in a map, not in a contiguous memory block. * Added functions `qsmm_set_node_ptr' and `qsmm_get_node_ptr', using which abritrary pointers can be associated with specific model nodes and then retrieved. Changes for assembler programs processing. * Added support for `#' operator to the assembler preprocessor. That operator converts a symbol value to a string literal, as in C preprocessor. For example, sequence of tokens "prefix_" #sym "_suffix" will be converted to string literal "prefix_INFIX_suffix" if `sym' is defined to INFIX. * Added support for an optional argument of `stt' instruction that specifies a state name. State names of a node must be unique. Added function `qsmm_get_node_state_name' that retrieves the name of a node state specified by its index. Added function `qsmm_get_node_state_by_name' that retrieves the index of a node state specified by its name. When the node uses a probability profile provided by another node, functions `qsmm_get_node_state_name' and `qsmm_get_node_state_by_name' will return information on a state of a node that acts as the source of probability profile. * Added flag QSMM_NODE_CLONE_STATE_NAMES that can be passed to function `qsmm_node_profile_clone' to clone node state names along with a node probability profile. * When used with an environment state identification engine represented by a large actor, function `qsmm_node_asm' will raise error QSMM_ERR_MPROF if there is no room in the pool to store a probability profile for an action choice state. * Functions `qsmm_node_asm' and `qsmm_get_prg_nstate' now take argument "unsigned int flags" (was reserved argument "int rez1") that specifies modes of their operation. * Added flag QSMM_ASM_DETERM_OPT that can be passed to functions `qsmm_node_asm' and `qsmm_get_prg_nstate' via argument `flags'. The flag specifies that the action emission matrix defines only deterministic action choices. In this mode states begin just before user and mixed type instructions, and there is no need to mark unnamed states by `stt' instructions. * When it is specified that the action emission matrix defines only deterministic action choices, unreachable user and mixed type instructions will be detected when assembling a node. Information on unreachable instructions will be recorded in the message list. * Added flag QSMM_ASM_TEMPLATE that can be passed to function `qsmm_node_asm' via argument `flags'. If this flag is specified, then a program to be assembled will be stored in the node as a template program. The template program will be used when disassembling the node by function `qsmm_node_disasm': a disassembled program will be a template program, in which profile probabilities in `jprob' and `case' instructions are replaced with calculated probabilities. * When calling function `qsmm_node_disasm' to disassemble a node, which was assembled with the QSMM_ASM_TEMPLATE flag, only values of fields `do_calc_prob', `prob_goto_min', `prob_action_min', and `prob_type' of structure `qsmm_disasm_desc_s' will be taken into account, values of other fields will be ignored. Fields `prob_goto_min' and `prob_action_min' specify minimum probabilities in `jprob' and `case' instructions, which must be retained in a disassembled program: instructions in a template program, to which lesser probabilities of type `prob_type' correspond, will not appear in the disassembled program. * When dumping an assembler program generated by function `qsmm_node_disasm' for a node assembled with the QSMM_ASM_TEMPLATE flag, `jprob' instructions, which are used in ambiguous contexts, will have "?" printed for their probabilities. * If a node uses a probability profile provided by another node and the latter node was assembled with the QSMM_ASM_TEMPLATE flag, then when disassembling the former node, an assembler program template will be taken from the latter node. * Added flag QSMM_NODE_CLONE_TEMPLATE that can be passed to function `qsmm_node_profile_clone' to clone a template program along with a node probability profile. * Introduced the concept of output probability variables, using which learnt probabilities in `jprob' and `case' instructions can be retrieved for a node. Every output probability variable should appear only once in `jprob' or `case' instructions and should be used in unambiguous context. * Added flag QSMM_ASM_VAR_OUT, which can be passed to functions `qsmm_node_asm' and `qsmm_get_prg_nstate' and which turns on collecting information on output probability variables in a program being assembled. Output probability variables are also supported for a multinode model which environment state identification engine is represented by a large actor, and they need not be registered by function `qsmm_reg_var_prob'. * If flag QSMM_NODE_CLONE_VARS is passed to function `qsmm_node_profile_clone', then the function will also clone information on output probability variables of a node if they exist. * Added function `qsmm_get_node_var_prob_out' that fetches the value of an output probability variable with specified name of a node. The type of a probability to fetch is specified using enumeration `qsmm_prob_e'. If a node uses a probability profile provided by another node and the latter node has output probability variables declared, then values of those probability variables can be retrieved by this function for a former node. * Added function `qsmm_enum_var_prob_out', which enumerates output probability variables of a node that appear in `jprob' and `case' instructions. If a node uses a probability profile provided by another node and the latter node has output probability variables declared, then those probability variables can be enumerated by this function for a former node. * Added flag QSMM_ASM_VAR_AUX that can be passed to functions `qsmm_node_asm' and `qsmm_get_prg_nstate' via argument `flags'. The flag removes a restriction that every probability variable used in an assembler program must either be registered in its instruction class set by function `qsmm_reg_var_prob' or be an output probability variable. When this flag is specified, auxiliary probability variables may be defined in an assembler program, which will be replaced with their actual values at the time of loading the assembler program into a node. Auxiliary probability variables cannot be accessed after loading the assembler program into the node. * Introduced the concept of a probabilities list that can be declared in an assembler program. When the environment state identification engine is a small actor, a probabilities list is only a syntactical construction that can reduce the number of lines in an assembler program. But when the engine is a large actor, referencing the same probabilities list in the assembler program is a direct indication that a Huffman tree, which corresponds to that list, should be reused. This greatly speeds up loading an assembler program into a large actor, because otherwise the following time-consuming operation is performed: a new Huffman tree is created and analyzed whether it represents a probabilities list already contained in the pool. * Introduced the `probeq' directive, which declares a probabilities list of specified length `nn' that contains equal probabilities. The second optional argument of the directive specifies this equal probability and can be a probability variable. If the second argument is not specified, then all elements of the list will be set equal to 1.0/(nn+1). The directive must be coded in a `.data' section of assembler program. * Introduced the `probls' directive, which declares a custom list of probabilities. Each probability can be a number or a variable. The directive must be coded in a `.data' section of assembler program. * Introduced the `casels' instruction (of type QSMM_INSTR_CASELS), which defines probabilistic jump locations that correspond to elements of probabilities list. The first instruction argument is the name of a probabilities list, and subsequent arguments are jump labels that correspond to elements of that list. * Function `qsmm_node_var_realize' will now raise error QSMM_ERR_PSUMGT1 if the sum of elements of a probabilities list used by a `casels' instruction exceeds 1. The description of the error has been made more general. * Introduced the concept of output probabilities arrays, using which probabilities that correspond to jump labels of `casels' instructions and to `case' instructions within `choice' instruction blocks can be retrieved for a node. Output probabilities arrays are referenced using location labels assigned to `casels' instructions and to `choice' instruction blocks. * Added function `qsmm_get_node_array_prob_out'. This function fetches a segment of elements of output probabilities array that correspond to jump labels of a `casels' instruction or to `case' instructions in a `choice' instruction block. The `casels' instruction or the `choice' instruction block are specified by their location labels. The type of probabilities to fetch is specified using enumeration `qsmm_prob_e'. If a node uses a probability profile provided by another node and the latter node has output probabilities arrays declared, then the contents of those probabilities arrays can be retrieved by this function for a former node. * Added function `qsmm_node_var_out_forget' that destroys the cache of output probabilities, which is used to speed up fetching values of output probability variables and elements of output probabilities arrays of a node. That function is called implicitly when unloading a probability profile from the node, when executing function `qsmm_node_call_default' for the node, after disassembling the node if it is assembled with the QSMM_ASM_TEMPLATE flag, and when destroying the model instance. * Added function `qsmm_get_instr_nlabel' that returns the number of location labels of an assembler instruction (which are printed before the instruction). * Added function `qsmm_get_instr_label' that returns a location label with specified index of an assembler instruction (which is printed before the instruction). * Added function `qsmm_get_instr_ls_name' that returns the name of a probabilities list associated with an assembler instruction. * Added function `qsmm_get_prg_ls_nprob' that returns the number of elements in a probabilities list with specified name of an assembler program. * Added field `do_print_state_name' to structure `qsmm_dump_instr_desc_s'. If the field has a non-zero value, then state names, where they are present in `stt' instructions, will be printed with those instructions. The default is to print. * Added field `is_line_after_multiline_comment_right' to structure `qsmm_dump_instr_desc_s'. A field with that name in structure `qsmm_dump_prg_desc_s' was marked as deprecated one. A mode controlled by that field became a property of instruction, not a program, because there could be multiline `casels' instructions, where each line has a separate multiline comment to the right. * Negative values of field `prob_prec' of structure `qsmm_dump_instr_desc_s' are now supported. They specify printing probabilities in `jprob' and `case' instructions in exponential notation. The number of digits after a decimal point is equal to the absolute value of the field. In fact, in all package releases, probabilities for `jprob' and `case' instructions in an assembler program could be specified in exponential notation. * Added field `margin_right_casels' to structure `qsmm_dump_instr_desc_s'. That field specifies a right margin for lists in arguments of `casels' instructions. * Added field `nline_casels' to structure `qsmm_dump_instr_desc_s'. The number of lines of a `casels' instruction printed by function `qsmm_instr_str' is written there. * Added field `are_lines_around_multiline_casels' to structure `qsmm_dump_prg_desc_s'. The field specifies whether to insert an empty line before and after a multiline `casels' instruction. * Added field `margin_right_ls' to structure `qsmm_dump_prg_desc_s'. The field specifies a right margin for elements of probabilities lists in list declarations using `probls' directives. * Added field `do_print_comment_tail' to structure `qsmm_dump_prg_desc_s'. The field specifies whether to print a comment at the end of an assembler program if the program has that comment. In the previous package releases that comment would always printed if it were present. * Functions `qsmm_parse_asm_source_stream' and `qsmm_preprocess_asm_source_stream' now correctly support reading an assembler program from `stdin' when the text of the assembler program is typed on the console. * The assembler preprocessor now supports up to 65535 nested macro expansions. Changes for the implementation of functionality of STL `map' template. * The implementation was completely rewritten in C. The dependency of the package on a C++ compiler and a C++ linker has been removed. * Added map and multimap constructors `qsmm_map_create_sz' and `qsmm_map_multi_create_sz' that take key size and value size in bytes as additional arguments. If value size is zero, then the map or the multimap will represent a set or a multiset. If key size and/or value size are negative, then it will be assumed that keys and/or values are untyped pointers. If key size and/or value size are positive, then it will be assumed that keys and/or values are memory blocks of specified sizes in bytes. * For conserving memory, it is recommended to specify positive key and/or value sizes, in which case room for keys and/or values is automatically reserved at the end of memory blocks that correspond to key-value pairs. This typically decreases the required number of memory block allocations/deallocations, thereby reducing memory blocks management overhead: the footprint of memory management structures and time spent for memory management operations. * When key size and/or value size are positive, function `qsmm_map_insert' copies memory blocks, pointed by arguments `keyp' and/or `valp', to an area at the end of a newly allocated key-value pair object. If value size is positive and valp==NULL, then the value in the key-value pair will be initialized with zero bytes. * When key size and/or value size are positive, functions `qsmm_map_iter_key' and/or `qsmm_map_iter_val' return pointers to key and/or value memory blocks located in an area at the end of a key-value pair object addressed by the iterator. * When value size is positive, function `qsmm_map_iter_set_val' copies a memory block, pointed by `valp' argument (if valp!=NULL), to the area at the end of a key-value pair object addressed by the iterator. * Added functions `qsmm_map_key_sz' and `qsmm_map_val_sz' that return the size of map keys and map values. When the size is negative, keys or values are untyped pointers (the only supported mode in previous package releases). When the size is positive, it is the size in bytes of memory blocks for map keys or map values located at the end of key-value pair objects. When value size is zero, the map or the multimap represents a set or a multiset. * Added functions `qsmm_map_key_compar_func' and `qsmm_map_key_compar_param' that return a pointer to a key comparison function and to its parameters specified when creating the map or the multimap. * Added functions `qsmm_map_iter_end', `qsmm_map_iter_rbegin', `qsmm_map_iter_rend', and `qsmm_map_iter_prev' that mimic the functionality of methods `end', `rbegin', and `rend' of `map' and `multimap' templates, and of `operator--' of iterators. * The return type of function `qsmm_map_size' was changed to `size_t'. Changes for sample program `tohuff-test'. * Program `tohuff-test' now internally generates assembler programs that provide deterministic choice of assembler instructions by an engine, which produces optimal actions on the basis of current assembler program states. Option `--kt-opt', which specifies the temperature of that engine, was removed. * The type of relative probability function of the environment state identification engine was set to QSMM_RELPROB_BUILTIN2. * Now the model uses 3 spur types. Spur of type 1 is incremented by logarithms of probabilities of pairs encountered during model execution. Spur of type 0 of the environment state identification engine (which is automatic spur) and spur of type 1 both have weights 0.5 and countervail spur of type 2, which has weight 1, an inverse way of perception, and is equal to the sum of logarithms of probabilities (which were randomly generated at program start) of output signals emitted during model execution. * The program can now internally build n-ary, not only binary trees. Tree arity can be specified using option `-A, --tree-arity=INT'. * The program now uses a compatibility level of algorithms equal to 1. * The program now works differently with a pseudorandom number generator. The generator is created and seeded once and then set for a multinode model (using new field 'rng' of structure `qsmm_desc_s') at each test pass. * Efficiency `efa' was renamed to `ef1'. Additional efficiency `ef2' is calculated and printed in the test log. Efficiency `ef2' depends on the sum of Euclidean distances between vectors of random probabilities, generated at program start, and vectors of actual probabilities of output signals emitted during model execution. Efficiency `ef2' will be 100% when the sum of distances between those vectors is zero, and will be 0% when the sum of distances is equal to the number of input signals. The sum of distances is printed in column `distance' of test log. * Changes made for program `tohuff-test' now allow to achieve moderate efficiency `ef1' without tuning the temperature of the environment state identification engine using option `--kt-env'. The efficiency could be achieved when the number of steps in a test pass is sufficient. * Because of the changes made, the program now prints different results compared to its version included in the previous package release. Additional changes for sample program `test'. * Added option `-c, --compat=INT'. That option allows to specify a compatibility level of algorithms used by the program in a mode when a single actor is used, i.e. no environment state tracking is performed. The level can be 0 or 1. Default value is 0. * Added option `-L, --large[=INT]'. If this option is given to the program and a single actor is used, i.e. no environment state tracking is performed, then that actor will be created as the large one. Tree arity can be specified as an argument of the option. By default, a binary tree is created. * Added option `-a, --auto-spur'. This option turns on the use of automatic spur by a single actor, i.e. when no environment state tracking is performed. * Added option `-P, --relprob-type=0|1|2'. This option allows to specify the type of a function that returns a relative probability of output signal choice by a single actor, i.e. when no environment state tracking is performed. Value 0 corresponds to function e^(C/T), default value 1 corresponds to a function used in previous package releases, and value 2 corresponds to an alternative function introduced in this package release. * Added options `--kt=FLOAT', `--kt-env=FLOAT', and `--kt-opt=FLOAT', which allow to specify the temperature of the single actor or actors that comprise the actor pair. Default temperature is 1. Changes for sample program `asm-disasm'. * Added option `--use-stt'. That option turns on generation of `stt' instructions in a disassembled program. * Added option `-D, --determ-mat-action'. That option controls which value is assigned to field `is_determ_opt' of structure `qsmm_desc_s' and specifies whether the action emission matrix must define only deterministic action choices. * Added option `-L, --large=INT'. That option can be used in conjuction with option `-D' to indicate that the environment state identification engine must be represented by a large actor. An argument of option `-L' specifies the size of the pool of ordered probabilities lists, which should be large enough to hold all those lists explicitly and/or implicitly defined in an assembler program. * Added option `--template'. That option turns on generating a disassembled program using a template which is a program to assemble. * Added option `--prob-goto-min=FLOAT'. When option `--template' is not given, this option specifies the minimum probability of state transition; transitions with lesser probabilities will be discarded when disassembling the node. When option `--template' is given, this option specifies the minimum probability in `jprob' and `case' instructions that correspond to the state transition matrix; instructions with lesser probabilities will be removed when disassembling the node. * Added option `--prob-action-min=FLOAT'. When option `--template' is not given, this option specifies the minimum probability of invocation of user or mixed type instruction; instructions with lesser probabilities will be discarded when disassembling the node. When option `--template' is given, this option specifies the minimum probability in `jprob' and `case' instructions that correspond to the action emission matrix; these instructions with lesser probabilities will be removed when disassembling the node. * Added option `--prob-prec-mat=INT' that specifies the number of digits after a decimal point to print for probabilities in the state transition matrix and in the action emission matrix. If an argument of the option is positive, then fixed-point notation will be used. If the argument is negative, then exponential notation will be used, and the number of digits will be equal to the absolute value of the argument. Zero argument specifies the default mode. * Added option `--dump-var-out[=FILE]' that makes the program to dump values of output probability variables. * Added option `--dump-var-choice', which makes the program to dump output probabilities arrays that correspond to `choice' instruction blocks with location labels assigned. When option `--template' is specified, all `casels' instructions encountered in an assembler program (in fact, except for `casels' instructions with only one jump label in their arguments) will be converted to `choice' instruction blocks, and output probabilities, which correspond to `case' instructions in these blocks, can be dumped using this option. * Added option `--no-nop' that disables registering instruction class `nop'. * Added option `--dont-reg-vars' that suppresses registering controlled probability variables using macro QSMM_REG_VAR_PROB. * Added option `-S, --storage' that specifies a type of storage used by the program. The default storage type is `map'. * The program now does not prepend a dump of action emission matrix with indices and names of instruction classes, because the new format of the dump provides output of instruction class names after action indices. Changes for sample program `parse-asm'. * Added option `--prob-prec=INT', using which the number of digits after a decimal point to print for probabilities can be specified. A non-negative argument of the option specifies fixed-point notation. A negative argument specifies exponential notation, and the number of digits is equal to the absolute value of the argument. The option is ignored when option `-E' is specified. * Added option `--no-preprocess' that turns off calling the assembler preprocessor before parsing an assembler program. The option is ignored when option `-E' is specified. * Added option '--strip-comments' that suppresses printing comments in an assembler program. The option is ignored when option `-E' is specified. * Added option `--no-space-after-comma'. If that option is specified, then spaces after commas not within comments and string literals will not be printed in the reformatted text of assembler program. The option is ignored when option `-E' is specified. Changes for sample program `asmenv'. * The program can now perform multiple test passes. The number of test passes is specified by option `-t, --test=INT' (the default value is 1). For each test pass there are printed values of spur accumulated by the system when it behaves normally and when it behaves (almost) completely randomly. At the end of the table with test results there are printed the sums and the standard deviation of those values. * Added option `-o FILE' that specifies a file for dumping the program output. The output includes test parameters and a table with test results. * The number of steps in each test pass (a step is interchange of a signal between the system and the environment in both directions) is now specified by option `-n, --nstep-pass=INT', which replaces option `-n, --nstep'. The default number of steps is 10000. * The program supports the use of a profile assembler program of the system. The name of a file with the profile assembler program can be specified using option `-I, --in-prg-sys=FILE'. * The program supports the special situation when a profile assembler program specifies an action emission matrix that defines deterministic action choices. When option `-D, --determ-mat-action' is given to the program, no warnings about missing `stt' instructions will be generated. * When option `-D, --determ-mat-action' is given to the program, option `-P, --relprob-type=0|1|2' can be specified, which sets the type of a function that returns a relative probability of output signal choice. Default type 1 corresponds to a function described in the accompanying paper. * A letter for option `--prg-env=FILE' was changed from `-P' to `-p', because letter `-P' is now used for option `--relprob-type=0|1|2', as in other sample programs. * When option `-D, --determ-mat-action' is given to the program, option `-L, --large=INT' can be specified, which makes the system to use a large actor for the environment state identification engine. An argument of option `-L' specifies the size of the pool of ordered probabilities lists, which should be large enough to hold all those lists explicitly and/or implicitly defined in a profile assembler program. * Added option `--template'. That option turns on generating a disassembled program of the system and dumping it to a file, specified by option `-O, --out-prg-sys=FILE', using a template, which is a profile assembler program read from a file specified by option `-I, --in-prg-sys=FILE'. * Added option `--determ-prg-sys' that turns on generating a completely deterministic assembler program of the system. The option has an effect when option `-O, --out-prg-sys=FILE' is specified and option `--template' is not given. * Added option `--dump-var-out=FILE', which makes the program to dump values of output probability variables and arrays of the node. Probabilities, which correspond to jump labels of `casels' instructions, will be dumped only when option `--template' is not specified. Changes for other sample programs. * Program `optact' now uses a compatibility level of actor algorithms equal to 1. This does not change results printed by the program, but is the correct approach that could help when the program is modified for research purposes. * Program `apsamp' now uses a compatibility level of actor pair algorithms equal to 1. Because of this change, the program now prints different results compared to its version included in the previous package release. * Program `labyr' now uses a compatibility level of multinode model algorithms equal to 1. In practice, this does not change results printed by the program, but is the correct approach that could help when the program is modified for research purposes. * Programs `maze' and `maze-mt' now use flat storage for storing statistics, which increases the speed of operation of those programs. * Programs `maze' and `maze-mt' now use a compatibility level of algorithms of the multinode model equal to 1. To compensate shortening the length of discrete cycle period used when calculating a relative probability of output signal choice, the default system temperature was decreased from 0.05 to 0.025. Because of these changes, the programs now print different results compared to their versions included in the previous package release. * Program `maze-mt' now does not output the text of disassembled program, because the disassembled program cannot be used directly to control movement of the agent in the labyrinth. Sets of allowed movement directions at labyrinth nodes are determined by the agent on the basis of input from the environment (labyrinth) every time the agent has to choose a movement direction and are not reflected in the disassembled program. * Program `fw-simple' now uses a compatibility level of multinode model algorithms equal to 1. Because of this change, the program now produces different results compared to its version included in the previous package release. * Program `fqtab' now does not use a multimap to sort words in descending order by frequency, because in the current implementation a multimap does not store key-value pairs in order, in which they were added to the multimap, and the program would print unstable results. * Program `asmat' now internally generates much shorter assembler program. At the end of execution, learnt probabilities in the state transition matrix and in the action emission matrix of the node are fetched from the node using function `qsmm_get_node_array_prob_out' and dumped to file "var_out". * Program `asmat' now uses a compatibility level of algorithms of the multinode model equal to 1. Because of this change, the program now prints different results compared to its version included in the previous package release. * Program `tohuff' was removed from the set of sample programs, because its function is performed by a more general program `tohuff-test'. * Added sample program `optpath' that demonstrates how to code state transition networks using assembler programs and perform the search of optimal path in those networks. * Added sample program `optact-p', which performs a function similar to program `tohuff-test', but creates an actor (which can be large one), not a multinode model. The program can be used to compare operating efficiency of small and large actors for various values of their parameters. * Added sample program `predict-test', which learns a state model that corresponds to a symbol sequence. The program uses the alternative form of relative probability function, which supports learning a state model without using increments in spur that have to be explicitly provided by an opposite interaction party. The symbol sequence has to be specified in the form of a deterministic probabilistic finite automaton. Several types of probability profiles for the state transition matrix can be used. An actor, which learns a state model, can be large one. Other changes. * Added option `--enable-coverage' to the `configure' script. That option configures the package for using `gcov', a coverage testing tool. * Significantly decreased the number of allocated memory blocks when adding information about a state or a cycle type to map storage. This was made possible by using new function `qsmm_map_create_sz' for creating maps used by the storage. Now state and cycle type information is stored directly in memory blocks of key-value pair objects. This reduces the memory footprint of map storage. * Storage API functions `qsmm_storage_enum_states', `qsmm_storage_remove_state', `qsmm_get_storage_state_stats', `qsmm_set_storage_state_stats', `qsmm_get_storage_cycle_stats', `qsmm_set_storage_cycle_stats', and `qsmm_get_storage_cycle_next' may now return QSMM_ERR_NGRAM if an n-gram passed to them has invalid contents. * Added function `qsmm_rng_create_custom' that creates a random number generator based on a user-supplied function. * Added functions `qsmm_get_rng_default' and `qsmm_set_rng_default' that retrieve and set a user-supplied function, on the basis of which random number generators will be created by function `qsmm_rng_create'. * Added function `qsmm_vec_clone' that creates a copy of a vector. * The number of elements actually stored in an ordinary vector may be less than the number of vector dimensions if the vector is a copy of another vector created by function `qsmm_vec_clone'. In this case only a range of elements that includes elements, which values were set, may be copied from a source vector. Therefore, for an ordinary vector, function `qsmm_get_vec_npos' may return a number less than the number of vector dimensions, and to access elements of the vector, functions `qsmm_get_vec_pos_by_idx' and `qsmm_get_vec_elm_by_pos' should be used, as for a sparse vector. * Added function `qsmm_vec_destroy' that can be used to destroy a copy of vector created by function `qsmm_vec_clone'. * Model execution trace log and side trace log now have a compact and readable format. * Side API functions were renamed to conform to the established naming scheme: `qsmm_side_get_name' to `qsmm_get_side_name', `qsmm_side_get_trace_flags' to `qsmm_get_side_trace_flags', `qsmm_side_get_trace_stream' to `qsmm_get_side_trace_stream', `qsmm_side_set_trace_flags' to `qsmm_set_side_trace_flags', `qsmm_side_set_err_handler' to `qsmm_set_side_err_handler', `qsmm_side_get_err_handler' to `qsmm_get_side_err_handler', `qsmm_side_set_trace_stream' to `qsmm_set_side_trace_stream'. The deprecated old functions are still available via aliases.