===================================================================
RCS file: /home/cvs/OpenXM/src/asir-contrib/packages/doc/n_wishartd/n_wishartd-en.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -p -r1.1 -r1.2
--- OpenXM/src/asir-contrib/packages/doc/n_wishartd/n_wishartd-en.texi	2016/08/24 08:10:37	1.1
+++ OpenXM/src/asir-contrib/packages/doc/n_wishartd/n_wishartd-en.texi	2016/08/25 03:13:54	1.2
@@ -1,4 +1,4 @@
-%comment $OpenXM$
+%comment $OpenXM: OpenXM/src/asir-contrib/packages/doc/n_wishartd/n_wishartd-en.texi,v 1.1 2016/08/24 08:10:37 noro Exp $
 %comment --- おまじない ---
 \input ../../../../asir-doc/texinfo
 @iftex
@@ -160,16 +160,18 @@ is specified by @var{[s,s]}.
 
 @table @t
 @item n_wishartd.message(@var{onoff})
-計算中のメッセージ出力をon/off する.
+starts/stops displaying messages during computation.
 @end table
 
 @table @var
 @item onoff
-@var{onoff=1} のときメッセージを出力し, @var{onoff=0} のときしない.
+Start displaying messages if @var{onoff}=1.
+Stop displaying messages if @var{onoff}=0.
 @end table
 
 @itemize @bullet
-@item 計算中のメッセージ出力を on/off する. デフォルトは off である.
+@item This function starts/stops displaying messages during computation.
+The default value is set to 0.
 @end itemize
 
 @node Numerical comptation of restricted function,,, n_wishartd.rr
@@ -186,42 +188,42 @@ is specified by @var{[s,s]}.
 @findex n_wishartd.prob_by_hgm
 
 @table @t
-@item n_wishartd.prrob_by_hgm(@var{m},@var{n},@var{[p1,p2,...]},@var{[s1,s2,...]},@var{t}[|@var{options}])
-HGM により重複固有値を持つ共分散行列に対する Wishart 行列の最大固有値の
-分布関数の値を計算する.
+@item n_wishartd.prob_by_hgm(@var{m},@var{n},@var{[p1,p2,...]},@var{[s1,s2,...]},@var{t}[|@var{options}])
+computes the value of the distribution function of the largest eigenvalue of a Wishart matrix.
 @end table
 
 @table @var
 @item return
 @item m
-変数の個数
+The number of variables.
 @item n
-自由度
-@item [p1,p2,...]
-重複固有値の個数のリスト
-@item [s1,s2,...]
-各重複固有値
+The degrees of freedom.
+@item [p1,p2,...,pk]
+A list of the multiplicities of repeated eigenvalues.
+@item [s1,s2,...,sk]
+A list of repeated eigenvalues.
 @end table
 
 @itemize @bullet
 @item 
-固有値 @var{si} を @var{pi} 個もつ対角行列を共分散行列とする Wishart 行
-列の最大固有値 @var{l1}の分布関数の値 @var{Pr[l1<t]} を計算する.
+Let @var{l1} be the largest eigenvalue of a Wishart matrix.
+Let @var{Pr[l1<t]} be the distribution function of @var{l1}.
+The function @code{n_wishartd.prob_by_hgm} computes the value of the distribution function by using HGM
+for a covariance matrix which has repeated eigenvalues @var{si} with multiplicity @var{pi} (@var{i=1,...,k}).
 
-@item ステップ数を指定したルンゲ=クッタ法を, ステップ数を 2 倍しながら
-一つ前の計算結果との相対誤差が @var{eps} (デフォルトで @var{10^(-4)})
-になるまで繰り返す.
+@item 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 @var{eps},
+The default value of @var{eps} is @var{10^(-4)}.
 @item
-@var{eq} オプション指定がない場合, @var{[p1,p2,...]} で指定される対角領
-域に制限した微分方程式系を計算する. 指定がある場合, オプションとして指
-定されたリストをチェックなしに制限した方程式と見なして計算する.
-@item @var{eps}オプションが指定された場合, 指定された値を @var{eps} として計算する.
-@item @var{td} オプションが指定された場合, 初期ベクトル計算のためのべき級数を @var{td} で
-指定された全次数まで計算する (デフォルトは100).
-@item @var{rk} オプションが指定された場合, 指定された次数のルンゲ=クッタ法を用いる.
-許される値は 4 または 5, でデフォルトは 5である.
-@item べき級数解の計算の困難さ, およびパフィアン行列の計算の困難さから, ブロック数が 2 以下の場合にのみ
-実用性がある.
+If an option @var{eq} is not set, 
+a system of PDES satisfied by 1F1 on the diagonal region specified by @var{[p1,p2,...]} is computed.
+If an option @var{eq} is set, the list specified by @var{eq} is regarded as the correct system of PDEs.
+@item If an option @var{eps} is set, the value is used as @var{eps}.
+@item If an option @var{td} is set, the truncated power series solution for computing the initial vector
+is computed up to the total degree specified by @var{td}. The default value is 100.
+@item If an option @var{rk} is set, it is regarded as the order of a Runge-Kutta method. The default vaule is 5.
+@item It is recommended to use this function only when @var{k<=2} where @var{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.
 @end itemize
 
 @example
@@ -253,31 +255,33 @@ Step=2560000
 
 @table @t
 @item n_wishartd.prrob_by_ps(@var{m},@var{n},@var{[p1,p2,...]},@var{[s1,s2,...]},@var{t}[|@var{options}])
-べき級数に重複固有値を持つ共分散行列に対する Wishart 行列の最大固有値の
-分布関数の値を計算する.
+computes the value of the distribution function of the largest eigenvalue of a Wishart matrix.
 @end table
 
 @table @var
+@item return
 @item m
-変数の個数
+The number of variables.
 @item n
-自由度
-@item [p1,p2,...]
-重複固有値の個数のリスト
-@item [s1,s2,...]
-各重複固有値
+The degrees of freedom.
+@item [p1,p2,...,pk]
+A list of the multiplicities of repeated eigenvalues.
+@item [s1,s2,...,sk]
+A list of repeated eigenvalues.
 @end table
 
 @itemize @bullet
 @item 
-直前の値との相対誤差が @var{eps} (デフォルト値は @var{10^(-4)}) 以下に
-なるまで, べき級数を全次数ごとに計算する. その値から分布関数の値を計算
-して返す.
-@item @var{eps}オプションが指定された場合, 指定された値を @var{eps} として計算する.
-@var{eq} オプション指定がない場合, @var{[p1,p2,...]} で指定される対角領
-域に制限した微分方程式系を計算する. 指定がある場合, オプションとして指
-定されたリストをチェックなしに制限した方程式と見なして計算する.
-@item @var{t} の値が小さい場合にのみ実用的に用いることができる.
+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 @var{eps}. The default value of @var{eps} is @var{10^(-4)}.
+The value of the distribution function is computed by using this power series.
+@item If an option @var{eps} is set, the value is used as @var{eps}.
+@item
+If an option @var{eq} is not set, 
+a system of PDES satisfied by 1F1 on the diagonal region specified by @var{[p1,p2,...]} is computed.
+If an option @var{eq} is set, the list specified by @var{eq} is regarded as the correct system of PDEs.
+@item It is recommened to use this function when @var{t} is small.
 @end itemize
 
 @example
@@ -298,24 +302,24 @@ Step=2560000
 
 @table @t
 @item n_wishartd.ps(@var{z},@var{v},@var{td})
-微分方程式系のべき級数解を指定された全次数まで計算する.
+computes a truncated power series solution up to the total degree @var{td}.
 @end table
 
 @table @var
 @item return
-多項式リスト
-
+A list of polynomial
 @item z
-differential operators with partial fraction coefficientsのリスト
+A list of differential operators with partial fraction coefficients.
 @item v
-変数リスト
+A list of variables.
 @end table
 
 @itemize @bullet
 @item 
-結果は @var{[p,pd]} なるリストで, @var{p} は @var{td} 次まで求めたべき級数解, @var{pd} は
-@var{p} の @var{td} 次部分である.
-@item @var{z} は, @var{v} に指定される変数以外のパラメタを含んではいけない.
+The result is a list @var{[p,pd]} where
+@var{p} is a truncated power series solution up to the total degree @var{td}
+and @var{pd} is the @var{td} homogeneous part of @var{p}.
+@item @var{z} cannot contain parameters other than the variables in @var{v}.
 @end itemize
 
 @example
@@ -335,42 +339,43 @@ differential operators with partial fraction coefficie
 @section Differential operators with partial fraction coefficients
 
 @menu
-* Expression of partial fractions::
-* Expression of differential operators with partial fraction coefficients::
+* Representation of partial fractions::
+* Representation of differential operators with partial fraction coefficients::
 * Operations on differential operators with partial fraction coefficients::
 @end menu
 
-@node Expression of partial fractions,,, Differential operators with partial fraction coefficients
-@subsection Expression of partial fractions
+@node Representation of partial fractions,,, Differential operators with partial fraction coefficients
+@subsection Representation of partial fractions
 
-matrix 1F1 が満たす微分方程式の係数は @var{1/yi}, @var{1/(yi-yj)} の定
-数倍の和として書かれている. さらに, ロピタル則を用いた対角領域への制限
-アルゴリズムの結果も同様に部分分数の和として書ける.
+The coefficients of the PDE satisfied by the matrix 1F1 are written
+as a sum of @var{1/yi} and @var{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.
 
 @itemize @bullet
 @item 
-分母に現れる @var{yi0^n0(yi1-yj1)^n1(yi2-yj2)^n2...(yik-yjk)^nk} は
-@var{[[yi0,n0],[yi1-yj1,n1],...,[yik-yjk,nk]]} なる形のリストとして表現
-される. ここで, 各因子 @var{yi-yj} は @var{i>j} を満たし, さらに因子は
-ある一定の順序で整列される.
+A product @var{yi0^n0(yi1-yj1)^n1(yi2-yj2)^n2...(yik-yjk)^nk}
+in the denominator of a fraction is represented as a list @var{[[yi0,n0],[yi1-yj1,n1],...,[yik-yjk,nk]]},
+Where each @var{yi-yj} satisfies @var{i>j} and the factors are sorted according to an ordering.
 @item 
-@var{f} を上のようなべき積とし, @var{c} を定数とするとき, 単項式にあた
-る @var{c/f} は @var{[c,f]} で表現される.  @var{f=[]} の場合, 分母が 1
-であることを意味する.
+Let @var{f} be a power sum as above and @var{c} a constant.
+Then a monomial @var{c/f} is represented by a list は @var{[c,f]}.
+@var{f=[]} means that the denominator is 1.
 @item 
-最後に, @var{c1/f1+...+ck/fk} は @var{[[c1,f1],...,[ck,fk]]} と表現され
-る. ここでも, 各項はある一定の順序で整列される.
+Finally @var{c1/f1+...+ck/fk} is represented as a list @var{[[c1,f1],...,[ck,fk]]},
+where terms are sorted according to an ordering.
 @item
-部分分数を通分して簡約した結果, 0 になることもあることに注意する.
+We note that it is possible that a partial fraction is reduced to 0.
 @end itemize
 
-@node Expression of differential operators with partial fraction coefficients,,, Differential operators with partial fraction coefficients
-@subsection Expression of differential operators with partial fraction coefficients
+@node Representation of differential operators with partial fraction coefficients,,, Differential operators with partial fraction coefficients
+@subsection Representation of differential operators with partial fraction coefficients
 
-前節の部分分数を用いて, それらを係数とする微分作用素が表現できる.
-@var{f1,...,fk} をExpression of partial fractions, @var{d1,...,dk} を分散表現単項式 (現
-在設定されている項順序で @var{d1>...>dk}) とするとき, 微分作用素
-@var{f1*d1+...+fk*dk} が@var{[f1,d1],...[fk,dk]]}で表現される.
+By using partial fractions explained in the previous section,
+differential operators with partial fraction coefficients are represented.
+Let @var{f1,...,fk} be partial fractions and @var{d1,...,dk} distributed monomials such that
+@var{d1>...>dk}) with respected to the current monomial ordering.
+Then a differential operator @var{f1*d1+...+fk*dk} is represented as a list @var{[f1,d1],...[fk,dk]]}.
 
 @node Operations on differential operators with partial fraction coefficients,,, Differential operators with partial fraction coefficients
 @subsection Operations on differential operators with partial fraction coefficients
@@ -393,12 +398,12 @@ matrix 1F1 が満たす微分方程式の係数は @var{1/yi}, @var
 
 @table @var
 @item m
-自然数
+A natural number.
 @end table
 
 @itemize @bullet
-@item @var{m} 変数の計算環境をセットする. 変数は @var{y0,y1,...,ym}, @var{dy0,...,dym}
-で @var{y0, dy0} は中間結果の計算のためのダミー変数である.
+@item This function sets a @var{m}-variate computational enviroment. The variables are @var{y0,y1,...,ym} and @var{dy0,...,dym},
+where @var{y0, dy0} are dummy variables for intermediate computation.
 @end itemize
 
 @node n_wishartd.addpf,,, Operations on differential operators with partial fraction coefficients
@@ -410,13 +415,13 @@ matrix 1F1 が満たす微分方程式の係数は @var{1/yi}, @var
 
 @table @var
 @item return
-differential operators with partial fraction coefficients
+A differential operator with partial fraction coefficients.
 @item p1, p2
-differential operators with partial fraction coefficients
+Differential operators with partial fraction coefficients.
 @end table
 
 @itemize @bullet
-@item 微分作用素 @var{p1}, @var{p2} の和を求める.
+@item This function computes the sum of differential operators @var{p1} and @var{p2}.
 @end itemize
 
 @node n_wishartd.mulcpf,,, Operations on differential operators with partial fraction coefficients
@@ -428,15 +433,15 @@ differential operators with partial fraction coefficie
 
 @table @var
 @item return
-differential operators with partial fraction coefficients
+A differential operator with partial fraction coefficients.
 @item c
-部分分数
+A partial fraction.
 @item p
-differential operators with partial fraction coefficients
+Differential operators with partial fraction coefficients.
 @end table
 
 @itemize @bullet
-@item 部分分数 @var{c} と微分作用素 @var{p} の積を計算する.
+@item This function computes the product of a partial fraction @var{c} and a differential operator @var{p}.
 @end itemize
 
 @node n_wishartd.mulpf,,, Operations on differential operators with partial fraction coefficients
@@ -448,13 +453,13 @@ differential operators with partial fraction coefficie
 
 @table @var
 @item return
-differential operators with partial fraction coefficients
+A differential operator with partial fraction coefficients.
 @item p1, p2
-differential operators with partial fraction coefficients
+Differential operators with partial fraction coefficients.
 @end table
 
 @itemize @bullet
-@item 微分作用素 @var{p1}, @var{p2} の積を計算する.
+@item This function computes the product of differential operators @var{p1} and @var{p2}.
 @end itemize
 
 @node n_wishartd.muldpf,,, Operations on differential operators with partial fraction coefficients
@@ -466,16 +471,16 @@ differential operators with partial fraction coefficie
 
 @table @var
 @item return
-differential operators with partial fraction coefficients
+A differential operator with partial fraction coefficients.
 @item y
-変数
+A variable.
 @item p
-differential operators with partial fraction coefficients
+A differential operator with partial fraction coefficients.
 @end table
 
 @itemize @bullet
-@item 変数 @var{y} に対し, 微分作用素 @var{dy} と @var{p} の微分作用素としての
-積を計算する.
+@item 
+This function computes the product of the differential operator @var{dy} corresponding to a variable @var{y} and @var{p}.
 @end itemize
 
 @example
@@ -497,58 +502,63 @@ differential operators with partial fraction coefficie
 
 @node rk_ratmat,,, Experimental implementation of Runge-Kutta methods 
 
-@code{n_wishartd.ps_by_hgm} では, パフィアン行列を計算したあと, 与えられたステップ数で
-Runge-Kutta 法を実行して近似解の値を計算する組み込み関数 @code{rk_ratmat} を実行している.
-この関数を, 値が与えられた精度で安定するまでステップ数を2倍しながら繰り返して実行する.
-@code{rk_ratmat} 自体, ある程度汎用性があるので, ここでその使用法を解説する.
+In the function @code{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
+@code{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.
+@code{rk_ratmat} can be used as a general-purpose Runge-Kutta driver and we explain how to use it.
 
 @subsection @code{rk_ratmat}
 @findex rk_ratmat
 
 @table @t
 @item rk_ratmat(@var{rk45},@var{num},@var{den},@var{x0},@var{x1},@var{s},@var{f0})
-有理関数係数のベクトル値一階線形常微分方程式系を Runge-Kutta 法で解く
+solves a system of linear ODEs with rational function coefficients.
 @end table
 
 @table @var
 @item return
-実数のリスト
-
+A list of real numbers.
 @item rk45
-4 または 5
+4 or 5.
 @item num
-定数行列の配列
+An array of constant matrices.
 @item den
-多項式
+A polynomial.
 @item x0, x1
-実数
+Real numbers.
 @item s
-自然数
+A natural number.
 @item f0
-実ベクトル
+A real vector.
 @end table
 
 @itemize @bullet
 @item 
-配列 @var{num} のサイズを @var{k} とするとき,
-@var{P(x)=1/den(num[0]+num[1]x+...+num[k-1]x^(k-1))} に対し @var{dF/dx = P(x)F}, @var{F(x0)=f0} を
-Runge-Kutta 法で解く.
+Let @var{k} be the size of an array @var{num}.
+The function @code{rk_ratmat} solves  an initial value problem
+@var{dF/dx = P(x)F}, @var{F(x0)=f0} for @var{P(x)=1/den(num[0]+num[1]x+...+num[k-1]x^(k-1))} by a Runge-Kutta method.
 @item
-@var{rk45} が 4 のとき 4 次 Runge-Kutta, 5 のとき 5 次 Runge-Kutta アルゴリズムを実行する.
-実験的実装のため, adaptive アルゴリズムは実装されていない.
+@var{rk45} specifies the order of a Runge-Kutta method. Adaptive methods are not implemented.
 @item
-@var{s} はステップ数で, 刻み幅は@var{(x1-x0)/s} である.
+The step size is specified by @var{s}. The step width is @var{(x1-x0)/s}.
 @item
-@var{f0} がサイズ@var{n} のとき, @var{num} の各成分は @var{n} 次正方行列である.
+If the size of @var{f0} is @var{n},  each component of @var{num} is a square matrix of size @var{n}.
 @item
-結果は, 長さ @var{s} の実数リスト @var{[rs,...,r1]} で, @var{ri} は @var{i} ステップ目に計算された
-解ベクトルの第0成分である. 次のステップに進む前に解ベクトルを @var{ri} で割るので, 最終的に
-解 @var{F(x1)} の第 0 成分が @var{rs*r(s-1)*...*r1} となる.
-@item 方程式が線形なので, Runge-Kutta の各ステップも線形となることを利用し,
-第0成分を1に正規化することで, 途中の解の成分が倍精度浮動小数の
-範囲に収まることを期待している. 初期ベクトル @var{f0} の成分が倍精度浮動小数に収まらない場合
-は, @var{f0} を正規化してから @code{rk_ratmat} を実行し, 前項の結果に @code{f0} の第 0 成分をかければ
-よい.
+The result is a list of real numbers @var{[r1,...,rs]} of length @var{s}.
+@var{ri} is the 0-th component of the solution vector after the step @var{i}.
+Before going to the next step the solution vector is divided by @var{ri}.
+Therefore the 0-th component of the final solution vector [var{F(x1)} is equal to @var{rs*r(s-1)*...*r1}.
+@item 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 in the initial vector @var{f0}, we apply this normalization
+to @var{f0}. After applying @code{rk_ratmat} we multiply the result for the normalized @var{f0} and the 0-th component
+of the original @var{f0} to get the desired result.
 @end itemize
 
 @example