Text parameters

Text parameters

Parameters text

These are text strings. There are three common uses for text parameters:

• To specify the name of files that are to be read by the submodel. In this case, you get access to a file browser as in the figure below. You can also use generic data filenames which are described in the next section. Figure 116: Specify the name of the file with the browser

• To specify the name of a directory.

• To give an expression that is to be evaluated by the submodel. In this case you get access to the Expression editor as in the following figure: Figure 113.

Generic data filenames

Generic data filenames

It is commonplace for Simcenter Amesim models to rely on data files, for instance for the purposes of parametrization, calibration, and result validation. These data files can have varied origins: they may contain experimental results, or maps used for the characterization of a component's operating state, or other types of data.

Users can refer to data files by providing the path to the file in the text parameter field (essentially providing the path to the file as it would appear in the file system). However, this absolute path reference is error-prone, as it assumes that the file is always present on the machine, and always in the same location.

An obvious shortcoming in this scenario is the case where the model needs to be shared with other users, who do not have access to the same file system as the original model creator. The need for sharing these data files, as attachments or accompaniments to the model, quickly arises. This is why a number of keywords are available, and provide a flexible and safe method for referring to the location of data files (or other resources) relative to the location of their models or libraries.

Below is a list of these keywords and their respective descriptions:

${full_circuit_name}	is automatically replaced by the complete name of the system, including its full path, during the execution of a run.
${circuit_name}	is automatically replaced by the name of the system (without its path) during the execution of a run.
${library_node}	is automatically replaced with the path of the library where the submodel of the selected component is saved.
${master_circuit_name}	is automatically replaced with the name of the master circuit, in the context of Discrete Partitioning master-slave systems (for more information, see the Discrete Partitioning manual)
${full_master_circuit_name}	is automatically replaced with the full name of the master circuit, in the context of Discrete Partitioning master-slave systems (for more information, see the Discrete Partitioning manual)
${SC_library_node}	is automatically replaced with the path of the supercomponent library.
${model_userdata_path}	points directly to the UserData folder associated with the model. This folder is solely under the user’s ownership and responsibility – Simcenter Amesim will never delete or otherwise modify files inserted into this folder by the user. It is the ideal place to store data files, specifications sheets, functional requirements documents, and other types of documentation associated with the model. The ${model_userdata_path} is expanded to the full path to the folder named ModelName_.UserData.

We will illustrate this with some examples.

As of Simcenter Amesim 2410, new keywords automatically and transparently replace their old counterparts:

Old keywords	New 2410 keywords
${circuit_name}	${model_name}
${full_circuit_name}	${model_path}
${master_circuit_name}	${primary_model_name}
${full_master_circuit_name}	${primary_model_path}

A log file is created whenever such an automatic replacement action occurs inside the model (for future debugging if necessary). This log file is saved as ModelName_.cir.log and contains a list of all the parameters whose values have automatically been updated from the old keywords to the new ones.

Using generic data file names

The following model (named CamAndValve.ame) contains a component which makes reference to a data file stored somewhere on the file system (cam.data):

Figure 117: Parameters pane

Referencing the absolute path to the data file is valid for a user on his or her own machine, but immediately becomes invalid the moment the user shares the model with colleagues or customers, unless they have the file available on their file system, under the same folder structure.

To avoid running into this type of problem, the user can store the file alongside the model, for instance here in the folder CamAndValve_.DataFiles, and refer to the data file using the ${model_name} keyword, as shown below:

Figure 118: Data file name

Note

Creating folders in the same parent folder where the .ame file is stored, and giving them the same name as the model itself, suffixed with _. and any additional relevant name (in the example below: CamAndValve_.DataFiles), will ensure that these folders are encapsulated in the .ame file once it is saved. This is a safe way of ensuring that data and resources are always provided with a model when it is shared.

In general, any file saved in the format [ModelName]_.[extension] is also saved into the .ame file. Additionally, if the .ame model is subsequently saved under a new name, any folder or file of this type is automatically saved under the new name, to ensure maximum data consistency.

Referencing files and resources present in Submodel Editor libraries

You can use the keyword ${library_node} in text parameters. In this case, the relative path is replaced with the path to the parent library of the submodel where the text parameter is being used. This is done according to the preferences set in the path handling preference (see General).

As an example, if a user employs the ${library_node} keyword in the parameters of a component from the Electric Motors and Drives library, then the keyword is expanded to the path of the Electric Motors and Drives library on the machine. This is also true for user libraries created in the Submodel Editor.

Figure 119: Using the ${library_node} keyword will reference the root folder of the submodel's parent library

Note

In the context of sharing models where this keyword is used, it is necessary for the recipient to also have the library in their file system, and added to their path list, otherwise an error is raised.

Referencing files in supercomponent user libraries

In contrast to the case above, supercomponent user libraries contain components from libraries (potentially both standard and user libraries).

Sharing resources with users of such supercomponent libraries becomes slightly confusing for users, especially since the keyword ${library_node}will still work as advertised: if used in the context of a supercomponent library, it will still refer to the parent library of the specific submodel (e.g. the Electric Motors and Drives library, as in the example above), even if used inside a supercomponent.

To address this use-case, users can use the keyword ${SC_library_node} (short for supercomponent library node), which allows them to explicitly refer to the path where the library of supercomponents itself is stored. Thus, users can also share data files and other resources with their fellow users when creating libraries of supercomponents.

Figure 120: Supercomponent Library node used in a library supercomponent

Note

• The ${SC_library_node} keyword returns the path of a library supercomponent.

• The ${SC_library_node} keyword cannot be used in a top-level circuit or local supercomponent. A warning message is displayed to inform you of this. Figure 121: Keyword used in top-level circuit

• The ${SC_library_node} keyword can be used in the global parameters of a library supercomponent. In this case it returns the path of the supercomponent library.

Figure 122: ${SC_library_node} in a global parameter

Using global parameters in text parameters

You can use any global text parameter to define (part of) the value of any text parameter. To do this, you use the ${globalname} syntax (which used to be limited to ${model_name} and ${model_path}). This syntax can only be used in text parameters (of any subtype), and can only be used to refer to text type global parameters.

A typical example is to set the path to a central directory as a global parameter (for example, a global parameter named files_root, which points to a directory such as C:\MyProject).

This means that each text parameter can easily refer to an individual file inside that central directory, using an expression such as ${files_root}/data/MyTableData.dat. Then, if you have many such expressions, you only need to update the value of the files_root global parameter to update the directory’s location, which would be necessary if, for example, you send the model to a colleague, or if you have another data set in another directory.

You can use multiple ${} occurrences in a single value, and you can also define global parameters using other global parameters (again using the ${} syntax). This is useful in more complex scenarios.

In addition to using global parameters (of the model) you can also use text type supercomponent global parameters using the ${} syntax. Just as with supercomponent parameters in numerical expressions, you simply have to type the varname of the supercomponent parameter, and Simcenter Amesim will automatically detect that it refers to a supercomponent parameter. If there is any ambiguity between using a supercomponent parameter and a global parameter, a prompt asks which one should be used:

References to supercomponent global parameters include the supercomponent’s name in parentheses:

References to global text parameters using the ${} syntax are also considered when creating a supercomponent, and the usual prompt for external parameter references is displayed: