gtdata_netcdf_generic.f90

Go to the documentation of this file.

!>
!> @file gtdata_netcdf_generic.f90
!>
!> @author Eizi TOYODA, Yasuhiro MORIKAWA
!> @copyright Copyright (C) GFD Dennou Club, 2000-2026. All rights reserved. <br/>
!>            License is BSD-2-Clause. See [COPYRIGHT](@ref COPYRIGHT) in detail
!>
!> @en
!> @brief Generic interface declarations for abstract netCDF interface
!> @enden
!>
!> @ja
!> @brief 抽象 netCDF インターフェイスの総称宣言
!> @endja
!>
 
!>
!> @en
!> @brief Generic interface declarations for abstract netCDF interface
!>
!> This module provides generic interface declarations for the abstract
!> netCDF layer. In the an library, "variables" rather than "files" are
!> opened and closed. Everything is treated as variables and their attributes.
!>
!> ## Main interfaces
!>
!> | Interface | Description |
!> |-----------|-------------|
!> | Open | Open a variable |
!> | Close | Close a variable |
!> | Create | Create a variable |
!> | Inquire | Query variable properties |
!> | Get | Read data from a variable |
!> | Put | Write data to a variable |
!> | get_attr | Get attribute value |
!> | Put_Attr | Set attribute value |
!> | del_attr | Delete an attribute |
!> | copy_attr | Copy an attribute |
!> | attr_rewind | Reset attribute iterator |
!> | attr_next | Get next attribute name |
!> | var_search | Search for variables |
!>
!> @enden
!>
!> @ja
!> @brief 抽象 netCDF インターフェイスの総称宣言
!>
!> このモジュールは抽象 netCDF 層の総称インターフェイス宣言を提供します。
!> an ライブラリでは「ファイル」ではなく「変数」を開いたり閉じたりします。
!> すべてのものは変数とその属性として扱われます。
!>
!> ## 主なインターフェイス
!>
!> | インターフェイス | 説明 |
!> |-----------------|------|
!> | Open | 変数を開く |
!> | Close | 変数を閉じる |
!> | Create | 変数を作成 |
!> | Inquire | 変数属性を問い合わせ |
!> | Get | 変数からデータを読込 |
!> | Put | 変数にデータを書込 |
!> | get_attr | 属性値を取得 |
!> | Put_Attr | 属性値を設定 |
!> | del_attr | 属性を削除 |
!> | copy_attr | 属性をコピー |
!> | attr_rewind | 属性イテレータをリセット |
!> | attr_next | 次の属性名を取得 |
!> | var_search | 変数を検索 |
!>
!> @endja
!>
module gtdata_netcdf_generic
  !
 
  implicit none
 
  !---------------------------------------------------------------------------
  !> @en Basic open/close operations @enden
  !> @ja 基本開閉動作 @endja
  !---------------------------------------------------------------------------
 
  !>
  !> @en
  !> @brief Open a netCDF variable
  !>
  !> In the an library, "variables" are opened/closed, not "files".
  !> Everything is treated as variables and their attributes.
  !> @enden
  !>
  !> @ja
  !> @brief netCDF 変数を開く
  !>
  !> an ライブラリでは「ファイル」ではなく「変数」を開きます。
  !> すべてのものは変数とその属性として扱われます。
  !> @endja
  !>
  interface open
    !>
    !> @en
    !> @brief Open a variable by URL
    !>
    !> Opens the variable identified by url and stores it in var.
    !> A variable is either a netCDF variable or a netCDF dimension.
    !> If writable is .true., opens in write mode (default: .false.).
    !> @enden
    !>
    !> @ja
    !> @brief URL で変数を開く
    !>
    !> url で識別される変数を開き var に格納します。
    !> 変数とは netCDF 変数または netCDF 次元です。
    !> writable が .true. なら書込モードで開きます (デフォルト: .false.)。
    !> @endja
    !>
    recursive subroutine gdncvaropen(var, url, writable, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(out):: var
      character(len = *), intent(in):: url
      logical, intent(in), optional:: writable
      logical, intent(out), optional:: err
    end subroutine gdncvaropen
    !>
    !> @en
    !> @brief Open a dimension variable by dimension order
    !>
    !> Opens the variable corresponding to the dimord-th dimension
    !> of an already opened variable src_var.
    !> @enden
    !>
    !> @ja
    !> @brief 次元順序で次元変数を開く
    !>
    !> 既に開かれた変数 src_var の dimord 番目の次元にあたる変数を開きます。
    !> @endja
    !>
    subroutine gdncvaropenbydimord(var, src_var, dimord, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(out):: var
      type(gd_nc_variable), intent(in):: src_var
      integer, intent(in):: dimord
      logical, intent(out), optional:: err
    end subroutine gdncvaropenbydimord
  end interface
 
  interface search_dim
    integer function gdncsearchdim(var, dimname)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: dimname
    end function gdncsearchdim
  end interface
 
  !>
  !> @en
  !> @brief Create a new netCDF variable
  !> @enden
  !> @ja
  !> @brief 新しい netCDF 変数を作成
  !> @endja
  !>
  interface create
    !>
    !> @en
    !> @brief Create a dependent variable
    !>
    !> Creates a variable with dimensions dims at location url.
    !> If xtype is omitted, defaults to real.
    !> To create a zero-dimensional variable, pass a zero-length array for dims.
    !> @enden
    !>
    !> @ja
    !> @brief 従属変数を作成
    !>
    !> 場所 url に次元 dims を持った変数を作成します。
    !> xtype を省略すると real とみなされます。
    !> ゼロ次元変数を作るには dims に長さゼロの配列を渡します。
    !> @endja
    !>
    subroutine gdncvarcreate(var, url, xtype, dims, overwrite, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(out):: var
      character(len = *), intent(in):: url
      character(len = *), intent(in):: xtype
      type(gd_nc_variable), intent(in):: dims(:)
      logical, intent(in), optional:: overwrite
      logical, intent(out), optional:: err
    end subroutine gdncvarcreate
    !>
    !> @en
    !> @brief Create a dimension variable
    !>
    !> Creates a dimension variable with the specified length.
    !> @enden
    !>
    !> @ja
    !> @brief 次元変数を作成
    !>
    !> 長さ length の次元変数を作成します。
    !> @endja
    !>
    subroutine gdncvarcreated(var, url, xtype, length, overwrite, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(out):: var
      character(len = *), intent(in):: url
      character(len = *), intent(in):: xtype
      integer, intent(in):: length
      logical, intent(in), optional:: overwrite
      logical, intent(out), optional:: err
    end subroutine gdncvarcreated
  end interface
 
  interface
    subroutine gdncvardel(varname, hint, stat)
      character(len = *), intent(in):: varname
      character(len = *), intent(in):: hint
      integer, intent(out):: stat
    end subroutine gdncvardel
  end interface
 
  interface close
    subroutine gdncvarclose(var, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      logical, intent(out), optional:: err
    end subroutine gdncvarclose
  end interface
 
  !---------------------------------------------------------------------------
  !> @en Variable inquiry @enden
  !> @ja 変数に関する問い合わせ @endja
  !---------------------------------------------------------------------------
 
  !> @en For debugging purposes @enden
  !> @ja デバッグ用 @endja
  interface tostring
    function gdncvartostring(var) result(result)
      use dc_types, only: string
      use gtdata_netcdf_types, only: gd_nc_variable
      character(string):: result
      type(gd_nc_variable), intent(in):: var
    end function gdncvartostring
  end interface
 
  interface inquire
 
    subroutine gdncvarinquire(var, ndims, dimlen, growable, name, url, xtype)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(out), optional:: ndims    !< @en Number of dimensions @enden @ja 次元数 @endja
      integer, intent(out), optional:: dimlen   !< @en Dimension length (for 1D variables) @enden @ja 次元長 (1次元変数の場合) @endja
      logical, intent(out), optional:: growable !< @en Whether variable has unlimited dimension @enden @ja 成長可能次元を持つか @endja
      character(*), intent(out), optional:: name  !< @en Variable name after '?' @enden @ja '?' 以降の変数名 @endja
      character(*), intent(out), optional:: url   !< @en Full URL including filename @enden @ja ファイル名を含む完全URL @endja
      character(*), intent(out), optional:: xtype !< @en Variable type name @enden @ja 変数の型名 @endja
    end subroutine gdncvarinquire
 
    !> @en Array argument must have ndims elements @enden
    !> @ja 引数は ndims 個でなければならない @endja
    subroutine gdncvarinquireia(var, dimlen)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(out):: dimlen(:)
    end subroutine gdncvarinquireia
 
    subroutine gdncattrinquire(var, attrname, xtype)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len=*), intent(in):: attrname
      character(len=*), intent(out), optional:: xtype
    end subroutine gdncattrinquire
 
  end interface
 
  interface inquireplus
 
    subroutine gdncattrinquireplus(var, attrname, varid, nf_attrname)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len=*), intent(in):: attrname
      integer, intent(out):: varid
      character(len=*), intent(out):: nf_attrname
    end subroutine gdncattrinquireplus
 
  end interface
 
  !---------------------------------------------------------------------------
  !> @en
  !> @brief Attribute operations
  !>
  !> From the an library's perspective that everything is a variable,
  !> global attributes are treated as variable attributes.
  !> When reading attributes, variable attributes are searched first,
  !> then global attributes.
  !> @enden
  !>
  !> @ja
  !> @brief 属性操作
  !>
  !> すべては変数という an ライブラリの立場から、
  !> 大域属性は変数属性とみなされます。
  !> 属性読み取り時には変数属性の次に大域属性を検索します。
  !> @endja
  !---------------------------------------------------------------------------
 
  !>
  !> @en
  !> @brief Reset attribute iterator
  !>
  !> To get all attributes of a variable, first call attr_rewind(var),
  !> then call attr_next(var, name, [end]) in a loop.
  !> @enden
  !>
  !> @ja
  !> @brief 属性イテレータをリセット
  !>
  !> 変数の全属性を取得するには、まず attr_rewind(var) を呼び、
  !> ループ内で attr_next(var, name, [end]) を呼び出します。
  !> @endja
  !>
  interface attr_rewind
    subroutine gdncvarattrrewind(var)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
    end subroutine gdncvarattrrewind
  end interface
 
  interface attr_next
    subroutine gdncvarattrnext(var, name, end)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(out):: name
      logical, intent(out), optional:: end
    end subroutine gdncvarattrnext
  end interface
 
  !>
  !> @en
  !> @brief Get attribute value
  !>
  !> Gets the attribute name of variable var and stores it in value.
  !> If the attribute doesn't exist or value is too short, default is used.
  !> Type conversion is performed as needed.
  !> @enden
  !>
  !> @ja
  !> @brief 属性値を取得
  !>
  !> 変数 var の属性 name を取得して value に格納します。
  !> 属性が存在しないか value の長さが不足している場合は
  !> default が補われます。必要に応じて型変換が行われます。
  !> @endja
  !>
  interface get_attr
 
    subroutine gdncattrgetchar(var, name, value, default, stat)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      character(len = *), intent(out):: value
      character(len = *), intent(in):: default
      integer, intent(out):: stat
    end subroutine gdncattrgetchar
 
    subroutine gdncvargetattrlogical(var, name, value, default)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      logical, intent(out):: value
      logical, intent(in), optional:: default
    end subroutine gdncvargetattrlogical
 
    !>
    !> @en
    !> @brief Get numeric attribute (stat return codes)
    !> - stat = -1: attribute does not exist
    !> - stat = 0..size(value): attribute fully read, size is stat
    !> - stat > size(value): array too short, needs stat elements
    !> @enden
    !>
    !> @ja
    !> @brief 数値属性を取得 (stat 戻り値)
    !> - stat = -1: 属性が存在しない
    !> - stat = 0..size(value): 属性を全部読み取った、サイズは stat 個
    !> - stat > size(value): 配列長不足、stat 個必要
    !> @endja
    !>
    subroutine gdncattrgetreal(var, name, value, stat, default)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      real, intent(out):: value(:)
      integer, intent(out):: stat
      real, intent(in), optional:: default
    end subroutine gdncattrgetreal
 
    subroutine gdncattrgetdouble(var, name, value, stat, default)
      use dc_types, only: dp
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      real(DP), intent(out):: value(:)
      integer, intent(out):: stat
      real(DP), intent(in), optional:: default
    end subroutine gdncattrgetdouble
 
    subroutine gdncattrgetint(var, name, value, stat, default)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      integer, intent(out):: value(:)
      integer, intent(out):: stat
      integer, intent(in), optional:: default
    end subroutine gdncattrgetint
 
  end interface
 
  !>
  !> @en
  !> @brief Set attribute value
  !>
  !> Stores value in attribute name of variable var.
  !> The attribute type is set to match the type of value.
  !> Logical values are stored as single character: T for true, F for false.
  !> @enden
  !>
  !> @ja
  !> @brief 属性値を設定
  !>
  !> 変数 var の属性 name に value を格納します。
  !> 属性の型は value の型に適合するように設定されます。
  !> 論理型は 1 文字の文字型として格納され、真は T、偽は F となります。
  !> @endja
  !>
  interface put_attr
 
    subroutine gdncvarputattrreal(var, name, value, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      real, intent(in):: value(:)
      logical, intent(out), optional:: err
    end subroutine gdncvarputattrreal
 
    subroutine gdncvarputattrdouble(var, name, value, err)
      use dc_types, only: dp
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      real(DP), intent(in):: value(:)
      logical, intent(out), optional:: err
    end subroutine gdncvarputattrdouble
 
    subroutine gdncvarputattrint(var, name, value, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      integer, intent(in):: value(:)
      logical, intent(out), optional:: err
    end subroutine gdncvarputattrint
 
    subroutine gdncvarputattrlogical(var, name, value, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      logical, intent(in):: value
      logical, intent(out), optional:: err
    end subroutine gdncvarputattrlogical
 
    subroutine gdncvarputattrchar(var, name, value, xtype, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      character(len = *), intent(in):: value
      character(len = *), intent(in), optional:: xtype
      logical, intent(out), optional:: err
    end subroutine gdncvarputattrchar
 
  end interface
 
  interface del_attr
    subroutine gdncvardelattr(var, name, err)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      character(len = *), intent(in):: name
      logical, intent(out), optional:: err
    end subroutine gdncvardelattr
  end interface
 
  interface copy_attr
    subroutine gdncvarattrcopy(to, attrname, from, stat)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: to
      character(len = *), intent(in):: attrname
      type(gd_nc_variable), intent(in):: from
      integer, intent(out):: stat
    end subroutine gdncvarattrcopy
  end interface
 
  !---------------------------------------------------------------------------
  !> @en Data I/O @enden
  !> @ja データ入出力 @endja
  !---------------------------------------------------------------------------
 
  !> @en Read data from a variable @enden
  !> @ja 変数からデータを読込 @endja
  interface get
 
    subroutine gdncvargetreal(var, start, count, stride, imap, &
      & siz, value, iostat)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(in):: start(:)
      integer, intent(in):: count(:)
      integer, intent(in):: stride(:)
      integer, intent(in):: imap(:)
      integer, intent(in):: siz
      real, intent(out):: value(siz)
      integer, intent(out):: iostat
    end subroutine gdncvargetreal
 
    subroutine gdncvargetdouble(var, start, count, stride, imap, &
      & siz, value, iostat)
      use dc_types, only: dp
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(in):: start(:)
      integer, intent(in):: count(:)
      integer, intent(in):: stride(:)
      integer, intent(in):: imap(:)
      integer, intent(in):: siz
      real(DP), intent(out):: value(siz)
      integer, intent(out):: iostat
    end subroutine gdncvargetdouble
 
    subroutine gdncvargetint(var, start, count, stride, imap, &
      & siz, value, iostat)
      use dc_types, only: dp
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(in):: start(:)
      integer, intent(in):: count(:)
      integer, intent(in):: stride(:)
      integer, intent(in):: imap(:)
      integer, intent(in):: siz
      integer, intent(out):: value(siz)
      integer, intent(out):: iostat
    end subroutine gdncvargetint
 
  end interface
 
  !> @en Write data to a variable @enden
  !> @ja 変数にデータを書込 @endja
  interface put
 
    subroutine gdncvarputreal(var, start, count, stride, imap, &
      & siz, value, iostat)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(in):: start(:)
      integer, intent(in):: count(:)
      integer, intent(in):: stride(:)
      integer, intent(in):: imap(:)
      integer, intent(in):: siz
      real, intent(in):: value(siz)
      integer, intent(out):: iostat
    end subroutine gdncvarputreal
 
    subroutine gdncvarputdouble(var, start, count, stride, imap, &
      & siz, value, iostat)
      use dc_types, only: dp
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(in):: start(:)
      integer, intent(in):: count(:)
      integer, intent(in):: stride(:)
      integer, intent(in):: imap(:)
      integer, intent(in):: siz
      real(DP), intent(in):: value(siz)
      integer, intent(out):: iostat
    end subroutine gdncvarputdouble
 
    subroutine gdncvarputint(var, start, count, stride, imap, &
      & siz, value, iostat)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(in):: start(:)
      integer, intent(in):: count(:)
      integer, intent(in):: stride(:)
      integer, intent(in):: imap(:)
      integer, intent(in):: siz
      integer, intent(in):: value(siz)
      integer, intent(out):: iostat
    end subroutine gdncvarputint
 
    subroutine gdncvarputchar(var, start, count, stride, imap, &
      & siz, value, iostat)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in):: var
      integer, intent(in):: start(:)
      integer, intent(in):: count(:)
      integer, intent(in):: stride(:)
      integer, intent(in):: imap(:)
      integer, intent(in):: siz
      character(*), intent(in):: value(siz)
      integer, intent(out):: iostat
    end subroutine gdncvarputchar
 
  end interface
 
  !---------------------------------------------------------------------------
  !> @en Search for variables by filename @enden
  !> @ja ファイル名から変数を検索 @endja
  !---------------------------------------------------------------------------
 
  !> @en Search for variables @enden
  !> @ja 変数を検索 @endja
  interface var_search
        
    subroutine gdncvarsearchinit(iter, urlBase)
      use gtdata_netcdf_types, only: gd_nc_variable_search
      type(gd_nc_variable_search), intent(out):: iter
      character(len = *), intent(in):: urlBase
    end subroutine gdncvarsearchinit
 
    subroutine gdncvarsearchnext(iter, url, end)
      use gtdata_netcdf_types, only: gd_nc_variable_search
      type(gd_nc_variable_search), intent(inout):: iter
      character(len = *), intent(out):: url
      logical, intent(out):: end
    end subroutine gdncvarsearchnext
 
  end interface
 
  !>
  !> @en
  !> @brief Emergency sync
  !>
  !> This routine does not call StoreError itself because it may be
  !> called from SysDepAbort.
  !> @enden
  !>
  !> @ja
  !> @brief 非常脱出用同期
  !>
  !> このルーチンは SysDepAbort からも呼ばれるため、
  !> 自分で StoreError することはありません。
  !> @endja
  !>
  interface
    subroutine gdncvarsync(var, stat)
      use gtdata_netcdf_types, only: gd_nc_variable
      type(gd_nc_variable), intent(in), optional:: var
      integer, intent(out), optional:: stat
    end subroutine gdncvarsync
  end interface
 
  !> @en Internal routine for an layer @enden
  !> @ja an 層の内部使用ルーチン @endja
  interface
    subroutine gdncxtypename(ixtype, xtype)
      integer, intent(in):: ixtype
      character(*), intent(out):: xtype
    end subroutine gdncxtypename
  end interface
 
end module gtdata_netcdf_generic