ALGORITHM 569

COLSYS: Collocation Software for

Boundary-Value ODEs [D2]
U. ASCHER
University of British Columbia, Canada
and
J. CHRISTIANSEN and R. D. RUSSELL
Simon Fraser University, British Columbia, Canada
Key Words and Phrases ordinary differential equations, boundary-value problems, collocation, Bsplme, mesh selechon, error estimates, damped Newton's method, general-purpose code
CR Categories 5 17
Language. FORTRAN

DESCRIPTION

This package is a complement to [1] where its usage is described and demonstrated.
COLSYS uses the following non-American National Standard FORTRAN
conventions:
(1) No run-time subscript range checking.
(2) Simple expressions used as subscripts.
(3) Specifications of array values in DATA statements (used in subroutine
CONSTS) by referring to the array name only.

REFERENCES
1. ASCHER, U., CHRISTIANBEN, J., AND RUSSELL, R D. Collocation software for boundary value
ODEs. A C M Trans. Math. Soflw. 7, 2 (June 1981), 209-222

ALGORITHM

[A part of the listing is printed here. The complete listing is available from the
ACM Algorithms Distribution Service (see page 257 for order form).]
Received 21 February 1979, 3 April 1979, and 26 October 1979.
Permission to copy without fee all or part of this materml is granted provided t h a t the copies are not
made or distributed for direct commercial advantage, the ACM copyright notice and the title of the
pubhcation and its date appear, and notme is given t h a t copying ]s by permission of the Assocmtmn
for Computing Machinery. To copy otherwise, or to repubhsh, requires a fee and/or specific
permission.
Authors' addresses: U. Ascher, Computer Science Department, University of British Columbia,
Vancouver, B.C. V6T 1W5, Canada; J. Christiansen and R.D. Russell, Mathematics Department,
Simon Fraser University, Burnaby, B.C. V5A 1S6, Canada.
1981 ACM 0098-3500/81/0600-0223 $00.75
ACM Transactions on Mathematmal Software, Vol 7, No. 2, June 1981, Pages 223-229

224

Algorithms

SUBROUTINE

C O L S Y S (NCOMP, M, A L E F T , A R I G H T ,
ZETA, IPAR,
TOL, F I X P N T ,
ISPACE, FSPACE,
IFLAg,
FSUB,
DFSUB, gSUB, DgSUB, SOLUTN)

1
2

LTOL,

C
C

C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C

PURPOSE
SUBROUTINE COLSYS SOLVES A MULTI-POINT
BOUNDARY V A L U E
PROBLEM FOR A M I X E D ORDER SYSTEM OF O D E - S g I V E N BY
(M(I))
U

X~

Z(U(X))

ALEF~

1,

,NCOMP

ZETA(d),

Z(U(ZETA(d)))

)=

d =

.LT.

ARIgH],

X .LT

1,

,MSTAR

d
MSTAR=M(1)+M(2)+.

WHERE

.+M(NCOMP),

T
U =

(U

U ,
2

,U

IS

THE M I = M ( I )

IS

THE E X A C T

SOLUTION

VECTOR

NCOMP

(HI)
U

TH

DERIVATIVE

OF U

I
(I)

Z(U(X))

(U

(X),U

1
F

(X,Z(U))

IS

(M1-1)
,U
(X),
1

(X),

1
A

(gENERALLY)

NONLINEAR

(MNCOMP--~)
,U
(X))
NCOMP

FUNCTION

OF

I
Z(U)=Z(U(X))

(ZETA(d),Z(U))

IS

(gENERALLY)

NONLINEAR

BOUNDARY

CONDITION
THE BOUNDARY P O I N T S S A T I S F Y
ALEFT
LE
ZETA(l)
.LE
THE ORDERS M I
M1 . L E

.LE

ZETA(MSTAR) . L E

OF THE D I F F E R E N T I A L
EQUATIONS
M2
LE .....
LE
MNCOMP . L E .

*********~**~*

INPUT TO C O L S Y S

ARIGHT

SATISFY
4.

***************

VARIABLES

C
C
C
C
C
C

NCOMP M(J)

ALEFT

NO.

OF D I F F E R E N T I A L

EQUATIONS

(NCOMP

.LE.

ORDER OF THE J - T H D I F F E R E N T I A L
EQUATION ( M(J)
AND MSTAR = M ( 1 ) +
+ M(NCOMP) .LE.
40 )
-

LEFT

END OF

INTERVAL

ACM T r a ~ a c t l o ~ o n M a ~ e m a u c ~ S o ~ w ~ e , Vol7, No, 2, J u n e l ~ l .

20)

LE.M(J+I)

Algorithms
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C

ARIGHT ZETA(d)

SIDE CONDITION POINT (BOUNDARY POINT).

d-TH

ZETAKd)

.LE.

MUST

ZETA(d+1)

AN INTEGER ARRAY DIMENSIONED AT LEAST 11

A LIST OF THE PARAMETERS IN IPAR AND THEIR MEANINg FOLLOWS
SOME PARAMETERS ARE RENAMED I N COLSYS, THESE NEW NAMES ARE
g I V E N I N PARENTHESES.

IPAR(1)

(
=
=

IPAR(2)

225

RIGHT END OF INTERVAL

HAVE
IPAR -

0
1

NONLIN

I F THE PROBLEM IS LINEAR

I F THE PROBLEM IS NONLINEAR

(= K )
= NO OF COLLOCATION POINTS PER SUBINTERVAL
WHERE M(NCOMP) LT.
K LE. 7 . I F I P A R ( 2 ) = O THEN
COLSYS SETS K = MAX ( MKNCOMP)+I, 5-M(NCOMP) )

I P A R ( 3 ) = NO. OF SUBINTERVALS IN THE I N I T I A L MESH ( = N ) ,

I F I P A R ( 3 ) = 0 THEN COLSYS ARBITRARILY SETS N = 5.
IPAR(4)

= NO
OF S O L U T I O N AND D E R I V A T I V E TOLERANCES.
WE R E G U I R E
0 .LT.
NTOL . L E .
MSTAR.

I P A R ( 5 ) = DIMENSION OF FSPACE

( = NDIMF

I P A R ( b ) = DIMENSION OF ISPACE

( = NDIMI

IPAR(7) =
=
=

( = NTOL

OUTPUT CONTROL ( = I P R I N T )
- 1 FOR FULL DIAGNOSTIC PRINTOUT
0 FOR SELECTED PRINTOUT
1 FOR NO PRINTOUT

IPAR(8)

( = IREAD )
= 0 CAUSES COLSYS TO gENERATE A UNIFORM I N I T I A L MESH.
= 1 I F THE I N I T I A L MESH I S PROVIDED BY THE USER
IT
IS DEFINED IN FSPACE AS FOLLOWS
THE MESH
ALEFT=X(1) L T . X < 2 ) L T . .
LT.X(N).LT.X(N+I)=ARIgHT
WILL OCCUPY FSPACE(1),
..,
FSPACE(N+I). THE
USER NEEDS TO SUPPLY ONLY THE INTERIOR MESH
POINTS
FSPACE(d)
= X(d),
d = 2, ...,
N.
= 2 I F THE I N I T I A L
MESH I S S U P P L I E D BY THE USER
AS WITH I P A R ( 8 ) = I , AND IN ADDITION NO ADAPTIVE
MESH SELECTION I S TO BE DONE.

IPAR(?)

( = IgUESS )
= 0 I F NO I N I T I A L gUESS FOR THE SOLUTION I S
PROVIDED.
= 1 I F AN I N I T I A L g U E S S I S P R O V I D E D BY THE USER
IN SUBROUTINE
SOLUTN.
= 2 I F AN I N I T I A L MESH AND APPROXIMATE SOLUTION
COEFFICIENTS ARE PROVIDED BY THE USER IN
FSPACE.
(THE FORMER AND NEW MESH ARE THE SAME).
= 3 I F A FORMER MESH AND AN APPROXIMATE SOLUTION
COEFFICIENTS ARE PROVIDED BY THE USER IN FSPACEo
AND THE NEW MESH I S TO BE TAKEN TWICE AS COARSE.
= 4 I F IN ADDITION TO A FORMER I N I T I A L MESH AND AN
APPROXIMATE SOLUTION COEFFICIENTS, A NEW MESH
I S PROVIDED IN FSPACE AS WELL
( S E E D E S C R I P T I O N OF OUTPUT FOR FURTHER D E T A I L S
ON I Q U E S S = 2 , 3 , AND 4. )

ACM

Transactlons on Mathematical Software, Vol. 7,N o 2, June 1981

226

Algorithms

C
C
IPAR(IO)=
0 I F THE PROBLEM I S REOULAR
C
= 1 I F THE F I R S T RELAX FACTOR I S = R S T A R T , AND THE
C
N O N L I N E A R I T E R A T I O N DOES NOT R E L Y ON P A S T COVERQENCE
c
( U S E FOR AN E X T R A S E N S I T I V E
N O N L I N E A R PROBLEM O N L Y ) .
C
= 2 I F WE ARE TO RETURN I M M E D I A T E L Y UPON
( A ) TWO
c
S U C C E S S I V E NONCONVERGENCES, OR
( B ) AFTER O B T A I N I N G
C
ERROR E S T I M A T E FOR THE F I R S T T I M E .
c
C
IPAR(11)=
NO. OF F I X E D P O I N T S I N THE MESH OTHER THAN
c
A L E F T AND A R I G H T .
( = N F X P N T , THE D I M E N S I O N OF F I X P N T )
c
C
LTOL
AN ARRAY OF D I M E N S I O N
IPAR(4).
LTOL(d)
= L
SPECIFIES
C
THAT THE J - T H T O L E R A N C E I N
TOL
CONTROLS THE ERROR
c
I N THE L - T H COMPONENT OF Z ( U )
ALSO R E G U I R E THAT
C
1. LE L T O L ( 1 ) . L T .
LTOL(2).LT .....
LT. L T O L ( N T O L ) . L E . MSTAR
C
AN ARRAY OF D I M E N S I O N I P A R ( 4 ) .
TOL(d)
I S THE
C
TOL
C
ERROR T O L E R A N C E ON THE L T O L ( J )
- T H COMPONENT
c
OF Z ( U ) .
THUS, THE CODE A T T E M P T S TO S A T I S F Y
C
FOR d = l . . . . , N T O L
ON EACH S U B I N T E R V A L
c
ABS(Z(V)-Z(U))
.LE
TOL(J)*Z(U)
+TOL(J)
c
LTOL(d)
LTOL(J)
C
IF V(X)
I S THE A P P R O X I M A T E S O L U T I O N VECTOR.
C
C
FIXPNT
AN ARRAY OF D I M E N S I O N I P A R ( 1 1 )
IT CONTAINS
C
THE P O I N T S ,
OTHER THAN A L E F T AND A R I G H T ,
WHICH
c
ARE TO BE I N C L U D E D I N EVERY MESH
C
C
I S P A C E - AN INTEGER WORK ARRAY OF DIMENSION I P A R ( 6 ) .
C
I T S S I Z E PROVIDES A CONSTRAINT ON NMAX,
C
THE MAXIMUM NUMBER OF SUBINTERVALS. CHOOSE
c
I P A R ( 6 ) ACCORDINg TO THE FORMULA
c
IPAR(6)
GE.
NMAX*NSIZEI
c
WHERE
C
N S I Z E I = 3 + KDM - NREC
C
WITH
c
KDM = KD + MSTAR ~
KD = K * NCOMP
c
NREC = NO. OF RIGHT END BOUNDARY CONDITIONS.
C
C
c
F S P A C E - A REAL WORK ARRAY OF D I M E N S I O N I P A R ( 5 ) .
c
I T S S I Z E P R O V I D E S A C O N S T R A I N T ON NMAX
c
CHOOSE I P A R ( 5 )
A C C O R D I N G TO THE FORMULA
c
IPAR(5)
.GE
NMAX*NSIZEF
C
WHERE
C
N S I Z E F = 4 + K + 2 * KD + ( 4 + 2 - K ) * MSTAR +
C
(KDM-NREC) * ( K D M + I )
c
c
c
I F L A G - THE MODE OF RETURN FROM COLSYS.
c
= I FOR NORMAL R E T U R N
c
= 0 I F THE C O L L O C A T I O N M A T R I X I S S I N G U L A R .
c
= - 1 I F THE E X P E C T E D NO. OF S U B I N T E R V A L S EXCEEDS STORAGE
C
SPECIFICATIONS.
c
=-2
I F THE N O N L I N E A R I T E R A T I O N HAS NOT CONVERGED
c
=-3
I F THERE I S AN I N P U T DATA ERROR
c
C
C*****~**************~-**~*********~**************.i~*~I.*****4b*************~
C
C
**********
USER S U P P L I E D E X T E R N A L S U B R O U T I N E S
*****~*
-

A C M T r a n s a c U o n s on M a t h e m a t i c a l Software, Vol 7, N o 2, J u n e 1981

Algorithms
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c
c

FSUB

NAME OF S U B R O U T I N E FOR E V A L U A T I N g F ( X , Z ( U ( X ) ) )
=
T
(F ,...,F
)
AT A P O I N T X I N ( A L E F T , A R I Q H T ) .
1
NCOMP
SHOULD HAVE THE HEADINg
SUBROUTINE

FSUB

(X

Z ,

227

IT

F)

WHERE F I S THE VECTOR C O N T A I N I N g

THE V A L U E OF F I ( X , Z ( U ) )
I N THE I - T H COMPONENT AND
T
Z(U(X))=(Z(1)
.... ,Z(MSTAR))
I S D E F I N E D AS ABOVE UNDER
PURPOSE .

DFSUB

NAME OF S U B R O U T I N E FOR E V A L U A T I N g THE J A C O B I A N OF

F(X,Z(U))
AT A P O I N T X.
I T SHOULD HAVE THE H E A D I N g
SUBROUTINE

DFSUB

(X

Z ,

DF)

WHERE Z ( U ( X ) )
I S D E F I N E D AS FOR FSUB AND THE ( N C O M P ) BY
( M S T A R ) ARRAY DF SHOULD BE F I L L E D BY THE P A R T I A L D E R I V A T I V E S OF F, V I Z ,
FOR A P A R T I C U L A R C A L L ONE C A L C U L A T E S
D F ( I , J ) = DFI / DZO, I = 1 . . . . . NCOMP
d=l ....
MSTAR.
gSUB

NAME OF SUBROUTINE FOR EVALUATINg THE I - T H COMPONENT OF

g(X,Z(U(X)))
= g (ZETA(I),Z(U(ZETA(I))))
AT A P O I N T X =
I
ZETA(I)
WHERE 1. LE I . LE. MSTAR.
I T SHOULD HAVE THE H E A D I N g
SUBROUTINE gSUB ( I
WHERE Z ( U )

IS

AS FOR FSUB,

Z ,

AND I

g)

AND g = g

NOTE THAT I N CONTRAST TO F I N

FSUB
ONLY ONE V A L U E PER C A L L I S RETURNED

DQSUB -

ARE AS ABOVE.

I
, HERE
I N g.

NAME OF S U B R O U T I N E FOR E V A L U A T I N g THE I - T H ROW OF

THE J A C O B I A N OF ( X , U ( X ) )
I T SHOULD H A V E THE H E A D I N g
SUBROUTINE

DQSUB

(I

Z ,

DQ)

WHERE Z ( U )
I S AS FOR FSUB, I AS FOR gSUB AND THE M S T A R VECTOR Dg SHOULD BE FILLED WITH THE PARTIAL DERIVATIVES
OF g, V I Z , FOR A PARTICULAR CALL ONE CALCULATES
Dg(I,J)
= DgI / DZJ
d = l , ..tMSTAR

SOLUTN- NAME OF SUBROUTINE TO EVALUATE THE I N I T I A L

APPROXIMATION FOR Z ( U ( X ) ) AND FOR DMVAL(U(X))= VECTOR
OF THE MJ-TH DERIVATIVES OF U ( X ) . I T SHOULD HAVE THE
HEADINg
SUBROUTINE

SOLUTN

(X

Z ,

DMVAL)

NOTE THAT THIS SUBROUTINE I S NEEDED ONLY I F USINg

I P A R ( 9 ) = 1, AND THEN ALL MSTAR COMPONENTSOF Z
AND NCOMP COMPONENTSOF DMVAL SHOULD BE SPECIFIED
FOR ANY X,
ALEFT .LE. X LE. ARIGHT .

ACM Transactions on Mathematical Software, Vol 7, No 2, June 1981

228

C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C

Algorithms

***************

APPSLN

OUTPUT FROM COLSYS

COLSYS ,
UPON RETURN FROM
S O L U T I O N VECTOR
Z(U(X)
)
BY C A L L I N g
:
CALL

(X,

Z,

***************

THE USER MAY PRODUCE THE

AT A P O I N T X, A L E F T . L E . X . LE. A R I g H T

FSPACE,

ISPACE)

T H I S S E T S UP A STANDARD C A L L TO
APPROX.
FOR A MORE
EFFICIENT
OR S O P H I S T I C A T E D
R E T R I E V A L OF THE S O L U T I O N
VALUES~ C A L L
APPROX
DIRECTLY
(SEE DOCUMENTATION IN
APPROX - THE P A R A M E T E R S NEEDED I N THE C A L L TO
APPROX
BY THE USER ARE SAVED I N
ISPACE
AND
FSPACE
BEFORE
COLSYS
RETURNS).

I N ORDER TO SAVE THE C O E F F I C I E N T S OF THE S O L U T I O N FOR LATER

REFERENCE,
ISPACE(1) .....
ISPACE(7+MSTAR)
AND
FSPACE(1) .....
FSPACE(ISPACE(7))
SHOULD BE
SAVED, S I N C E THESE ARE USED I N THE C A L L TO
APPSLN (APPROX).
ONE CAN ALSO USE THE FORMERLY O B T A I N E D A P P R O X I M A T E
S O L U T I O N AS A F I R S T A P P R O X I M A T I O N FOR THE N O N L I N E A R
ON A NEW PROBLEM ( E . g .
FOR C O N T I N U A T I O N P U R P O S E S ) .
I N V O L V E S U S I N g I g U E S S = 2 , 3 , OR 4 , AS FOLLOWS:

ITERATION
THIS

FOR I g U E S S = 2 OR 3 , THE USER SHOULD PUT THE ABOVE SAVED

V A L U E S BACK I N T O F S P A C E ( 1 ) , . . . ~ F S P A C E ( I S P A C E ( 6 ) ) .
THE S I Z E OF THE FORMER MESH, NOLO, I S P R O V I D E D I N I P A R ( 3 ) .
IF
I g U E S S = 2 THEN THE S I Z E OF THE NEW MESH, N, I S TAKEN TO BE =NOLD.
I F I g U E S S = 3 THEN N : = N O L D / ~ AND THE NEW MESH I S TO BE T W I C E AS
COARSE.
FOR I g U E S S = 4 ,
PUT N IN IPAR(3)
AND NOLO I N I S P A C E ( 1 ) .
THE
V A L U E S OF THE FORMER S O L U T I O N ,
SAVED AS D E S C R I B E D ABOVE,
SHOULD BE P U T I N T O F S P A C E ( N + 2 ) . . . . .
FSPACE(ISPACE(6)+N+I),
AND
A NEW MESH U N R E L A T E D TO THE FORMER ONE I S P R E S C R I B E D I N
FSPACE(1),...,FSPACE(N+I).

*********~****~

PACKAGE
SUBROUTINES

**************~

THE FOLLOWINg DESCRIPTION gIVES A BRIEF OVERVIEW OF HOW THE

C
PROCEDURE I S BROKEN DOWN I N T O THE S U B R O U T I N E S W H I C H MAKE UP
C
THE PACKAGE C A L L E D
C O L S Y S . FOR FURTHER D E T A I L S THE
C
USER SHOULD REFER TO D O C U M E N T A T I O N I N THE V A R I O U S S U B R O U T I N E S
C
AND TO THE R E F E R E N C E S C I T E D ABOVE.
C
C
THE S U B R O U T I N E S F A L L I N T O FOUR gROUPS:
C
C P A R T 1 - THE M A I N STORAGE A L L O C A T I O N AND PROGRAM CONTROL S U B R O U T I N E S .
C
C
C O L S Y S - T E S T S I N P U T V A L U E S , DOES I N I T I A L I Z A T I O N
AND BREAKS UP
C
THE WORK AREAS, F S P A C E AND I S P A C E ~ I N T O THE A R R A Y S
C
USED BY THE PROGRAM.
C
C
CONTRL - I S THE A C T U A L D R I V E R OF THE PACKAGE. T H I S R O U T I N E
C
C O N T A I N S THE STRATEGY FOR N O N L I N E A R PROBLEMS.
C
C
C P A R T 2 - MESH S E L E C T I O N AND ERROR E S T I M A T I O N
SUBROUTINES
ACM T r a n s a ~ m ~ o n M a ~ e m a t l c ~ S o f t w ~ e , V ~ 7, No 2, June1981.

Algorithms

PART

C
C
C
C
C
C
C
C
C
C

PART

229

CONSTS -

I S C A L L E D ONCE BY
COLSYS
TO I N I T I A L I Z E
CONSTANTS
WHICH ARE USED FOR ERROR E S T I M A T I O N AND MESH S E L E C T I O N

NEWMSH

gENERATES MESHES. IT CONTAINS THE TEST TO DECIDE

WHETHER OR NOT TO R E D I S T R I B U T E A MESH.

ERRCHK

PRODUCES ERROR E S T I M A T E S AND CHECKS A G A I N S T

TOLERANCES AT EACH S U B I N T E R V A L

C O L L O C A T I O N SYSTEM S E T - U P

THE

SUBROUTINES

LSYSLV

CONTROLS THE S E T - U P AND S O L U T I O N OF THE L I N E A R

A L G E B R A I C SYSTEMS OF C O L L O C A T I O N EQUATIONS WHICH
A R I S E AT EACH NEWTON I T E R A T I O N .

BLDBLK

I S USED BY L S Y S L V TO SET UP THE E G U A T I O N ( S ) A S S O C I A T E D

WITH A SIDE CONDITION POINT OR A COLLOCATION POINT.

B-SPLINE

SUBROUTINES

APPSLN -

SETS UP A STANDARD C A L L TO

APPROX -

EVALUATES

BSPFIX -

EVALUATES THE MESH INDEPENDENT B-SPLINES

(I.E.
THE F I X E D B - S P L I N E S )

BSPVAR -

EVALUATES THE MESH DEPENDENT B - S P L I N E S

VARYINg B-SPLINES)

BSPDER -

gENERATES VALUES FOR THE D E R I V A T I V E S

UP THE C O L L O C A T I O N EQUATIONS.

APPDIF

gENERATES A D I V I D E D D I F F E R E N C E TABLE FROM THE B - S P L I N E

C O E F F I C I E N T S FOR A C O L L O C A T I O N S O L U T I O N . THE TABLE
I S USED I N
APPROX

HORDER -

EVALUATES THE H I G H E S T ORDER D E R I V A T I V E S OF THE

CURRENT C O L L O C A T I O N S O L U T I O N USED FOR MESH REFINEMENT.

A PIECEWISE

APPROX

P O L Y N O M I A L SOLUTION.

(I.E.

ThE

NEEDED TO SET

TO SOLVE THE L I N E A R SYSTEMS OF C O L L O C A T I O N EQUATIONS

CONSTRUCTED I N PART 3,
COLSYS
USES THE PACKAGE
SOLVEBLOK
OF DE BOOR - WEISS (TO APPEAR I N TOMS).

ACM

Transactlons on Mathematical Software, Vol 7, No. 2, June 1981.