XSIM (Version 3.x) Installation Guide

1. Availability on various UNIX platforms

The XSIM full distribution includes packages for four popular UNIX platforms: SunOS-4 and Solaris (SunOS-5) for sparc, IRIX for SGI, and Linux for Intel-PC (glibc version).

2. License (free for non-commercial use)

3. What you get in the XSIM distribution package

The XSIM distribution package contains the files for:

Standard installation:

  • XSIM and TEXSIM (a command driven version of XSIM) programs,
  • Fourteen XSIM model programs (demo, sinout, simbts, btex20, btex40, micmen, comp2ode, enzmem, compos, hodhux, mmid4, msid4, gentex and body),
  • four XSIM utility programs (mktac, checktac, quickcf, and tdiff),
  • object libraries for creating new XSIM models,
  • XSIM documentation and on-line help files, and
  • miscellaneous auxiliary files.

Optional installation:

  • development libraries for mass transport and exchange models.

4. What you need to install XSIM

Hardware/software requirements

XSIM requires one of the following hardware:

  • a Sun SPARC/ULTRA station running SunOS 4.1.4 or later
  • a Sun SPARC/ULTRA station running Solaris 2.5 or later
  • a SGI station running IRIX 6.2 or later
  • an Intel-PC running Linux (glibc version) e.g. Redhat-Linux release 5 or later uses glibc.

Space requirements

  • 30 MB of free disk space is required space to install XSIM on the disk containing the XSIM installation directory.

Software requirements

Version 11, Release 5 of the X Window System (commonly referred to as X11R5) is required.

There are a number of system libraries that are required by XSIM. Contact your system manager if XSIM complains about missing libraries.

5. Automatic Installation (for CD distribution only)

A shell script is provided for automatic installation. It may not work on all systems.

Assume you have mounted the XSIM CD and the CD mount point is /mnt/cdrom by doing something like "mount -t iso9660 /dev/cdrom /mnt/cdrom", then do the following to try the installation script:

cd /mnt/cdrom

sh install.sh INSTALLATION-DIRECTORY

Note: replace INSTALLATION-DIRECTORY with a directory name where you want XSIM to be installed, e.g., /usr/local/xsim.

6. Manual Installation

Select an XSIM installation directory

Select a directory into which the XSIM programs, libraries, and documentation will be placed. We recommend creating the directory /usr/local/xsim. (You will probably need to be logged in as root to do this.) Make sure this directory is readable by all users. This directory will be referred to as the INSTALLATION-DIRECTORY in this document.

Installing XSIM

Assume you have mounted the XSIM CD and the CD mount point is /mnt/cdrom by doing something like "mount -t iso9660 /dev/cdrom /mnt/cdrom", then do the following to do the manual installation:

cd INSTALLATION-DIRECTORY

zcat /mnt/cdrom/xsim3.10-PLATFORM.tar.Z | tar xvf -

Replace PLATFORM with one of the following:

  • SUNOS for SunOS 4.1.x
  • SOLARIS for Solaris 2.x
  • IRIX for IRIX 6.2
  • LINUX for Intel Linux with glibc

If you have downloaded XSIM packages from NSR web site, replace "/mnt/cdrom" with the directory where you store the downloaded files.

Installing XSIM license file

After you download the license file, xsim.license, from NSR, you MUST copy it to the directory, INSTALLATION-DIRECTORY/local.

Install the XSIM application defaults file

The application defaults directory contains files that specify default resources for X11 applications. The default location for this directory is /usr/lib/X11/app-defaults. If an alternate location is used, the XAPPLRESDIR environment variable in the user's environment should be set to the name of the directory in which the application defaults are found.

Log in as root, and issue the following commands:

cd INSTALLATION-DIRECTORY

cp dist/aux/XSim $XAPPLRESDIR/XSim

To be compatible with the common desktop environment (CDE) available on some systems, the application defaults file does not contain defaults for foreground and background colors. If you do not have or use CDE and want to provide a high contrast background, modify the application defaults file and add the line:

XSim.background: background-color

where background-color is the name of the desired color. (At the Simulation Resource, we use LightSkyBlue1.)

Make the windex database

The windex database contains one-line summaries of manual pages and is used by the whatis and apropos programs. To create the database, as xsim, issue the following command on SUNOS/SOLARIS:

/bin/catman -w -M INSTALLATION-DIRECTORY/dist/man

or for LINUX

/usr/sbin/makewhatis INSTALLATION-DIRECTORY/dist/man

or for IRIX

/usr/lib/makewhatis -M INSTALLATION-DIRECTORY/dist/man

Print the XSIM documentation package (Optional)

A PostScript version of the XSIM documentation package is provided. If you wish to print a hardcopy of the package, issue the following commands:

cd INSTALLATION-DIRECTORY/dist/doc

lpr XSIM.ps

The documentation package is set up for double-sided duplication.

Other documentation packages are available in INSTALLATION-DIRECTORY/dist/doc and INSTALLATION-DIRECTORY/local/doc.

7. Setting up an XSIM user environment

The values of the following environment variables are often set. See your local system documentation on the syntax required:

  • PATH should include INSTALLATION-DIRECTORY/dist/PLATFORM/bin. On Solaris 2.7 boxes, PATH should also include INSTALLATION-DIRECTORY/dist/SOLARIS/bin7, placed before the previous directory.
  • MANPATH should include INSTALLATION-DIRECTORY/dist/man.
  • PRINTER should be set to the name of the queue for a printer near the user.
  • LD_LIBRARY_PATH should include local X11 and Motif libraries as well as INSTALLATION-DIRECTORY/dist/PLATFORM/lib. (Note: Motif libraries for Linux are built into the XSIM executable, and not required here.)
  • XSIMHOME, if set, must be set to INSTALLATION-DIRECTORY. Setting XSIMHOME is not required if XSIM is installed in the default location (/usr/local/xsim).
  • XAPPLRESDIR as mentioned in section 5.2.
  • XSIMCPP may set to the complete name of the cpp program if, for some reason, the system-specific default built into XSIM does not exist on your system. Normally, this setting is not required.

If you have a system file that is "sourced" by the .login files of individual users, initial values for the environment variables should be set in the system file. You will probable have to log in as root to make such modifications. If you do not have such a file or if some users do not source the system file, XSIM users will have to set the environment values in their own .login files.

NOTE: There are a number of other environment variables that may be used to fine tune XSIM, however only the variables listed above are necessary for basic XSIM functioning.

A note of caution: When reports are printed, the file sent to the printer is ASCII text. In contrast, printing a plot produces a PostScript program file which may be many hundreds of lines long. Thus, when a PostScript program is sent to a non-PostScript printer, the program itself is printed. If you do not have PostScript printers, you may want to ensure that XSIMPRINTFILE is set and let users send those files they want printed to the printer.

The final XSIM-specific environment variable, XSIMPRINTFILE, has no default value. If PRINTER is set, XSIMPRINTFILE should not normally be set. Otherwise, XSIMPRINTFILE should be set to some name that you choose as the default name for XSIM printed output, such as XSIMout.txt.

8. Verifying the XSIM installation

Check for library compatibility

Log in as a normal (unprivileged) user and issue the following commands:

cd

xsim demo

As a further check, press the run button when the model is loaded. In the window titled "Main," the widgets for sine, cosine, tangent, and time should update at the run progresses from time = 0 to time = 30, and only a message indicating successful completion of the model run should be printed in the diagnostic area of the XSIM main window.

At the completion of the model run, select the Quit option from the Model menu, click the No button in the dialogue pop-up, and proceed to section 8.2.

Diagnosing XSIM problems

If XSIM does not exhibit correct behavior above, you should run the following command and note errors in the output:

texsim -v demo

  • the output from "texsim -v demo"
  • your INSTALLATION-DIRECTORY
  • a long recursive directory list of INSTALLATION-DIRECTORY, usually "ls -lR"
  • a copy of your user environment, usually "env" with no parameters

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.