**********************************************************************
*     ISPACK利用の手引き (ver 1.0.4)          By 石岡圭一 (2015/06/30)
**********************************************************************
-----------------------------------------------------------------------
・概要
-----------------------------------------------------------------------

  このライブラリ(ISPACK)は, 主に簡単な流体方程式の数値計算に必要となる
基本的な道具(スペクトル変換, 時間積分, IO, 等)をサブルーチン群としてま
とめたものである. 各サブルーチンともできるだけ単独で使えることを目標と
して設計されているため, お気楽な統合環境では無いことに注意されたい. す
なわち, これらのサブルーチン群をどのように組み合わせて使うかはすべてユー
ザ次第である.

-----------------------------------------------------------------------
・著作権および使用許諾
-----------------------------------------------------------------------

  本ライブラリの著作権は石岡圭一に属する. また, 使用許諾については
COPYRIGHTファイルに書いてあるように, GNU LESSER GENERAL PUBLIC LICENSE
(LGPL-2.1 またはそれ以降のバージョン)に従う. なお, 本ライブラリを用いて
行った数値実験の結果等を論文に発表する際には, 本ライブラリを用いたこと
を記してくれるとありがたい(これはあくまで希望であって, いわゆる宣伝条項
ではない).

-----------------------------------------------------------------------
・構成
-----------------------------------------------------------------------

本パッケージは以下のようなディレクトリ構成になっている.

  - README: 本ファイル
  - README.en: 本ファイルの英語版
  - CHANGELOG: 変更履歴
  - COPYRIGHT: 著作権を記述したファイル(英文)
  - LGPL: GNU LESSER GENERAL PUBLIC LICENSE (LGPL)
  - Makefile: Makefileの本体
  - Mkinclude: Makefileにおいて読み込まれるインクルードファイル
		(デフォルトでは, 通常の Linux環境に合わせてある).
  - Mkinclude.sub: 各サブディレクトリ内のMakefileにおいて読み込まれる
		   インクルードファイル

  - appack: 時刻計測ルーチン
  - bspack: 配列のコピー等の下層ルーチン群
  - fepack: 上位レベルのIOルーチン(機種依存性のないファイルIO)
  - fhpack: 下位レベルのIOルーチン(単純なIOルーチン群)
  - flpack: 実数の内部表現などを変換するフィルタールーチン群
  - ftpack: 高速Fourier変換を行うルーチン群
  - p2pack: Double-Fourierモデルのための変換ルーチン群
  - pzpack: p2pack と同様の機能を fftj を使って実現したもの.  
  - p3pack: 周期境界条件3次元モデルのためのルーチン群
  - p3pack-mpi: p3packをMPIで並列化したもの
  - c2pack: チャネルモデルのための変換ルーチン群
  - u2pack: y方向無限領域のモデルのための変換ルーチン群
  - ujpack: ujpack と同様の機能を fftj を使って実現したもの.  
  - snpack: 球面調和関数変換を行うルーチン群(ベクトル計算機向け)
  - snpack-mpi: snpackをMPIで安直並列化したもの
  - sppack: snpack の応用ルーチン群
  - sppack-mpi: sppackをMPIで安直並列化したもの
  - sopack: 球面上の2次元非発散流体の渦度方程式の非線形項を効率良く計算する
            ルーチン
  - sopack-mpi: sopackをMPIで安直並列化したもの
  - sjpack: 球面調和関数変換を行うルーチン群(スカラー計算機向け)
  - sjpack-mpi: sjpackをMPIで安直並列化したもの
  - sjpack-cuda: sjpackの変換ルーチンをCUDA化したもの    
  - tdpack: 時間積分のためのルーチン群(常微分方程式を解く)
  - dkpack: 円盤領域のスペクトル法のためのルーチン群(この中では
            LAPACK を利用しているので, これを含める場合は別途
	    LAPACKもインストールしておくこと)
  - sample: 上のサブルーチン群を用いて構成した, 流体の数値実験等のための
	    サンプルプログラムの置き場所
  - .fftj: 同梱している fftj-0.2 のディレクトリ. Makefile のみオリジナル
           の状態から書き換えてある.
           (fftjについての詳細は .fftj/README を参照.)

なお, 各**packのディレクトリ以下には, 次のような2つのディレクトリがあ
るので, 必要に応じて参照されたい.

    src: 各サブルーチン群のソースを収めたディレクトリ
    doc: 各サブルーチン群のドキュメント(LaTeX形式)を収めたディレクトリ

また, バージョン 1.0.0 以前のバージョンに含まれていた obsolete なパッ
ケージ(n2pack, stpack, および smpack) は, 本バージョンには含まれてい
ないので注意されたい.

-----------------------------------------------------------------------
・ライブラリのインストール方法
-----------------------------------------------------------------------

  1) Mkincludeファイル内のマクロ定義を自分の環境に合わせて変更

      それぞれのマクロの意味は自明だとは思うが, 変更が必要となりうる項
    目についてだけ解説する.

    - DIRS: ライブラリ化したいパッケージを列挙する. デフォルトでは全パッ
         ケージになっているが, もし全パッケージが必要ない場合には, 必
         要なパッケージのみを書くこと(例えば, IOライブラリのみ必要な場
         合は, DIRS = flpack fhpack fepack だけでよい).

    - LIBNAME: 静的ライブラリの名前. 重複するおそれがなければ,
	デフォルトの libisp のままでよい.

    - DESTDIR: 静的ライブラリの置き場所のディレクトリ.

    - FC,FFLAGS: FORTRAN77 コンパイラ名および, 最適化のオプションなどの
	フラグ. 

    - MPIFC,MPIFFLAGS: FORTRAN77で書かれたMPIプログラムをコンパイル
        するためのコンパイラ名および, それに対応する最適化のオプション
	などのフラグ.

    - CC,CFLAGS: Cコンパイラ名およびそのためのフラグ. 
	
    - DCLFRT: sample ディレクトリ中のサンプルプログラムでは描画に
         dcl (http://www.gfd-dennou.org/arch/dcl/) を用いるので, 
	 dcl のライブラリをリンクするコンパイラ名(通常は dclfrt)
	 を指定する( ispack のインストール自体には dcl は必要ない).
	   
    - SSE: 同梱されている fftj および sjpack を make する際に与えるスィッチ.
        環境に合わせて以下のいずれかを指定する.
      * SSE2命令を持つ Intel x86 互換CPU(Pentium4以降)上の 32bit Linux 環境:
	     → sse32
      * SSE2命令を持つ Intel x86 互換CPU(Pentium4以降)上の 64bit Linux 環境:
	     → sse64
      * AVX命令を持つ Intel x86 互換CPU(Sandy Bridge以降)上の 64bit Linux 環境:
	     → avx
      * 上記以外
	     → fort

    - CPPFLAGS:	IOルーチン fhpack および fepack で使われるフラグ. 各機
        種の性質に応じて指定すること. これらのルーチン群を使わなければ
        デフォルトのままで構わない.

       i) IOの仕方に関するフラグ

          UNIX系OS等で, 直接参照入出力が問題無い場合は
  	
		-DDIRECT 

	  を指定. それ以外の場合(例えば, メインフレーム系等で直接参照
	  入出力がうまくできない場合など)には

		-DSEQUENTIAL

	  を指定すること. また, 直接参照入出力が問題無くとも, 書式なし
	  だと問題を生ずる場合もある(Linux でも ifort を使っている場合等)
	  ので, そのような機種では, 

	        -DDIRECT -DFORMAT

	  を追加すること.

       ii) 実数の内部表現に関するフラグ

	   その機種の実数の内部表現に合せて,

	        -DIEEE (IEEE表現) または -DIBM (IBM表現またはM形式)

	   のいずれかを指定すること.

       iii) 文字の内部表現に関するフラグ

	   その機種の文字の内部表現に合せて,

	        -DASCII (ASCIIコード) または -DEBCDIC (EBCDICコード)

	   のいずれかを指定すること.

       iv) エンディアンに関するフラグ

	   その機種がリトルエンディアンである場合には,

 		-DLEN

	   を指定すること. ビッグエンディアンなら何も指定しなくてよい.

       ※指定例)
       
	  - x86な CPU上の Linux で gfortran を使っている場合:

		CPPFLAGS = -DDIRECT -DIEEE -DASCII -DLEN 

	  - x86な CPU上の Linux で ifort を使っている場合:

		CPPFLAGS = -DDIRECT -DFORMAT -DIEEE -DASCII -DLEN 

  2) この README のあるディレクトリにおいて, 以下を実行.

	% make

      以上で DESTDIR で指定したディレクトリ以下にライブラリ libisp.a
      が作成されるはずである.

      ※ make 中にいくつかのパッケージ, 特に I/O まわり (fhpack,
      fepack, flpack など)で文法違反のワーニングが出ることがあるが,
      通常問題ないはずなので, 気にしないこと.

  3) ライブラリ作成後, 不要となったオブジェクトファイルを掃除したい場
     合は,

	% make clean

      とすればよい. また,

	% make veryclean

      とするとライブラリおよびパッケージファイルも消去され, make 前の状
    態に戻る. CPPFLAGS のオプション等を間違えた場合は, これによって最初
    からインストールをやりなおすこと.

-----------------------------------------------------------------------
・ライブラリの使い方
-----------------------------------------------------------------------

  上で生成されたライブラリ(libisp.a)は, 通常のFORTRAN77のライブラリで
あるので, 適宜メインプログラムのコンパイル時にリンクしていただければ使
用可能である. 具体的な使用例は sample ディレクトリ以下を参考にされたい.

-----------------------------------------------------------------------
・サンプル集について
-----------------------------------------------------------------------

  本ライブラリを用いて構成された簡単な流体実験等のためのサンプルプログ
ラムを sample ディレクトリ以下にそれぞれディレクトリに分けて置いてある.
現在のところ, 以下のようなものがある.

 - 3D-box: 3次元非圧縮流体数値実験のためのプログラム(3次元周期境界条件)
 
 - 3D-box-mpi: 3D-box のプログラムを MPIで並列化したもの

 - 2D-plane: 2次元流体数値実験のためのプログラム(平面; ダブルピリオディック
             境界条件)

 - 2D-channel: 2次元流体数値実験のためのプログラム(チャネルジオメトリ;
             ピリオディック・スリップ境界条件)

 - 2D-disk-inviscid-shallow: 2次元流体数値実験のためのプログラム
                             (円盤領域の非粘性浅水方程式)

 - non-div-2d-sphere: 2次元非発散流体数値実験のためのプログラム(球面)

 - non-div-2d-sphere: 2次元非発散流体数値実験のためのプログラム(球面)

 - non-div-2d-sphere-mpi: non-div-2d-sphere を MPIで並列化したもの

 - non-div-2d-sphere-sjpack: 2次元非発散流体数値実験のためのプログラム(球面)
                             を sjpack で実装したもの
 
 - shallow-water-sphere: 浅水方程式数値実験のためのプログラム(球面)

 - shallow-water-sphere-mpi: shallow-water-sphere を MPIで並列化したもの

 - IO: f[ehl]packを用いたIOのサンプルプログラム
 
 - snpack-openmp-test: OpenMP によって並列化された snpack 中の変換
                       ルーチンのテストプログラム

 - sjpack-test: sjpack のテストプログラム
 
 - sjpack-cuda-test: sjpack-cuda のテストプログラム

 - sjpack-mpi-test: sjpack-mpi のテストプログラム

それぞれの利用方法については, 各ディレクトリ以下にあるMEMOファイルを参
照されたい.

-----------------------------------------------------------------------
・並列化について
-----------------------------------------------------------------------

  MPIで並列化されたパッケージ(現在は p3pack-mpi, snpack-mpi, sppack-mpi, 
sopack-mpi)を使用する場合には, コンパイラや実行コマンドなどについて各処
理系におけるMPIのマニュアルを参照のこと. なお, 並列化されたパッケージの
ライブラリの具体的な呼出し方などについては, サンプルプログラム(現在は 
3D-box-mpi, non-div-2d-sphere-mpi, shallow-water-sphere-mpi)を参考にされ
たい.

  また, p3pack-mpi では プロセス数が 1024 以下であることを仮定している.
もし 1024 より多くのプロセス数になりうる場合は, p3pack-mpi/src/
以下にあるプログラム中で
      PARAMETER(MP=1024)
として設定されているMPの値を適宜変更してライブラリを再構築すること.

  OpenMPで並列化されたパッケージ(現在は snpack, pzpack, および sjpack)
を使用する場合には, コンパイラオプションの設定や実行時の環境変数の設定
などについて各処理系におけるマニュアルを参照のこと.

-----------------------------------------------------------------------
・CUDA版について
-----------------------------------------------------------------------

  Nvidia社製のGPGPU上での利用を想定して, 球面調和関数変換のパッケージ
sjpackの一部の変換ルーチンをCUDA化したものを sjpack-cuda として提供して
いる. 詳細については sjpack-cuda/doc 以下にあるドキュメントを参照されたい.

  なお, この sjpack-cuda はデフォルトではライブラリに含めない設定になっ
ているため, 利用する際には, Mkinclude 中で変数 NVCC と NVCFLAGS を適切
に設定した上で, 変数 DIRS に sjpack-cuda を追加してから make すること.

-----------------------------------------------------------------------
・その他
-----------------------------------------------------------------------

  このパッケージに対するバグレポートや意見は E-mail で

     ishioka@gfd-dennou.org

までお寄せいただきたい.
