PMODEL:  Parallel Modeling in ISIS
			Draft  Documentation
			  Version: 12/12/08

Introduction
------------

Pmodel is an extension module for the Interactive Spectral Interpretation
System (ISIS), which aims to provide a general but easy to use means of
increasing the speed at which astrophysical models may be computed by
executing portions of them in parallel.  Pmodel can substantially enlarge
the scope of models which may be tractably computed, while requiring
little explicit knowledge of parallel programming on the part of
astronomers.

Parallelism benefits the user by decomposing large problems into smaller
subproblems which can be computed simultaneously.  The pmodel package
does this in two ways:

   (1)	Component decomposition:  where individual components of a
	multi-component model, such as

   		gauss(1) + (warmabs(2) * hotabs(3) * ismabs(4))

	are simultaneously evaluated, over the entire model grid, on
	multiple processors.  For example, the right hand portion this
	model can be computed in parallel by changing the expression to

		gauss(1) + pm_mult(1, warmabs(2), hotabs(3), ismabs(4))

	Here pm_mult() is used to ship 3 components of the original
	model expression to different CPUs, then collect the individual
	results and multiply them together (a "multiplicative reduction"
	operation).

	pmodel provides 3 functions which perform component decomposition:

		pm_add()  - an additive reduction operation
		pm_mult() - a multiplicative reduction operation
		pm_func() - a general, functional reduction operation

	The first two farm out N components, gather their results and
	then simply either add or multiply them together (subtraction
	and division may also be performed, by using the negation - and
	division operators in the respective components expressions.
	The third allows for more generality, in that any arbitrary
	function of the parallelized components may defined & then
	computed during results collection.

   (2)	Grid decomposition:  where the grid over which a model is
	evaluated is partitioned into subgrids, and the entire model
	is simultaneously evaluated over each subgrid, on multiple
	processors.  This is achieved in pmodel with the

			pm_subgrid(N)

	function, where N indicates the number of subdivisions in the
	grid partition.  At present only grids for models with bin
	independence may be subdivided, i.e. where the computation
	in the ith bin

			model(lo[i], hi[i], params)

	does not require knowledge of bins i-1 or i+1, etc.

Examples
--------

   The regression test suite in the ./tests provides examples for
   each of the additive, multiplicative, & functional reduction
   forms, as well for subgrid decomposition.  Assuming the PVM
   toolkit and PVM S-Lang module have been installed (and ISIS
   knows where to find the latter), the pmodel tests can be
   executed from the top-level pmodel directory as soon as the
   tarball is unpacked.  A typical sequence will look like

   	linux%  tar xvzf pmodel-0.3.0.tar.gz
   	linux%  cd pmodel-0.3.0
	linux%  make test

   and, if everything is configured properly, yield output resembling

	Inspect test.log for detailed test results

	Building host file & launching local pvm

	make[3]: Entering directory `/tmp/pmodel-0.1.7/tests'
	make[3]: Leaving directory `/tmp/pmodel-0.1.7/tests'

	make[3]: Entering directory `/tmp/pmodel-0.1.7/tests'
	Testing add1.sl ...
	Testing add2.sl ...
	Testing mult1.sl ...
	Testing mult2.sl ...
	Testing mult3.sl ...
	Testing func.sl ...
	Testing subgrid.sl ...
	Testing compose.sl ...

   Notice from these test scripts that pmodel allows model component
   terms in each parallel clauses to be essentially arbitrary arithmetic
   expressions.  For example,

   	pm_mult(1,  3.2 *tmod(1),
		9.9*tmod2(1)/7.0)*pm_mult(2, tmod( 2 ), tmod2(2)+3.3)");

   This model expression also shows that parallel clauses may be nested
   within one another.  More examples of this are given in the compose.sl
   script.


Caveats
-------

   Using Isis_Active_Dataset in a model expression defined during
   load_par() requires that at least some data are already loaded.