ruby-list

西松と申します.

Fortran型の配列をRubyで扱うための拡張ライブラリとして
FortranArrayと名付けたものを書きはじめました.

下に README-jp.rd を添付しました.
tar-ballを
http://www-lab.imr.tohoku.ac.jp/~t-nissie/computer/software/FortranArray/README-jp.html
http://www-lab.imr.tohoku.ac.jp/~t-nissie/computer/software/FortranArray/FortranArray-0.00.23.tar.gz
に置きました.
% ls -l FortranArray-0.00.23.tar.gz 
-rw-r--r--   1 t-nissie kawazoe     22014 Aug 12 19:30 FortranArray-0.00.23.tar.gz
% md5sum FortranArray-0.00.23.tar.gz
52838c8f68354e4edf4c62da46007dec  FortranArray-0.00.23.tar.gz

まだ実装していない機能が多いのですが, このままぼく一人
で書き進むのがちょっと不安なので, 皆様のご意見, 感想,
誤りの指摘などをいただければ幸いです. よろしくお願いし
ます.


=begin
= README before using Ruby/FortranArray (Japanese version)
Ruby/FortranArrayはFortran型の配列をRubyで扱うための
拡張ライブラリです.

== Ruby/FortranArrayの特徴
* 要素は倍精度実数または倍精度複素数に限定 (@kind = 'D' or 'Z').
* メモリに要素がFortranと同じ順序で並ぶ.
* デフォルトでインデックスが1から始まる.
* 要素のアクセス方法 (例: 二次元配列 mat_A[i,j]) は Fortran (A(i,j)) や
  数学の行列の添字 (A_{ij}) と同じ.
* Rangeを使ってインデックスの範囲を任意に指定可能. 0や負の値から始める
  こともできる.
* 自然な部分配列の参照 (手抜きともいう).
* 部分配列の参照方法のせいでコストはかかるが mat_A[j][i] という
  要素のアクセスも可能.
* BLAS (dgemv, gemv, symv, zsymvのみ実装済), LAPACK (未実装) への自然な
  インタフェース.
* BLAS, LAPACK の Matrix type (@matrix_type = 'GE', 'SY', 'HE', 'TR',
  'GB', 'SB', 'HB', 'TB', 'SP', 'HP', 'TP'), UPLO (@uplo = 'UPPER' or
  'LOWER'), DIAG (@diag = 'NON-UNIT' or 'UNIT'), band width (@band_width,
  @band_width_u) を属性として持つので, あるメソッドから呼ばれる BLAS,
  LAPACK のサブルーチンがある程度自動的に選択される.
* FFT. 数種のOSに付属の科学計算ライブラリの FFT subroutine を共通の
  メソッドでラップ (未実装).
* Rubyで高速な数値計算が可能.
* logical dimension (ld) を指定できるので, 基数2のアルゴリズムで
  発生しがちなキャッシュミス, バンクコンフリクト等による低速化を
  回避できる (アホくさいけどかなり切実).
* Matrix type や ld は一度指定してしまえば忘れることができる.
* RubyUnitで書かれたtestcaseを使ってTestをしながら開発が可能.

== Ruby/FortranArrayの欠点かもしれないこと
* +,-,*,/,%,** 等の演算子を定義していない.

== NArrayとの比較
NArray ((<[NArray]>)) はRubyの拡張ライブラリで, 強力な多次元((*数値*))配列クラス
を提供している. 西松はNArrayのソースコードを見ながらFortranArrayを書いた.
NArrayとFortranArrayとを比較すると:
* NArrayは 1,2,4 byte 整数, 単/倍 精度 実数/複素数, およびRubyオブジェクトを
  要素に持つことができる. FortranArrayは倍精度実数または倍精度複素数のみ.
* NArrayのインデックスは常に0から始まる. FortranArrayは任意.
* NArrayではNArrayのサブクラスとして行列 (NMatrix), ベクトル (NVector) が
  定義されている. FortranArrayでは特に区別しない.
* 数学の行列: A_{ij} → NArray: mat_A[j-1, i-1], FortranArray: mat_A[i,j]
  (であっていると思う).
* NArrayには強力な部分配列機能がある. FortranArrayのは手抜き.

== 入手方法
Please download a tar-ball from:
((<URL:http://www-lab.imr.tohoku.ac.jp/%7Et-nissie/computer/software/FortranArray/>))

== インストール方法
 $ ruby install.rb config
 $ ruby install.rb setup
 # ruby install.rb install

== テストして動作を確認したOS
:GNU/Linux
  Turbolinux 6.0 Workstation, ruby 1.6.6 (2001-12-26) [i686-linux], FortranArray-0.00.23
:sgi IRIX64
  IRIX 6.5, ruby 1.6.7 (2002-03-01) [mips-irix6.5], FortranArray-0.00.23
:IBM AIX
  AIX+ESSL, ruby 1.6.6 (2001-12-26) [powerpc-aix4.3.3.0], FortranArray-0.00.23

== 作者
西松 毅 ((<URL:mailto:t-nissie@imr.tohoku.ac.jp>))

== 書いた日
2002,08,12

== FortranArrayクラスメソッド
--- FortranArray.new(ndim,range[0], ... , range[ndim-1],ld[0], ... , ld[ndim-1],kind='D', matrix_type='GE', uplo='UP', diag='NON-UNIT', band_width, band_width_u)
    新しいFortranArrayを作る.
    :ndim
      配列の次元.
    :range[i]
      範囲. 整数 n が指定された場合は 1..n と等価.
    :ld[i]
      logical dimension. 整数 n が指定された場合は 1..n と等価.
      省略時は ld[i]==range[i] になる.
    :kind
      'D' - double precision (default value)
      'Z' - complex double
    :matrix_type
      'GE', 'SY', 'HE', 'TR', 'GB', 'SB', 'HB', 'TB', 'SP', 'HP', 'TP'
    :uplo
      'UPPER' - upper triangular (はじめの２文字だけを見るので'UP'と省略可)
      'LOWER' - lower triangular (はじめの２文字だけを見るので'LO'と省略可)
      general matrix のときは意味を持たない.
    :diag
      'NON-UNIT' - NOT unit triangular matrix
      'UNIT'     - unit triangular matrix
      triangular matrix のときにのみ意味を持つ.
    :band_width
      整数で指定できるldと区別するためにband_widthを指定する場合は
      その前に必ず文字列の引数を置くこと.
      matrix_type が 'GB' (General Band) のときはlowerのband_width.
    :band_width_u
      upperのband_width. matrix_type が 'GB' (General Band) のとき指定.

== FortranArrayインスタンスメソッド:
--- FortranArray#ndim
    @ndim の reader.
--- FortranArray#range
    @range の reader.
--- FortranArray#ld
    @ld の reader.
--- FortranArray#kind
    @kind の reader. 'D' か 'Z' のどちらかを返す.
--- FortranArray#matrix_type
    @matrix_type の reader.
    'GE', 'SY', 'HE', 'TR', 'GB', 'SB', 'HB', 'TB', 'SP', 'HP', 'TP' のどれかを返す.
--- FortranArray#uplo
    @uplo の reader. 'UPPER' か 'LOWER' のどちらかを返す.

--- FortranArray#set_all(x)
    配列の要素すべてを x にする.
    x は倍精度実数か倍精度複素数に変換されて用いられる.
    @rangeの中の要素だけでなく, @ldの中の要素すべてが
    x になる (その方がコーディングが楽だったから) .

--- FortranArray#[]
    reference or partial array.

    @ndimより少ない数のFixnumのインデックスで指定した部分配列は
    「親の配列」の要素をそのまま参照している. そのため, この部分
    配列を書き換えると「親の配列」も変わる.

    Partial array assigned by Ranges is not implemented yet.
    こっちはクローンを作る予定.

--- FortranArray#[]=
    代入.
    @kind='Z' な FortranArray に Float, Fixnum, Bignum などを代入
    することは可能. 虚部は0になる.
    @kind='D' な FortranArray に Complex を代入しようとすると TypeError
    になる.

--- FortranArray#set_all(all_value)

--- FortranArray#data(val1, val2, ...)
      各要素に val1, val2, ... を代入.

--- FortranArray#to_s(with_attr=TRUE, format, fd)
    FortranArrayをFortran風に書き出す.
    第一引数がFALSEの場合は属性 (@ndim, @range, @ld, @kind, @matrix_type,
    @uplo, @diag, @band_width, @band_width_u) を書かない.

    formatが指定されたらそれが用いられる.

    fd が指定されたならそこに書き出す (未実装).
    FortranArrayがデカくてStringのためのメモリ領域を確保できない
    ときなどに使う.
    こfd が指定された時の戻り値は不定?????

--- FortranArray#clone
      (未実装)

--- FortranArray#gemv(mat_A, x, alpha=(1.0, 0.0), beta=(0.0, 0.0), trans='N', incx=1, incy=1, m = mat_A.range[0].length, n = mat_A.range[1].length, lda = mat_A.ld[0].length)
      incx, incy の方が m, n, lda より設定する機会が多そうだから前にした.
      BLASのdgemvまたはzgemvを呼ぶ.

--- FortranArray#symv(mat_A, x, alpha=(1.0, 0.0), beta=(0.0, 0.0), uplo=mat_A.uplo, incx=1, incy=1, n = mat_A.range[0].length, lda = mat_A.ld[0].length)
      BLASのdsymvまたはzsymvを呼ぶ.

== 参考文献
:[NArray]
  Masahiro TANAKA: ((<"NArray"|URL:http://www.ir.isas.ac.jp/~masa/ruby/>))

:[BLAS]
  ((<URL:http://www.netlib.org/blas/>))

:[LAPACK]
  ((<URL:http://www.netlib.org/lapack/>))

=end

-- 
 love && peace && free_software
 NISHIMATSU Takeshi   t-nissie@imr.edu OR t-nissie@imr.tohoku.ac.jp
 西松 毅