
----------------------------------------------------------------------
Commands.txt: user-defined model commands at version 6
----------------------------------------------------------------------

The syntax is defined by Bardsley and Prasad (Computers Chem. 21, 71-82,
1997) and in the Simfit reference manual and the Simfit readme files.
Program usermod can test codes and check models for errors, and there
are example test model files that can be run to illustrate the various
techniques.

1) Commands described in w_readme.f5 (The basic commands)
=========================================================

Command        Stack effect
-------        ------------
x              stack -> stack, x
y              stack -> stack, y
z              stack -> stack, z
add            stack, a, b -> stack, (a + b)
subtract       stack, a, b -> stack, (a - b)
multiply       stack, a, b -> stack, (a*b)
divide         stack, a, b -> stack, (a/b)
p(i)           stack -> stack, p(i)         ...  i can be 1, 2, 3, etc
f(i)           stack, a -> stack  ...evaluate model since now f(i) = a
power          stack, a, b -> stack, (a^b)
squareroot     stack, a -> stack, sqrt(a)
exponential    stack, a -> stack, exp(a)
tentothepower  stack, a -> stack, 10^a
ln (or log)    stack, a -> stack, ln(a)
log10          stack, a -> stack, log(a) (to base ten)
pi             stack -> stack, 3.1415927
sine           stack, a -> stack, sin(a)       ... radians not degrees
cosine         stack, a -> stack, cos(a)       ... radians not degrees
tangent        stack, a -> stack, tan(a)       ... radians not degrees
arcsine        stack, a -> stack, arcsin(a)    ... radians not degrees
arccosine      stack, a -> stack, arccos(a)    ... radians not degrees
arctangent     stack, a -> stack, arctan(a)    ... radians not degrees
sinh           stack, a -> stack, sinh(a)
cosh           stack, a -> stack, cosh(a)
tanh           stack, a -> stack, tanh(a)
exchange       stack, a, b -> stack, b, a
duplicate      stack, a -> stack, a, a
pop            stack, a, b -> stack, a
absolutevalue  stack, a -> stack, abs(a)
negative       stack, a -> stack , -a
minimum        stack, a, b -> stack, min(a,b)
maximum        stack, a, b -> stack, max(a,b)
gammafunction  stack, a -> stack, gamma(a)
lgamma         stack, a -> stack, ln(gamma(a))
normalcdf      stack, a -> stack, phi(a)  integral from -infinity to a
erfc           stack, a -> stack, erfc(a)
y(i)           stack    -> stack, y(i)                Only diff. eqns.
j(i)           stack, a -> stack  J(i-(i/n), (i/n)+1) Only diff. eqns.
***            stack -> stack, ***          ...  *** can be any number

2) Commands described in w_readme.f6 (global storage and sub-models)
====================================================================

Command           Effect
-------           ------
begin{model(i)}   Start of definition of sub-model i
end{model(i)}     End of definition of sub-model i
put(i)            Cut top stack element into storage location i
get(i)            Copy storage location i to top of stack
get3(i,j,k)       Get one of (i,j,k) following use of command order
epsabs            Re-define absolute error tolerance
epsrel            Re-define relative error tolerance
blim(i)           Re-define bottom limit i
tlim(i)           Re-define top limit i
putpar            Copy parameters into global storage for sub-models
value(i)          Evaluate model i
quad(i)           Integrate model i
convolute(i,j)    Convolute models i and j
root(i)           Estimate a root of model i
value3(i,j,k)     Evaluate one of (i,j,k) following use of command order
order             -1,0,1 depending on values (use before get3 and value3)
middle            Reflect a value back between limits if necessary

3) Commands described in w_readme.f7 (Special functions)
========================================================

Command       NAG    Description
-------       ----   -----------
arctanh(x)    S11AAF Inverse hyperbolic tangent
arcsinh(x)    S11AAF Inverse hyperbolic sine
arccosh(x)    S11AAF Inverse hyperbolic cosine
ai(x)         S17AGF Airy function Ai(x)
dai(x)        S17AJF Derivative of Ai(x)
bi(x)         S17AHF Airy function Bi(x)
dbi(x)        S17AKF Derivative of Bi(x)
besj0(x)      S17AEF Bessel function J0
besj1(x)      S17AFF Bessel function J1
besy0(x)      S17ACF Bessel function Y0
besy1(x)      S17ADF Bessel function Y1
besi0(x)      S18ADF Bessel function I0
besi1(x)      S18AFF Bessel function I1
besk0(x)      S18ACF Bessel function K0
besk1(x)      S18ADF Bessel function K1
phi(x)        S15ABF Normal cdf
phic(x)       S15ACF Normal cdf complement
erf(x)        S15AEF Error function
erfc(x)       S15ADF Error function complement
dawson(x)     S15AFF Dawson integral
ci(x)         S13ACF Cosine integral Ci(x)
si(x)         S13ADF Sine integral Si(x)
e1(x)         S13AAF Exponential integral E1(x)
ei(x)         ...... Exponential integral Ei(x)
rc(x,y)       S21BAF Elliptic integral RC
rf(x,y,z)     S21BBF Elliptic integral RF
rd(x,y,z)     S21BCF Elliptic integral RD
rj(x,y,z,r)   S21BDF Elliptic integral RJ
sn(x,m)       S21CAF Jacobi elliptic function SN
cn(x,m)       S21CAF Jacobi elliptic function CN
dn(x,m)       S21CAF Jacobi elliptic function DN
ln(1+x)       S01BAF ln(1 + x) for x near zero
mchoosen(m,n) ...... Binomial coefficient
gamma(x)      S13AAF Gamma function
lngamma(x)    S14ABF log Gamma function
psi(x)        S14ADF Digamma function, (d/dx)log(Gamma(x))
dpsi(x)       S14ADF Trigamma function, (d^2/dx^2)log(Gamma(x))
igamma(x,a)   S14BAF Incomplete Gamma function
igammac(x,a)  S14BAF Complement of Incomplete Gamma function
fresnelc(x)   S20ADF Fresnel C function
fresnels(x)   S20ACF Fresnel S function
bei(x)        S19ABF Kelvin bei function
ber(x)        S19AAF Kelvin ber function
kei(x)        S19ADF Kelvin kei function
ker(x)        S19ACF Kelvin ker function
cdft(x,m)     G01EBF cdf for t distribution
cdfc(x,m)     G01ECF cdf for chi-square distribution
cdff(x,m,n)   G01EDF cdf for F distribution (m = num, n = denom)
cdfb(x,a,b)   G01EEF cdf for beta distribution
cdfg(x,a,b)   G01EFF cdf for gamma distribution
invn(x)       G01FAF inverse normal
invt(x,m)     G01FBF inverse t
invc(x,m)     G01FCF inverse chi-square
invb(x,a,b)   G01FEF inverse beta
invg(x,a,b)   G01FFF inverse gamma
spence(x)     ...... Spence integral: 0 to x of -(1/y)log|(1-y)|
clausen(x)    ...... Clausen integral: 0 to x of -log(2*sin(t/2))
struveh(x,m)  ...... Struve H function order m (m = 0, 1)
struvel(x,m)  ...... Struve L function order m (m = 0, 1)
kummerm(x,a,b)...... Confluent hypergeometric function M(a,b,x)
kummeru(x,a,b)...... U(a,b,x), b = 1 + n, the logarithmic solution
lpol(x,m,n)   ...... Legendre polynomial of the 1st kind, P_n^m(x),
                     -1 =< x =< 1, 0 =< m =< n
abram(x,m)    ...... Abramovitz function order m (m = 0, 1, 2), x > 0,
                     integral: 0 to infinity of t^m exp( - t^2 - x/t)
debye(x,m)    ...... Debye function of order m (m = 1, 2, 3, 4)
                     (m/x^m)[integral: 0 to x of t^m/(exp(t) - 1)]
fermi(x,a)    ...... Fermi-Dirac integral (1/Gamma(1 + a))[integral:
                     0 to infinity t^a/(1 + exp(t - x))]
heaviside(x,a)...... Heaviside unit impulse function h(x - a)
delta(m,n)    ...... Kronecker delta impulse function
impulse(x,a,b)...... Unit impulse function (small b for Dirac delta)
spike(x,a,b)  ...... Unit triangular impulse function
gauss(x,a,b)  ...... Unit Gauss pdf impulse function
sqwave(x,a)   ...... Square wave, amplitude 1, period 2a
rtwave(x,a)   ...... Rectified triangle, amplitude 1, period 2a
mdwave(x,a)   ...... Morse dot wave, amplitude 1, period 2a
stwave(x,a)   ...... Sawtooth wave, amplitude 1, period a
rswave(x,a)   ...... Rectified sine wave, amplitude 1, period pi/a
shwave(x,a)   ...... Sine half-wave, amplitude 1, period 2*pi/2
uiwave(x,a,b) ...... Unit impulse, area 1, period a, width b


4) Commands described in w_readme.f8 (Operations with vectors)
==============================================================

Command         Effect
-------         ------
store(j)        Initialise global store(j)
storef(file)    Initialise global store(1) to global store(n) from a file
poly(x,m,n)     Evaluate a polynomial
cheby(x,m,n)    Evaluate a Chebyshev expansion
l1norm(m,n)     Evaluate a L_1 norm
l2norm(m,n)     Evaluate a L_2 norm
linorm(m,m)     Evaluate a L_infinity norm
sum(m,n)        Evaluate the sum of vector components
ssq(m,n)        Evaluate the sum of squares of vector components
dotprod(l,m,n)  Evaluate the scalar product of two vectors

Commands to use mathematical constants
======================================

 Command   Value                     Comment
 -------   -----                     -------
      pi   3.141592653589793e+00     pi
   piby2   1.570796326794897e+00     pi divided by two
   piby3   1.047197551196598e+00     pi divided by three
   piby4   7.853981633974483e-01     pi divided by four
   twopi   6.283185307179586e+00     pi multiplied by two
 root2pi   2.506628274631000e+00     square root of two pi
 deg2rad   1.745329251994330e-02     degrees to radians
 rad2deg   5.729577951308232e+01     radians to degrees
   root2   1.414213562373095e+00     square root of two
   root3   1.732050807568877e+00     square root of three
  eulerg   5.772156649015329e-01     Euler's gamma
lneulerg  -5.495393129816448e-01     log (Euler's gamma)

5) Commands described in w_readme.f9 (integers and arbitrary functions)
=======================================================================

Note: x, y, z, m and n are the stack values but j is a literal constant,
while logicals 1 = true and 0 = false are stored as floating point numbers,
to be converted into integers using nint(.) internally when required.

Command        Effect
-------        ------
int(x)         x replaced by the integer part of x
nint(x)        x replaced by the nearest integer to x
sign(x)        x replaced by -1 if x < 0, by 0 if x = 0 or by 1 if x > 0
lt0(x)         x replaced by 1 if x < 0, otherwise by 0
le0(x)         x replaced by 1 if x =< 0, otherwise by 0
eq0(x)         x replaced by 1 if x = 0, otherwise by 0
ge0(x)         x replaced by 1 if x >= 0, otherwise by 0
gt0(x)         x replaced by 1 if x > 0, otherwise by 0
not(m)         m replaced by not(m), error if m not 0 or 1
and(m,n)       m and n replaced by and(m,n), error if m and n not 0 or 1
or(m,n)        m and n replaced by or(m,n), error if m and n not 0 or 1
xor(m,n)       m and n replaced by xor(m,n), error if m and n not 0 or 1
if(j)          execute the next line iff storage(j) = 1.0
ifnot(j)       execute the next line iff storage(j) = 0.0
user1(x,m)     model m evaluated at x
user2(x,y,m)   model m evaluated at x, y
user3(x,y,z,m) model m evaluated at x, y, z

6) Commands described in w_readme.f10 (using expressions)
=========================================================

Standard mathematical expressions can be used if started with the
token begin{expression} and ended with the token end{expression}.

For instance, f(1) can be defined as a 2:2 rational function like this

begin{expression}
f(1) = [p(1)x + p(2)x^2]/[1.0 + p(3)x + p(4)x^2] 
end{expression}


or equally

begin{expression}
p(1)x + p(2)x^2
end{expression}
begin{expression}
1.0 + p(3)x + p(4)x^2
end{expression}
divide
f(1)

where numerator and denominator added to the stack then the numerator is
divided by the denominator in order to define f(1).


