Each profile instance is guaranteed to be evaluated exactly once per simulation time step.
This holds even if the return value of a profile is not required during a time step, the ‘evaluate’ method will still be called. This guarantee is important for a number of reasons.
The ‘evaluate’ method can be used to maintain state. This permits the progression of a model or tracking of a rolling average, regardless of whether the profile return value is required at a particular time step.
It removes the need to implement result caching code within the profile itself. All class variables and the return value are automatically stored and reused on subsequent calls within the same iteration. This reduces the impact on performance when a scripted profile evaluation may be a relatively costly operation.
It facilitates additional profile logging. If output from a profile is required during a simulation, this can be achieved by writing output to a log file. There will be one write per time step, regardless of whether the profile value is used or evaluated several times.
All profile instances are evaluated consecutively at the start of a time step. The order of profile instance evaluation is not defined.
A profile class can include any number of methods. A few methods of a profile class, however, carry special significance and are called by Apache during a simulation. As shown in the previous example, ‘evaluate’ is required and called each time step. If defined, the routines, ‘setup’ and ‘finalise’ are called by Apache at the beginning and end of a simulation. These routines are optional, if there are not defined Apache will not attempt to call them.
The ‘setup’ routine of each profile instance is called at the start of a simulation. A common use case would be to initialise class data structures, load additional settings, read data from file, or to initialise an external model to be used during the simulation.
The ‘finalise’ routine of each profile instance is called at the end of the simulation. It will not be called if the simulation is stopped or aborted. The routine could be used to write a results file containing information accumulated over the course of a simulation.
Profiles operate in two modes, modulating or absolute.
A modulating scripted profile, will have the return value from ‘evaluate’, automatically clamped to the range [0,1]. True and False can also be returned from this function, with True converted to 1 and False indicating a return value of 0.
Scripted profiles are aware of two unit sets, Metric and IP. The unit set is specified as part of the profile class. Values returned by an absolute profiles are assumed to be in the declared unit set. Simulation variables accessed by the profile will be provided to the profile in the appropriate units set.
