Many Simulation Resource collaborators have been using the SIMCON simulation interface. This appendix describes the use of SIMCON models and parameter files by XSIM.

Some major differences between SIMCON and XSIM, summarized in the table below, should be borne in mind.

SIMCON:	XSIM:
Parameters are real numbers only	Parameters can be double precision, real, and integer, bytes, or strings
Parameter array is fixed length (2000)	Parameter arrays can be variable length
Reads reference data files in IDEAL or TAC format	Reads reference data file in TAC format only
Interface and model are single task	Interface and model are separate tasks
No model auxiliary files are required, but parameter names and groups file may be provided	A model configuration file is required; there are no other auxiliary files
SIMCON cannot place limits on parameters except those parameters being optimized	Model configuration files may place constrain minimum and/or maximum values of parameters
Only inputs and outputs explicitly calculated by the model are available	Mathematical combinations of parameters can be entered at run time and are available for plotting, optimizing, etc.
Appearance of the interface is fixed	Appearance of the interface is determined at run time by the model configuration file
Inner and outer loops each modify one parameter in arithmetic or geometric progression	Each loop can modify multiple parameters using a mathematical formula and/or a list of values
A single function generator is provided; additional generators must be provided in the model	As many function generators as required are available under the control of the model configuration file

While, as described above, XSIM provides for several types of model parameters in variable length arrays, in the current release (XSIM Version 2.0) only real parameters are transmitted to/fetched from an XSIM model. The length of the array of real parameters may be less than but cannot exceed 2000. These restrictions ore compatible with all existing SIMCON models.

The source code, and object files, for all existing SIMCON models is completely compatible with XSIM. The modules of a model must, of course, be linked with the XSIM model main program and library rather the equivalent SIMCON files.

A prototype makefile is provided for creating an XSIM model is provided. After setting up your environment for XSIM as discussed in section 2.1 of the Interface Reference Manual, you can create a prototype by issuing the commands:

cd model directory

cp $XSIMHOME/lib/Makefile_xsim.proto Makefile

chmod u+w Makefile

where model directory is the directory containing the source/object files for the model. Edit the prototype and change the definitions of PROG, OBJS, INCLUDES, and lFLAGS as appropriate for the model.

Some SIMCON models use include files and programmer utilities that are specific to SIMCON. These include files have been added to the XSIM includes and the programmer utilities to the XSIM library. Using the prototype makefile should insure that they are found.

After you make an new XSIM model program, you must write a configuration file for it before the model can be run under XSIM. Information about model configuration files is given in the Configuration File Reference Manual.

You can create a configuration file de novo using a text editor or by editing an already existing file. In the latter case, you should start with a configuration file for a model that is similar to your mode; otherwise, the changes will be extensive and often confusing. For SIMCON models, however, you can generate a configuration file using the sim2cf utility. This program creates a model configuration file based on an augmented parameter names file and, optionally, a SIMCON parameter file in database format. The resulting configuration file gives the model a SIMCON-like appearance in that the model parameters are placed in windows in groups of forty in a two column format similar to that used by the SIMCON parameter editor. See the sim2cf manual page for additional information.

It is recommended that configuration files created by sim2cf be edited to add additional information to the parameter declarations that is not available from the augmented parameter names or database files. Specifically, the clauses that specify units and parameter limits, where appropriate, should be added.

The parameter file format used by XSIM quite different than that used by SIMCON. XSIM will, however, read values from files in SIMCON database format. These files are found in your SIMCON database directory or are created when you use the ``s'' option after a simulation run. (Text files created when by setting parameters 197, 198, and 199 to write the file named simcon.par cannot be read by XSIM.)

When XSIM reads a SIMCON database file, it loads only the values of the model parameters declared in the model configuration file using the ``loc'' clause and the independent variable control parameters, p(128), p(129), and p(131). The values of all other control parameters are lost. Plots, optimization, loops, etc. must be set up using the normal XSIM procedures.

As discussed in section 1, only the values of real parameters are currently passed from XSIM to the model, but configuration files can use integer and choice parameters and pass their values to real parameters using an eval or fixeval clause in the declaration of the parameter that is passed to the model.

Consider, for instance, a model in which the user must choose between two mathematical functions, a lagged normal density curve and a random walk density curve, to model flow heterogeneity in an organ. A SIMCON model would use a real parameter for this choice, the user would have to remember what value represented each choice, and the model program would have to handle the situation in which the user entered an invalid value. Using an XSIM choice parameter makes things simpler for the user and the model. For example, let p(501) controls the choice of functions, where p(501) = 1 selects the lagged normal and p(501) = 2 selects the random walk. The configuration file could contain the following lines:

choice Model_h   {values = (``Lagged normal'', ``Random walk''),

                  init   =  ``Lagged normal''}

real   Select_h  {loc    = 501, fixeval = ``Model_h''}

When Model_h is displayed in an XSIM parameter group, the user can see the names of the choices available, and the value of p(501) passed to the model will be guaranteed to contain a valid value.

While using integer and choice parameters makes things easier in some respects, it introduces a problem when parameter values are loaded from a SIMCON database file in that the values of integer and choice parameters will not loaded. Thus, in the example above, the value Select_h will not be altered regardless of the value of p(501) in the database file.

To insure that all XSIM model parameters match those in a SIMCON database file, the values of XSIM choice and integer parameters must be set by the user. For configuration files included in the standard XSIM distribution, lists of integer and choice parameters are given in the tables below. The XSIM path shows how to find the parameter. The first item is the path is the group name in the Parameters menu, and the last item is the label used for the parameter in the group window. If there are more than two items in the path, the additional ones show names of items in cascading menus. For choice parameters, the initial value is also shown. The first item shows the name of the default choice and the second the resulting numerical value of the real parameter. Use SIMCON or the simnlist utility to examine the parameter values in the SIMCON database file that is being loaded.

Note that the problems introduced by integer and choice parameters do not exist for configuration files created with sim2cf because they will only contain declarations of real parameters.

A further complication introduced when parameter values are loaded from a SIMCON database file relates to generation of input functions. The btex20, btex40, and mmid4 models in the standard distribution use the XSIM function generator. Thus, when parameters are loaded from a SIMCON database file, the function generator parameters will not be affected. This applies to distributed configuration files and to those created by sim2cf for models that used the SIMCON function generator. In the latter case, the function generator parameters will be present in the configuration file, but will not be used by XSIM.

If you take existing SIMCON model code that generates its input functions(s) within the model, link it to the XSIM model code, and use a sim2cf-generated configuration file, input function generation will work as it did under SIMCON, and controlling parameters can be loaded from SIMCON database files.

While SIMCON will read reference data files in either IDEAL or TAC format, XSIM will only read files that are in TAC format. The ide2tac utility program, distributed with XSIM, will read an IDEAL file and write the data to a new file in TAC format. See the ide2tac manual page for details.

In addition to the considerations discussed above regarding the use of SIMCON parameter files, users of the distributed mmid4 model should read the XSIM release notes for special considerations about generating input functions and deconvolution.

Integer and Choice Parameters Used by Distributed Configuration Files

P-array location	XSIM path	Default value
BTEX20 model
p(37)	BTEX20 main window: Nseg	7
BTEX40 model
p(37)	BTEX40 main window: Nseg	60
MMID4 model
p(4)	MMID4 model layout: Path	20
p(5)	Vascular/microvascular operators: Tissue-capillary units: BTEX unit (vascular tracer): Nseg	7
p(59)	Input functions: Deconvolution: Reference curve index	1
p(59)	Input functions: Deconvolution: Reverence curve type	``Sample'' = 0
p(60)	Input functions: Deconvolution: Use deconvolution?	``No'' = 0
p(118)	Input functions: Deconvolution: Run number	1
p(241)	Model outputs: Contents: Contents switches: Use inlet tubing?	``No'' = 0
p(242)	Model outputs: Contents: Contents switches: Use artery?	``Yes'' = 1
p(243)	Model outputs: Contents: Contents switches: Use arterioles?	``Yes'' = 1
p(244)	Model outputs: Contents: Contents switches: Use tissue units?	``Yes'' = 1
p(245)	Model outputs: Contents: Contents switches: Use venules?	``Yes'' = 1
p(246)	Model outputs: Contents: Contents switches: Use veins?	``Yes'' = 1
p(247)	Model outputs: Contents: Contents switches: Use outlet tubing?	``No'' = 0
p(403)	Model outputs: Contents by region: Path selection	``All'' = 0
p(443)	Model outputs: Concentrations by region: Path selection	``All'' = 0
p(501)	Flow heterogeneity: Heterogeneity inputs: PDF model	``Lagged normal'' = 1
p(505)	Flow heterogeneity: Heterogeneity inputs: PDF clipping	``Standard'' = 0
p(508)	Flow heterogeneity: Heterogeneity inputs: Selection method	``Weighted'' = 2
p(509)	Flow heterogeneity: Heterogeneity inputs: PDF smoothing?	``No'' = 0
p(510)	Flow heterogeneity: Heterogeneity inputs: Copy to user PDF?	``No'' = 0
p(570)	Flow heterogeneity: Heterogeneity inputs: Number of values	1

Copyright 1995-1998, University of Washington

Last modified: 01:22pm PDT October 17, 1998