4.2.6 Creating the Model Instance ¶

A multinode model can have an instance holding model parameters specific to a single model run against input data or a single course of interaction with external entities. That is, a model represents the structure of a system, and a model instance is a system created to carry out a particular process of interaction or computation—a process of model execution. After finishing the process, a program can accumulate learned model parameters and recreate the instance for a new process of model execution. Multiple model runs would provide average values of learned model parameters.

Creating a model instance includes creating an environment state identification engine and instruction emitting engine. The function qsmm_destroy implicitly destroys a model instance if it exists.

When a model instance exists, nodes have extended parameters listed in Node Parameters. A node takes initial values of extended parameters on creating the model instance after creating the node and on creating the node after creating the model instance. All nodes lose their extended parameters on destroying the model instance.

Use the following function to create a model instance.

Function: int qsmm_engine_create (qsmm_t model) ¶

This function creates the instance of a multinode model. A model instance holds parameters specific to a particular process of interaction or computation performed using a model with certain structure. If the model instance already exists, the function first destroys it. The function returns a non-negative value on success or negative error code QSMM_ERR_NOMEM on out of memory error.

Use the following function to destroy the model instance.

Function: void qsmm_engine_destroy (qsmm_t model) ¶

This function destroys the instance of a multinode model. Destroying the model instance includes destroying the environment state identification engine and instruction emitting engine and removing all statistics they might have collected. If the model instance does not exist, the function has no effect.

An object called actor pair addressed by an actor pair handle is a container of an environment state identification engine and instruction emitting engine in the scope of a model instance.

Data type: qsmm_actpair_t ¶

This is a type for an actor pair handle. It is a pointer, so variables of this type can be NULL. The function qsmm_get_actpair returns the handle of an actor pair for a model instance. That handle is valid until destroying the model instance.

Use the following function to get an actor pair associated with a model instance.

Function: qsmm_actpair_t qsmm_get_actpair (qsmm_t model) ¶

This function returns the handle of an actor pair associated with the instance of a multinode model. That handle is valid until destroying the model instance. If the model instance does not exist, the function returns NULL.

Use the following function to get an actor representing an environment state identification engine or instruction emitting engine, which is a part of an actor pair. See Creating a Handle, for a description of qsmm_engine_e enumeration used by the function.

Function: qsmm_actor_t qsmm_get_actpair_actor (qsmm_actpair_t actpair, enum qsmm_engine_e engine_type) ¶

This function returns the handle of an actor contained in an actor pair actpair. If engine_type is QSMM_ENGINE_ENV, the function returns the handle of an environment state identification engine. If engine_type is QSMM_ENGINE_IEE, the function returns the handle of an instruction emitting engine. For other values of engine_type, the function returns NULL.

To be confident that key parameters of an environment state identification engine and instruction emitting engine have expected values, you should explicitly set the parameters after creating the model instance. If the variable qsmm holds the handle of a multinode model, use the following lines of code to assign to the variable actor_env the handle of the environment state identification engine and assign to the variable actor_iee the handle of the instruction emitting engine:

const qsmm_actpair_t actpair=qsmm_get_actpair(qsmm);
const qsmm_actor_t actor_env=qsmm_get_actpair_actor(actpair,
                                                    QSMM_ENGINE_ENV),
    actor_iee=qsmm_get_actpair_actor(actpair,QSMM_ENGINE_IEE);

Some parameters are applicable to a small actor associated with a large actor representing the environment state identification engine. Use the following lines of code to assign the handle of this small actor to the variable actor_env_env:

const qsmm_actor_t actor_env_env=
    qsmm_get_actpair_actor(
        qsmm_get_actpair(qsmm_get_actor_large_model(actor_env)),
        QSMM_ENGINE_ENV);

Some parameters are applicable to a small actor associated with a large actor representing the instruction emitting engine. Use the following lines of code to assign the handle of this small actor to the variable actor_iee_env:

const qsmm_actor_t actor_iee_env=
    qsmm_get_actpair_actor(
        qsmm_get_actpair(qsmm_get_actor_large_model(actor_iee)),
        QSMM_ENGINE_ENV);

The table below summarizes parameters you can set for the aforementioned variables actor_env, actor_iee, actor_env_env, and actor_iee_env—an environment state identification engine and instruction emitting engine and their associated small actors (if applicable). The table shows initial parameter values for the actors. Consider explicit setting the initial value of a parameter if a corresponding cell contains “varies.”