III HOTomography TierraLab Basics
VI TierraLab's Preconfiguration
VII Installing, Configuring, and Running TierraLab
VIII Application Program Interface
X Overview of TierraLab Software Architecture
Tierra stands for Tomographic Imaging Environment for Ridge Research and Analysis. TierraLab is a software system that gives a user runtime access to data within a tomographic modeling application called HOTomography. The TierraLab Client uses MatLab as the user interface to this data, giving the user access to all the mathematical and graphic power MatLab provides. In addition, the user is free to develop and expand MatLab scripts for accessing and manipulating data from the running HOTomography application.
Data is passed from HOTomography to the TierraLab Client interface using probe calls (described in detail later in this document). The TierraLab system manages the computer memory and variable tracking, allowing the user to concentrate on using the data for scientific purposes.
A single Makefile is used to make both main components that comprise. In the Makefile you must set two macros, TIERRALAB_BASE_DIR and MATLAB_DIR.
All the code can be compiled by simply typing make.
TierraLab has been designed as a light-weight, easy to use package that allows a user access to data from the HOTomography code at run time. This section describes how to set up and use TierraLab within the HOTomography code.
TierraLab must be initialized using the TIERRA_INIT subroutine. This subroutine reads a setup file, creates data structures, and initializes the mechanism that passes data between HOTomography and the TierraLab client. This routine must be executed before any other Tierra subroutines. It is called as follows:
CALL TIERRA_INIT(setup_file_name)
where:
In order to work with a variable, TierraLab must know its type, its rank (dimensionality), and the size of each dimension. A register routine is used to provide this information. If a variable is of global scope and its size never changes, then it only needs to be registered one time. A variable must be declared before it is registered. Note that variables assigned using a PARAMETER statement may not be with TierraLab.
Two types of subroutines can be used to register variables. The first is
CALL TIERRA_REGISTER_nD(type,dim_1,[dim_2,][dim_3,],var,var_name)
where:
The other is
CALL TIERRA_REGISTER_MULTI_nD(num_vars,type,1,dim_1,[dim_2,][dim_3,],
$var_1,var_name_1,
. . .
$var_n,var_name_n)
where:
Some examples:
INTEGER*4 int_4(10)
INTEGER*4 int_1, int_2, int_3
REAL*4 r_1(5,5), r_2(5,5), r_3(6,6,6)
. . .
CALL TIERRA_REGISTER_1D(T_INTEGER4,10,int_4,'int_4')
CALL TIERRA_REGISTER_MULTI_1D(3,T_INTEGER4,1,
$int_1,'int_1',
$int_2,'int_2',
$int_3,'int_3')
CALL TIERRA_REGISTER_MULTI_2D(T_REAL4,5,5,
$r_1,'r_1',
$r_2,'r_2',
$r_3,'r_3')
CALL TIERRA_REGISTER_3D(T_REAL4,6,6,6,r_3,'r_3')
Data is made available to the TierraLab client through the use of probe calls in the HOTomography program. Every probe call contains a label and a list of variables to be probed. What probe calls in the code the user wants executed will vary from run to run.
The probe subroutine is the most important TierraLab subroutine for the user. This is the subroutine that tells the system to make data available to the TierraLab client and suspend execution until the client releases the HOTomography.
The syntax of the probe subroutine is as follows:
CALL TIERRA_PROBE(label,number_of_variables,variable_1,...,
$variable_n)
where
For example
CALL TIERRA_PROBE("probe_1",3,x,y,z)
would make the variables x, y, and z, associated with the label 'probe_1' available to the client (assuming that the label and the variables are turned 'on', but more on that in a bit).
CALL TIERRA_PROBE("MyDataProbe",1,my_data)
would make the variable my_data, associated with the label 'MyDataProbe' available to the client (again assuming the label and variable are on).
Note that labels are case sensitive and must match between the TIERRA_PROBE call in HOTomography and the client's call.
One option to change what probe calls are executed and what variables are made available to the client is to go through the code, change the probe calls by hand, and recompile. A more efficient option was chosen for TierraLab. Labels and variables can be turned on an off at run time. If a label is turned off, any probe call which uses that label will be ignored. If a variable is turned off, then that data will not be made available in any probe call in which it is an argument. A setup file, Tierra.setup, which resides in the HOTomography directory and is read by HOTomography as part of TierraLab's initialization process is used to turn variables on and off. Tierra.setup can also be used to turn TierraLab off altogether and to set the default to on or off for variables registered without first being set to on or off in Tierra.setup.
Any line in Tierra.setup that begins with a pound sign '#' is interpreted as a comment and is ignored by TierraLab. Blank lines are also ignored. Any line that begins with 'var' is used to turn a variable on or off. Any line that begins with 'lbl' is used to turn labels on and off.
Here are some examples pulled from Tierra.setup
Example 1:
# global and default for variables var global on var default off # variables var t_knshts on var t_knpdsc on var t_knsta on #global and default for labels lbl global on lbl default off lbl writeA_Params on lbl writeA_Control on
In this example, TierraLab is on, the default for variables and labels not explicitly turned on or off is 'on'. All variables and labels within the file are on.
Example 2:
var global off . . . lbl global on
Example 3:
var global on . . . lbl global off
In Examples 2 and 3 TierraLab is turned off altogether because in each case one of the global options is off.
Example 4:
In Tierra.setup:
var global on var default off # variables var t_knshts off var t_knpdsc on var t_knsta off #global and default for labels lbl global on lbl default off lbl writeA_Params off lbl writeA_Control on
In HOTomography:
CALL TIERRA_PROBE("writeA_Params",t_knshts, t_knpdsc) ! first call
CALL TIERRA_PROBE("writeA_Control",t_knshts, t_knpdsc) ! second call
CALL TIERRA_PROBE("writeA_Control",t_knshts, t_knsta) ! third call
The first call would effectively not execute because the label, 'writeA_Params' has been turned off.
In the second would be executed, but only t_knpdsc would be made available to the client because t_knshts has been turned off.
The third call would also effectively not execute because, even though the label is on, both its variables are off.
The TierraLab Client uses Matlab as its interface and is designed to allow the user to take advantage of MatLab's powerful functions.
The best way to explain what is provided by the TierraLab Client is through an example. Consider the following probe calls from HOTomography and MatLab script file:
From HOTomography:
CALL TIERRA_INIT("Tierra.setup")
CALL TIERRAREGISTER ! register vars from common blocks
. . .
CALL TIERRA_PROBE("writeModel_Params",3,
$t_knshts,
$t_knpdsc,
$t_knsta)
. . .
STOP
END
From the MatLab script file:
% note that in MatLab scripts, the percent sign '%' precedes comments
% initialize TierraLab and attach to HOTomography
Tierra('init')
err = Tierra('attach')
% Probe the first group of variables
% Check to make sure that the Probe call is on in the HOTomography program
if((Tierra('islblon','writeModel_Params')) == 1)
disp 'Waiting for probe writeModel_Params'
% Wait for HOTomography to reach probe call
while((Tierra('isprobeready')) ~= 1)
pause(1)
end % while
% Start the probe
if((Tierra('beginprobe')) ~= 0)
disp 'Error, unable to begin probe'
end % if
% Check to see that the variable is on and that its data is available
% for probing. If so execute the probe.
if((Tierra('isvaron','t_knshts')) == 1 & (Tierra('isvaropen','t_knshts')) == 1)
[err,t_knshts] = Tierra('probe','t_knshts')
if(err ~= 0)
disp 'error probing t_knshts'
end % if(err...
end % if(...'isvaron'...
% Do the same for the second variable
if((Tierra('isvaron','t_knpdsc')) == 1 & (Tierra('isvaropen','t_knpdsc')) == 1)
[err,t_knpdsc] = Tierra('probe','t_knpdsc')
if(err ~= 0)
disp 'error probing t_knpdsc'
end % if(err...
end % if(...'isvaron'...
% Do the same for the third variable
if((Tierra('isvaron','t_knsta')) == 1 & (Tierra('isvaropen','t_knsta')) == 1)
[err,t_knsta] = Tierra('probe','t_knsta')
if(err ~= 0)
disp 'error probing t_knsta'
end % if(err...
end % if(...'isvaron'...
% End the probe and free the HOTomography program to continue executing
if((Tierra('endprobe')) ~= 0)
disp 'Error calling endprobe'
status = -1
end % if
end % if(...'islblon'...
% Now that we have the data we can do whatever we want with it
. . .
% When we're done with the entire script, detach from HOTomography
err = Tierra('detach')
The first thing to notice is the format of Tierra commands in the matlab script. The command is actually the first argument of the Tierra function. If the command requires any arguments itself, these are subsequent arguments in the Tierra function. All Tierra arguments must be enclosed in single quotes.
Tierra('init') and Tierra('attach') must be the first two Tierra commands executed.
The Tierra('islblon',label_name) command is used to make sure that the label associated with the probe statement in HOTomography is on.
The Tierra('isprobeready') command is used to halt execution of the script until HOTomography reaches its probe call.
The Tierra('beginprobe') command starts the probing process. Note that beginprobe blocks until HOTomography is calling probe. So the isprobeready call need not be used.
The Tierra('isvaron',var_name) command is used to insure that the variable is turned on in HOTomography. It it is off, the TierraLab Client will not be able to access it.
The Tierra('isvaropen',var_name) command is used to check to make sure that the variable is open, that is, ready to be probed.
The Tierra('probe',var_name) command does the actual probing. In the above example the value of the error return value is checked to make sure the probe was successful. The variable return value is where the desired data from HOTomography is stored.
In order to make TierraLab simpler to use, probe calls have been added to the HOTomography code in many routines and for many variables. Most users will find they do not have to alter the code at all. In addition, script files for checking and probing variable have been developed. These give the user a starting point and allow the user to concentrate on developing script files that utilize the data.
Probe calls have been added to the subroutines in the following HOTomography source files:
In these files, probe calls are present for nearly all variables declared in the following files:
In addition, there are several probe calls present in hpt.f. These calls are used for execution flow control in the TierraLab Client.
TierraLab.setup has lines for every variable that appears in a probe call and for every label associated with a probe call. To regulate the execution of probe calls or the availability of variables the user need not change the source code, but can make simple changes within Tierra.setup.
A set of TierraLab Client script files that do the probes corresponding to the probe calls in the HOTomography code is available as a starting point for the TierraLab user. These files are located in the .../Tierra/m_files directory:
This section presents a complete example of configuring and running TierraLab starting with the TierraLab.tar and ending with a sample run. This example uses C shell.
Print the starting directory, create the TierraLab directory, copy the tar file, and untar it:
pyros% pwd /research/paraducks/users/sheehan pyros% md TierraLab pyros% cp TierraLab.tar TierraLab pyros% cd TierraLab pyros% tar xvf TierraLab.tar [output from tar extraction]
Edit the Makefile so that directories are correct:
TIERRALAB_BASE_DIR = /research/paraducks/users/sheehan/TierraLab MATLAB_DIR= /local64/apps/matlab-5.3
Make the libraries and executables.
pyros% make fresh [output from make]
You will now need two separate windows, one for HOTomography and one for the TierraLab Client. HOTomography is most often run from a script file. TierraLab comes with an example script file called com_example.
Change directory to the HOTomography directory, set up the environment, make the appropriate change to com_example, and execute the com_example which in turn executes the HOTomogrophy code:
pyros% cd /research/paraducks/users/sheehan/TierraLab/HOTomography
pyros% setenv TIERRA_DIR /research/paraducks/users/sheehan/TierraLab/Tierra
pyros% setenv PATH ${PATH}:/research/paraducks/users/sheehan/TierraLab/HOTomography
Set the RPATH variable in com_example:
RPATH=/research/paraducks/users/sheehan/TierraLab/HOTomography
Execute com_example:
pyros% com_example [output from HOTomography code]
In the TierraLab Client window, change to the client directory, setup the environment and start TierraLab:
pyros% cd /research/paraducks/users/sheehan/TierraLab/Tierra
pyros% setenv TIERRA_DIR /research/paraducks/users/sheehan/TierraLab/Tierra
pyros% setenv PATH ${PATH}:/research/paraducks/users/sheehan/TierraLab/Tierra
pyros% TierraLab
[opening messages from TierraLab and MatLab]
At the MatLab prompt, add the path to the .m script files, then run the
>> addpath m_files >> run Tierra_writeModel
You will see data and notices from the applications in both windows. The TierraLab Client will seem stalled while the HOTomography code runs and the HOTomagraphy code will seem stalled while the TierraLab Client is printing out the variables it is probing. Note, to suppress the printing out of variables from MatLab scripts, end assignment statements with a semicolon.
The total time for the example run should be about 15 minutes. At the end of the run you should see the following:
In the HOTomography window:
TIERRA_PROBE call for label tierra_control
Probe variables:
tierra_control
pyros%
In the TierraLab Client window:
Tierra_writeModel.m complete. TierraLab Client has detached from HOTomography. Tierra_writeModel.m quitting MatLab. 298 flops. Thank you for using TierraLab pyros%
Occasonally, you may find that the TierraLab system hangs for one reason or another, for example running a TierraLab Client script that doesn't match up with the probe calls in HOTomography. In such a case, you may end up having to kill the HOTomography and/or TierraLab Client processes. If this happens, you should ensure that your environment doesn't leave orphaned processes.
If you are using C shell, you can do this as follows:
Get a list of all processes
ps -ef | grep user_name
where user_name is your user name on the system.
kill -9 process_ids
where process_ids are the PIDs for processes related to TierraLab.
The second step to cleaning up after an unsuccessful run is to delete the shared memory file pointers. To do this, execute the TierraCleanUp program in the TierraLab Client directory.
TierraCleanUp
The following TierraLab functions are available for use in HOTomography. A user could also use these calls with another program to add TierraLab type instrumentation. These are declared in in TierraAppCalls.h and defined in TierraAppCalls.C.
Usage:
CALL TIERRA_EXIT()
Description:
Frees data structures used by TieraLab. Should be called immediately before exiting application program (HOTomography).
Example:
. . .
CALL TIERRA_EXIT()
STOP
END
Usage:
CALL TIERRA_INIT(CHAR *SETUPFILENAME)
Description:
Initializes TierraLab and follows actions as indicated in setup file. Must be executed before any other TierraLab subroutines.
Example:
CALL TIERRA_INIT("Tierra.setup")
Usage:
CALL TIERRA_LBL_REGISTER(CHAR *NAME)
Description:
Registers a label with TierraLab.
Example:
CALL TIERRA_LBL_REGISTER("probe_1")
Usage:
CALL TIERRA_LBL_REG_DUMP()
Description:
Prints the contents of the TierraLab label directory. Used for debugging code.
Example:
CALL TIERRA_LBL_REG_DUMP()
Usage:
CALL TIERRA_PROBE(CHAR *LBL, INT COUNTPTR, VOID *var_1[,...,var_n])
where
Description:
Makes variables accessible to the TierraLab Client and blocks until the TierraLab Client executes an endprobe call.
CALL TIERRA_PROBE("First_Probe_Call",1,x)
CALL TIERRA_PROBE("writeModel_Graph1",3,u,t,iprec)
Usage:
CALL TIERRA_REGISTER_MULTI_1D(INT NUM_VARS, INT DATA_TYPE,
$ INT DIM_1,VOID *var_1, CHAR *var_name_1[,...,var_n,var_name_n])
where
NUM_VARS is the number of variables registered in this call
DATA_TYPE is the type of data being registered. Best expressed by one
of these parameter variables found in Tierra.f:
T_UNKNOWN
T_INTEGER
T_INTEGER4
T_REAL
T_REAL4
T_REAL8
DIM_1 is the dimension of the variables.
var_1...var_n are the variables being registered
var_name_1...var_name_n are the names of the variables being
registered
Description:
Registers multiple 1 dimensional variables at the same time. The dimension of the variables in one call must be identical.
Example:
INTEGER*4 t_knshts, t_knpdsc, t_knsta
REAL*4 r_a(30), r_b(30)
CALL TIERRA_REGISTER_MULTI_1D(3,T_INTEGER4,1,
$t_knshts,'t_knshts',
$t_knpdsc,'t_knpdsc',
$t_knsta,'t_knsta')
CALL TIERRA_REGISTER_MULTI_1D(2,T_REAL,30,
$r_a,'r_a',
$r_b,'r_b')
Usage:
CALL TIERRA_REGISTER_MULTI_2D(INT NUM_VARS, INT DATA_TYPE,
$ INT DIM_1, DIM_2, VOID *var_1, CHAR *var_name_1[,...,var_n,var_name_n])
where
NUM_VARS is the number of variables registered in this call
DATA_TYPE is the type of data being registered. Best expressed by one
of these parameter variables found in Tierra.f:
T_UNKNOWN
T_INTEGER
T_INTEGER4
T_REAL
T_REAL4
T_REAL8
DIM_1 is the first dimension of the variables.
DIM_2 is the second dimension of the variables.
var_1...var_n are the variables being registered
var_name_1...var_name_n are the names of the variables being
registered
Description:
Registers multiple 2 dimensional variables at the same time. All dimensions of variables in the call must be identical to one another.
Example:
INTEGER*4 i_a(3,3), i_c(3,3), i_c(5,5)
REAL *4 r_a(6,4), r_b(6,4), r_d(6,4)
CALL TIERRA_REGISTER_MULTI_2D(2,T_INTEGER4,3,3,
$i_a,'i_a',
$i_b,'i_b')
CALL TIERRA_REGISTER_MULTI_2D(3,T_REAL4,6,4,
$r_a,'r_a',
$r_b,'r_b')
$r_c,'r_c')
Usage:
CALL TIERRA_REGISTER_1D(INT *DATA_TYPE, INT *DIM_1,
$ VOID *var, CHAR *NAME)
where
DATA_TYPE is the type of data being registered. Best expressed by one
of these parameter variables found in Tierra.f:
T_UNKNOWN
T_INTEGER
T_INTEGER4
T_REAL
T_REAL4
T_REAL8
DIM_1 is the dimension of the variable.
var is the variable being registered
var_name is the name of the variable.
Description:
Registers a single 1 dimensional variable.
Example:
INTEGER*4 i_a(3)
CALL TIERRA_REGISTER_1D(T_INTEGER4,3,i_a)
Usage:
CALL TIERRA_REGISTER_2D(INT DATA_TYPE, INT DIM_1, DIM_2
$ VOID *var, CHAR *NAME)
where
DATA_TYPE is the type of data being registered. Best expressed by one
of these parameter variables found in Tierra.f:
T_UNKNOWN
T_INTEGER
T_INTEGER4
T_REAL
T_REAL4
T_REAL8
DIM_1 is the first dimension of the variable
DIM_2 is the second dimension of the variable
var is the variable being registered
var_name is the name of the variable.
Description:
Registers a single 2 dimensional variable.
Example:
INTEGER*4 i_a(3,7)
CALL TIERRA_REGISTER_2D(T_INTEGER4,3,7,i_a)
Usage:
CALL TIERRA_REG_DUMP()
Description:
Prints the contents of the TierraLab registries. This subroutine is used for debugging.
Example:
CALL TIERRA_REG_DUMP()
Usage:
CALL TIERRA_REG_WRITE_SHMEM()
Description:
Prints out register data that is in the shared memory. This subroutine is used for debugging.
Example:
CALL TIERRA_REG_WRITE_SHMEM()
Usage:
CALL TIERRA_VAR_REG_LOCK_SERVER()
Description:
Sets the TierraLab server (HOTomography) lock. This is a lower level subroutine that is not normally used.
Example:
CALL TIERRA_VAR_REG_LOCK_SERVER()
Usage:
CALL TIERRA_VAR_REG_BLOCK_SERVER()
Description:
Blocks execution of the TierraLab server (HOTomography) until the TierraLab Client releases it. This is a lower level routine that is not normally used.
Example:
CALL TIERRA_VAR_REG_BLOCK_SERVER()
Usage:
CALL TIERRA_VAR_REG_DUMP()
Description:
Prints the contents of the TierraLab variable directory. Used for debugging code.
Example:
CALL TIERRA_VAR_REG_DUMP()
Usage:
err = Tierra('attach')
Description:
Attaches the TierraLab Client to the running HOTomography code. This should be the second TierraLab command executed on the Client.
Returns err of 0 on success, -1 on error.
Example:
err = Tierra('attach')
Usage:
err = Tierra('beginprobe')
Description:
Starts a probe operation on the HOTomography code. This call will not return until the HOTomography code reaches a probe point.
Returns err of 0 on success, -1 on error.
Example:
err = Tierra('beginprobe')
Usage:
err = Tierra('endprobe')
Description:
Ends a set of probe operations and releases the HOTomography code to continue executing.
Returns err of 0 on success, -1 on error.
Example:
err = Tierra('endprobe')
Usage:
err = Tierra('detach')
Description:
Detaches the TierraLab Client from the HOTomography code. Once this command is executed, no more TierraLab Client calls can be made.
Returns err of 0 on success, -1 on error.
Example:
err = Tierra('detach')
Usage:
Tierra('dumpcmds')
Description:
prints a list of TierraLab Client commands.
Example:
Tierra('dumpcmds')
Usage:
err = Tierra('dumplblreg')
Description:
Prints data from the TierraLab label registry.
Returns err of 0 on success, -1 on error.
Example:
err = Tierra('dumplblreg')
Usage:
err = Tierra('dumpvarreg')
Description:
Prints data from the TierraLab variable registry.
Returns err of 0 on success, -1 on error.
Example:
err = Tierra('dumpvarreg')
Usage:
[err,labels] = Tierra('getlbls')
Description:
Returns the labels from the label directory.
Returns err of 0 on success, -1 on error.
Example:
[err,labels] = Tierra('getlbls')
Usage:
[err,vars] = Tierra('getopenvars')
Description:
Returns the open variables, that is, those variables ready to be probed.
Returns err of 0 on success, -1 on error.
Example:
[err,vars] = Tierra('getopenvars')
Usage:
[err,dims] = Tierra('getvardims',var_name)
where var_name is the name of a registered variable.
Description:
Returns the dimensions of a registered variable.
Returns err of 0 on success, -1 on error.
Example:
[err,dims] = Tierra('getvardims','time_matrix')
Usage:
[rank] = Tierra('getvarrank',var_name)
where var_name is the name of a registered variable.
Description:
Gets the rank of a registered variable.
Returns -1 on error.
Example:
[rank] = Tierra('getvarrank','time_matrix')
Usage:
[err,vars] = Tierra('getvars')
Description:
Returns names of all registered variables.
Returns err of 0 on success, -1 on error.
Example:
[err,vars] = Tierra('getvars')
Usage:
[size] = Tierra('getvarsize',var_name)
Description:
Returns the size, or number of elements, of a variable.
Returns -1 on error.
Example:
[size] = Tierra('getvarsize','time_matrix')
Usage:
Tierra('init')
Description:
Initializes the TierraLab Client. This must be executed before any other TierraLab Client commands.
Example:
Tierra('init')
Usage:
[rslt] = Tierra('islblon',lbl_name)
where:
lbl_name is a label name.
Description:
Tells whether or not the label associated with a probe is on.
Returns 1 if label is on, 0 if label is off, -1 on error.
Example:
rslt = Tierra('islblon','time_lbl')
Usage:
rslt = Tierra('isprobeready')
Description:
Tells whether HOTomography is waiting at a probe.
Returns 1 if probe is ready, 0 if probe is not ready, -1 on error.
Example:
rslt = Tierra('isprobeready')
Usage:
rslt = Tierra('isvarglobalon')
Description:
Tells if TierraLab is on in HOTomography.
Returns 1 if it is on, 0 if it is off, -1 on error.
Example:
rslt = Tierra('isvarglobalon')
Usage:
rslt = Tierra('isvaron',var_name)
Description:
Tells if a registered variable is on, that is, will it be made available when it is in a HOTomography probe call.
Returns 1 if it is on, 0 if it is off, -1 on error.
Example:
rslt = Tierra('isvaron','time_matrix')
Usage:
rslt = Tierra('isvaropen',var_name)
Description:
Tells if a registered variable is open, that is, is it available to be probed.
Returns 1 if it is open, 0 if it is not, -1 on error.
Example:
rslt = Tierra('isvaropen','time_matrix')
Usage:
[err,var] = Tierra('probe',var_name)
where var_name is the name of the variable name.
Description:
Returns a copy of a variable from the HOTomography code.
Returns err of 0 on success, -1 on error.
Example:
[err,time_matrix] = Tierra('probe','time_matrix')
TierraLab uses shared memory to move data from the HOTomography context to the TierraLab Client context. Registries are used for tracking variables and labels. The below diagram illustrates the architecture.