Writing XSim-style models for JSim in Fortran
Introduction
This document describes how to create the free-standing computational model code for an XSim-style model under JSim. It assumes you understand the Introduction to XSim-style models under JSim and are familiar with building Fortran programs on your system.
Contents
Writing & compiling Fortran model code
Wrapping your model code with jsxwrap
Writing appropriate Fortran code
Fortran model code, conforming the XSIM API for Fortran must be created. This main source file will have extension .f or .F. The compiled version will have extension .o. It is assumed you have installed a Fortran compiler on your system and know how to operate it. The API is given below:
- The file "scparf.h" in directory $JSIMHOME/$OS/include must be copied or included in your Fortran. This code defines the REAL P array as a common block.
- The code must have SUBROUTINE ENTRY points for simini, simlop and simend (these are not optional, as in XSim). simini is called once at the beginning of the program. simlop is called once for each independent variable (usually time) step. simend is called once at the end of the run.
- A block of 4 P array locations are reserved for the independent variable. Sequentially, these values represent the minimum, maximum, current and step increment. Traditionally, the current value is at location 130, however it may be anywhere so long as the "ivar" of the associated MML wrapper has the appropriate location.
- Warning messages from the model should call scwmsg(S), where S is a CHARACTER* variable containing the warning message. These messages will be displayed in the JSim GUI, but will not affect the run. Similarly, fatal errors should call scfmsg(S), which will cause JSim to terminate the model run.
Wrapping your model code with jsxwrap
The program jsxwrap wraps a Fortran object and associated libraries in a native library that can be utilized by JSim. The usage is:
jsxwrap -f modelName objects libraries
The "-f" switch indicates the objects implement the XSim Fortran API for JSim.
jsxwrap required you have installed a version of gcc compatible with the JSim distribution. gcc must be installed for jsxwrap to run, and the objects and libraries specified must be compatible with the JSim distribution (see caveats below). Upon successful completion, jsxwrap will print a message giving the name of the native library generated.
A simple example
Here is an example of a single source Fortran model (demo.F) that requires the C math library. The example assumes you're on Linux:
g77 -I $JSIMHOME/linux/include -c demo.o demo.F
jsxwrap -f demo demo.o -lm
The generated file will be libjsxdemo.so.
Some caveats
Here are some current problems we intent to fix shortly:
- jsxwrap is currently available only for Linux and MacIntosh distributions. A Windows version is under development. Users of the JSim source distribution may use jsxwrap.db.
- Warning and fatal messages are written to the console rather that into the JSim project window, and fatal messages are not fatal.
- Must get users more information on gcc compatibility.
[This page was last modified 03Mar08, 3:11 pm.]
Model development and archiving support at physiome.org provided by the following grants: 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.
