n_wishartd.rr
*************

This manual explains about n_wishartd.rr, a package for computing a system of differential equations satisfied by the matrix 1F1 on a diagonal region. To use this package one has to load n_wishartd.rr.

     [...] load("n_wishartd.rr");

A prefix n_wishartd. is necessary to call the functions in this package.

Restriction of matrix 1F1 on diagonal regions
=============================================

n_wishartd.diagpf
-----------------

n_wishartd.diagpf(M,BLOCKS)
     computes a system of PDEs satisfied by the M variate matrix 1F1 on a diagonal region specified by BLOCKS.

return
     A list [E1,E2,...] where each EI is a differential operator with partial fraction coefficients and it annihilates the restricted 1F1.

m
     A natural number

vars
     A list [[S1,E1],[S2,E2],...].

options
     See below.

  * This function computes a system of PDEs satisfied by the M variate matrix 1F1 on a diagonal region specified by BLOCKS.

  * Each component [S,E] in BLOCKS denotes YS=Y(S+1)=...=YE. The representative variable of this block is YE.

  * One has to specify BLOCKS so that all the variables appear in it. In particular a block which contains only one variable is specified by [S,S].

  * It has not yet been proven that this function always succeeds. At least it is known that this function succeeds if the size of each block <= 36.

  * See Differential operators with partial fraction coefficients for the format of the result.

     [2649] Z=n_wishartd.diagpf(5,[[1,3],[4,5]]);
     [
      [[[[-1,[]]],(1)*<<0,0,0,0,3,0>>],
       [[[-2,[[y1-y4,1]]],[-2,[[y4,1]]]],(1)*<<0,1,0,0,1,0>>],
       [[[9/2,[[y1-y4,1]]],[-3*c+11/2,[[y4,1]]],[3,[]]],(1)*<<0,0,0,0,2,0>>],
       ...
       [[[-6*a,[[y1-y4,1],[y4,1]]],[(4*c-10)*a,[[y4,2]]],[-4*a,[[y4,1]]]],
        (1)*<<0,0,0,0,0,0>>]],
      [[[[-1,[]]],(1)*<<0,4,0,0,0,0>>],

       [[[-6,[[y1-y4,1]]],[-6*c+10,[[y1,1]]],[6,[]]],(1)*<<0,3,0,0,0,0>>],
       [[[5,[[y1-y4,1]]],[-5,[[y1,1]]]],(1)*<<0,2,0,0,1,0>>],
       ...
       [[[21*a,[[y1-y4,2],[y1,1]]],[(36*c-87)*a,[[y1-y4,1],[y1,2]]],
        [-36*a,[[y1-y4,1],[y1,1]]],[(18*c^2-84*c+96)*a,[[y1,3]]],
        [-9*a^2+(-36*c+87)*a,[[y1,2]]],[18*a,[[y1,1]]]],(1)*<<0,0,0,0,0,0>>]]
     ]

n_wishartd.message
------------------

n_wishartd.message(ONOFF)
     starts/stops displaying messages during computation.

onoff
     Start displaying messages if ONOFF=1. Stop displaying messages if ONOFF=0.

  * This function starts/stops displaying messages during computation. The default value is set to 0.

Numerical comptation of restricted function
===========================================

n_wishartd.prob_by_hgm
----------------------

n_wishartd.prob_by_hgm(M,N,[P1,P2,...],[S1,S2,...],T[|OPTIONS])
     computes the value of the distribution function of the largest eigenvalue of a Wishart matrix.

return

m
     The number of variables.

n
     The degrees of freedom.

[p1,p2,...,pk]
     A list of the multiplicities of repeated eigenvalues.

[s1,s2,...,sk]
     A list of repeated eigenvalues.

  * Let L1 be the largest eigenvalue of a Wishart matrix. Let PR[L1<T] be the distribution function of L1. The function n_wishartd.prob_by_hgm computes the value of the distribution function by using HGM for a covariance matrix which has repeated eigenvalues SI with multiplicity PI (I=1,...,K).

  * This function repeats a Runge-Kutta method for the Pfaffian system by doubling the step size until the relative error between the current result and the previous result is less than EPS, The default value of EPS is 10^(-4).

  * If an option EQ is not set, a system of PDES satisfied by 1F1 on the diagonal region specified by [P1,P2,...] is computed. If an option EQ is set, the list specified by EQ is regarded as the correct system of PDEs.

  * If an option EPS is set, the value is used as EPS.

  * If an option TD is set, the truncated power series solution for computing the initial vector is computed up to the total degree specified by TD. The default value is 100.

  * If an option RK is set, it is regarded as the order of a Runge-Kutta method. The default vaule is 5.

  * It is recommended to use this function only when K<=2 where K is the number of diagonal blocks because of the difficulty of the truncated power series solution and the difficulty of computation of the Pfaffian matrices.

     [...] n_wishartd.message(1)$
     [...] P=n_wishartd.prob_by_hgm(10,100,[9,1],[1/100,1],100|eps=10^(-6));
     ...
     [x0=,8/25]
     Step=10000
     [0]
     [8.23700622458446e-17,8.23700622459772e-17]
     ...
     Step=1280000
     [0][100000][200000][300000]...[900000][1000000][1100000][1200000]
     [0.516246820120598,0.516246820227214]
     [log ratio=,4.84611265040128]

     Step=2560000
     [0][100000][200000][300000]...[2200000][2300000][2400000][2500000]
     [0.516246912003845,0.516246912217004]
     [log ratio=,4.93705929488356]
     [diag,18.6292,pfaffian,1.09207,ps,41.0026,rk,213.929]
     0.516246912217004
     266.4sec + gc : 8.277sec(276.8sec)

n_wishartd.prob_by_ps
---------------------

n_wishartd.prrob_by_ps(M,N,[P1,P2,...],[S1,S2,...],T[|OPTIONS])
     computes the value of the distribution function of the largest eigenvalue of a Wishart matrix.

return

m
     The number of variables.

n
     The degrees of freedom.

[p1,p2,...,pk]
     A list of the multiplicities of repeated eigenvalues.

[s1,s2,...,sk]
     A list of repeated eigenvalues.

  * This function compute a truncated power series solution up to a total degree where the relative error between the current value and the previous value at the desired point is less than EPS. The default value of EPS is 10^(-4). The value of the distribution function is computed by using this power series.

  * If an option EPS is set, the value is used as EPS.

  * If an option EQ is not set, a system of PDES satisfied by 1F1 on the diagonal region specified by [P1,P2,...] is computed. If an option EQ is set, the list specified by EQ is regarded as the correct system of PDEs.

  * It is recommened to use this function when T is small.

     [...] Q=n_wishartd.prob_by_ps(10,100,[9,1],[1/100,1],1/2);
     ...
     [I=,109,act,24.9016,actmul,0,gr,19.7852]
     2.69026137621748e-165
     61.69sec + gc : 2.06sec(64.23sec)
     [...] R=n_wishartd.prob_by_hgm(10,100,[9,1],[1/100,1],1/2|td=50);
     [diag,15.957,pfaffian,1.00006,ps,5.92437,rk,1.29208]
     2.69026135182769e-165
     23.07sec + gc : 1.136sec(24.25sec)

n_wishartd.ps
-------------

n_wishartd.ps(Z,V,TD)
     computes a truncated power series solution up to the total degree TD.

return
     A list of polynomial

z
     A list of differential operators with partial fraction coefficients.

v
     A list of variables.

  * The result is a list [P,PD] where P is a truncated power series solution up to the total degree TD and PD is the TD homogeneous part of P.

  * Z cannot contain parameters other than the variables in V.

     [...] Z=n_wishartd.diagpf(10,[[1,5],[6,10]])$
     [...] Z0=subst(Z,a,(10+1)/2,c,(10+100+1)/2)$
     [...] PS=n_wishartd.ps(Z0,[y1,y6],10)$
     [...] PS[0];
     197230789502743383953639/230438384724900975787223158176000*y1^10+
     ...
     +(6738842542131976871672233/1011953706634779427957034268904320*y6^9
     ...+3932525/62890602*y6^2+1025/4181*y6+55/111)*y1
     +197230789502743383953639/230438384724900975787223158176000*y6^10
     +...+1395815/62890602*y6^3+3175/25086*y6^2+55/111*y6+1

Differential operators with partial fraction coefficients
=========================================================

Representation of partial fractions
-----------------------------------

The coefficients of the PDE satisfied by the matrix 1F1 are written as a sum of 1/YI and 1/(YI-YJ) multiplied by constants. Furthermore the result of diagonalization by l'Hopital rule can also be written as a sum of partial fractions.

  * A product YI0^N0(YI1-YJ1)^N1(YI2-YJ2)^N2...(YIK-YJK)^NK in the denominator of a fraction is represented as a list [[YI0,N0],[YI1-YJ1,N1],...,[YIK-YJK,NK]], Where each YI-YJ satisfies I>J and the factors are sorted according to an ordering.

  * Let F be a power sum as above and C a constant. Then a monomial C/F is represented by a list は [C,F]. F=[] means that the denominator is 1.

  * Finally C1/F1+...+CK/FK is represented as a list [[C1,F1],...,[CK,FK]], where terms are sorted according to an ordering.

  * We note that it is possible that a partial fraction is reduced to 0.

Representation of differential operators with partial fraction coefficients
---------------------------------------------------------------------------

By using partial fractions explained in the previous section, differential operators with partial fraction coefficients are represented. Let F1,...,FK be partial fractions and D1,...,DK distributed monomials such that D1>...>DK) with respected to the current monomial ordering. Then a differential operator F1*D1+...+FK*DK is represented as a list [F1,D1],...[FK,DK]].

Operations on differential operators with partial fraction coefficients
-----------------------------------------------------------------------

n_wishartd.wsetup
.................

n_wishartd.wsetup(M)

m
     A natural number.

  * This function sets a M-variate computational enviroment. The variables are Y0,Y1,...,YM and DY0,...,DYM, where Y0, DY0 are dummy variables for intermediate computation.

n_wishartd.addpf
................

n_wishartd.addpf(P1,P2)

return
     A differential operator with partial fraction coefficients.

p1, p2
     Differential operators with partial fraction coefficients.

  * This function computes the sum of differential operators P1 and P2.

n_wishartd.mulcpf
.................

n_wishartd.mulcpf(C,P)

return
     A differential operator with partial fraction coefficients.

c
     A partial fraction.

p
     Differential operators with partial fraction coefficients.

  * This function computes the product of a partial fraction C and a differential operator P.

n_wishartd.mulpf
................

n_wishartd.mulpf(P1,P2)

return
     A differential operator with partial fraction coefficients.

p1, p2
     Differential operators with partial fraction coefficients.

  * This function computes the product of differential operators P1 and P2.

n_wishartd.muldpf
.................

n_wishartd.muldpf(Y,P)

return
     A differential operator with partial fraction coefficients.

y
     A variable.

p
     A differential operator with partial fraction coefficients.

  * This function computes the product of the differential operator DY corresponding to a variable Y and P.

     [...] n_wishartd.wsetup(4)$
     [...] P=n_wishartd.wishartpf(4,1);
     [[[[1,[]]],(1)*<<0,2,0,0,0>>],[[[1/2,[[y1-y2,1]]],[1/2,[[y1-y3,1]]],
     ...,[[[-a,[[y1,1]]]],(1)*<<0,0,0,0,0>>]]
     [...] Q=n_wishartd.muldpf(y1,P);
     [[[[1,[]]],(1)*<<0,3,0,0,0>>],[[[1/2,[[y1-y2,1]]],[1/2,[[y1-y3,1]]],
     ...,[[[a,[[y1,2]]]],(1)*<<0,0,0,0,0>>]]

Experimental implementation of Runge-Kutta methods
==================================================

In the function n_wishartd.ps_by_hgm, after computing the Pfaffian matrices for the sytem of PDEs on a diagonal region, it executes a built-in function rk_ratmat which computes an approximate solution of the Pfaffian system by Runge-Kutta method for a spcified step size. This function is repeated until the result gets stabilized, by doubling the step size. rk_ratmat can be used as a general-purpose Runge-Kutta driver and we explain how to use it.

rk_ratmat
---------

rk_ratmat(RK45,NUM,DEN,X0,X1,S,F0)
     solves a system of linear ODEs with rational function coefficients.

return
     A list of real numbers.

rk45
     4 or 5.

num
     An array of constant matrices.

den
     A polynomial.

x0, x1
     Real numbers.

s
     A natural number.

f0
     A real vector.

  * Let K be the size of an array NUM. The function rk_ratmat solves  an initial value problem DF/DX = P(X)F, F(X0)=F0 for P(X)=1/DEN(NUM[0]+NUM[1]X+...+NUM[K-1]X^(K-1)) by a Runge-Kutta method.

  * RK45 specifies the order of a Runge-Kutta method. Adaptive methods are not implemented.

  * The step size is specified by S. The step width is (X1-X0)/S.

  * If the size of F0 is N,  each component of NUM is a square matrix of size N.

  * The result is a list of real numbers [R1,...,RS] of length S. RI is the 0-th component of the solution vector after the step I. Before going to the next step the solution vector is divided by RI. Therefore the 0-th component of the final solution vector [varF(x1) is equal to RS*R(S-1)*...*R1.

  * Since the ODE is linear, each step of Runge-Kutta method is also linear. This enables us to apply a normalization such that the 0-th component of each intermediate solution vector is set to 1.  By applying this normalization we expect that all the components of intermediate solution vectors can be represented by the format of double precision floating point number. If there exist some components which cannot be represented by the format of double precision floating point number in the initial vector F0, we apply this normalization to F0. After applying rk_ratmat we multiply the result for the normalized F0 and the 0-th component of the original F0 to get the desired result.

     [...] F=ltov([sin(1/x),cos(1/x),sin(1/x^2),cos(1/x^2)]);
     [ sin((1)/(x)) cos((1)/(x)) sin((1)/(x^2)) cos((1)/(x^2)) ]
     [...] F0=map(eval,map(subst,F,x,1/10));
     [ -0.54402111088937 -0.839071529076452 -0.506365641109759 0.862318872287684 ]
     [...] N0=matrix(4,4,[[0,0,0,0],[0,0,0,0],[0,0,0,-2],[0,0,2,0]])$
     [...] N1=matrix(4,4,[[0,-1,0,0],[1,0,0,0],[0,0,0,0],[0,0,0,0]])$
     [...] N=ltov([N0,N1])$
     [...] D=x^3$
     [...] R=rk_ratmat(5,N,D,1/10,10,10^4,F0)$
     [...] for(T=R,A=1;T!=[];T=cdr(T))A *=car(T)[1];
     [...] A;
     0.0998334
     [...] F1=map(eval,map(subst,F,x,10));
     [ 0.0998334166468282 0.995004165278026 0.00999983333416666 0.999950000416665 ]