2.    GENTEX Tutorial

2.1.    Getting Started

Conventions used in this tutorial

This tutorial assumes you are running GENTEX (and XSIM) under the UNIX operating system with a windowing environment, and using the C-shell as your command interpreter. If you are not using the C-shell consult your system manager or another knowledgeable person about procedures given below that do not work as you expect. The commands and text you are to enter are shown in a monospaced (monospaced) font. Unless otherwise specified (or evident from the context), commands are entered at the system prompt: no representation of the return or enter key is used.

XSIM notes

While this tutorial is not intended to teach you the details of XSIM, it is sometimes necessary to include information specific to XSIM. Such information follows a "XSIM Note" heading such as is shown in the example below:

XSIM Note: 

Text of XSIM-specific information. This usually includes a reference to the applicable section of the XSIM User Guide.

Exercises

Exercises follow headings of the kind exampled below:

"Title" is a short descriptive title of the exercise, and NAME is the name of the parameter file you should select from the tutorial database.

Appendix B contains samples of the graphical results that you should obtain by running the exercises.

Menu shorthand

The path to many windows or parameters is often abbreviated in this manual. For example, the statement "Change Parameters: Input functions > Reference Tracers > Vascular ref tracer ^Function to Sine pulse train." is a shorthand way of describing how to change the vascular input to a sine pulse train. A full description would read: Click on the Parameters menu, then select the "Input functions" from the pop-up menu, select "Reference Tracers" option, and then select the "Vascular reference tracer" option. Now, in the "Vascular reference tracer input function" window click on the "Function" button and select "Sine pulse train". Fig. 2.1.1 provides a graphical example of this operation.

An explanation of the shorthand notation: The first word in the series is always one of the pull-down menus in the main window. The colon before the second phrase (": Input functions" in this case) indicates that this is a pull-down menu option. The right angle bracket before a phrase ("> Vascular input"), designates an option on a secondary pop up menu. Finally the carat (^) preceding a word or phrase ("^ Function") indicates the name of a button or field in the newly opened window. Note that menu names are printed in emphasis in this manual.

2.1.1.   Overview

In this section, "Getting Started", you will learn how to set up an environment for the simulation interface that is used by GENTEX. You will also learn how to start GENTEX and load values for its parameters from disk files.

2.1.2.   The XSIM simulation interface

GENTEX runs under the XSIM simulation interface. Thus, it is necessary to become acquainted with XSIM before attempting to use GENTEX.

XSIM is a graphical simulation control interface that runs in a UNIX windowing environment. It was developed by the National Simulation Resource (NSR) to run computer simulations of various types; its functions and usage are described in the XSIM User Guide. The appearance of the XSIM screen is not predefined, but is assigned at run time according to a user defined configuration file. This file specifies the parameter values and their locations in the pop-up windows, as well as the content and appearance of the windows.

Upon starting GENTEX, the GENTEX model layout window appears. The coordinates and colors of the text, buttons and graphics in this window are all specified in the configuration file.

2.1.3.   Setting up a XSIM environment

If XSIM has been fully installed on your system, the environment should be properly configured for running the GENTEX tutorial. If changes are required, section 2.1 of the XSIM Interface Reference Manual gives complete information about setting up a custom environment.

2.1.4.    Running the GENTEX model

Running GENTEX with the tutorial parameter files

To run the exercises of this tutorial, you should use the GENTEX tutorial parameter files. To do so, you must first copy them into your directory. Use the following command sequence.

cd
mkdir GENTEXtutor
cd GENTEXtutor
zcat XSIMHOME/dist/model/GENTEXtutor.tar.Z  | tar xf -

Where XSIMHOME is the XSIM installation directory, usually /usr/local/xsim (check with your system administrator).

This tutorial database has a number of GENTEX parameter files that have been preloaded with the values appropriate to each exercise. Note that this also copies the reference data files that are used in some of the tutorial exercises. You are now ready to run the model. Type:

xsim -m gentex -p 1input.par

to load the first tutorial parameter file. The name of each tutorial file is composed of the tutorial number preceding a descriptive name, followed by the `.par' extension.

Note that each time you want to run one of the tutorial exercises you should use the command cd ~/GENTEXtutor. This will place you in the subdirectory where the tutorial parameter and reference data files are located.

Running GENTEX for general usage

If you have previously run GENTEX, you can select a parameter file that was previously used for GENTEX; otherwise, you have two options to load meaningful values into the selected parameter file.

1. Import the values from a another user's parameter file.
2. Modify the default values for all the relevant parameters manually.

The second option is not usually recommended because there are many parameters to be entered. It is nearly always better to load parameters from another user's parameter file and then modify the values that are required to make it appropriate to your needs.

In order to create your own parameter file, select Save as... from the Par-File pull-down menu in the main window. Enter a name (e.g. test.par) for the parameter file in the Parameter File field and press return.

2.1.5.   Summary

You have set up an XSIM environment that allows you to run GENTEX and any other model that uses XSIM. You made a copy of the GENTEX tutorial directory that you can use and modify when you run the exercises in the remainder of the tutorial. Additionally, you learned how to start GENTEX and have it load parameter values from your parameter files or from the tutorial parameter files.