[ English | 日本語 ] [ dcmodel ]

dcmodel プログラミングガイドライン

はじめに

dcmodel プログラミングガイドライン (旧 dcmodel コーディングルール. 以下, 本プログラミングガイドラインと称する) は Fortran 90/95 プログラムのソースコード書法, 更に実行プログラムの動作およびデータの入出力に関する スタイルを提案するものである.

本プログラミングガイドラインは以下の 2 点を目指して策定されている.

本プログラミングガイドラインで想定している「読みやすいソースコード」とは, ソースコード中の演算実行部分からどのような計算を行っているか, ひいては元の支配方程式がどのようなものかを比較的簡単に想像できるものである. 読みやすいソースコードは, 改変しやすく, 管理もしやすい. このため, 本プログラミングガイドラインでは, 数式と対応させやすいソースコードを書 くための工夫に力点が置かれている.

本プログラミングガイドラインのソースコード書法の策定においては, ヨーロッパ・米国・日本の気象関係機関で作成されている既存の Fortran プログラムのプログラミングガイドライン ( 参考文献 1,2,3 ) を参考にした. なお, 本プログラミングガイドラインは dcmodel プロジェクトのモデル群の開発と共に検討, 修正を重ねていくものであり, 常に変更の可能性があることに注意されたい.

ルールの概要

ここでは, ソースコードならびにソースコードに埋め込まれる ソースコードリファレンスマニュアルの書法を定める.

基本的な書法

原則として気象庁標準コーディングルール ( 参考文献 1 ) に従う.

ただし, 以下の例外を設ける.

変数命名法

基本ルール

配列型の変数名の基本形は以下のようにする.

(次元情報に関する接頭詞)_(物理的意味)(時間方向添字)

配列ではない変数名の基本形は以下のようにする.

(物理的意味)(時間方向添字)

時間方向に変化しない変数は (時間方向添字) を記述しない.

次元情報に関する接頭詞, 物理的意味, 時間方向添字の付け方については以下で説明する.

特定のモジュール, サブルーチン内でのみ現れる変数の名前については, その都度工夫して変数の名前を付けるようにする. 基本ルールに従わない変数の例については, 基本ルールに従わない変数名 を参照せよ.

次元情報に関する接頭詞・接尾詞

次元情報に関する接頭詞・接尾詞には, 以下の文字を用いる.

s  sin 展開スペクトルデータ
c  cos 展開スペクトルデータ
e  フーリエ展開スペクトルデータ
n  水平全波数スペクトルデータ
m  経度波数スペクトルデータ
w  球面調和関数展開スペクトルデータ(mn を 1 次元に格納)
l  ルジャンドル多項式データ
t  チェビシェフ多項式展開スペクトルデータ(端点で値をとる)
u  チェビシェフ多項式展開スペクトルデータ(中点で値をとる)
   b  チェビシェフ多項式の線形結合 (ノイマンーディレクレー)
   d  チェビシェフ多項式の線形結合 (両端ディレクレー)
   p  チェビシェフ多項式の線形結合 (ディレクレーノイマン)
   v  チェビシェフ多項式の線形結合 (両端ノイマン)
   f  チェビシェフ多項式の線形結合 (ディレクレーノイマン混合型)
   h  チェビシェフ多項式の線形結合 (ディレクレーノイマン混合型一般形)
   q  チェビシェフ多項式の線形結合 (ディリクレ+二階微分または一階微分がゼロ)
q  ヤコビ多項式データ
x  格子点データ(x / 経度座標)
y  格子点データ(y / 緯度座標)
z  格子点データ(z / 動径座標)
p  格子点データ半整数レベル(x / 経度座標)
q  格子点データ半整数レベル(y / 緯度座標)
r  格子点データ半整数レベル(z / 動径座標)
a  格子点データ(任意)
f  物質データ

今後検討を要する次元情報に関する接頭詞・接尾詞は以下のとおりである.

b  Bessel 関数展開スペクトルデータ 
h  エルミート多項式展開スペクトルデータ 

時間方向添字

時間方向の添え字には大文字を用いる. 未来のタイムステップを表すには A を, 現在のタイムステップを表すには N を, 過去のタイムステップを表すに B を用いる.

AA: 時刻 t+2Δt (After のさらに After)
A : 時刻 t+ Δt (After)
N : 時刻 t      (Now)
B : 時刻 t- Δt (Before)
BB: 時刻 t-2Δt (Before のさらに Before)

time split 等を用いた場合のように複数の時間レベルが現れる 場合には, 区別するための任意の文字を追加する.

As: 時刻 t+Δτ (短い時間刻で計算した After)
Al: 時刻 t+Δt  (長い時間刻で計算した After)

    Bl          Nl          Al
   -|-----------|-----------|---->t
   -|-----|-----|-----|-----|---->τ
    Bs    Ns    As    AAs

物理的意味

基本的なルール

個別名

複数の数値モデルにおいて必要となるであろう 名前について個別名を定める. 以下それらを列挙する. 個別名を定めるべきかどうかは適宜判断する必要が ある.

今後検討を要する個別名

パラメータの変数名 (検討事項)

円周率             Pi
ステファン-ボルツマン定数  ??
気体定数           GasConst

重力加速度         Grav
定圧比熱           Cp
定積比熱           Cv
非熱比             Gamma
自転角速度         Omega
気体分子量         Gaswt, MolWt
惑星名             Planet

文字定数の命名法 (検討事項)

計算条件, 状態を指定するような文字列を決めておいた方がよいかもしれない.

各変数に対し境界条件を適用する下請けモジュールまたはサブルーチン内で スイッチなどに用いられる文字列は, 各数値モデルの実装に応じて決めてよい.

基本ルールに従わない変数名

数値モデルのソースコード中には, 変数命名法の基本ルールに従わない名前を持つ変数が存在していてもよい. それらの変数の名前は, それらしい意味を持った名前にする. 原則として数値モデルに関する文書に用いられている名前と対応した変数名にする.

式中に現れる個別の項

たとえば

dT/dt = ADV + DIFF

のように数値モデルに関する文書に書かれており, ADV, DIFF に対応 する変数を使用する場合には, ADV, DIFF に対応した変数名にする.

計算パラメータ

数値モデルに関する文書に記述されていない変数の名前は, それらしい意味 を持った名前をその都度考えて与える.

例えば, 計算パラメータの具体例としては, 時間差分に陰解法を用いた場合 の重み, 音波減衰項の係数, Asselin 時間フィルターの係数, 乱流エネルギー から拡散係数を求める際の比例係数, などが挙げられる.

行列の要素

数値モデルに関する文書には単に「逆行列を解く」とのみ記載されている場合, 実際の逆行列を解く部分で必要になる中間変数の変数名は, それらしい意味を持つものにする.

たとえば係数行列を LU 分解して解く場合, L 行列の要素は LL, U 行列の要素は UU などとする.

配列要素の大きさ

配列要素の大きさを表す変数もそれらしい名前を持たせる.

格子モデルのように, 「配列要素の大きさ」と「物理的に意味のあ る領域の大きさ」を区別する必要がある場合, 以下のように多少長めの変数名を付けておいた方がよいだろう. この場合の欠点は, 配列変数の宣言文が長くなることである.

  • 例 5 : 配列の上限と下限(配列要素の大きさ)を指定する変数の例

    imax, imin, jmax, jmin
  • 例 6 : 物理的に意味のある領域の大きさ(箱の大きさ)を指定する変数の例

    例1: XMax, XMin, PressMax, PressMin
    例2: Xmax, Xmin, Pressmax, Pressmin
  • 例 7 : のりしろ部分の大きさ(壁の大きさ)を指定する変数の例

    例1: XMargin, YMargin
    例2: Xmargin, Ymargin
作業領域
単に一時的に値を格納するためだけに用いられる変数の名前は Work にする.
Do ループ時に配列の要素を指定する変数
数値モデルに関する文書に用いられている添字と対応させやすい変数名にする.

関数命名法

基本ルール

関数名の基本形は以下のようにする.

(返り値の次元情報を示す接頭詞)_(機能)_(引数の次元情報を示す接尾詞)

ただし, 引数が複数である場合, さらにこの後ろに `_(引数の次元情報を示す接尾詞)' を引数の数だけ並べるようにする.

次元情報に関する接頭詞・接尾詞の具体例は 次元情報に関する接頭詞・接尾詞 を参照.

コメントの書き方

コメントの基本ルール

ソースコードファイルには, ファイル中のソースの要約, メインルーチン・モジュール・サブルーチン・関数の機能の要約, 変数・定数・引数・構造体の役割をコメント文として記述する. コメントは, RDOC Fortran90/95 ソースコード解析機能強化版(地球流体電脳倶楽部 dcmodel プロジェクト用) で処理ができる形式で書く.

コメントを付記することにより, ソースコードの読みやすさを向上させるとともに, RDoc のソースコード解析機能を用いてモジュール・サブルーチン・関数・変数・ 定数の仕様に関する解説文書を自動生成できるようにする.

コメントの書法

ファイル自体に関するコメントは, ファイルの一番最初に記述する.

メインルーチン・モジュール・サブルーチン・関数・構造体 に関するコメントは, それぞれ program, module, subroutine, function, type で始まる行よりも下の行に記述する.

サブルーチンや関数の引数・変数・定数に関するコメントは, 原則として, トレイリングコメント (行末に, コメント記号 ` ! ' 後に記述するコメント)として付記する. 記述する内容が行末のみに収まらない場合, 改行して以降の行に記述する. 改行の際, 行頭の位置はそろえる.

授受特性の記述

サブルーチンを呼び出す call 文の引数の後ろには, 授受特性をコメントで記述する. 見た目をそろえるため, subroutine 文にも同様に授受特性を記述する. なお, 引数の授受特性の後ろに引数の説明等を追記しても良い.

call 文に授受特性に関するコメントを付けるのは, サブルーチンの call 文だけでは引数の授受特性がわからないからである.

ポインタを引数に使用する場合は, 変数の定義文の後ろに入出力情報をコメントで記述する. ポインタの場合はソースコードに intent 属性を付記できないからである.

ソースコード例を 例 2 に示す.

(検討事項) 授受特性に加え, 割り付け状態がどのようになっているかを示す ことを推奨する. ソースコード例を 例 3 に示す. しかし, 授受特性が in と inout のポインタは既に割り付けられているべきであり, 一方で授受特性 が out のポインタは既に解放されているべきであることは明らかである. 従っ て, in, out, inout を指定すればポインタの割り付け状態を別途示す必要は ないかもしれない.

入出力データ

数値モデルに入出力するデータを格納したファイルは, 原則として, NAMELIST ファイル , リスタートファイル, ヒストリーファイルの 3 種類であるとする.

リスタートファイルとヒストリーファイルの詳細に関しては リスタートファイルとヒストリーファイル を参照せよ. NAMELIST ファイルに関しては, NAMELIST ファイルに関するルールを参照せよ.

データの入出力には, gtool4 プロジェクトの データ I/O ライブラリ gt4f90io ( 参考文献 5 ) を使用する. 入出力インターフェースの形式をそろえることにより, 複数の数値モデルにおけるソースの読みやすさを高める.

入力データ

原則的に, 計算の開始時において, リスタートファイルと NAMELIST ファイルとの組を入力する.

リスタートファイルには初期値としての数値データが格納される. NAMELIST ファイルにはリスタートファイルの名前や各種パラメータの値の設定などを記述する. NAMELIST ファイル内でリスタートファイル名を指定しない場合には, プログラムの内部でデフォルトの初期値を作成し, その初期値からプログラムをスタートさせる. 各種のパラメータは NAMELISTファイル内で指定するものを用いる.

NAMELIST ファイル名を与えずにプログラムを実行した場合, プログラム内部でデフォルトの初期値を生成し, その初期値から プログラムをスタートさせる. 各種のパラメータはデフォルトのものを用いる.

出力データ

計算の実行中および実行終了時には, 必要に応じてリスタートファイルとヒストリーファイルを出力する.

数値モデルが出力するデータに与えるデータ時刻としては, 入力するリスタートファイルのデータ時刻を引き継いだもの, およびモデル時刻の両方が許容されていなければならない. どちらの方法を選択するかの指定は NAMELIST ファイルでなされるように なっていなければならない.

ここで, モデル時刻とは数値モデル中の積分時間を指し, データ時刻とは入出力するデータに与えられる時刻を指す. 以下の例を参照せよ.

  • 例 1 : NCEP の 2000 年 1 月 1 日のデータを初期値に与えて 1 年積分する場合の例

    モデル時刻                              : 0 日 〜 1 年
    初期値データのデータ時刻                : 2000 年 1 月 1 日
    出力されるリスタートファイルのデータ時刻: 2000 年 12 月 31 日 
  • 例 2 : 理想的な初期値を与えて 1 年積分する場合の例

    モデル時刻                              : 0 日 〜 1 年
    初期値データのデータ時刻                : 0 日
    出力されるリスタートファイルのデータ時刻: 1 年

リスタートファイルとヒストリーファイル

数値モデルは, リスタートファイルとヒストリーファイルを別々のファイルに分けて出力する. リスタートファイルとヒストリーファイルとを分けるのは, 出力する個々のデータがリスタートに必要なのか不要なのかを明確にする利点があるからである.

リスタートファイルとヒストリーファイルの説明は以下の通りである.

リスタートファイル

いわゆる初期値として必要なデータや継続実験 を行うためのデータ(リスタートデータ)を格納するファイルである. 格納されるデータの種類はプログラムによって異なる.

1 つのリスタートファイルには, 継続実験を行うためにに必要なデータ全てを 出力すること. 正しくリスタートを行うため, プログラム内で用いる最も高い精度と同じ精度のデータを格納する.

プログラムのスタート, リスタートに不要なデータは含まないようにする.

リスタートファイルの出力のタイミングは任意だが, プログラム終了時には必ず出力する.

ヒストリーファイル

プログラムによって生成された結果のデータを出力するファイルである. 多くの場合, 特定の変数の時系列データが格納される.

ヒストリーファイルにはプログラム実行者が必要とするデータを任意で出力する. 必要となるデータは場合によって異なるため, 出力する変数の種類や データを書き出すタイミングはプログラム実行者によって決められる. 複数のデータを 1 つのファイルにまとめても, 複数のファイルに分けても良い. 精度もプログラム実行者が決めて良い.

ヒストリーファイルにモデル時刻ゼロのデータ (プログラムを実行する際に入力した リスタートファイルのデータ) を出力したい場合もあろう. モデル時刻ゼロのデータを出力できるかどうか, NAMELIST によって動的に 変化できるようにしておくべきである. デフォルトの動作としては, リスタートファイルを入力する際には出力し, 初期値データを自身で生成する際には出力しない, とするのが良いように思われる.

平均値を計算する際に座標重みを必要とする数値データの場合には, 座標重みのデータも各ヒストリーファイルに格納することを推奨する.

ヒストリーファイルの名称について

個々のヒストリーファイルに特定の変数の時系列データを格納する場合, そのファイル名はソースコード内で使用されている変数名の物理的意味 をあらわす文字列(例: 変数名が xyz_Temp であれば Temp の部分)を 含んだものとすることを推奨する.

NAMELIST ファイルに関するルール

NAMELIST ファイルの書法

NAMELIST ファイルには, 入力する定数/変数の説明を以下の形式のコメントで記述する.

NAMELIST ファイル名の取得方法

NAMELIST ファイル名の取得には組み込み関数 getarg を使用する.

この方法を採用する理由は以下の通りである.

この方法には以下の欠点も指摘されている.

NAMELIST 変数のデフォルト値の設定

NAMELIST 変数で入力する値にはプログラム内部でデフォルト値を設定し, NAMELIST 変数が入力できない場合 (NAMELIST ファイル内に変数が 記述されていない場合) にもなんらかの値が設定されるようにする. これは, NAMELIST 変数が無くても正常に動作が続くことを強制する のではなく, 場合によってはプログラムを終了させることも含む.

これにより不定な変数がプログラム内で用いられるのを防ぐことができ, 結果として予期しない動作を抑止することができる.

モジュールとポインタの使用方法

モジュールを使用する際の注意

ポインタを使用する際の注意

参考文献

  1. 気象庁標準コーディングルール
  2. ヨーロピアンスタンダード ( オリジナル / 気象研究所による和訳 )
  3. The GFDL Flexible Modeling System (FMS) のコーディングマニュアル
  4. 階層的地球流体スペクトルモデル集 SPMODEL
  5. gtool4 プロジェクト
  6. RDOC Fortran90/95 ソースコード解析機能強化版(地球流体電脳倶楽部 dcmodel プロジェクト用)

付録

  1. emacs 利用の際に Tab キーで字下げを行う時に

    このファイルに書きこまれる内容を ~/.emacs に追加することで, タブによる自動字下げの文字数を気象庁標準コーディングルールに 合わせることができる.

関連する URL

使用上の注意とライセンス規定

ライセンス規定

dcmodel プログラミングガイドラインに関する全ての権利は dcmodel プログラミングガイドライン作成メンバーに属する. dcmodel プログラミングガイドラインは「無保証・無責任」の原則 の元で利用が可能である. dcmodel プログラミングガイドラインを利用することによって生じる いかなる結果に対しても dcmodel プログラミングガイドライン作成メンバーは責任を 持たない. 変更の有無に関わらず, 上記著作権表示・責任限定規定・および本条件 書を必ず含める限りにおいて dcmodel プログラミングガイドラインを再配布してかまわない.

使用上の注意

dcmodel プログラミングガイドラインは, 研究・教育の場で用いられることを前提とし ています. 利用する場合には上記の正式なライセンス規定に従ってくださ い. 教育現場においては自由に使用・改変・再配布していただいて結構です.

dcmodel プログラミングガイドラインを利用して得られた科学技術的成果を論文や Web 等 にて発表する際には, その旨を記し, リファレンス等に挙げて頂くようお願いします.

引用例 (和文)
地球流体電脳倶楽部 dcmodel プロジェクト, 2008: dcmodel プログラミングガイドライン, http://www.gfd-dennou.org/library/dcmodel/, 地球流体電脳倶楽部.
引用例 (英文)
GFD Dennou Club Dcmodel Project, 2008: dcmodel programming guideline, http://www.gfd-dennou.org/library/dcmodel/, GFD Dennou Club.

dcmodel プログラミングガイドライン作成メンバー

2009 年度

石渡 正樹, 小高 正嗣, 佐々木 洋平, 杉山 耕一朗, 高橋 芳幸, 竹広 真一, 中島 健介, 林 祥介, 堀之内 武, 森川 靖大, 納多 哲史, 山下 達也

2008 年度

石渡 正樹, 小高 正嗣, 佐々木 洋平, 杉山 耕一朗, 高橋 芳幸, 竹広 真一, 中島 健介, 林 祥介, 堀之内 武, 森川 靖大, 山田 由貴子, 納多 哲史, 山下 達也

2007 年度

石渡 正樹, 小高 正嗣, 佐々木 洋平, 杉山 耕一朗, 高橋 芳幸, 竹広 真一, 中島 健介, 林 祥介, 堀之内 武, 森川 靖大, 山田 由貴子

2006 年度

石渡 正樹, 小高 正嗣, 杉山 耕一朗, 高橋 芳幸, 竹広 真一, 中島 健介, 林 祥介, 堀之内 武, 森川 靖大, 山田 由貴子

2005 年度

石渡 正樹, 小高 正嗣, 柿並 義宏, 北守 太一, 杉山 耕一朗, 高橋 芳幸, 竹広 真一, 谷口 博, 中島 健介, 林 祥介, 堀之内 武, 森川 靖大, 山田 由貴子

2004 年度

石渡 正樹, 小高 正嗣, 北守 太一, 杉山 耕一朗, 高橋 芳幸, 中島 健介, 林 祥介, 森川 靖大, 山田 由貴子