2.6.2 Helper Relative Probability Functions

Below there are descriptions of types for functions f(L) and g.

Data type: qsmm_relprob_user1_func_t

This is a type for the pointer to a helper function provided by a developer for relative probability function type QSMM_RELPROB_USER1. The following declaration corresponds to this type:

typedef double
(*qsmm_relprob_user1_func_t)(
    qsmm_actor_t actor,
    double cycle_period,
    void *paramp
);

The argument actor specifies an actor called the helper function. The argument cycle_period holds the value of L. The argument paramp is a user parameter specified when setting the helper function for the actor.

On success, the helper function should return the value of f(L). On failure, the helper function should return NaN; in this case, the function qsmm_actor_calc_action_prob returns QSMM_ERR_CALLBACK.

Data type: qsmm_relprob_user2_func_t

This is a type for the pointer to a helper function provided by a developer for relative probability function type QSMM_RELPROB_USER2. The following declaration corresponds to this type:

typedef double
(*qsmm_relprob_user2_func_t)(
    qsmm_actor_t actor,
    qsmm_sig_t sig_cycle,
    const struct qsmm_state_s *state_p,
    const struct qsmm_cycle_s *cycle_p,
    const struct qsmm_sspur_s *sspur_p,
    const struct qsmm_cspur_s *cspur_p,
    void *paramp
);

The argument actor specifies an actor called the helper function. The argument sig_cycle holds the value of z. The arguments state_p, cycle_p, sspur_p, and cspur_p hold statistics associated with h and z. See Structures for Accessing Storage, for the descriptions of corresponding structures. The argument paramp is a user parameter specified when setting the helper function for the actor.

On success, the helper function should return the value of g. On failure, the helper function should return NaN; in this case, the function qsmm_actor_calc_action_prob returns QSMM_ERR_CALLBACK.

To obtain working parameters of an actor, you may call such functions as qsmm_get_actor_nsig_ctrl and qsmm_get_actor_discrete_cycle_period_mean in a helper function. Call the function qsmm_get_actor_sig_ngram to obtain the n-gram of h if you need to access application-specific information associated with h.

Use the following functions to retrieve or set a helper function for an actor.

Function: void qsmm_get_actor_relprob_helper (qsmm_actor_t actor, void **helper_func_pp, void **helper_func_param_pp)

This function retrieves information on a helper function used by an actor when calculating the relative probabilities of output signals. If there is such helper function set for the actor, and helper_func_pp is not NULL, the function qsmm_get_actor_relprob_helper sets *helper_func_pp equal to the pointer to the helper function. If there is no such helper function set for the actor, and helper_func_pp is not NULL, qsmm_get_actor_relprob_helper sets *helper_func_pp to NULL. If helper_func_param_pp is not NULL, this function sets *helper_func_param_pp equal to the user parameter of that helper function specified when setting it for the actor. If the actor is the large one, qsmm_get_actor_relprob_helper retrieves information on a helper function used by a small actor associated with the large actor. A particular interpretation of a pointer stored in *helper_func_pp depends on a relative probability function type set for the actor by a call to qsmm_set_actor_relprob_type.

Function: void qsmm_set_actor_relprob_helper (qsmm_actor_t actor, void *helper_func_p, void *helper_func_param_p)

This function sets the pointer to a helper function used by an actor when calculating the relative probabilities of output signals. The argument helper_func_p specifies that pointer. Additionally, the function qsmm_set_actor_relprob_helper sets the user parameter of this helper function to helper_func_param_p. If the actor is the large one, qsmm_set_actor_relprob_helper sets the helper function for a small actor associated with the large actor.

A particular interpretation of a helper_func_p pointer depends on a relative probability function type set for the actor by a call to qsmm_set_actor_relprob_type. Passing a pointer that does not conform with the relative probability function type leads to undefined behavior.

The value of helper_func_p can be NULL. This NULL value means the absence of a helper function for the actor. Setting the NULL value makes a certain sense when the relative probability function type is QSMM_RELPROB_USER1.

To provide an example of using the functions qsmm_set_actor_relprob_type and qsmm_set_actor_relprob_helper, let us suppose a developer has proved that it is mathematically correct to use a function for calculating the relative probability of an output signal similar to the function QSMM_RELPROB_BUILTIN2 but with the following one difference: the numerator of the exponent contains the expression L instead of L+1. To make an actor calculate the relative probability of an output signal by this function, the developer may define the helper function as:

#include <math.h>

static double
get_relprob_exp_mlt(
    qsmm_actor_t actor,
    double cycle_period,
    void *paramp
) {
    return log(qsmm_get_actor_nsig_ctrl(actor))*cycle_period/2;
}

To set this helper function for an actor, the developer may add the function calls:

qsmm_set_actor_relprob_type(actor,QSMM_RELPROB_USER1);
qsmm_set_actor_relprob_helper(actor,&get_relprob_exp_mlt,0);

Alternatively, the developer may add the function calls shown below. See Actor Temperature, for a description of qsmm_set_actor_ktemperature function.

qsmm_set_actor_relprob_type(actor,QSMM_RELPROB_BUILTIN3);
qsmm_set_actor_ktemperature(actor,2);