Adding Input and Output
Arguments for an External Pathway
In addition to passing the mass flux link An interconnnection between two transport pathways that defines the rate at which species move between the pathways. data to and from the External pathway A transport pathway element that provides a mechanism by which external program modules for contaminant transport (e.g., analytical, finite elelement, or finite difference models) can be directly integrated into GoldSim. function, GoldSim allows you to send and receive additional input and output arguments to and from the function.
This can allow, for example, the External pathway function to utilize the same species The chemical (or non-chemical, such as bacterial or viral) constituents that are stored and transported through an environmental system in a contaminant transport model. In GoldSim, the Species element defines all of the contaminant species being simulated (and their properties). properties (e.g., solubilities and partition coefficients) used by other pathways in your model. It also allows you to pass back into your GoldSim model other information that your External pathway function may be computing (e.g., flow rates, heads, total mass in pathway).
You define additional input arguments via the Interface tab:
The top part of this dialog is used to define the input arguments. The bottom portion is used to define the output arguments.
In order to add an input argument, press the Add button in the Input Interface portion of the dialog:
When you do this, GoldSim displays the Insert Link dialog, allowing you to select an existing output to add to the interface):
After selecting a link and pressing OK, the following dialog is displayed:
The Definition displays the output that was selected. The Name (ID) defaults to the output name. The Name (ID) will appear on the input interface for the External element (accessed via the input port). The Description is optional and simply provides additional information regarding the input argument (it defaults to the element description for the output that was selected).
The dimensions An output attribute for an element that defines the dimensionality (in terms of Length, Time and other fundamental dimensions) of the output. of the External Units and Type... (e.g., value/condition, scalar An output consisting of a single value or condition./vector A one-dimensional array./matrix A two-dimensional array.) for the input argument are automatically determined by the output that was selected. Prior to sending the argument to the DLL, GoldSim converts it to a number in the External Units specified. This can be edited, but must have dimensions consistent with the Definition.
Note: If you send a output whose Type is a Condition to an external function, GoldSim will automatically convert it to either a 0 (for False) or 1 (for True) prior to sending the argument to the DLL.
Note: If you pressed Cancel (rather than selecting an output) when adding the input argument, the Definition (and hence External Units and Type) will be blank. You could enter any expression into the Definition field (including constants). The External Units and Type would need to be specified in a manner that was consistent with the Definition.
In order to add an output argument, press the Add button in the Output Interface portion of the dialog:
When you do this, GoldSim displays the following dialog:
The Name (ID) is the name by which the output variable can be referenced in the model. For example, if the name of the External Pathway element was X, and the name of the output was Y, the output could be referenced as X.Y. This ID has the same restrictions as an element ID.
The Description is an optional description of the output. The External Units represent the units in which the External function returns the value. The specified units also become the Display Units for the output. The Type... button is used to access a dialog for specifying the data type (e.g., value/condition, scalar/vector/matrix).
Note: If you add an output whose Type is a Condition to the output interface, GoldSim will treat any non-zero number as True, and zero as False.
There is no limit to the number of input and output arguments that can be added.
After adding the input and output arguments, the Interface tab displays them as follows:
The input arguments and output arguments are transferred between GoldSim and the external function in exactly the order in which they are listed on the Interface tab (inputs first, and then outputs).
Buttons for deleting, editing and moving the input and output arguments up and down in the list are available directly below the Add buttons.
Note: You can export the interface definition to an XML file (this can also be done for a standard External element that is not a pathway). The interface definition consists of a list of input definitions and output definitions. This does not include, however, fluxes passed to and from the External pathway.
- Adding Input and Output Arguments for an External Pathway
- Defining Initial/Boundary Conditions for an External Pathway
- Locking onto an External Pathway DLL File
- Running the External Pathway DLL in a Separate Process
- Specifying the External Pathway Function
- When is the External Pathway Function Called?