gtool_history_nmlinfo_generic.f90

Go to the documentation of this file.

!> @file gtool_history_nmlinfo_generic.f90
!>
!> @author Yasuhiro MORIKAWA
!> @copyright Copyright (C) GFD Dennou Club, 2007-2026. All rights reserved. <br/>
!>            License is BSD-2-Clause. See [COPYRIGHT](@ref COPYRIGHT) in detail
!>
!> @en
!> @brief Interface of procedures provided from gtool_history_nmlinfo
!> @enden
!>
!> @ja
!> @brief gtool_history_nmlinfo より提供される手続の引用仕様宣言
!> @endja
 
module gtool_history_nmlinfo_generic
  !>
  !> @en
  !> @brief Interface of procedures provided from gtool_history_nmlinfo
  !>
  !> See gtool_history_nmlinfo for brief of this module.
  !>
  !> ### Procedures List
  !>
  !> - HstNmlInfoCreate : Constructor of gtool_history_nmlinfo_types::GTHST_NMLINFO
  !> - HstNmlInfoClose : Destructor of gtool_history_nmlinfo_types::GTHST_NMLINFO
  !> - HstNmlInfoPutLine : Print information of gtool_history_nmlinfo_types::GTHST_NMLINFO
  !> - HstNmlInfoInitialized : Check initialization of gtool_history_nmlinfo_types::GTHST_NMLINFO
  !> - HstNmlInfoDefineMode : True is returned if current state is define mode
  !> - HstNmlInfoEndDefine : Transit define mode about information of variables to output mode
  !> - HstNmlInfoReDefine : Transit output mode to define mode about information of variables
  !> - HstNmlInfoAdd : Add information of variables
  !> - HstNmlInfoDelete : Delete information of variables
  !> - HstNmlInfoResetDefault : Reset to default settings
  !> - HstNmlInfoInquire : Inquire information of variables
  !> - HstNmlInfoAssocGtHist : gtool_history_types::GT_HISTORY correspond to variable is returned
  !> - HstNmlInfoOutputStepDisable : Configure that output_step returns .false. already
  !> - HstNmlInfoOutputStep : True is returned when a configuration of output is valid
  !> - HstNmlInfoOutputValid : True is returned when current time is output timing
  !> - HstNmlInfoNames : Return list of registered variable identifiers (function)
  !> - HstNmlInfoGetNames : Return list of registered variable identifiers (subroutine)
  !> - HstNmlInfoAllVarIniCheck : Check uninitialized variable names
  !> - HstNmlInfoSetValidName : Set validation to variable names
  !> - HstNmlInfoAllNameValid : Check invalid variable names
  !> @enden
  !>
  !> @ja
  !> @brief gtool_history_nmlinfo より提供される手続の引用仕様宣言
  !>
  !> モジュールの概要については, gtool_history_nmlinfo
  !> を参照ください.
  !>
  !> ### 手続リスト
  !>
  !> - HstNmlInfoCreate : gtool_history_nmlinfo_types::GTHST_NMLINFO 型変数の初期設定
  !> - HstNmlInfoClose : gtool_history_nmlinfo_types::GTHST_NMLINFO 型変数の終了処理
  !> - HstNmlInfoPutLine : gtool_history_nmlinfo_types::GTHST_NMLINFO 型変数に格納されている情報の印字
  !> - HstNmlInfoInitialized : gtool_history_nmlinfo_types::GTHST_NMLINFO 型変数が初期設定されているか否か
  !> - HstNmlInfoDefineMode : 定義モードの場合に真を返す
  !> - HstNmlInfoEndDefine : 変数情報定義モードから出力モードへ変更
  !> - HstNmlInfoReDefine : 出力モードから変数情報定義モードへ変更
  !> - HstNmlInfoAdd : 変数情報の追加
  !> - HstNmlInfoDelete : 変数情報の削除
  !> - HstNmlInfoResetDefault : デフォルト設定のみに戻す
  !> - HstNmlInfoInquire : 変数情報の問い合わせ
  !> - HstNmlInfoAssocGtHist : 変数に応じた gtool_history_types::GT_HISTORY 型変数を返す
  !> - HstNmlInfoOutputStepDisable : output_step が常に .false. を返すよう設定する
  !> - HstNmlInfoOutputStep : 出力の設定が有効である場合に真を返す
  !> - HstNmlInfoOutputValid : 現在の時刻が出力のタイミングの場合に真を返す
  !> - HstNmlInfoNames : 登録されている変数名リストを返す (関数)
  !> - HstNmlInfoGetNames : 登録されている変数名リストを返す (サブルーチン)
  !> - HstNmlInfoAllVarIniCheck : 初期設定されていない変数名のチェック
  !> - HstNmlInfoSetValidName : 変数名の有効性を設定
  !> - HstNmlInfoAllNameValid : 無効な変数名のチェック
  !> @endja
  !>
  !>
  !> @en
  !> ### Usage
  !>
  !> Use this module as follows.
  !>
  !> Sample Fortran programs generator (Ruby script) is available from
  !> http://www.gfd-dennou.org/library/dcpam/dcpam4/dcpam4_current/script/f90/dcmodel_f90sample_maker.rb .
  !> Sample Fortran programs are created by executing this script.
  !> It is recommended to see sample Fortran programs actually.
  !>
  !> 0. Declare gtool_history_nmlinfo_types::GTHST_NMLINFO variable in the module.
  !>
  !> 1. Initialize gtool_history_nmlinfo_types::GTHST_NMLINFO variable by HstNmlInfoCreate.
  !>    On this occasion, configure default
  !>    interval_value, interval_unit,
  !>    precision, time_average, fileprefix (prefix of output file).
  !>
  !> 2. Register by using HstNmlInfoAdd when there are variables that
  !>    the program outputs by default.
  !>    Variable identifier is given to name. Do not specify same name
  !>    for different variables because name is used as a key to
  !>    identify the variable. The output file name is given to file.
  !>    A suitable file name is set when not giving it.
  !>
  !> 3. Register information of output variables obtained from NAMELIST
  !>    by using HstNmlInfoAdd. When registered name is registered again,
  !>    the setting concerning the name has been overwritten.
  !>
  !> 4. Shift from the define mode to output mode by using HstNmlInfoEndDefine
  !>    when registration is completed.
  !>
  !> 5. Pass HstNmlInfoAssocGtHist variable identifier name and
  !>    history of gtool_history_types::GT_HISTORY pointer when
  !>    setting output and data output is performed with
  !>    gtool_history_generic::HistoryCreate, gtool_history_generic::HistoryAddVariable,
  !>    gtool_history_generic::HistoryPut, etc.
  !>    history is associated to gtool_history_types::GT_HISTORY correspond
  !>    to name stored in gtool_history_nmlinfo_types::GTHST_NMLINFO variable.
  !>    Necessary output interval and precision for
  !>    gtool_history_generic::HistoryCreate can be obtained by using
  !>    HstNmlInfoInquire.
  !>    Please put history into a null state by NULLIFY after use.
  !>    (Information of output is lost when DEALLOCATE is used,
  !>    so do not use it).
  !>
  !>    It can know whether the output setting is effective
  !>    for each variable with HstNmlInfoOutputValid.
  !>
  !>    Moreover, it can know whether current time is output timing
  !>    when gtool_history_generic::HistoryPut is used
  !>    while integrating time with HstNmlInfoOutputStep.
  !>
  !> 6. Acquire history of gtool_history_types::GT_HISTORY type as well as
  !>    the above-mentioned procedure, and terminate that by
  !>    gtool_history_generic::HistoryClose when the output of the file ends.
  !>
  !> 7. Finally, the termination of the variable of gtool_history_nmlinfo_types::GTHST_NMLINFO
  !>    type is done by HstNmlInfoClose.
  !> @enden
  !>
  !> @ja
  !> ### 使用方法
  !>
  !> このモジュールは以下のような手順で用いてください.
  !>
  !> このモジュールを使用したサンプル Fortran プログラム作成スクリプトが
  !> http://www.gfd-dennou.org/library/dcpam/dcpam4/dcpam4_current/script/f90/dcmodel_f90sample_maker.rb
  !> から入手できます. Ruby で記述されており, 実行することで
  !> サンプルとなる Fortran プログラムが作成されます.
  !> 下記の解説のみでは実際の利用法やご利益が分かりにくいため,
  !> サンプル Fortran プログラムを実際に見てみることをオススメします.
  !>
  !> 0. モジュール内で, gtool_history_nmlinfo_types::GTHST_NMLINFO 型の変数を定義しておきます.
  !>
  !> 1. HstNmlInfoCreate を用いて, gtool_history_nmlinfo_types::GTHST_NMLINFO 型の変数の初期設定を行います.
  !>    この際にデフォルトの出力間隔 interval_value,
  !>    interval_unit, 精度 precision, 時間の平均化 time_average,
  !>    出力ファイル名接頭詞 fileprefix を設定します.
  !>
  !> 2. プログラムがデフォルトで出力する変数がある場合, HstNmlInfoAdd を
  !>    使用して登録してください.
  !>    name には変数名を与えます. name は変数を識別するためのキーと
  !>    して利用するため, 異なる変数に対して同じ name を指定しないでください.
  !>    file には出力ファイル名を与えます. 与えない場合,
  !>    適当なファイル名が設定されます.
  !>    その他の情報は上記と同様です.
  !>
  !> 3. NAMELIST から得られた出力変数の情報を,
  !>    HstNmlInfoAdd を使用して登録してください.
  !>    HstNmlInfoAdd で既に登録済みの name を再度登録することで,
  !>    設定が上書きされます.
  !>
  !> 4. 登録が完了したら, HstNmlInfoEndDefine を用いて,
  !>    定義モードから出力モードへ移行してください.
  !>
  !> 5. gtool_history_generic::HistoryCreate, gtool_history_generic::HistoryAddVariable,
  !>    gtool_history_generic::HistoryPut 等で出力設定およびデータ出力を行う際には,
  !>    HstNmlInfoAssocGtHist に対し, 変数名 name と
  !>    gtool_history_types::GT_HISTORY 型のポインタ history を渡してください.
  !>    gtool_history_nmlinfo_types::GTHST_NMLINFO 型の変数に登録されている
  !>    name に関する gtool_history_types::GT_HISTORY 型変数に結合された
  !>    history が返ります. この history
  !>    を上記 gtool_history のサブルーチン群の引数 history に渡して
  !>    出力設定およびデータ出力を行ってください.
  !>    gtool_history_generic::HistoryCreate に必要な
  !>    出力間隔や精度は HstNmlInfoInquire を用いて得ることができます.
  !>    使用後は, NULLIFY によって history を空状態にしてください.
  !>    (DEALLOCATE を使用すると出力に関する情報が失われるため,
  !>    使用しないでください).
  !>
  !>    それぞれの変数に関して, 出力設定が有効かどうかについては,
  !>    HstNmlInfoOutputValid で知ることが可能です.
  !>
  !>    また, 時間積分中に gtool_history_generic::HistoryPut を使用する際
  !>    に, 現在時刻が出力タイミングかどうかについては,
  !>    HstNmlInfoOutputStep で知ることが可能です.
  !>
  !> 6. ファイルの出力が終了したら, 上記の手順と同様に
  !>    gtool_history_types::GT_HISTORY 型の history を取得し,
  !>    gtool_history_generic::HistoryClose によって終了処理を行ってください.
  !>
  !> 7. 最後に, HstNmlInfoClose によって, gtool_history_nmlinfo_types::GTHST_NMLINFO 型の変数の
  !>    終了処理を行います.
  !> @endja
  !>
 
  implicit none
  private
  public:: hstnmlinfocreate, hstnmlinfoclose
  public:: hstnmlinfoputline, hstnmlinfoinitialized
  public:: hstnmlinfodefinemode, hstnmlinfoenddefine, hstnmlinforedefine
  public:: hstnmlinfoadd, hstnmlinfodelete
  public:: hstnmlinforesetdefault
  public:: hstnmlinfoinquire
  public:: hstnmlinfoassocgthist
  public:: hstnmlinfooutputstepdisable
  public:: hstnmlinfooutputstep
  public:: hstnmlinfooutputvalid
  public:: hstnmlinfonames, hstnmlinfogetnames
  public:: hstnmlinfoallvarinicheck
  public:: hstnmlinfosetvalidname
  public:: hstnmlinfoallnamevalid
 
  !-----------------------------------------------------------------
  !  公開手続
  !  Public procedures
  !-----------------------------------------------------------------
 
  interface hstnmlinfocreate
    subroutine hstnmlinfocreate( gthstnml, &
      & interval_value, &
      & interval_unit, &
      & precision, &
      & time_average, average, &
      & fileprefix, &
      & origin_value, origin_unit, &
      & terminus_value, terminus_unit, &
      & slice_start, slice_end, slice_stride, &
      & space_average, &
      & newfile_intvalue, newfile_intunit, &
      & err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      use dc_types, only: dp
      type(gthst_nmlinfo), intent(inout):: gthstnml
      real(DP), intent(in), optional:: interval_value
      character(*), intent(in), optional:: interval_unit
      character(*), intent(in), optional:: precision
      logical, intent(in), optional:: time_average
      logical, intent(in), optional:: average
      character(*), intent(in), optional:: fileprefix
      real(DP), intent(in), optional:: origin_value
      character(*), intent(in), optional:: origin_unit
      real(DP), intent(in), optional:: terminus_value
      character(*), intent(in), optional:: terminus_unit
      integer, intent(in), optional:: slice_start(:)
      integer, intent(in), optional:: slice_end(:)
      integer, intent(in), optional:: slice_stride(:)
      logical, intent(in), optional:: space_average(:)
      integer, intent(in), optional:: newfile_intvalue
      character(*), intent(in), optional:: newfile_intunit
      logical, intent(out), optional:: err
    end subroutine hstnmlinfocreate
  end interface
 
  interface hstnmlinfoclose
    subroutine hstnmlinfoclose( gthstnml, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(inout):: gthstnml
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoclose
  end interface
 
  interface hstnmlinfoputline
    subroutine hstnmlinfoputline( gthstnml, unit, indent, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
      integer, intent(in), optional:: unit
      character(*), intent(in), optional:: indent
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoputline
  end interface
 
  interface hstnmlinfoinitialized
    logical function hstnmlinfoinitialized( gthstnml ) result(result)
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
    end function hstnmlinfoinitialized
  end interface
 
  interface hstnmlinfodefinemode
    logical function hstnmlinfodefinemode( gthstnml ) result(result)
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
    end function hstnmlinfodefinemode
  end interface
 
  interface hstnmlinfoenddefine
    subroutine hstnmlinfoenddefine( gthstnml, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(inout):: gthstnml
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoenddefine
  end interface
 
  interface hstnmlinforedefine
    subroutine hstnmlinforedefine( gthstnml, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(inout):: gthstnml
      logical, intent(out), optional:: err
    end subroutine hstnmlinforedefine
  end interface
 
  interface hstnmlinfoadd
    recursive subroutine hstnmlinfoadd( gthstnml, &
      & name, file, &
      & interval_value, interval_unit, &
      & precision, &
      & time_average, average, &
      & fileprefix, &
      & origin_value, origin_unit, &
      & terminus_value, terminus_unit, &
      & slice_start, slice_end, slice_stride, &
      & space_average, &
      & newfile_intvalue, newfile_intunit, &
      & err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      use dc_types, only: dp
      type(gthst_nmlinfo), intent(inout):: gthstnml
      character(*), intent(in), optional:: name
      character(*), intent(in), optional:: file
      real(dp), intent(in), optional:: interval_value
      character(*), intent(in), optional:: interval_unit
      character(*), intent(in), optional:: precision
      logical, intent(in), optional:: time_average
      logical, intent(in), optional:: average
      character(*), intent(in), optional:: fileprefix
      real(dp), intent(in), optional:: origin_value
      character(*), intent(in), optional:: origin_unit
      real(dp), intent(in), optional:: terminus_value
      character(*), intent(in), optional:: terminus_unit
      integer, intent(in), optional:: slice_start(:)
      integer, intent(in), optional:: slice_end(:)
      integer, intent(in), optional:: slice_stride(:)
      logical, intent(in), optional:: space_average(:)
      integer, intent(in), optional:: newfile_intvalue
      character(*), intent(in), optional:: newfile_intunit
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoadd
  end interface
 
  interface hstnmlinfodelete
    recursive subroutine hstnmlinfodelete( gthstnml, name, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(inout):: gthstnml
      character(*), intent(in):: name
      logical, intent(out), optional:: err
    end subroutine hstnmlinfodelete
  end interface
 
  interface hstnmlinforesetdefault
    subroutine hstnmlinforesetdefault( gthstnml, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(inout):: gthstnml
      logical, intent(out), optional:: err
    end subroutine hstnmlinforesetdefault
  end interface
 
  interface hstnmlinfoinquire
    subroutine hstnmlinfoinquire( gthstnml, &
      & name, &
      & file, &
      & interval_value, &
      & interval_unit, &
      & precision, &
      & time_average, average, &
      & fileprefix, &
      & origin_value, origin_unit, &
      & terminus_value, terminus_unit, &
      & slice_start, slice_end, slice_stride, &
      & space_average, &
      & newfile_intvalue, newfile_intunit, &
      & err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      use dc_types, only: dp
      type(gthst_nmlinfo), intent(in):: gthstnml
      character(*), intent(in), optional:: name
      character(*), intent(out), optional:: file
      real(DP), intent(out), optional:: interval_value
      character(*), intent(out), optional:: interval_unit
      character(*), intent(out), optional:: precision
      logical, intent(out), optional:: time_average
      logical, intent(out), optional:: average
      character(*), intent(out), optional:: fileprefix
      real(DP), intent(out), optional:: origin_value
      character(*), intent(out), optional:: origin_unit
      real(DP), intent(out), optional:: terminus_value
      character(*), intent(out), optional:: terminus_unit
      integer, intent(out), optional:: slice_start(:)
      integer, intent(out), optional:: slice_end(:)
      integer, intent(out), optional:: slice_stride(:)
      logical, intent(out), optional:: space_average(:)
      integer, intent(out), optional:: newfile_intvalue
      character(*), intent(out), optional:: newfile_intunit
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoinquire
  end interface
 
  interface hstnmlinfoassocgthist
    subroutine hstnmlinfoassocgthist( gthstnml, &
      & name, history, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      use gtool_history, only: gt_history
      type(gthst_nmlinfo), intent(in):: gthstnml
      character(*), intent(in):: name
      type(gt_history), pointer:: history
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoassocgthist
  end interface
 
  interface hstnmlinfooutputstepdisable
    subroutine hstnmlinfooutputstepdisable( gthstnml, &
      & name, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
      character(*), intent(in):: name
      logical, intent(out), optional:: err
    end subroutine hstnmlinfooutputstepdisable
  end interface
 
  interface hstnmlinfooutputstep
    logical function hstnmlinfooutputstep( gthstnml, &
      & name, time ) result(result)
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      use gtool_history, only: gt_history
      use dc_date_types, only: dc_difftime
      type(gthst_nmlinfo), intent(in):: gthstnml
      character(*), intent(in):: name
      type(dc_difftime), intent(in):: time
    end function hstnmlinfooutputstep
  end interface
 
  interface hstnmlinfooutputvalid
    logical function hstnmlinfooutputvalid( gthstnml, &
      & name ) result(result)
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
      character(*), intent(in):: name
    end function hstnmlinfooutputvalid
  end interface
 
  interface hstnmlinfonames
    function hstnmlinfonames( gthstnml ) result(result)
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      use dc_types, only: string
      character(STRING):: result
      type(gthst_nmlinfo), intent(in):: gthstnml
    end function hstnmlinfonames
  end interface
 
  interface hstnmlinfogetnames
    subroutine hstnmlinfogetnames( gthstnml, varnames_ary, err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      use dc_types, only: token
      type(gthst_nmlinfo), intent(in):: gthstnml
      character(TOKEN), pointer:: varnames_ary(:)
      logical, intent(out), optional:: err
    end subroutine hstnmlinfogetnames
  end interface
 
  interface hstnmlinfoallvarinicheck
    subroutine hstnmlinfoallvarinicheck( gthstnml, &
      & invalid, &
      & names, &
      & err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
      logical, intent(out):: invalid
      character(*), intent(out):: names
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoallvarinicheck
  end interface
 
  interface hstnmlinfosetvalidname
    subroutine hstnmlinfosetvalidname( gthstnml, &
      & name, &
      & err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
      character(*), intent(in):: name
      logical, intent(out), optional:: err
    end subroutine hstnmlinfosetvalidname
  end interface
 
  interface hstnmlinfoallnamevalid
    subroutine hstnmlinfoallnamevalid( gthstnml, &
      & invalid, &
      & names, &
      & err )
      use gtool_history_nmlinfo_types, only: gthst_nmlinfo
      type(gthst_nmlinfo), intent(in):: gthstnml
      logical, intent(out):: invalid
      character(*), intent(out):: names
      logical, intent(out), optional:: err
    end subroutine hstnmlinfoallnamevalid
  end interface
 
end module gtool_history_nmlinfo_generic