Creating the Output Interface to a SubModel

Because a SubModel is a self-contained system (i.e., a separate model), by default, elements outside a SubModel cannot "see" anything on the inside. Moreover, because a SubModel is a separate simulation (that will often be carried out multiple times during a simulation of the outer model), intermediate results of a SubModel are typically overwritten during a simulation of the outer model and are not available in the outer model.

Of course, in order to be of any value, a SubModel must have some way to communicate with (e.g., provide outputs to) the outer model. This is done by creating an output interface between the SubModel and the outer model.

The output interface is accessed via the Interface tab on the SubModel dialog:

The top part of this dialog is used to define the input interface. The bottom portion is used to define the output interface.

The output interface allows you to specify the outputs that you want the SubModel to provide to the outer model. It is important to understand that the output interface represents the only mechanism by which you can access outputs of a SubModel outside of the SubModel.

In order to allow the outer model to access an output of the SubModel, you must select the output and add it to the output interface. This is done by pressing the Add button in the Output Interface portion of the dialog.

When you press this button, you will be presented with a browser displaying the outputs inside the SubModel. You must select the output that you are interested in.

The Output ID is the name by which the output variable can be referenced in the outer model. This ID has the same restrictions as an element ID.

Note that the outputs defined in the output interface are added to the output port interface of the SubModel and can be accessed there (in exactly the same manner the outputs from other kinds of elements are accessed). The Output ID is what is shown in the interface:

The Description is an optional description of the output. The Internal Output field displays the selected output (which you can change using the button to the right of the field).

The Data Type and Unit fields are automatically populated based on the Internal Output selection.

After selecting the Internal Output you must then select what type of result is to be made available to the parent model on the output interface. This is controlled by two fields: Output Type and Output Definition. For some Output Definition selections, a third field will be presented to the immediate right of the Output Definition field.

“Final Value”. The following Output Definitions are available (some of which are only valid selections under specific circumstances):

• Statistic. This selection is only valid for Probabilistic SubModels (it is not valid for Deterministic SubModels). A specific Statistic must be defined immediately to the right of the Output Definition field.

• Distribution. This selection is only valid for Probabilistic SubModels and scalar outputs (it is not valid for Deterministic SubModels or for array outputs).

• Last Calculated. This selection is only valid for dynamic SubModels and scalar outputs (it is not valid for Static SubModels or for array outputs).

• Statistic History. This selection is only valid for Probabilistic, dynamic SubModels and scalar outputs (it is not valid for Deterministic or Static SubModels or for array outputs). A specific Statistic must be defined immediately to the right of the Output Definition field.

• Realization Histories. This selection is only valid for Probabilistic, dynamic SubModels and scalar outputs (it is not valid for Deterministic or Static SubModels or for array outputs).

Note: For some advanced applications, you may select a Time Series Definition output (from an External element or Time Series element inside the SubModel) rather than a Value as the Internal Output. If you do so, the Output Type is automatically set to be a Time Series Definition (rather than a Final Value or Time History).

When you add an output to the Output Interface and select the Output Type and Output Definition, you will be notified if your selections are invalid.

The Output Interface provides a summary of all of the outputs (as well as their Output Type and Output Definition):

If you change the settings such that some of the selections are no longer valid, the Results will be identified in red (and the model will not run). In the example below, the SubModel has been set to Deterministic, invalidating those Output Types that require a Probabilistic SubModel:

It is important to understand what these various results are and how they can be used in the parent model:

Last Calculated. This result is simply the final value of the output that was computed at the end of the simulation (for the final realization of the SubModel if multiple realizations were run). This will be listed in the Output Interface as “Final Value”. It can be used directly in the parent model as any other value (or condition) output could be used.

Statistic. If this is selected as the Output Definition, a third field appears directly to the right:

The first two options are “Mean” and “50%” (the Median). The third option provides access to a dialog where you can specify any percentile. In these three cases, the result represents the specified statistic (computed over all realizations of the SubModel) for the final value of the selected output (i.e., the value computed at the end of each realization).

The fourth option (“Specify Result Condition”) provides access to the following dialog:

In this case, the result represents the probability (computed over all realizations of the SubModel) that the final value of the output satisfies the specified condition. In the example above, within the parent model, the result would represent the probability that the final value of the selected SubModel output was less than 0 m3/day.

In all cases, the result will be listed in the Output Interface as “Final Value (Statistic)”, where Statistic is the selected option. It can be used directly in the parent model as any other value (or condition) output could be used.

Distribution. This result is a complex output (referred to as a Distribution output) that represent all the statistical information necessary to define a probability distribution computed by the SubModel. It can be used to define a Stochastic in the parent model (as an “externally-defined” distribution). More frequently, it will serve as an input to specialized functions that operate on distributions. For example, PDF_Mean(X) returns the mean of the distribution X; PDF_Value(X,0.95) returns the 95% percentile. Under certain conditions (nested Monte Carlo simulation), Final Value Distributions can represent a distribution of distributions.

The result will be listed in the Output Interface as “Final Value Distribution”. Unlike other results, because it is a complex type of output, it can only be used in the parent model in specific locations (e.g., as input to an externally-defined Stochastic, as input to a specialized distribution function, within a Distribution Result element).

Time History results on a SubModel Output Interface are complex outputs that represent all the information necessary to define a time series. As such, they can only be used in three places within the parent model: 1) to define a Time Series element in the parent model; 2) as an input to an External (DLL) element; or 3) directly within a Time History Result.

Last Calculated. This result is the time history of the output for the final realization of the SubModel (which is equivalent to the only realization if the SubModel Monte Carlo Settings do not specify multiple realizations). Hence, regardless of whether the SubModel is probabilistic or deterministic, it always consists of a single time history (for each realization of the parent model). This will be listed in the Output Interface as “Time History”.

Statistic History. If this is selected as the Output Definition, a third field appears directly to the right:

The first two options are “Mean” and “50%” (the Median). The third option provides access to a dialog where you can specify any percentile. In these three cases, the result represents a time history of the specified statistic (computed over all realizations of the SubModel) for the selected output.

The fourth option (“Specify Result Condition”) provides access to the following dialog:

In this case, the result represents a time history of the probability (computed over all realizations of the SubModel) that the output satisfies the specified condition. In the example above, within the parent model, the result would represent the time history of the probability that the selected SubModel output was less than 0 m3/day.

In all cases, regardless of whether the SubModel is probabilistic or deterministic, it always consists of a single time history (for each realization of the parent model). This will be listed in the Output Interface as “Statistic History (Statistic)”, where Statistic is the selected option.

Realization Histories. This result is the time history of the output for all realizations of the SubModel. Hence, unless the SubModel Monte Carlo Settings do not specify multiple realizations, it consists of multiple time histories (for each realization of the parent model). Hence, when running nested Monte Carlo simulation (i.e., in which both the parent model and the SubModel are probabilistic), this can result in a very complex set of results. For example, if the parent model was run for 100 realizations, and the SubModel was run for 50 realizations, the results being displayed in a Time History Result element within the parent model would be based on 5000 individual time histories (50 * 100). Fortunately, GoldSim provides some powerful tools to view this complex set of results.

This type of result will be listed in the Output Interface as “All Realization Histories”.

Note: Calculations in GoldSim are carried out in double-precision. However, outputs of a SubModel are reduced to single precision when they pass through the output interface.

Note: Buttons for deleting, editing, moving and alphabetically sorting the outputs on the interface are available directly below the Add button.

At the bottom of the Definition tab for SubModels are options to Save Results for Final Values and Time History. The outputs for a SubModel, of course, are those results that have been added to the output interface. However, it is important to understand that these flags do not apply to all outputs in the output interface. In particular, they only apply to “standard” outputs (which must be Last Calculated or Statistic Final Values). They do not apply to the special output types discussed above (Distribution outputs or Time Series Definition outputs). These output types can only be viewed through Result elements in the parent model. (Note that time histories of “standard” SubModel results as viewed in a dynamic parent model would only change if the SubModel was called multiple times during simulation of the parent model).