www.delorie.com/gnu/docs/mcsim/mcsim_12.html

search

	Buy GNU books!

MCSim User' Manual

4. Working Through an Example

Pharmacokinetics models describe the transport and transformation of chemical compounds in the body. These models often include nonlinear first-order differential equations. The following example is taken from our own work on the kinetics of tetrachloroethylene (a solvent) in the human body (Bois et al., 1996; Bois et al., 1990) (see section Bibliographic References). Go to the `sim' directory (under Unix) or to the `Development' folder (on a Macintosh). Open the file `perc.model' with any text editor (e.g., emacs or vi under Unix). This file is distributed as an example of a model definition file (see section B.3 `perc.model': A sample model description file). You can use it as a template for your own model, but you should leave it unchanged for now. Notice that it defines:

• state variables for the model (for which differentials are defined), for example:

  States = {Q_fat, # Quantity of PERC in the fat Q_wp, # ... in the well-perfused compartment Q_pp, # ... in the poorly-perfused compartment Q_liv, # ... in the liver Q_exh, # ... exhaled Qmet} # Quantity of metabolite formed

• output variables (obtainable at any time as analytical functions of the states, inputs and parameters), for example:

  Outputs = {C_liv, # mg/l in the liver C_alv, # ... in the alveolar air C_exh, # ... in the exhaled air C_ven, # ... in the venous blood Pct_metabolized, # % of the dose metabolized C_exh_ug} # ug/l in the exhaled air

• input variables (independent of the others variables, and eventually varying with time), for example:

  Inputs = {C_inh} # Concentration inhaled

• model parameters (independent of time), such as:

  LeanBodyWt = 55; # lean body weight

• system's dynamics (differential or algebraic equations defining the model per se),

• parameters' scaling (the parameters used in the equations can be made functions of other parameters: for example volumes can be computed from masses and densities),

• equations to compute the output variables.

This model definition file as a simple syntax, easy to master. It needs to be turned into a C program file before compilation and linking to the other routines (integration, file management etc.) of MCSim. You will use mod for that. First, quit the editor and return to the operating system.

To start mod under Unix just type mod perc.model. On a Macintosh, double click the `Mod' icon; Mod prompts you for the name of your model definition file; Type `perc.model'. After a few seconds, with no error messages if the model definition is syntactically correct, Mod announces that the `model.c' file has been generated. On a Macintosh you need to hit the return key to exit Mod.

The next step is to compile and link together the various C files that will constitute the simulation program for your particular model. Note that each time you want to change an equation in your model you will have to change the model definition file and repeat the steps above. However, changing just parameter values or state initial values does not require recompilation since that can be done through simulation specification files.

• Under Unix, the simplest is to use the make utility. Just type make and compilation will be done automatically (see section A. Using make). An executable `mcsim' is created. You can rename it to better describe the fact that it is model specific: rename it `mcsim_perc', for example.

• On a Macintosh, or PC, the best is to use a Think C project or a similar programming environment. You should first use the command make or its equivalent to compile the modified `model.c' file and other C files. Then create an application (you should give it a name specific to the model you are developing, e.g., `MCSim Perc'). Refer to your compiler manual for details on how to use your programming environment. Your executable `MCSim Perc' program is now ready to perform simulations.

To start your MCSim program just type mcsim_perc (if you gave it that name) under Unix, or double click the `MCSim Perc' Ð or whatever name you specified Ð icon on your Macintosh. After an introductory banner (telling in particular which model file the program has been compiled with), you are prompted for an input file name: type perc.lsodes.in (see section B.4 `perc.lsodes.in', to see this file now). The program then prompts you for the output file name: type perc.lsodes.out. After a few seconds or less (depending on your machine) the program announces that it has finished and that the output file is `perc.lsodes.out' (on a Macintosh you should hit the return key to exit the program completely). You can open the output file with any text editor or word processor, you can edit it for input in graphic programs etc.

Several other models and simulation specification files are provided with the package as examples (they are in the `sim' directory. Try them and observe the output you obtain. You can then start programming you own models and doing simulations. The next sections of this manual reference the syntax for model definition and simulation specifications.