NuSDaS Interface Reference Manual

Notation Note for NuSDaS Interface

Data Types in nusdas.h

• Symbol N_SI4 in following text is typedef-ed name in "nusdas.h". It means 32bit signed integer type, and is equivalent to int in most environments.
• In Fortran, subroutine arguments given to place declared as CHARACTER(n) must have at least n characters length.
• In C, function arguments given to place declared as const char * must have at least the same size to corresponding Fortran interface. Character array have not to be terminated with NUL ('\0') character.

NuSDaS Data Identifier Dimensions

In NuSDaS, data is identified by following dimensions: data type, base time, member name, valid time, plane name, element name.

data type

Data type is 16-character string composed from type1, type2, and type3.

type1

Type1 is 8-character string. The first 4 characters are model name. Following 2 characters are horizontal grid name. The last 2 characters are vertical grid name. (See tables for predefined name).

type2

Type2 is 4-character string. The first 2 characters are data attribute name. The last 2 characters are time attribute name. (See tables for predefined name).

type3

Type3 is 4-character string. You can use arbitrary name for this field; it does not affect behavior of library nor conventional meaning. Name "STD1" is used for the most typical operational dataset.

base time

Base time is also known as reference time. The initial time is used for forecast data. It is expressed as a number of minutes counted from 00:00GMT January 1, 1801 ^*1. Typically, return value of NWP_GETTIME@ is used. In case of constant data, 0 is used as base time.

member name

Member is 4-character string representing member of ensemble forecast. Name " " (four spaces) is used for non-ensemble data. Note that this field must have at least 4 characters, and space character should be filled if conventional name is shorter. For example, the control run of ensemble is called '00' in JMA, and it is represented as "00 " (double digit zero, followed by two spaces) in NuSDaS. Do not use "00" (double digit zero, followed by NUL terminator) even in C interface.

valid time

Valid time is a time or period to which the requested data is most closely related. It is expressed as a pair of integers, interpreted as beginning and ending of the period. If the requested data corresponds to one time moment, the end of time span is expressed as special value 1. In case of constant data, (0, 1) is used as valid time. Note that the value is in absolute date, not relative time from base time or any other date.

plane name

Plane name identifies plane/layer to which the requested data belongs. In most cases, it is vertical height. Plane name is a pair of six-character string. They are upper and lower boundary of layer and two plane names. Data for a plane is identified by a pair of two same plane names. For example, "SURF " represents surface, and "500 " denotes 500hPa level. Meaning of numbers is dependent to the vertical coordinate of the dataset shown in type1. Note that these fields must have at least 6 characters.

element name

Physical element name. Standard names are shown in table. Note that this field must have at least 6 characters.

Data Identifier in the Interface

In NuSDaS interface functions/subroutines, they are specified with the first 3-10 arguments. They looks like

/* C */
    int
nusdas_xxx(type1, type2, type3, btime, memb, vtime1, plane1, elem, ...)
    int
nusdas_xxx2(type1, type2, type3, btime, memb, vtime1, vtime2, plane1, plane2, elem, ...)

! Fortran
SUBROUTINE NUSDAS_XXX(type1, type2, type3, btime, memb, vtime1, plane1, elem, ...)
SUBROUTINE NUSDAS_XXX2(type1, type2, type3, btime, memb, vtime1, vtime2, plane1, plane2, elem, ...)

Some subroutines/functions have two forms: name of one ends with '2', and the other without '2'. In such a case, the with-2-form is the essential interface. Calling the latter, the no-2-form, is equivalent to that of the with-2-form with vtime2 and plane2 set to 1 and plane1 respectively.

^*1Using 32bit signed integer, it will overflow in year 5884, and it can be enough late even for climate change simulation