You can define Macros that can be used the same way as builtin functions allowing you to provide specialized capabilities that can be created once and then used multiple times. For example, you can create variations of the built in delay and smooth functions such as a second or fourth order material delay.
Macros are defined using modules (see Working with Modules) where there is only a single output coming from the module. Most of the creation work in macros is, thus, just standard modeling work, with some additional information needed to define the arguments that the macros take and identify the output.
Because macros are defined in this way when you make a change to the definitions, that change will be applied everywhere the macro is used. This effectively allows you to set up specialized logic for combining different inputs and then change that logic globally without having to look for each place it was used (as you would need to do if the logic were repeated in different places within the model).
Creating and Managing Macros
Macros are associated with models, though there is functionality that makes it easy to bring macros in from other models so that it is straightforward to create a library of macros that can be used with multiple models. Creating, importing, and exporting macros is done using the Macro Manager dialog. You can also start editing a macro by right clicking on the name of the macro and selecting Jump to Definition (in the Equation Tab of the properties panel for a variable using the macro). When you do this Picture in Picture Module Viewing will be enabled for the macro and you can look at the macro structure and click on the Go button to edit it.
Note Stella supports equation only macros with no defined stock and flow structure, but you will not be able to edit these in Stella, instead you will need to edit the mode file directly.
Most of the work in creating macros is the same as it is for creating model components. The specification of the inputs and the output is done on the Macro Settings Tab.
Units in Macros
The units of measure of the output of a macro are based on the units of measure of the macro's inputs. The software uses the units equation of the output to determine that relationship. This equation is specified in terms of the input variables. For example, suppose you have the macro definition:
With out having the equation a/b. In this case, specifying the units of measure for out as a/b will divide the units of measure for whatever input replaces a by those for the input replacing b - just as the equation would if it were entered directly. For more complex macros the specification may be less obvious, but still will involve only the inputs, since the intermediate variables within a macro are not visible to the software.
In addition to the names of the inputs you can use Time in the unit equation, and this will be replaced by the time units that the model is in (for example, Months). You can also use proper unit names (apples, widgets, liters) if this is appropriate.
The Macro editor itself does not perform units checking, and no checking is performed within the macro when it is applied in an equation. For complex macros it is recommended that you development them in a module or separate model to be sure that the units all work out. In this case you can assign units to the inputs that have the same names as the inputs. While this will look odd, it lets you be sure that the units you assign to the output really do derive properly.
Using Macros
Macros are used in equations the same way that the builtins are used. In the Equation Tab for a variable you can type in the name of the macro or select it from the list of Builtins (User Macro is one type that can be used to filter this list). As you begin to type the name, auto-complete will list any macro names that match and you may choose one. Once a macro name is in the equation, when you hover over it the arguments that the macro takes will be displayed, with optional arguments identified by square brackets [].
If the macro does not take any arguments (or all of its arguments are optional and you are not using any arguments) the name should appear without any parenthesis (as PI and DT do). Otherwise the name should appear with a comma (or semicolon if you are using , as a decimal) separated list of arguments.
If you hover over the name of the macro it will display the arguments. These argument names are the names that you set for the variables when defining the macro.
Fixing Macros
Macros can, of course, have errors in them and these errors are treated like other model errors. They will be included in the list of errors shown on the dropdown in the lower right of the model window. Clicking on one will then open the macro for editing so that you can fix the errors. The errors can be in model equations, and these are fixed the same way that all more errors are fixed, or there can be errors in the macro arguments and output. The latter errors will display on the Macro Settings Tab of the properties panel.
Macro errors will prevent a model from simulating, even when the macro is not used. Once the macro errors are corrected you will be able to simulate the model. Use the dropdown error list to find and fix the errors.
Naming Conventions
Macro names follow the same rules as other variable names, but there are some naming conventions that will make it easier to work with them.
- Don't use special characters requiring quotes. These can make equations hard to read.
- Avoid spaces. This will make them look more like the Builtins.
- Use CamelCase in naming. This will make them different from the Builtins which are all upper case. (Alternatively you could use prefix such as MM to distinguish them and keep them together in alphabetical lists).
- Keep names relatively short. Again this will make the equations easier to read.
- Use descriptive names for the input variables. These will be used in the tool tip for the macro.
- Name the output the same as the macro name. This will make it easier for others to understand the macro definition.
Nesting and Recursion
You can use macros in a macro definition, and there is no limit on the depth of such nesting (that is you can define a macro with a macro that depends on another macro and so on).
Recursion, on the other hand, is not supported. If you use a macro in its own definitions, or if you use a macro that depends on the macro you are defining, you will get an error message.
Macro Example
To see an example of creating and using macros look at Macro Example.