To create a component, simply add a
component primitive to your model. This primitive behaves much like a folder
primitive and you can drag other primitives into it. It is a very simple
relationship. When primitives are within the component folder, they are part of
that component, and when they are outside the component folder, they are
independent of it.
There are some limitations on what may be made part of a component. For instance, display primitives cannot be placed into a component as they act on the level of an entire model. Additionally, components may not contain other components in a nested fashion.
In their default form, components display everything that they contain. Often you will want to hide the details of components in your models, especially if you wish to distribute them to other modelers. This can be achieved by “encapsulating” the component. When a component is encapsulated, its inner workings are hidden from the user. Encapsulation can be enacted or reversed by selecting the pertinent menu item under the “Components” menu or right-clicking on the component. When encapsulating, it is possible to specify a password that will be used to lock the component into its encapsulated state. The component cannot then be unencapsulated without the password. This feature is useful for distributing commercial or proprietary components.
A component in its Unencapsulated and Encapsulated states
Of course the user will most likely need to be able to access some simple primitives within an encapsulated component – such as inlet and outlet stocks. To allow the user to access these items in the component’s encapsulated state, you mark them as “exposed.” An exposed primitive will remain visible to, and modifiable by, the user even after the component has been encapsulated.
Components have two properties that can be used to automatically execute macros. The first macro can be set to run after the user has clicked the “Run Simulation” button but before the simulation has started, and a second may be set to be executed after the completion of the simulation. For more information about macros, see the relevant section later in this manual.
The Options dictionary available to the component’s macros has a number of special entries to give the component the ability to interact effectively with the model. Both the Before Start and After Finish macros can access the following keys:
· “Component”: The component primitive itself.
· “Model”: A model object referencing the model that contains the component.
· “ModelWindow”: A ModelWindow object referencing the window containing the model. If the model window does not exist (for instance, the model is run through Simgua’s online publishing feature), this key will return nil. It is important that you check for this occurrence.
· All the properties defined in the component’s calibration page are also available to the macro through the Options dictionary with the properties’ names as the keys.
The After Finish macro can additionally access the following keys:
· “Results”: A results object containing the results of the simulation.
· “AnalysisWindow”: An AnalysisWindow object containing a reference to the window displaying the results of the simulation to the user. As with the ModelWindow key, the results of using this key should be tested against nil before they are used.
Macros can also be executed on demand in one additional way: you can invoke macros from within component calibration pages. To do this, use the “ExecuteMacro” JavaScript function that’s added to the default component calibration pages. Just call this function passing the macro code you want to execute. The Options dictionary of the macro will contain a key called “Component” whose value is the component whose calibration page is executing the macro.
Components have three important properties that can be used
to extend your own custom programmatic behavior during simulation. This first is the On Start
property. This is a block of Visual Basic code that is executed by Simgua when
your component is created during a simulation. The second is the On Step
property. This is another block of code that is executed once during each time
period as your model simulation is run. The final, is the On Finish
property and is executed on the completion of the model simulation. All these
blocks are executed within a subroutine so you should not declare any functions
or classes as part of them. See Programming Simgua for more details on this
topic. An important feature that your On Step properties might need to
access is the exploratory variable. When using a Runge Kutta type
solution algorithm, each time step will be evaluated multiple times. If you
have a badly designed component, an On Step function that you wanted to
be executed exactly once each time step would be executed multiple times each
step. The exploratory variable will be set to true for all but the final
evaluation. Therefore, if you want some code to be evaluated exactly once each
step, you can wrap it with an if-statement checking whether exploratory
is false.