0 Votes

Invoking mathematical model

Last modified by WikiBot on 2025/03/20 14:16

Invoking mathematical model

In order to simulate a physical-level or a wizard-level system, IDA Modeler has to create a math level system. To do this, IDA Modeler calls :run method, that should contain commands for creating and simulating math model.

A math level system may also be created on the user’s demand. This is done by calling :invoke method that typically contains commands for creating and displaying the math level system.

The math level system may be either implemented as a separate document or as an advanced mode of the physical system. If the math system is a separate document, it may be created using :build command. To add a mathematical model to an existing document, call function map-model, or some application-defined function that calls map-model with two parameters, the source and the target objects. This function reads the invoking algorithm from the :invoking-map properties of the target document and its macro components. The value of this property contains either the mapping code describing the invoking procedure or the name of the file containing this code. For applications with extensions the invoking code is loaded from multiple files, see extending applications.

Mapping code

The mapping code contains

Mapping sections, description of components that should be generated;
Script commands :set, :call, :assert, :cond, :case, :for, :include.
Special commands :enter, :leave, and :fields described below

The mapping sections describe the math models, their parameters, start values of variables, boundary conditions, connections between objects, selection of output, and the layout of the schema view.

For hierarchical macro objects, the inner macros may also have mapping code.

Unlike script commands, the mapping sections are descriptive: they do not specify the order of evaluation.

The invoking is executed in the following order:

Parsing mapping code. The parsed mapping sections are stored and used in the followed steps. The script commands are executed during the parsing. Any local variables assigned in mapping code are discarded after parsing is finished.
If the required target components do not exist, they are created and inserted in the target macro. For components that are macro objects, the steps 1-3 are executed for mapping code of the target component (using source component assigned in the mapping section).
The values of target components’ system parameters are assigned.
The models are connected, first hierarchically inside components that are macro objects and then in the target macro itself.
The values of parameters and other attributes are assigned, first hierarchically inside components that are macro objects and then in the target macro itself.

Special commands

(:enter object): Temporarily changes the source object (used as base for executing scripts). The argument is evaluated.

(:leave): Revert the change made by the last :enter.

(:fields field ...): Adds fields and other graphical elements to the schematic view. The arguments are evaluated. The result of the evaluation should be a list of descriptions of graphical elements as they are stored in *.idc files

Mapping sections

The format of the mapping section is

(:single name command argument command argument …)

(:group name command argument command argument …)

There is no difference between the two forms; the number of generated components is determined by the result of the :source command, see below.

The name is a unique section name and determines (by default) the name of the created component.

The section with name :self is used to describe the macro object itself.

The mapping section may contain some script commands and special component commands. The following script commands are supported: :set, :gset, :assert, :case, :cond, :include, :for, :call, :return. The component commands are described below.

All evaluations are performed in the source environment (i.e., the base is the current source object).

Component commands

:source object: Specifies the source object (for a single component) or list of source objects (for a group of components). The argument is evaluated.
If the result is a list, the subsequent commands are parsed repeatedly, once for every non-nil element of the list. If the result is NIL, the target object is not generated and the subsequent commands are discarded.
The assigned source object is used in the subsequent commands as base for references.

:at (points): Specifies the geometrical location of the target object in the schema view. May be either (left top right bottom) or a list of points ((x y) …). All coordinates are evaluated.

:name name: Specifies the name of the target object. May be used only inside of conditions or loops to override the default name. Evaluated (currently – only when is a non-empty list).

:type name: Specifies the model type of the target object. The argument is evaluated.
The target object is created if it does not already exist. If an object with the required name exists but is of a wrong type, it is replaced with a new object.
If the result is :none, the whole target macro is taken as target object
The same happen if the result is NIL and the target object with required name does not exist.

:parameters ((name value) …) :model-parameters ((name value) …): Specifies the values of parameters and start values of variables in the target object. This command does not create new parameters. The values may be either expressions or references to parameters in the source objects. All expressions are evaluated when parsing. The references are resolved at mapping step (only the local variables are substituted when parsing).

A value may be evaluated to

;*. a value in the range allowed for the target parameter;
;*. a parameter. The value of the parameter is used;
;*. a list. The length of the list is used as the value (for model parameters only)
Special evaluation rules allow converting parameters in the lists of objects to arrays.

The format of reference is different – no @ required.

All listed parameters are mapped to the invoked values. The parameters that had invoked values but are not listed now are mapped to their default values.

:connections ((from to [line]) …) :internal-connections ((from to [line]) …) :parent-conections ((from to [line]) …): Defines the connections. The argument from is either the name of the interface in the target object, or a reference from the target object to an interface. The same applies to the argument to, with one difference: the start point of references is the target’s parent object. The rest of the arguments are graphical attributes of the connection line (:at, :color, etc.)

The graphical attributes are evaluated when parsing. The references are resolved at connecting step (only the local variables are substituted when parsing).

This command may also be used for connecting variables.

The argument to may also represent a plug or a resource parameter that points to a schedule.

:boundary-connections: Same as :connection, but may create new interface references

:ref-connections (ref-macro (from to [line]) …): Similar to :connection.

The target object should be a macro object similar to ref-macro, and every from should be a name of an interface reference.

The command connects only the interface references that exist and are connected inside ref-macro.

:boundary-values ((var value) …): Specifies the binding of variables in the target object

:log ((file varname …) …): Specifies which variables that are logged and where they are logged

graph-attr value: All other commands are treated as graphical attributes to the object’s symbol in the schema view. The values are calculated.

Local variables

:source: The source object specified by :source command. For groups – the source in the current iteration of mapping

:number: The number of the current object in the group of objects.