Functions and Subroutines

Functions and Subroutines#

This page documents the public procedures re-exported by nc4f. Optional err arguments receive an error_type; when omitted, an operation failure follows the library’s fail-fast policy. See Exposed NC Constants for constants used with error_type.

`CLOSE_NETCDF` – Close a NetCDF File#

Synopsis
`CALL CLOSE_NETCDF(NC[, ERR])`

Class
Subroutine.

Description
Close an open dataset and release its allocated model metadata.

Arguments
`NCtype(netcdf_type), INTENT(inout)` Open dataset to close.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(netcdf_type) :: nc nc = open_netcdf("input.nc") call close_netcdf(nc)

`DATARRAY` – Construct a Variable#

Synopsis
`VAR = DATARRAY(NAME, VALUES, DIMS[, ATTS, DEEP])`

Class
Generic function.

Description
Construct a `variable_type` from a rank-one through rank-fifteen numeric or character array. `DIMS` are in Fortran order. `DEEP=.true.` (the default) copies `VALUES` into owned storage; `DEEP=.false.` borrows a simply contiguous, named target array. Shallow character arrays are unsupported.

Arguments
`NAMEcharacter(len=*), INTENT(in)` Variable name.
`VALUESTYPE(INTEGER(INT8, INT16, INT32, INT64), REAL(REAL32, REAL64), CHARACTER), RANK(1:15), INTENT(IN)` Values to copy or borrow.
`DIMStype(dimension_type), DIMENSION(:), INTENT(in)` Dimensions matching the array shape.
`ATTStype(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)` Variable attributes.
`DEEPlogical, OPTIONAL, INTENT(in)` Choose owned (`.true.`) or borrowed (`.false.`) storage.

Return
`VARtype(variable_type)` Constructed variable.

Example

program main

  use, non_intrinsic :: nc4f
  implicit none (type, external)

  type(dimension_type) :: lon, lat, tme
  type(variable_type) :: var
  logical, parameter :: UNLIMITED = .true.
  real, allocatable, target :: values(:, :, :)
  integer :: nlon, nlat, ntme, i, j, k

  nlon = 360
  nlat = 181
  ntme = 24

  allocate (values(ntme, nlat, nlon))
  do concurrent (i = 1:ntme, j = 1:nlat, k = 1:nlon)
    values(i, j, k) = 0. !> Dummy values
  end do

  var = datarray("temperature", values,                 &
    dims=["time" .dim. (ntme .and. UNLIMITED),          &
          "latitude" .dim. nlat,                        &
          "longitude" .dim. nlon],                      &
    atts=["units" .att. "K",                            &
          "description" .att. "Temperature in Kelvin",  &
          "missing value" .att. -1],                    &
    deep=.false.)

  print *, var
  call to_netcdf("var.nc", var)

end program main

`DATASET` – Construct a Group#

Synopsis
`GRP = DATASET(NAME[, ATTS, DEEP])` `GRP = DATASET(NAME, VARS[, ATTS, DEEP])` `GRP = DATASET(NAME, GRPS[, ATTS, DEEP])` `GRP = DATASET(NAME, VARS, GRPS[, ATTS, DEEP])`

Class
Generic function.

Description
Construct a `group_type` from a name and optional variables, child groups, and attributes. `DEEP=.false.` (the default) shares referenced model storage; `DEEP=.true.` recursively clones it.

Arguments
`NAMEcharacter(len=*), INTENT(in)` Group name.
`VARStype(variable_type), DIMENSION(:), INTENT(in)` Variables to attach to the group.
`GRPStype(group_type), DIMENSION(:), INTENT(in)` Child groups to attach to the group.
`ATTStype(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)` Attributes to attach to the group.
`DEEPlogical, OPTIONAL, INTENT(in)` Clone supplied model components when true.

Return
`GRPtype(group_type)` Constructed group.

Example

use, non_intrinsic :: nc4f
implicit none (type, external)

type(dimension_type) :: point
type(variable_type) :: var
type(group_type) :: root
real, target :: values(1) = [273.15]

point = "point" .dim. 1
var = datarray("temperature", values, [point])
root = dataset("/", [var], atts=["title".att."Example dataset"])

`EXTRACT` – Access Model Data#

Synopsis
`CALL EXTRACT(ATT, VALUES)` `CALL EXTRACT(VAR, VALUES)`

Class
Generic subroutine.

Description
Associate a typed Fortran pointer with an attribute or variable’s active byte storage. The pointer’s type and rank must match the stored NetCDF data and remains valid only while the source storage remains valid.

Arguments
`ATTtype(attribute_type), TARGET, INTENT(in)` Attribute supplying storage.
`VARtype(variable_type), TARGET, INTENT(in)` Variable supplying storage.
`VALUESTYPE(INTEGER(INT8, INT16, INT32, INT64), REAL(REAL32, REAL64), CHARACTER), RANK(0:15), POINTER, INTENT(OUT)` Type- and rank-compatible pointer receiving the association.

Example

use, non_intrinsic :: nc4f
implicit none (type, external)

type(dimension_type) :: point
type(variable_type) :: var
real, pointer :: values(:)
real, target :: source(1) = [273.15]

point = "point" .dim. 1
var = datarray("temperature", source, [point])
call extract(var, values)
values = values + 273.15

`GET_ATTRIBUTE` – Read Attributes#

Synopsis
`ATT = GET_ATTRIBUTE(GRP, NAME[, ERR])` `ATTS = GET_ATTRIBUTE(GRP[, ERR])` `ATT = GET_ATTRIBUTE(GRP, VAR, NAME[, ERR])` `ATTS = GET_ATTRIBUTE(GRP, VAR[, ERR])`

Class
Generic function.

Description
Read one named global or variable attribute, or all attributes attached to a group or variable.

Arguments
`GRPclass(group_type), INTENT(in)` Containing group.
`VARtype(variable_type), OPTIONAL, INTENT(in)` Variable whose attributes to read.
`NAMEcharacter(len=*), OPTIONAL, INTENT(in)` Name of one attribute to read.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Return
`ATTtype(attribute_type)` Requested attribute. `ATTStype(attribute_type), allocatable` Attributes attached to the requested group or variable.

Example

use, non_intrinsic :: nc4f
implicit none (type, external)

type(netcdf_type) :: nc
type(group_type) :: atmosphere
type(variable_type) :: temperature
type(attribute_type) :: title, units

nc = open_netcdf("input.nc")
atmosphere = get_group(nc, "atmosphere")
temperature = inquire_variable(atmosphere, "temperature")
title = get_attribute(nc, "title")
units = get_attribute(atmosphere, temperature, "units")

`GET_GROUP` – Get a Child Group#

Synopsis
`CHILD = GET_GROUP(PARENT, NAME[, ERR])`

Class
Function.

Description
Return a direct child group by local name.

Arguments
`PARENTclass(group_type), INTENT(in)` Containing group.
`NAMEcharacter(len=*), INTENT(in)` Name of a direct child group.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Return
`CHILDtype(group_type)` Matching direct child group.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(netcdf_type) :: nc type(group_type) :: atmosphere nc = open_netcdf("input.nc") atmosphere = get_group(nc, "atmosphere")

`GET_VARIABLE` – Read a Variable#

Synopsis
`VAR = GET_VARIABLE(GRP, NAME[, START, COUNT, STRIDE, ERR])`

Class
Function.

Description
Read variable metadata and values. `START`, `COUNT`, and `STRIDE` are one-based and in Fortran order. Omitting all reads the complete variable.

Arguments
`GRPclass(group_type), INTENT(in)` Containing group.
`NAMEcharacter(len=*), INTENT(in)` Name of the variable to read.
`STARTinteger, DIMENSION(:), OPTIONAL, INTENT(in)` One-based start index for each dimension.
`COUNTinteger, DIMENSION(:), OPTIONAL, INTENT(in)` Number of values to read in each dimension.
`STRIDEinteger, DIMENSION(:), OPTIONAL, INTENT(in)` Step between values in each dimension.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Return
`VARtype(variable_type)` Requested variable and its selected data.

Example

use, non_intrinsic :: nc4f
implicit none (type, external)

type(netcdf_type) :: nc
type(variable_type) :: pressure, slice

nc = open_netcdf("input.nc")
pressure = get_variable(nc, "P")
slice = get_variable(nc, "temperature", start=[1, 1], count=[12, 1])

`INITIALIZE` – Allocate Model Storage#

Synopsis
`CALL INITIALIZE(ATT, NAME, DTYPE, LEN)` `CALL INITIALIZE(ATT, NAME, MOLD[, DEEP])` `CALL INITIALIZE(VAR, NAME, DTYPE, LEN, DIMS[, ATTS])` `CALL INITIALIZE(VAR, NAME, MOLD[, ATTS, DEEP])`

Class
Generic subroutine.

Description
Initialize a writable attribute or variable when values will be supplied later. From-scratch forms always allocate owned storage. Mold forms use the mold’s metadata and default to fresh owned storage; `DEEP=.false.` borrows the mold’s active storage.

Arguments
`ATTtype(attribute_type), INTENT(inout)` Attribute to initialize.
`VARtype(variable_type), INTENT(inout)` Variable to initialize.
`NAMEcharacter(len=*), INTENT(in)` Name for the initialized object.
`DTYPEinteger(data_type), INTENT(in)` NetCDF data type for from-scratch initialization.
`LENinteger(int64), INTENT(in)` Element count for from-scratch initialization.
`DIMStype(dimension_type), DIMENSION(:), INTENT(in)` Dimensions for a from-scratch variable.
`MOLDtype(attribute_type) or type(variable_type), INTENT(in)` Object supplying metadata and, optionally, storage.
`ATTStype(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)` Attributes to attach to an initialized variable.
`DEEPlogical, OPTIONAL, INTENT(in)` Allocate fresh mold storage when true, or borrow it when false.

Example

use, non_intrinsic :: nc4f
implicit none (type, external)

type(variable_type) :: total, output
real, pointer :: total_values(:), output_values(:)

call initialize(output, "mean_pressure", mold=total)
call extract(output, output_values)
output_values = 0.5 * total_values

`INQUIRE_DIMENSIONS` – Get Dimensions#

Synopsis
`DIMS = INQUIRE_DIMENSIONS(GRP[, ERR])` `DIMS = INQUIRE_DIMENSIONS(GRP, VAR[, ERR])`

Class
Generic function.

Description
Return an allocatable array of a group’s dimensions or the dimensions attached to a variable, ordered for Fortran use.

Arguments
`GRPclass(group_type), INTENT(in)` Dataset or group to inspect.
`VARtype(variable_type), OPTIONAL, INTENT(in)` Variable whose dimensions to return.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Return
`DIMStype(dimension_type), allocatable` Dimensions attached to the requested group or variable.

Example

use, non_intrinsic :: nc4f
implicit none (type, external)

type(netcdf_type) :: nc
type(variable_type) :: temperature
type(dimension_type), allocatable :: dims(:), variable_dims(:)

nc = open_netcdf("input.nc")
temperature = inquire_variable(nc, "temperature")
dims = inquire_dimensions(nc)
variable_dims = inquire_dimensions(nc, temperature)

`INQUIRE_GROUP` – Materialize Group Metadata#

Synopsis
`CALL INQUIRE_GROUP(GRP[, INQ_DIMS, INQ_ATTS, INQ_VARS, INQ_GRPS, RECUR, ERR])`

Class
Subroutine.

Description
Materialize selected local metadata in place. The `INQ_*` flags default to `.true.`; `RECUR` defaults to `.false.` and, when true, recursively materializes child groups.

Arguments
`GRPclass(group_type), INTENT(inout)` Group receiving materialized metadata.
`INQ_DIMSlogical, OPTIONAL, INTENT(in)` Whether to inquire dimensions.
`INQ_ATTSlogical, OPTIONAL, INTENT(in)` Whether to inquire attributes.
`INQ_VARSlogical, OPTIONAL, INTENT(in)` Whether to inquire variables.
`INQ_GRPSlogical, OPTIONAL, INTENT(in)` Whether to inquire direct child groups.
`RECURlogical, OPTIONAL, INTENT(in)` Whether to recurse into child groups.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Example

use, non_intrinsic :: nc4f
implicit none (type, external)

type(group_type) :: atmosphere

call inquire_group(atmosphere, inq_dims=.true., inq_atts=.true., &
  & inq_vars=.true., inq_grps=.true., recur=.true.)

`INQUIRE_SUBGROUPS` – List Child Groups#

Synopsis
`CHILDREN = INQUIRE_SUBGROUPS(PARENT[, ERR])`

Class
Function.

Description
Return an allocatable array of direct child groups with identifiers and names populated.

Arguments
`PARENTclass(group_type), INTENT(in)` Group to inspect.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Return
`CHILDRENtype(group_type), allocatable` Direct child groups with populated identifiers and names.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(netcdf_type) :: nc type(group_type), allocatable :: children(:) nc = open_netcdf("input.nc") children = inquire_subgroups(nc)

`INQUIRE_VARIABLE` – Read Variable Metadata#

Synopsis
`VAR = INQUIRE_VARIABLE(GRP, NAME[, ERR])`

Class
Function.

Description
Return a variable’s metadata, including dimensions and attributes, without reading its data buffer.

Arguments
`GRPclass(group_type), INTENT(in)` Containing group.
`NAMEcharacter(len=*), INTENT(in)` Name of the variable to inspect.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Return
`VARtype(variable_type)` Requested variable metadata.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(group_type) :: atmosphere type(variable_type) :: temperature temperature = inquire_variable(atmosphere, "temperature")

`OPEN_NETCDF` – Open a NetCDF File#

Synopsis
`NC = OPEN_NETCDF(FILE[, MODE, ERR])`

Class
Function.

Description
Open or create a NetCDF dataset. `MODE` accepts `"r"`/`"read"` (default), `"w"`/`"write"`/`"replace"`, and `"a"`/`"append"`/`"rw"`.

Arguments
`FILEcharacter(len=*), INTENT(in)` Path of the dataset to open or create.
`MODEcharacter(len=*), OPTIONAL, INTENT(in)` Requested file access mode.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Return
`NCtype(netcdf_type)` Opened or created NetCDF dataset.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(netcdf_type) :: nc nc = open_netcdf("input.nc", mode="r")

`SHAPE` – Get Variable Extents#

Synopsis
`EXTENTS = SHAPE(VAR)`

Class
Function.

Description
Return allocatable default-integer dimension extents in Fortran order.

Arguments
`VARtype(variable_type), INTENT(in)` Variable to inspect.

Return
`EXTENTSinteger, allocatable` Variable extents in Fortran order.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(variable_type) :: var integer, allocatable :: extents(:) extents = shape(var)

`SIZE` – Get Element Count#

Synopsis
`N = SIZE(VAR[, DIM])`

Class
Function.

Description
Return the total element count as `integer(int64)`, or the one-based Fortran-order length of `DIM`.

Arguments
`VARtype(variable_type), INTENT(in)` Variable to inspect.
`DIMinteger, OPTIONAL, INTENT(in)` One-based Fortran-order dimension to select.

Return
`Ninteger(int64)` Total element count or the selected dimension length.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(variable_type) :: var integer(int64) :: elements elements = size(var) print *, size(var), size(var, dim=1)

`SUM` – Add Compatible Variables#

Synopsis
`TOTAL = SUM(VARS)`

Class
Function.

Description
Return the element-wise sum of a rank-one array of compatible, materialized variables. The result uses the first variable’s metadata.

Arguments
`VARStype(variable_type), DIMENSION(:), INTENT(in)` Compatible variables with materialized data.

Return
`TOTALtype(variable_type)` Element-wise sum with the first variable’s metadata.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(variable_type) :: pressure, base_pressure, total total = sum([pressure, base_pressure])

`TO_NETCDF` – Write a NetCDF File#

Synopsis
`CALL TO_NETCDF(FILE, VARS[, ATTS, ERR])` `CALL TO_NETCDF(FILE, GRP[, ATTS, ERR])`

Class
Generic subroutine.

Description
Write a scalar or rank-one array of variables, or a scalar or rank-one array of groups. A scalar group becomes the file root and its name is ignored. A group array becomes direct children of a new root; no first-level group may be named `/`.

Arguments
`FILEcharacter(len=*), INTENT(in)` Path of the output file.
`VARStype(variable_type), scalar or dimension(:), INTENT(in)` Variables to write.
`GRPtype(group_type), scalar or dimension(:), INTENT(in)` Group model to write.
`ATTStype(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)` Root attributes when writing variables or groups.
`ERRtype(error_type), OPTIONAL, INTENT(out)` Receives an operation error.

Example
use, non_intrinsic :: nc4f implicit none (type, external) type(group_type) :: root type(attribute_type) :: title title = "title" .att. "Output" call to_netcdf("output.nc", root, atts=[title])

Functions and Subroutines

Contents

Functions and Subroutines#

CLOSE_NETCDF – Close a NetCDF File#

DATARRAY – Construct a Variable#

DATASET – Construct a Group#

EXTRACT – Access Model Data#

GET_ATTRIBUTE – Read Attributes#

GET_GROUP – Get a Child Group#

GET_VARIABLE – Read a Variable#

INITIALIZE – Allocate Model Storage#

INQUIRE_DIMENSIONS – Get Dimensions#

INQUIRE_GROUP – Materialize Group Metadata#

INQUIRE_SUBGROUPS – List Child Groups#

INQUIRE_VARIABLE – Read Variable Metadata#

OPEN_NETCDF – Open a NetCDF File#

SHAPE – Get Variable Extents#

SIZE – Get Element Count#

SUM – Add Compatible Variables#

TO_NETCDF – Write a NetCDF File#

`CLOSE_NETCDF` – Close a NetCDF File#

`DATARRAY` – Construct a Variable#

`DATASET` – Construct a Group#

`EXTRACT` – Access Model Data#

`GET_ATTRIBUTE` – Read Attributes#

`GET_GROUP` – Get a Child Group#

`GET_VARIABLE` – Read a Variable#

`INITIALIZE` – Allocate Model Storage#

`INQUIRE_DIMENSIONS` – Get Dimensions#

`INQUIRE_GROUP` – Materialize Group Metadata#

`INQUIRE_SUBGROUPS` – List Child Groups#

`INQUIRE_VARIABLE` – Read Variable Metadata#

`OPEN_NETCDF` – Open a NetCDF File#

`SHAPE` – Get Variable Extents#

`SIZE` – Get Element Count#

`SUM` – Add Compatible Variables#

`TO_NETCDF` – Write a NetCDF File#