Naming Conventions

This article is part of the GoldSim Style Guide. For an introduction, please start here.

In a GoldSim model, you will be providing custom names for various types of objects throughout the model. The most common type of object you will work with in GoldSim are elements. Because these are referenced in expressions throughout your model, they should be easy to read. It is important to be consistent with this style (or a style of your own) for all elements in your model, especially if you are working together with others.

Element IDs

Element IDs are the most common names in a GoldSim model, which can only include letters, numbers, and the underscore ("_") character. They cannot include spaces and must begin with a letter. In addition, some names (e.g., sin, cos, min) are reserved for use as functions and cannot be used as an element name. Two types of elements (Result elements and Dashboards) have slightly more flexibility in terms of their names, which can include spaces.

There are 3 recommended ways to write element names:

• Capitalized camel case (i.e. EvapRate)
• Capitalized with underscores (i.e. Evap_Rate)
• Small case with underscores (i.e. evap_rate)

We recommend that you choose 1 of the 3 options shown above and stick with it throughout the model. Note: The examples shown in this document use capitalized with underscores, but you can replace these with either of the other 2 if you prefer.

In general, follow these rules of thumb for names of Elements in your model:

• Abbreviations are okay if obvious to the reader, such as Evap_Rate (meaning “evaporation rate”)
• Avoid initialisms and other abbreviations that are unique to your model or difficult to decipher by the reader

Use your natural language to tell a story in a way that you might do so when talking. In English, write names that follow a convention of attribute followed by object (Red_Car) or object followed by function (Airplane_Flies). One exception is when naming elements located inside a localized Container, where the attribute will likely follow the name of the Container that represents a physical object. Refer to the “Containers” Section for more information.

If you are using capitalized words with underscores, then you might want to avoid capitalizing some small words like prepositions in a name like “Supply_to_Pump”. This would not be the same for camel case though: “SupplyToPump”.

There are some additional ideas to consider for different types of elements, described below. 

Global Containers

Global (open) Containers can use verbose, full names with underscores. These names are not used in expressions within the logic of the model so long names will not encumber expressions. The only constraint is the space provided in the graphics pane. In the examples shown below, we don’t need to abbreviate words more than we have already.

Localized Containers

Localized (closed) Containers may need to use names that are more concise since they will be used in expressions when referring to internal outputs from outside of the Container. Often, the localized Container represents a physical object or location. If there is an element called “Population” inside the Container called “Seattle”, then you must refer to the output outside of the Container using the name “Seattle.Population”. For more discussion of how to use localized Containers, refer to the Model Organization section.

Conditional Variables

Model variables with a main output of a conditional type such as Status, And, Or, Not, and an Expression with conditional output type can be appended with a word that represents its true conditional output. The word used to define the condition can be in ALL CAPS for more emphasis. For example, if a Status element is used to report the state of a light bulb, it would be: Light_ON.

Other examples of these names include: Pump_ON, Operation_FAILED, Gate_OPEN, Engine_STANDBY, Tank_FULL, Tank_EMPTY, High_Target_ENABLED

Constants

A constant in GoldSim is a value or array of values that never change during all model simulations. Scenario data and data controlled via dashboard controls are not considered constants. Don’t confuse a model constant with a variable that remains constant during a realization or scenario. In this section, I am referring to true constants, which would never change during all realizations and scenarios.

It can be helpful to write the names of true constants in all-caps with underscores separating words, such as FRICTION_FACTOR or VISCOSITY.

Lookup Tables

To help differentiate from other types of input data, you can append the word “Table” on the name such as Elev_Volume_Table or Cost_Table. The benefit of doing this is that it provides context within expressions, which differentiates this type of input from built-in functions. The downside to using this approach is that it makes the name longer, which complicates the expression.

Time Series Recordings

Time Series elements provide an advanced option in which you can read the output of another element in GoldSim, and "record" the results. An easy way to differentiate a recording Time Series element from others is to append the word “Record” on the end of the element name.

Previous Values

The input of a Previous Value element can only be defined by a link to a single output so it is helpful to give it a name similar to the output it is referencing, along with “PV” or “Previous”. For example, if the Previous Value element is referencing an output called “Bypass_Request” then you could call it Bypass_Request_PV or Previous_Bypass_Request.

Results, Dashboards, and Hyperlinks

The names of Result and Dashboard elements allow for spaces in the names. Because of this, you should use spaces when more than a single word is used. By default, the name of the element is displayed in the header of the chart so you should make the names as descriptive as possible within reason.

Append the word “Dashboard” to all dashboards.

It is recommended that Hyperlinks in GoldSim also follow these same conventions of Capitalized words separated by spaces.

Differentiate Between Types of Information

In some cases, it might be helpful to differentiate between types of information in your model. For example, you might have elements that refer to concentrations (or flows) and you want all elements of this type to have a similar name. To do so, for example, you could add “_C” or “Conc” (and “Q” or “Flow”) to the beginning or end of these element’s names. 

Array Label Set Names and Array Labels

It is helpful to create concise names for Array Label Sets because they appear in the Type display for non-scalar elements. Using camel case and abbreviations are good ways to shorten the names.

To reduce confusion between element IDs in your model and array item names in arrays, the names of array labels should follow a different convention than element IDs. In the example below, lower case words with underscores are used for the array item names.

Result Labels

This is for labels of outputs connected to Result elements. You can modify the Label for each result (which can subsequently be displayed in legends and headers, footers and axes labels). Use capitalized words with spaces.

Global Properties

In some cases, you may want to define global properties that can be referenced throughout your model.  Of course, one way to do this is to define Data elements at the global level of the model (i.e., outside of any localized Containers). GoldSim also provides a more convenient way to do this via the Globals tab of the Simulation Settings dialog. Names of a global property have the same restrictions as an element ID.

A good way to differentiate the names of global properties from others is to use ALL_CAPS separated by underscores.

Scenario IDs

Scenario ID names should be concise because they appear in various UI controls, the status bar, results and Dashboards. It is recommended that you use Capitalized words separated by spaces as shown in the example below.

If you use names that are too long, you will find some controls must stretch to show the full length and cannot fit well (as seen in the example below).

Other Names

There are a few other places where you can specify user-defined names in GoldSim, as shown below. For these, use the same conventions as other element names.

Custom Units of Measurement

One of the more powerful features of GoldSim is that it is dimensionally-aware. GoldSim has an extensive internal database of units (all of these units are listed in Appendix D of the GoldSim User’s Guide). You can also create your own units. Any unit that you create on your computer automatically becomes a system unit (i.e., it is stored in the system units file, and hence is subsequently available to any other model you open on your computer).

When creating a new custom unit, make sure you are using the correct case and spelling that is typically found in literature and published standards.

File Name

The name of the GoldSim model file is important because you will likely be creating copies to share the file and need to avoid name conflicts. Capitalized words with spaces or camel case are good ways to name the file, followed by an identifier for a specific update to the file. Many people prefer a date, but another option is a version number, as shown below. 

Exposed Output Alias on a Localized Container

Try to avoid custom alias names on localized Containers as this can lead to confusion if element names inside the container are changed later on. However, in some cases (when multiple exposed outputs have the same names) this will not be possible, and custom alias names will need to be used.

Submodel Output Interface Labels

Use a similar convention as described for exposed outputs of localized Containers.

NEXT -->