Key Parameters

USim has the ability to create key parameters. These variables are visible in the Editor pane of the Setup tab in USimComposer, and they can be modified without the user having to sift through the input file (also called the pre file). They are useful when creating a base simulation that can be easily modified to simulate different phenomena within the same base simulation. This tutorial is for power users who wish to use key parameters within their own simulations and who are familiar with the USimComposer Introduction. As preparation for a discussion of key parameters, the user must be comfortable with accessing the input file, as discussed in Pre File Syntax.

The two main components of the key parameters feature are the XSim block and the XVar block. An example XSim block in a run space input file is boxed in red in the below figure, and an example XVar block is boxed in blue.

XSim and XVar blocks

Figure 10: Example XSim and XVar blocks in a run space input file

A description of the elements of these blocks and their effect on the Parameters view in the USimComposer Setup tab is given in the following sections.

XSim Block

Given below is a template XSim block that can be modified to fit any file:

<XSim simulationName>
  shortDescription = "Simulation Name"
  description = "Description of the simulation."
  longDescription = "Longer description of the simulation."
  image = "simulationName.png"
  thumbnail = "simulationNameTn.png"
</XSim>

Each line in this block is explained below:

  1. image - The image parameter should give the name of a picture, located in the same directory as the .pre file, that will be given on the right hand side of the Editor pane in the Setup tab. Frequently, this image is used to illustrate key parameters such as dimensions of a physical structure. 400 by 500 pixels is a good image size.
  2. longDescription - This text block will be visible above the image, and is generally used to give a description of what the simulation does, and what will happen when key parameters are modified.
Parameters View

Figure 11: Where image and longDescription appear in the Parameters View.

The three following parameters are only useful to very advanced users who are creating, and placing input files in the Examples directory of USimComposer. The examples directory can be found in [USimInstallDirectory]ContentsExamples.

  1. thumbnail - This is the small image that is visible when you select an example file, located in the same directory as the .pre file. 250 x 250 pixels in a good image size.
  2. shortDescription - This is the name that will be given to the example file.
  3. description - This is the description given in the window on the right side in the examples window.
  4. analyzers[SCRIPT] - This will cause USimComposer to load the analysis script specified by SCRIPT, located in the same directory as the .pre file, for use in the Analyze Tab.
Select An Example Window

Figure 12: Select An Example Window

XVar Block

Key parameters can be created in the input, or .pre, file of a USim simulation, and appear in the Setup tab in USimComposer as seen below boxed in red.

Key parameters

Figure 13: Key parameters

To create these parameters, the user must modify the .pre file and add XVar blocks, in the same way that the user must add an XSim block as described in the preceding section. It is the practice of Tech-X developers to first declare the primary variables with a default value, then give the XVar blocks for the primary variables below that. Given below is a template XVar block that can be modified to fit any file:

$ variableName = default value
<XVar variableName>
  description = "Description of the variable"
  min = minimum value
  max = maximum value
</XVar>

Each line in this block is explained below:

  1. variableName - The very first line, above the XVar block, sets the default value of the variable.
  2. <XVar variableName> - This line, which begins the XVar block, must exactly match the name of the variable given in the line preceding it.
  1. description - This text should describe the variable and will appear when the cursor is placed over the variable name.
  2. min - This is the minimum value for the variable and is optional. This can be very useful with certain simulation parameters such as cell size that can cause an instability if incorrectly specified.
  3. max - This is the maximum value for the variable and is optional.

Note that the name of the key parameter will turn red if there is no value given for the parameter, or if the value is not greater than or equal to min and less than or equal to max, if they are specified.