@menu
* Introduction to lapack::
* Functions and Variables for lapack::
@end menu

@node Introduction to lapack, Functions and Variables for lapack, lapack, lapack
@section Introduction to lapack

@code{lapack}は
SLATECプロジェクトから得られるようなFortranライブラリLAPACKの
(プログラム @code{f2c}を介した) Common Lisp翻訳です。

(訳者注意書き: lapackを使用するには、load("lapack"); load("eigensys");を実行してください。load("lapack")には、初回だけコンパイルで時間がかかるかもしれません。)

@opencatbox
@category{Numerical methods}
@category{Share packages}
@category{Package lapack}
@closecatbox


@node Functions and Variables for lapack, , Introduction to lapack, lapack
@section Functions and Variables for lapack

@deffn {関数} dgeev (@var{A})
@deffnx {関数} dgeev (@var{A}, @var{right_p}, @var{left_p})

行列@var{A}の固有値と、オプションで固有ベクトルを計算します。
@var{A}の要素はすべて整数か浮動小数点数でなければいけません。
@var{A}は平方(行と列が同じ数)でなければいけません。
@var{A}は対称であってもなくてもいいです。

@code{dgeev(@var{A})}は@var{A}の固有値だけを計算します。
@code{dgeev(@var{A}, @var{right_p}, @var{left_p})}は
@var{A}の固有値と、
@math{@var{right_p} = @code{true}}の時、右固有ベクトル、
@math{@var{left_p} = @code{true}}の時、左固有ベクトルを計算します。

3項目のリストが返されます。
最初の項目は固有値のリストです。
二番目の項目は@code{false}か右固有ベクトルの行列です。
三番目の項目は@code{false}か左固有ベクトルの行列です。

右固有ベクトル@math{v(j)} (右固有ベクトル行列の@math{j}番目の列)は

@math{A . v(j) = lambda(j) . v(j)}

を満たします。ここで@math{lambda(j)}は対応する固有値です。

左固有ベクトル@math{v(j)} (左固有ベクトル行列の@math{j}番目の列)は

@math{u(j)**H . A = lambda(j) . u(j)**H}

を満たします。ここで@math{u(j)**H}は@math{u(j)}の共役転置を意味します。
Maxima関数@code{ctranspose}が共役転置を計算します。

計算された固有ベクトルは、
Euclideanノルムが1に等しく、
最大成分の虚部が0になるように規格化されます。

例:

@c ===beg===
@c load ("lapack")$
@c fpprintprec : 6;
@c M : matrix ([9.5, 1.75], [3.25, 10.45]);
@c dgeev (M);
@c [L, v, u] : dgeev (M, true, true);
@c D : apply (diag_matrix, L);
@c M . v - v . D;
@c transpose (u) . M - D . transpose (u);
@c ===end===
@example
(%i1) load ("lapack")$
(%i2) fpprintprec : 6;
(%o2)                           6
(%i3) M : matrix ([9.5, 1.75], [3.25, 10.45]);
                         [ 9.5   1.75  ]
(%o3)                    [             ]
                         [ 3.25  10.45 ]
(%i4) dgeev (M);
(%o4)          [[7.54331, 12.4067], false, false]
(%i5) [L, v, u] : dgeev (M, true, true);
                           [ - .666642  - .515792 ]
(%o5) [[7.54331, 12.4067], [                      ], 
                           [  .745378   - .856714 ]
                                        [ - .856714  - .745378 ]
                                        [                      ]]
                                        [  .515792   - .666642 ]
(%i6) D : apply (diag_matrix, L);
                      [ 7.54331     0    ]
(%o6)                 [                  ]
                      [    0     12.4067 ]
(%i7) M . v - v . D;
                [      0.0       - 8.88178E-16 ]
(%o7)           [                              ]
                [ - 8.88178E-16       0.0      ]
(%i8) transpose (u) . M - D . transpose (u);
                     [ 0.0  - 4.44089E-16 ]
(%o8)                [                    ]
                     [ 0.0       0.0      ]
@end example

@opencatbox
@category{Package lapack}
@closecatbox

@end deffn

@deffn {関数} dgeqrf (@var{A})

行列 @var{A}のQR分解します。
All elements of 
@var{A}のすべての要素は整数か浮動小数点数でなければいけません。
@var{A}は行と列の数は同じかもしれませんし違うかもしれません。

2つの項目のリストを返します。
一番目の項目は行列 @var{Q}で、それは@var{A}と同じ行数を持つ平方正規直交行列です。
二番目の項目は行列 @var{R}で、それは@var{A}tお同じサイズで、
対角以下のすべての要素がが零に等しいものです。
積 @code{@var{Q} . @var{R}}は(浮動小数点の丸め誤差を除いて)@var{A}に等しい。
ここで "."は非可換乗算演算子です。

@c ===beg===
@c load ("lapack")$
@c fpprintprec : 6;
@c M : matrix ([1, -3.2, 8], [-11, 2.7, 5.9]);
@c [q, r] : dgeqrf (M);
@c q . r - M;
@c mat_norm (%);
@c ===end===
@example
(%i1) load ("lapack") $
(%i2) fpprintprec : 6 $
(%i3) M : matrix ([1, -3.2, 8], [-11, 2.7, 5.9]) $
(%i4) [q, r] : dgeqrf (M);
       [ - .0905357  .995893  ]
(%o4) [[                      ], 
       [  .995893    .0905357 ]
                               [ - 11.0454   2.97863   5.15148 ]
                               [                               ]]
                               [     0      - 2.94241  8.50131 ]
(%i5) q . r - M;
         [ - 7.77156E-16   1.77636E-15   - 8.88178E-16 ]
(%o5)    [                                             ]
         [      0.0       - 1.33227E-15   8.88178E-16  ]
(%i6) mat_norm (%, 1);
(%o6)                      3.10862E-15
@end example

@opencatbox
@category{Package lapack}
@closecatbox

@end deffn

@deffn {関数} dgesv (@var{A}, @var{b})

線形方程式 @math{@var{A} @var{x} = @var{b}}の
解 @var{x}を計算します。
ここで、 @var{A}は平方行列、
@var{b}は@var{A}と同じ数の行と任意の長さの列を持つ行列です。
戻り値 @var{x}は @var{b}と同じサイズです。

@var{A}と @var{b}の要素は
@code{float}を介して実の浮動小数点数に評価されなければいけません;
従って、要素は任意の数値型か、数値定数のシンボルか、
浮動小数点に評価される式であり得ます。
@var{x}の要素はいつも浮動小数点数です。
すべての算術は浮動小数演算として実行されます。

@code{dgesv}は
@var{A}のLU分解を介して
解を計算します。

例:

@code{dgesv}は
線形方程式 @math{@var{A} @var{x} = @var{b}}の解を計算します。

@c ===beg===
@c A : matrix ([1, -2.5], [0.375, 5]);
@c b : matrix ([1.75], [-0.625]);
@c x : dgesv (A, b);
@c dlange (inf_norm, b - A . x);
@c ===end===
@example
(%i1) A : matrix ([1, -2.5], [0.375, 5]);
                               [   1    - 2.5 ]
(%o1)                          [              ]
                               [ 0.375    5   ]
(%i2) b : matrix ([1.75], [-0.625]);
                                  [  1.75   ]
(%o2)                             [         ]
                                  [ - 0.625 ]
(%i3) x : dgesv (A, b);
                            [  1.210526315789474  ]
(%o3)                       [                     ]
                            [ - 0.215789473684211 ]
(%i4) dlange (inf_norm, b - A.x);
(%o4)                                 0.0
@end example

@var{b}は@var{A}と同じ数の行と任意の長さの列を持つ行列です。
@var{x}は @var{b}と同じサイズです。

@c ===beg===
@c A : matrix ([1, -0.15], [1.82, 2]);
@c b : matrix ([3.7, 1, 8], [-2.3, 5, -3.9]);
@c x : dgesv (A, b);
@c dlange (inf_norm, b - A . x);
@c ===end===
@example
(%i1) A : matrix ([1, -0.15], [1.82, 2]);
                               [  1    - 0.15 ]
(%o1)                          [              ]
                               [ 1.82    2    ]
(%i2) b : matrix ([3.7, 1, 8], [-2.3, 5, -3.9]);
                              [  3.7   1    8   ]
(%o2)                         [                 ]
                              [ - 2.3  5  - 3.9 ]
(%i3) x : dgesv (A, b);
      [  3.103827540695117   1.20985481742191    6.781786185657722  ]
(%o3) [                                                             ]
      [ - 3.974483062032557  1.399032116146062  - 8.121425428948527 ]
(%i4) dlange (inf_norm, b - A . x);
(%o4)                       1.1102230246251565E-15
@end example

@var{A}と @var{b}の要素は
実の浮動小数点数に評価されなければいけません;

@c ===beg===
@c A : matrix ([5, -%pi], [1b0, 11/17]);
@c b : matrix ([%e], [sin(1)]);
@c x : dgesv (A, b);
@c dlange (inf_norm, b - A . x);
@c ===end===
@example
(%i1) A : matrix ([5, -%pi], [1b0, 11/17]);
                               [   5    - %pi ]
                               [              ]
(%o1)                          [         11   ]
                               [ 1.0b0   --   ]
                               [         17   ]
(%i2) b : matrix ([%e], [sin(1)]);
                                  [   %e   ]
(%o2)                             [        ]
                                  [ sin(1) ]
(%i3) x : dgesv (A, b);
                             [ 0.690375643155986 ]
(%o3)                        [                   ]
                             [ 0.233510982552952 ]
(%i4) dlange (inf_norm, b - A . x);
(%o4)                        2.220446049250313E-16
@end example

@opencatbox
@category{Package lapack}
@category{Linear equations}
@closecatbox

@end deffn

@deffn {関数} dgesvd (@var{A})
@deffnx {関数} dgesvd (@var{A}, @var{left_p}, @var{right_p})

特異値から成る行列 @var{A}の特異値分解(SVD)を計算します。
オプションで左および右特異ベクトルを取ります。

@var{A}の要素はすべて整数か浮動小数点数でなければいけません。
@var{A}は(行と列が同じ数の)平方かもしれませんし、そうでないかもしれません。

@math{m}を @var{A}の行数、@math{n}を列数とします。
@var{A}の特異値分解は
@c this code breaks texi2pdf: @math{@var{A} = @var{U} . @var{Sigma} . @var{V^T}}
@math{@var{A} = @var{U} . @var{Sigma} . @var{V}^T}
のような3つの行列 @var{U}, @var{Sigma}, @var{V^T}から構成されます。
ここで、 @var{U}は @math{m}掛け@math{m}のユニタリ行列、
@var{Sigma}は @math{m}掛け@math{n}の対角行列、
@var{V^T}は @math{n}掛け@math{n}のユニタリ行列です。

@math{sigma[i]}を
@math{Sigma}の対角要素、すなわち、 @math{@var{Sigma}[i, i] = @var{sigma}[i]}と
します。
要素 @math{sigma[i]}は @var{A}のいわゆる特異値です;
これらは実数で、非負で、降順で返されます。
@var{U}と @var{V}の最初の @math{min(m, n)}列は
@var{A}の左と右特異ベクトルです。
@code{dgesvd}は、@var{V}自身ではなく@var{V}の転置を返すことに注意してください。

@code{dgesvd(@var{A})}は @var{A}の特異値だけを計算します。
@code{dgesvd(@var{A}, @var{left_p}, @var{right_p})}は
@var{A}の特異値と、
@math{@var{left_p} = @code{true}}の時、左特異ベクトル、
@math{@var{right_p} = @code{true}}の時、右特異ベクトルを計算します。

3つの項目のリストが返されます。
一つ目の項目は特異値のリストです。
二つ目の項目は @code{false}か、左特異ベクトルの行列です。
三つ目の項目は @code{false}か、右特異ベクトルの行列です。

例:

@c ===beg===
@c load ("lapack")$
@c fpprintprec : 6;
@c M: matrix([1, 2, 3], [3.5, 0.5, 8], [-1, 2, -3], [4, 9, 7]);
@c dgesvd (M);
@c [sigma, U, VT] : dgesvd (M, true, true);
@c m : length (U);
@c n : length (VT);
@c Sigma:
@c   genmatrix(lambda ([i, j], if i=j then sigma[i] else 0),
@c             m, n);
@c U . Sigma . VT - M;
@c transpose (U) . U;
@c VT . transpose (VT);
@c ===end===
@example
(%i1) load ("lapack")$
(%i2) fpprintprec : 6;
(%o2)                           6
(%i3) M: matrix([1, 2, 3], [3.5, 0.5, 8], [-1, 2, -3], [4, 9, 7]);
                        [  1    2    3  ]
                        [               ]
                        [ 3.5  0.5   8  ]
(%o3)                   [               ]
                        [ - 1   2   - 3 ]
                        [               ]
                        [  4    9    7  ]
(%i4) dgesvd (M);
(%o4)      [[14.4744, 6.38637, .452547], false, false]
(%i5) [sigma, U, VT] : dgesvd (M, true, true);
(%o5) [[14.4744, 6.38637, .452547], 
[ - .256731  .00816168   .959029    - .119523 ]
[                                             ]
[ - .526456   .672116   - .206236   - .478091 ]
[                                             ], 
[  .107997   - .532278  - .0708315  - 0.83666 ]
[                                             ]
[ - .803287  - .514659  - .180867    .239046  ]
[ - .374486  - .538209  - .755044 ]
[                                 ]
[  .130623   - .836799   0.5317   ]]
[                                 ]
[ - .917986   .100488    .383672  ]
(%i6) m : length (U);
(%o6)                           4
(%i7) n : length (VT);
(%o7)                           3
(%i8) Sigma:
        genmatrix(lambda ([i, j], if i=j then sigma[i] else 0),
                  m, n);
                  [ 14.4744     0        0    ]
                  [                           ]
                  [    0     6.38637     0    ]
(%o8)             [                           ]
                  [    0        0     .452547 ]
                  [                           ]
                  [    0        0        0    ]
(%i9) U . Sigma . VT - M;
          [  1.11022E-15        0.0       1.77636E-15 ]
          [                                           ]
          [  1.33227E-15    1.66533E-15       0.0     ]
(%o9)     [                                           ]
          [ - 4.44089E-16  - 8.88178E-16  4.44089E-16 ]
          [                                           ]
          [  8.88178E-16    1.77636E-15   8.88178E-16 ]
(%i10) transpose (U) . U;
       [     1.0      5.55112E-17    2.498E-16     2.77556E-17  ]
       [                                                        ]
       [ 5.55112E-17      1.0       5.55112E-17    4.16334E-17  ]
(%o10) [                                                        ]
       [  2.498E-16   5.55112E-17       1.0       - 2.08167E-16 ]
       [                                                        ]
       [ 2.77556E-17  4.16334E-17  - 2.08167E-16       1.0      ]
(%i11) VT . transpose (VT);
          [      1.0           0.0      - 5.55112E-17 ]
          [                                           ]
(%o11)    [      0.0           1.0       5.55112E-17  ]
          [                                           ]
          [ - 5.55112E-17  5.55112E-17       1.0      ]
@end example

@opencatbox
@category{Package lapack}
@closecatbox

@end deffn

@deffn {関数} dlange (@var{norm}, @var{A})
@deffnx {関数} zlange (@var{norm}, @var{A})

行列 @var{A}のノルムもしくはノルムのような関数を計算します。

@table @code
@item max
@math{max(abs(A(i, j)))}を計算します。
ここで @math{i}と @math{j}はそれぞれ行と列を行き渡ります。
この関数は適切な行列ノルムではないことに注意してください。
@item one_norm
@var{A}の @math{L[1]}ノルム、
すなわち、それぞれの列の要素の絶対値の和の最大値
を計算します。
@item inf_norm
@var{A}の @math{L[inf]}ノルム、
すなわち、それぞれの行の要素の絶対値の和の最大値
を計算します。
@item frobenius
@var{A}のFrobeniusノルム、すなわち、
行列要素の平方の和の平方根
を計算します。
@end table

@opencatbox
@category{Package lapack}
@closecatbox

@end deffn

@deffn {関数} dgemm (@var{A}, @var{B})
@deffnx {関数} dgemm (@var{A}, @var{B}, @var{options})
2つの行列の積を計算します。オプションで積を三つ目の行列に足し算します。

最も簡単な形式では、
@code{dgemm(@var{A}, @var{B})}は
2つの実行列 @var{A}と @var{B}の積を計算します。

二番目の形式では、
@code{dgemm}は
@math{@var{alpha} * @var{A} * @var{B} + @var{beta} * @var{C}}
を計算します。
ここで @var{A}, @var{B}, @var{C}は
適当なサイズの実行列であり、
@var{alpha}と @var{beta}は実数です。
オプションで、 @var{A}と/もしくは @var{B}は
積を計算する前に転置を取ることができます。
追加のパラメータはオプションのキーワード引数で指定できます:
キーワード引数はオプションで、
どんな順番でも指定できます。
それらはすべて、形式 @code{key=val}を取ります。
キーワード引数は以下の通りです:

@table @code
@item C
足すべき行列 @var{C}。
デフォルトは @code{false}であり、行列を足さないことを意味します。
@item alpha
@var{A}と @var{B}の積がこの値に掛けられます。
デフォルトは1です。
@item beta
もし行列 @var{C}が与えられたら、
この値は、足される前に@var{C}に掛けられます。
デフォルト値は0で、これは, たとえ@var{C}が与えられても
@var{C}が足されないことを意味します。
故に、必ず@var{beta}に零でない値を指定してください。
@item transpose_a
もし @code{true}なら、
@var{A}の代わりに@var{A}の転置が積に使われます。
デフォルトは @code{false}です。
@item transpose_b
もし @code{true}なら
@var{B}の代わりに@var{B}の転置が積に使われます。
デフォルトは @code{false}です。
@end table

@c ===beg===
@c load ("lapack")$
@c A : matrix([1,2,3],[4,5,6],[7,8,9]);
@c B : matrix([-1,-2,-3],[-4,-5,-6],[-7,-8,-9]);
@c C : matrix([3,2,1],[6,5,4],[9,8,7]);
@c dgemm(A,B);
@c A . B;
@c dgemm(A,B,transpose_a=true);
@c transpose(A) . B;
@c dgemm(A,B,c=C,beta=1);
@c A . B + C;
@c dgemm(A,B,c=C,beta=1, alpha=-1);
@c -A . B + C
@example
(%i1) load ("lapack")$
(%i2) A : matrix([1,2,3],[4,5,6],[7,8,9]);
                                  [ 1  2  3 ]
                                  [         ]
(%o2)                             [ 4  5  6 ]
                                  [         ]
                                  [ 7  8  9 ]
(%i3) B : matrix([-1,-2,-3],[-4,-5,-6],[-7,-8,-9]);
                               [ - 1  - 2  - 3 ]
                               [               ]
(%o3)                          [ - 4  - 5  - 6 ]
                               [               ]
                               [ - 7  - 8  - 9 ]
(%i4) C : matrix([3,2,1],[6,5,4],[9,8,7]);
                                  [ 3  2  1 ]
                                  [         ]
(%o4)                             [ 6  5  4 ]
                                  [         ]
                                  [ 9  8  7 ]
(%i5) dgemm(A,B);
                         [ - 30.0   - 36.0   - 42.0  ]
                         [                           ]
(%o5)                    [ - 66.0   - 81.0   - 96.0  ]
                         [                           ]
                         [ - 102.0  - 126.0  - 150.0 ]
(%i6) A . B;
                            [ - 30   - 36   - 42  ]
                            [                     ]
(%o6)                       [ - 66   - 81   - 96  ]
                            [                     ]
                            [ - 102  - 126  - 150 ]
(%i7) dgemm(A,B,transpose_a=true);
                         [ - 66.0  - 78.0   - 90.0  ]
                         [                          ]
(%o7)                    [ - 78.0  - 93.0   - 108.0 ]
                         [                          ]
                         [ - 90.0  - 108.0  - 126.0 ]
(%i8) transpose(A) . B;
                           [ - 66  - 78   - 90  ]
                           [                    ]
(%o8)                      [ - 78  - 93   - 108 ]
                           [                    ]
                           [ - 90  - 108  - 126 ]
(%i9) dgemm(A,B,c=C,beta=1);
                         [ - 27.0  - 34.0   - 41.0  ]
                         [                          ]
(%o9)                    [ - 60.0  - 76.0   - 92.0  ]
                         [                          ]
                         [ - 93.0  - 118.0  - 143.0 ]
(%i10) A . B + C;
                            [ - 27  - 34   - 41  ]
                            [                    ]
(%o10)                      [ - 60  - 76   - 92  ]
                            [                    ]
                            [ - 93  - 118  - 143 ]
(%i11) dgemm(A,B,c=C,beta=1, alpha=-1);
                            [ 33.0   38.0   43.0  ]
                            [                     ]
(%o11)                      [ 72.0   86.0   100.0 ]
                            [                     ]
                            [ 111.0  134.0  157.0 ]
(%i12) -A . B + C;
                               [ 33   38   43  ]
                               [               ]
(%o12)                         [ 72   86   100 ]
                               [               ]
                               [ 111  134  157 ]

@end example
@opencatbox
@category{Package lapack}
@closecatbox

@end deffn
