
	Description and usage of pbd

pbd is an ODE solution package, written in C, and based on the PBD
method of van Bokhoven (IEEE Trans. on Circuits and Systems, v CAS-22,
no 2, Feb. 1975, pp109-115). pbd provides a callable function, pbd(),
which is intended to be called from user supplied code as part of a
larger simulation or computation. It consists of fairly simple code,
and is released under the GNU General Public License. pbd was written
by Ed Richley. Any and all comments are welcome, and can be directed
to richley@mailaps.org.

This archive should contain the following files:

README -- this documentation file
makefile -- a "make" file which compiles pbd and an example calling program
pbd.h -- a header file required to be included in a calling program
basics.h -- another header file required to be included in a calling program
pbd.c -- source code for the integration routine, and other routines it needs
pbd_test.c -- source code for an example test program implementing a simple set
              of ODEs: dx/dt = -y, dy/dt = x

		
Integration of N equations, for time TT is performed
by calling:
		
	pbd(N, x, TT, f, Output_Flag)
			
where x is a pointer to the dependent variable vector, and f is a
pointer to a (user-supplied) function containing the equation
information. f must be defined as:
		
	double *f(double *x)
			
where each element of the resultant vector evaluates:
		
		g(x, dx/dt, t)
		
and the equations are satisfied when g = 0. 
	
Inside f, dx[i]/dt must be represented by (beta*x[i] + xdot[i]), 
or by using the equivalent macro: dx_dt(i), which expands to the
same thing. "pbd.h", must be included in the calling program in
order to access these quantities.

Time within the integration is available as the variable "pbd_Time".
		
A quantity called N_eq is available, and is made equal to N by pbd. 

pbd is a variable step and order algorithm. Maximum order has been set
to 6, but can be modified. pbd is a predictor/ corrector method with
implicit corrector, so that stiff systems can be treated. pbd depends
on procedures "newton" and, hence, "gauss", contained herein.

Output_Flag is a boolean which, when set == true will output to stdout
the latest vector of results after EACH time step. Format is suitable
for plotting with "gnuplot": t x0 x1 x2 ...xN. Output is sent to 
stdout, unless "pbd_outfile" is set to some valid file pointer, in
which case it goes there.

External variables are (available through extern declarations in "pbd.h"):
		
	max_order	maximum order (6)
	N_eq		number of equations
	xdot		fixed part of the derivative estimate 
			(see eqn (16))...NOT the total derivative.
	beta		\g{beta}_k of eqn (21). Sum of 1/h for
			current order.
	pbd_tol		Overall tolerance; set to .0001 as default.
			Quantity "A" of eqn (30).
	pbd_Time	Time within step TT (0 < pbd_Time < TT)
	min_step        optional minimum time step to get through
	                singularities, etc. 
	pbd_N_tries     number of tries to take in nonlinear iteration
	pbd_outfile	File pointer for output. defaults to stdout.
			Only needed if Output_Flag set to "true".

pbd  is intended  to  be  coupled into  simlations  which require  ODE
solutions for at  least part of their algorithm.  For example, pbd can
be coupled into a flow solution to perform reaction/diffusion kinetics
computations.  As with  all routines  in the  (to be  released) MD_FCT
package, it  is assumed  that smaller time  steps are easier  to solve
(more linear),  so that  re-tries on failures  can be attempted  a few
times. For  this and all computational routines,  memory allocation is
performed dynamically, with no new allocation taking place when called
with the same size of problem as the previous call.

If a variable becomes zero, or has an initial value of zero, its
magnitude can not be determined for convergence purposes, and so is
assumed to have unit magnitude (as with newton()).

Known problems:

pbd relies on a Newton-Raphson algorithm which uses a computed
Jacobian matrix, and so is susceptible to roundoff errors when
the equations are poorly conditioned. Smaller time intervals
should lead to more linear (and, hence, well-conditioned) equations,
and the appearance of this problem can be expected to be rare, but
poor initial conditions or extreme cases may pop up now and then. 

To use the example "pbd_test":

1) Unpack the archive (which you probably already have done in order to
be reading this file):

$ tar zxvf pbd.tar.gz

2) Look at the makefile, and at "basics.h" to see if there are any obvious
incompatibilities with your system. The package was developed on several
Linux systems and so will likely have no problems for most *nix users.

3) type:

$ make pbd_test

4) Hopefully there are no compilation/linking errors (it's pretty simple code),
but of there are, please notify me (richley@mailaps.org).

5) run pbd_test:

$ ./pbd_test

6) Answer the prompts with a time interval and initial values:

delta t: 1
initial x:0
initial y:1

7) see the result:

x: -8.41470e-01 y: 5.40300e-01

8) Check to be sure. The answer should be x = -sin(delta t), y = cos(delta t)
Check to see that a file called "sin.dat" has been created with all
the intermediate data.

You can then use the file "pbd_test.c" as a template for other types
of integrations. Be careful to represent derivatives as
(beta*x[i]+xdot[i]) for each variable x[i]. Alternately, you can
use the macro "dx_dt(i)". Remember that N equations
are needed, and that they can be of any form involving the x[i], and
the (beta*x[i]+xdot[i]).  So, for example, if your equations require
(dx1/dt)^2 + (dx2/dt), this can be expressed as:

(beta*x[1]+xdot[1])*(beta*x[1]+xdot[1]) + (beta*x[2]+xdot[2])

or as:

(dx_dt(1))*(dx_dt(1)) + (dx_dt(2)])

Be sure to remember that conventional C array indexing is followed.
So, a vector of N variables is represented by x[0], x[1], ... x[N-1].

Also, be sure that calling programs, as well as files where the equations
are defined, include "basics.h" and "pbd.h":

#include "basics.h"
#include "pbd.h"

Created 2005 by Edward A. Richley (richley@mailaps.org)

This file, as with all files in the pbd package, is subject to the
terms and conditions of the GNU General Public License.
