;; simhelp.txt -- Help file for PKSim (pharmaco-kinetic simulation program)
;;
;; Date:    27 July 1992
;; Author:  Don Robert Maszle
;;
;;  Copyright (c) 1993.  Don Maszle, Frederic Bois.  All rights reserved.
;;
;;  -- Revisions -----
;;    Logfile:  %F%
;;   Revision:  %I%
;;       Date:  %G%
;;    Modtime:  %U%
;;     Author:  @a
;;  -- SCCS  ---------
;;
;; Topics are demarcated by a keyword in brackets at the beginning of
;; a line.  Lines up to the first topic are ignored as comment lines

[Mod]
  Model Creation
  --------------
  The "model" used for simulation is defined by a set of state
  variables, inputs, outputs and parameters.  Each state has an
  associated differential equation that defines how its progression in
  time relates to its current state and the remaining variables of the
  model. 

  PKSim uses a preprocessor program called `mod' to convert a description of
  the model into C program code which can then be linked to the program.

  To run the model preprocessor enter at the command line

	mod model-description-file

  where the model-description-file contains declarations of model
  variables and state equations, an optional scaling function that is
  called before each simulation, and an optional output scaling
  function that is called before saving output values.

  More in the works....

[CmdLineArgs Usage]
  Usage:

  pksim [options] [input-file [output-file]]
-or-
  pksim [options] [input-file [pass-file fail-file behavior-file summary-file]]

  Options:

  -h topic		Print help on topic
  -O OutputOption	One of the following options:
	MCOutputs	--Include Print() observations in MonteCarlo output
	MCResult	--Include result of MC analysis
	ParmList	--Include parameters in MC output

	VarNames	--Include variable names in output  [NOT USED]

	NoXxxx		--Negate one of the above options

[Inputs]
  Input Functions
  ---------------
  Not documented.

See Also:  Spikes, Doses, PerExp, PerDose
[PerExp]
  PerExp() Input Function
  -----------------------
  Not documented.

See Also:  Inputs
[Doses]
  Doses Input Function
  --------------------
  The syntax for specifying a series of different constant doses is
  
    input-var = NDoses ( nDoses, <list-of-n Mags>,
                                 <list-of-n Starting Times>,
                                 <list-of-n Exposure Times> );

  Example:
    C_inh = NDoses (2, .08 .05    0 300    240 240);

    defines an inhalation dose of magnitude 0.08 from 0 to 240 and of
    magnitude 0.05 from 300 to 540.

  NOTE:  The model generator has not yet been modified to save the
         structure for this input.  An NDoses input that is used for
         all experiments can be specified in the global section of the
         simulation file, as these modifications are made before each
         experiment. 

See Also:  Inputs
[Spikes]
  Spikes Input Function
  ---------------------
  Spikes is an input function that can be used to schedule
  discontinuities.  It is analogous to Doses() with the syntax

    Spikes (nSpikes, <List-of-n Mags>, <List-of-n Times>);

  however there is no duration array because Spikes are infinitely
  short discontinuities.  They are so short in fact that they have no
  effect if they appear in differential equations, that is to say
  they are not integrated across (granted, an inconsistency). 

  Like Doses(), Spikes() are not implemented in the model generator
  file.

See Also:  Inputs
[PerDose]
  PerDose() Input Function
  ------------------------
  Not documented.

See Also:  Inputs

[Print]
  Printing Variables
  ------------------
  To specify times to print a variable, use the Print() command.

    Print (Var, <list-of-times>);

  Example:
    Print (Cb_bm,  360,   420,    1080.0, 2520.0, 2880.0);
    Print (Cb_fat, 520,   2520.0, 2880.0);

[States]
  State Variables
  ---------------
  Not documented.

[OutputVariables]
  Output Variables
  ----------------
  Not documented.

[Output Format]
  Output Format
  -------------
  The main output file can be specified the OutputFile command
    OutputFile (szQuotedFilename); 

  The main output file can also be specified on the command line with
  the -o option.

See Also:  CmdLineArgs
[Experiments]
  Experiment Specification
  ------------------------
  Not documented.

[Variations]
  Variations for Multiple Simulation
  ----------------------------------
  Not documented.

[SetPoints]
  Running from a file of Set Points
  ---------------------------------
  Include a single SetPoints() specification to specify forced
  parameter set points.  The syntax is

    SetPoints (szOutputfile, szSetPointsFile, szExtDataFile,
               nSimulations, <Parm-List...>);

  Example:

    SetPoints ("", "SetPoints.dat", "Monster.dat", 1
               V_fat,     V_bm,    Sc_Flow_tot,  etc...);

  If a null string ("") is given for the output file, output is written
  to "simmc.out".

  The set points input file should have one line of set points for
  each simulation run specified.

  If a null string is given for the external data file, no analysis
  will be performed.

  * NOTE:  To support the old forced points format, the first argument
           of each line is a dummy numeric field that is thrown away.

[MonteCarlo]
  Monte Carlo Simulation
  ----------------------
  Request a Monte Carlo simulation with one MontCarlo() specification

    MonteCarlo (szOutputfile, szExtDataFile, nSims, dSeed, Indep.runs [Yes/No])

  Example:

    MonteCarlo ("MCOutput.dat", "Sherwood.dat", 1, -56761.1164, Yes);

  If a null string ("") is given for the output file, output is written
  to "simmc.out".

  If a null string is given for the external data file, no analysis
  will be performed.

  The MonteCarlo() command should be followed by one Distrib() variation
  specification for each parameter being varied.  The syntax is

     Distrib (Parm, Sample-Type, dMin, dMax);

See Also:  Distrib
[Distrib Sample MCVary]

  Distrib () sample distribution specification.  (Formerly MCVary().)

  Syntax:

     Distrib (Parm, Sample-Type, [shape parms,] dMin, dMax);

  where the Sample-Type is one of the following:
	Uniform | LogUniform | Normal | LogNormal | Beta

  For normal distributions the shape parameters are mean and standard
  deviations.  For log normal distributions, the shape parameters are
  given in the log space, and the range parameters are given in the
  natural space.

  *  Note 'uniform' and 'loguniform' can be abbreviated to 'uni' and
     'loguni'.  Capitalized or lowercase is allowed.

  For Beta functions the shape parameters A and B define the shape
  of the density function in the interval [0, 1] as

   
	         /  x^(alpha-1) * (1-x)^(beta-1) * Gamma(alpha+beta)
	        |  ------------------------------------------------
   f_beta(x) =  <              Gamma(alpha) * Gamma(beta)
	        |
	         \   0, x < 0 or x > 1

  The interval [0, 1] is uniformly mapped into the range specified.

  Examples:

  A uniform distribution over .01 to .06.
 
    Distrib (V_bm,  LogUni, 0.01 0.06);      

  A normal distribution mean 70, sd 10, truncated to the range 40-90.

    Distrib (Weight, Normal, 70, 10, 40, 90);


  The log of the concentration of radon is a standard normal, and
  C_radon is in the range 0 to 5.

    Distrib (C_radon, LogNormal, 0, 1, 0, 5)


See Also:  MonteCarlo
[PerExp]

  PerExp() Input Function
  -----------------------
  Not documented.

See Also:  MonteCarlo

[GenSyntax Intro Help elp]
  General Syntax
  --------------
  The general syntax is similar to that of the model definition file (MDF).
 
  *  Comments begin with a pound sign ('#') and continue
     to the end of the line.
 
  *  Blank lines are skipped.
 
  *  All commands can span several lines and are terminated by ';'.
      
  *  The file consists of two sections:
     1) Global analysis declarations, and
     2) Experiment specifications,
        including model variables modifications
 
 ----------------------------------------------------------------------
 
  1)  GLOBAL ANALYSIS SPECIFICATONS
      -----------------------------
 
     The 'global' section can include default specifications for all
     experiments that follow in the input file.  These include
     integrator settings, simulation time, and specification of analysis.
     All specifications have default values so that no global specifications
     are required.  If no analysis is specified, normal simulations will
     be performed.
 
 
  2)  EXPERIMENTS
      -----------

     Each experiment sections describe a set of experimental conditions.
 
     These sections begin with the keyword "Experiment" and are
     enclosed in curly braces.  You can give specifications here
     that are specific to this experiment, and which differ from
     the global defaults.  You can also re-define model parameters
     with the same syntax that they were defined in the model
     definition file.
 
     Variable assignments have the syntax
 
 	<var-name> '=' <constant-value or expression> ';'
 
     where <var-name> is any declared model variable, with
     certain restrictions.
 
 	o  States, inputs, outputs, and parameters can be re-defined
 	   with constant numeric values (no expressions!).  In this
           way parameters can be varied from one experiment to another.
 
 	o  Values given to states and outputs are INITIAL values.
 
        o  Variable names are case sensitive.

See Also:  Commands
[Syntax  Commands]
  Command Syntax
  --------------
  The syntax for commands follows.  For general syntax help, see Intro.

    Integrate ([Gear], nOrder, dStep, dMinStep, dMaxStep, dError);

    Distrib (Parm, Sample-Type, [shape parms,] dMin, dMax); 

    MonteCarlo (szOutputfile, szExtDataFile, nSims, dSeed, Indep.runs[Yes/No]);

    SetPoints (szOutputfile, szSetPtsFile, szDataFile, nSims, <Parm-List...>);

    Experiment {
      Var = Constant;
      ...
      Print (Var, <list-of-times>);
    }

    where
      Var is any model variable/parameter,
      Parm is a parameter of the model,
      <Parm-List> is a comma separated list of parameters,
      szArg is a "" delimited string,
      nArg is an integer argument,
      dArg is a double argument,
      sample-type ::=  [Uniform | LogUniform | Beta | Normal | LogNormal].

   See the documentation for more details.

See Also:  CmdLineArgs, Intro
[NoHelp]
