# 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](exposed-nc-constants.md) 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 | |:--| | `NC``type(netcdf_type), INTENT(inout)`
Open dataset to close. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `NAME``character(len=*), INTENT(in)`
Variable name. | | `VALUES``TYPE(INTEGER(INT8, INT16, INT32, INT64), REAL(REAL32, REAL64), CHARACTER), RANK(1:15), INTENT(IN)`
Values to copy or borrow. | | `DIMS``type(dimension_type), DIMENSION(:), INTENT(in)`
Dimensions matching the array shape. | | `ATTS``type(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)`
Variable attributes. | | `DEEP``logical, OPTIONAL, INTENT(in)`
Choose owned (`.true.`) or borrowed (`.false.`) storage. | | Return | |:--| | `VAR``type(variable_type)`
Constructed variable. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `NAME``character(len=*), INTENT(in)`
Group name. | | `VARS``type(variable_type), DIMENSION(:), INTENT(in)`
Variables to attach to the group. | | `GRPS``type(group_type), DIMENSION(:), INTENT(in)`
Child groups to attach to the group. | | `ATTS``type(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)`
Attributes to attach to the group. | | `DEEP``logical, OPTIONAL, INTENT(in)`
Clone supplied model components when true. | | Return | |:--| | `GRP``type(group_type)`
Constructed group. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `ATT``type(attribute_type), TARGET, INTENT(in)`
Attribute supplying storage. | | `VAR``type(variable_type), TARGET, INTENT(in)`
Variable supplying storage. | | `VALUES``TYPE(INTEGER(INT8, INT16, INT32, INT64), REAL(REAL32, REAL64), CHARACTER), RANK(0:15), POINTER, INTENT(OUT)`
Type- and rank-compatible pointer receiving the association. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `GRP``class(group_type), INTENT(in)`
Containing group. | | `VAR``type(variable_type), OPTIONAL, INTENT(in)`
Variable whose attributes to read. | | `NAME``character(len=*), OPTIONAL, INTENT(in)`
Name of one attribute to read. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | | Return | |:--| | `ATT``type(attribute_type)`
Requested attribute.
`ATTS``type(attribute_type), allocatable`
Attributes attached to the requested group or variable. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `PARENT``class(group_type), INTENT(in)`
Containing group. | | `NAME``character(len=*), INTENT(in)`
Name of a direct child group. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | | Return | |:--| | `CHILD``type(group_type)`
Matching direct child group. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `GRP``class(group_type), INTENT(in)`
Containing group. | | `NAME``character(len=*), INTENT(in)`
Name of the variable to read. | | `START``integer, DIMENSION(:), OPTIONAL, INTENT(in)`
One-based start index for each dimension. | | `COUNT``integer, DIMENSION(:), OPTIONAL, INTENT(in)`
Number of values to read in each dimension. | | `STRIDE``integer, DIMENSION(:), OPTIONAL, INTENT(in)`
Step between values in each dimension. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | | Return | |:--| | `VAR``type(variable_type)`
Requested variable and its selected data. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `ATT``type(attribute_type), INTENT(inout)`
Attribute to initialize. | | `VAR``type(variable_type), INTENT(inout)`
Variable to initialize. | | `NAME``character(len=*), INTENT(in)`
Name for the initialized object. | | `DTYPE``integer(data_type), INTENT(in)`
NetCDF data type for from-scratch initialization. | | `LEN``integer(int64), INTENT(in)`
Element count for from-scratch initialization. | | `DIMS``type(dimension_type), DIMENSION(:), INTENT(in)`
Dimensions for a from-scratch variable. | | `MOLD``type(attribute_type) or type(variable_type), INTENT(in)`
Object supplying metadata and, optionally, storage. | | `ATTS``type(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)`
Attributes to attach to an initialized variable. | | `DEEP``logical, OPTIONAL, INTENT(in)`
Allocate fresh mold storage when true, or borrow it when false. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `GRP``class(group_type), INTENT(in)`
Dataset or group to inspect. | | `VAR``type(variable_type), OPTIONAL, INTENT(in)`
Variable whose dimensions to return. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | | Return | |:--| | `DIMS``type(dimension_type), allocatable`
Dimensions attached to the requested group or variable. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `GRP``class(group_type), INTENT(inout)`
Group receiving materialized metadata. | | `INQ_DIMS``logical, OPTIONAL, INTENT(in)`
Whether to inquire dimensions. | | `INQ_ATTS``logical, OPTIONAL, INTENT(in)`
Whether to inquire attributes. | | `INQ_VARS``logical, OPTIONAL, INTENT(in)`
Whether to inquire variables. | | `INQ_GRPS``logical, OPTIONAL, INTENT(in)`
Whether to inquire direct child groups. | | `RECUR``logical, OPTIONAL, INTENT(in)`
Whether to recurse into child groups. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `PARENT``class(group_type), INTENT(in)`
Group to inspect. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | | Return | |:--| | `CHILDREN``type(group_type), allocatable`
Direct child groups with populated identifiers and names. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `GRP``class(group_type), INTENT(in)`
Containing group. | | `NAME``character(len=*), INTENT(in)`
Name of the variable to inspect. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | | Return | |:--| | `VAR``type(variable_type)`
Requested variable metadata. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `FILE``character(len=*), INTENT(in)`
Path of the dataset to open or create. | | `MODE``character(len=*), OPTIONAL, INTENT(in)`
Requested file access mode. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | | Return | |:--| | `NC``type(netcdf_type)`
Opened or created NetCDF dataset. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `VAR``type(variable_type), INTENT(in)`
Variable to inspect. | | Return | |:--| | `EXTENTS``integer, allocatable`
Variable extents in Fortran order. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `VAR``type(variable_type), INTENT(in)`
Variable to inspect. | | `DIM``integer, OPTIONAL, INTENT(in)`
One-based Fortran-order dimension to select. | | Return | |:--| | `N``integer(int64)`
Total element count or the selected dimension length. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `VARS``type(variable_type), DIMENSION(:), INTENT(in)`
Compatible variables with materialized data. | | Return | |:--| | `TOTAL``type(variable_type)`
Element-wise sum with the first variable's metadata. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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 | |:--| | `FILE``character(len=*), INTENT(in)`
Path of the output file. | | `VARS``type(variable_type), scalar or dimension(:), INTENT(in)`
Variables to write. | | `GRP``type(group_type), scalar or dimension(:), INTENT(in)`
Group model to write. | | `ATTS``type(attribute_type), DIMENSION(:), OPTIONAL, INTENT(in)`
Root attributes when writing variables or groups. | | `ERR``type(error_type), OPTIONAL, INTENT(out)`
Receives an operation error. | :::{list-table} :class: example-table :header-rows: 1 * - Example * - ```fortran 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]) ``` :::