PURPOSE:
=========

The purpose of this package is the computation of 
the Marcum-Q function Q_(mu)(x,y) and its complementary,
the function P_(mu)(x,y). 


RANGE OF COMPUTATION
====================

 The codes compute the functions Q_(mu)(x,y), P_(mu)(x,y) in the
range

0<=x<=10000,  0<=y<=10000,  1<=mu<=10000


THIS PACKAGE CONTAINS THE FOLLOWING FILES: 
==========================================
 
1.  cons.f90        Includes the module Someconstants for internal 
                    global parameters

2.  constants       Data file for the module Someconstants 

                    
3.  incgam.f90      Includes the module IncgamFI, with the public routine
                    incgam for the computation of the incomplete
                    gamma function ratios. 

4.  marcumq.f90     Includes the module MarcumQ with the public routine
                    marcum for the computation of the Marcum-Q function
                    and its complementary function.

5.  testmarq.f90    Test program for the module MarcumQ


6.  outputQP        Expected results file 

7.  Makefile        "Make" file, including compiler/linker commands. 

Here is an example set of compiler/linker commands for building
the programs using the GNU Fortran compiler g95. 
Options: -c compile to object code -- don't make executable
 
g95 -c cons.f90  
g95 -c incgam.f90 
g95 -c marcumq.f90
g95 -c testmarq.f90 
g95 cons.o incgam.o marcumq.o testmarq.o -o testmarq

where testmarq is the name of the executable file.
Basically the first files are compiled as object code libraries, and
then a program using marcum (testmarq) is compiled and linked to those libraries.
The set of the previous compiler/linker commands are include in the Makefile. When
using a different Fortran compiler (other than g95), just edit the Makefile
and replace g95 by the corresponding Fortran compiler.  

When the file testmarq.exe is executed, the file testPQ (containing the
outputs of the test program) is created. It is then convenient
to compare testPQ and outputQP  


DESCRIPTION OF THE MODULE MarcumQ
===================================

The public routine of the module MarcumQ is marcum, which
computes the Marcum-Q function Q_(mu)(x,y) and its
complementary function P_(mu)(x,y).

The relation with the Marcum functions computed by
Matlab or Mathematica (QM_(mu)(x,y),PM_(mu)(x,y)) 
is the following:

Q_(mu)(x,y)=QM_(mu)(sqrt(2*x),sqrt(2*y))
  
and similarly for the P function.

CALLING SEQUENCE
 ----------------

 The calling sequence for the routine marcum is the following

 SUBROUTINE marcum(mu,x,y,p,q,ierr)
 REAL(r8), INTENT(IN) :: mu
 REAL(r8), INTENT(IN) :: x
 REAL(r8), INTENT(IN) :: y
 REAL(r8), INTENT(OUT) :: p
 REAL(r8), INTENT(OUT) :: q   
 INTEGER,  INTENT(OUT) :: ierr
 where r8 represents the available double precision 
 arithmetics.

  Inputs and outputs
  ------------------

   Inputs:
    
      mu, x, y  arguments of the functions
    
    Outputs:
       p,     function P_(mu)(x,y)
       q,     function Q_(mu)(x,y)  
       ierr , error flag
              ierr=0, computation succesful
              ierr=1, underflow problems. The computed function value 
              is set to zero; the complementary function value is
              set to one.
              ierr=2, any of the arguments of the function is 
              out of range. The function values (P_mu(a,x) 
              and Q_mu(a,x)) are set to zero.
   Other routines included in the module MarcumQ which are used by 
   the routine marcum are:

   1. qser:    computes Q_(mu)(x,y) using a series expansion in terms of 
               the incomplete gamma function ratios. The incomplete gamma 
               function ratios are computed using the routine incgam, which 
               is included in the module IncgamFI. P is computed as the
               complementary function.
   2. pser:    computes P_(mu)(x,y) using a series expansion in terms of 
               the incomplete gamma function ratios. The incomplete gamma 
               function ratios are computed using the routine incgam, which 
               is included in the module IncgamFI. Q is computed as the
               complementary function.
   3. pqasyxy: computes P and Q using an asymptotic expansion 
               for xy large.
   4. pqasymu: computes P and Q using an asymptotic expansion 
               for mu large.
   5. qrec:    computes Q using a three term recurrence relation with
               coefficients in terms of ratios of Bessel functions.
               P is computed as the complementary function.
   6. prec:    computes P using a three term recurrence relation with
               coefficients in terms of ratios of Bessel functions.
               Q is computed as the complementary function.
   7. MarcumPQtrap: computes P and Q using an integral representation
                    approximated using the trapezoidal rule.
   

ACCURACY OF THE COMPUTED FUNCTION VALUES
=======================================

 The minimum aimed relative accuracy for the functions 
 is close to 1.0e-11 in the whole range of parameters. Better accuracies
 can be obtained in smaller parameter regions.