General

group harp_general

The HARP General module contains all general and miscellaneous functions and procedures of HARP.

Defines

HARP_NUM_DATA_TYPES (6)
HARP_NUM_DIM_TYPES (5)

Typedefs

typedef enum harp_data_type_enum harp_data_type
typedef union harp_scalar_union harp_scalar
typedef union harp_array_union harp_array
typedef enum harp_dimension_type_enum harp_dimension_type

Enums

enum harp_data_type_enum

Values:

harp_type_int8

BYTE

harp_type_int16

INTEGER

harp_type_int32

LONG

harp_type_float

FLOAT

harp_type_double

DOUBLE

harp_type_string

STRING

enum harp_dimension_type_enum

Values:

harp_dimension_independent = -1
harp_dimension_time
harp_dimension_latitude
harp_dimension_longitude
harp_dimension_vertical
harp_dimension_spectral

Functions

int harp_convert_unit(const char *from_unit, const char *to_unit, long num_values, double *value)

Perform unit conversion on data

Apply unit conversion on a range of floating point values. Conversion will be performed in-place. If there is no conversion available from the current unit to the new unit then an error will be raised.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • from_unit: Existing unit of the data that should be converted (use udunits2 compliant units).
  • to_unit: Unit to which the data should be converted (use udunits2 compliant units).
  • num_values: Number of floating point values in value.
  • value: Array of floating point values that should be converted.

const char *harp_basename(const char *path)

Remove everything but the last pathname component from path.

Return
Pointer to the last pathname component of path, i.e. everything from the end of path up to the first pathname component separation character (‘\’ or ‘/’ on Windows, ‘/’ otherwise).
Parameters
  • path: Path to compute the basename of.

static void clean_path(char *path)
int harp_path_find_file(const char *searchpath, const char *filename, char **location)
int harp_path_from_path(const char *initialpath, int is_filepath, const char *appendpath, char **resultpath)
int harp_path_for_program(const char *argv0, char **location)
const char *harp_get_data_type_name(harp_data_type data_type)

Returns the name of a data type.

Return
if the data type is known a string containing the name of the type, otherwise the string “unknown”.
Parameters
  • data_type: HARP basic data type

long harp_get_size_for_type(harp_data_type data_type)

Retrieve the byte size for a HARP data type.

Return
The size of the data type in bytes.
Parameters
  • data_type: Data type for which to retrieve the size.

harp_scalar harp_get_fill_value_for_type(harp_data_type data_type)

Retrieve the fill value for a HARP data type.

Return
The fill value for the data type.
Parameters
  • data_type: Data type for which to retrieve the fill value.

harp_scalar harp_get_valid_min_for_type(harp_data_type data_type)

Retrieve the minimum valid value for a HARP data type.

Return
The minimum valid value of the data type.
Parameters
  • data_type: Data type for which to retrieve the minimum valid value.

harp_scalar harp_get_valid_max_for_type(harp_data_type data_type)

Retrieve the maximum valid value for a HARP data type.

Return
The maximum valid value of the data type.
Parameters
  • data_type: Data type for which to retrieve the maximum valid value.

int harp_is_fill_value_for_type(harp_data_type data_type, harp_scalar value)

Test if value equals the fill value for the specified data type.

Return
  • 0, Value is not equal to the fill value.
  • 1, Value equals the fill value.
Parameters
  • data_type: Data type corresponding to the value of value.
  • value: Value to test.

int harp_is_valid_min_for_type(harp_data_type data_type, harp_scalar value)

Test if value equals the minimum valid value for the specified data type.

Return
  • 0, Value is not equal to the minimum valid value.
  • 1, Value equals the minimum valid value.
Parameters
  • data_type: Data type corresponding to the value of value.
  • value: Value to test.

int harp_is_valid_max_for_type(harp_data_type data_type, harp_scalar value)

Test if value equals the maximum valid value for the specified data type.

Return
  • 0, Value is not equal to the maximum valid value.
  • 1, Value equals the maximum valid value.
Parameters
  • data_type: Data type corresponding to the value of value.
  • value: Value to test.

int harp_isfinite(double x)

Find out whether a double value is a finite number (i.e. not NaN and not infinite).

Return
  • 1, The double value is a finite number.
  • 0, The double value is not a finite number.
Parameters
  • x: A double value.

int harp_isnan(double x)

Find out whether a double value equals NaN (Not a Number).

Return
  • 1, The double value equals NaN.
  • 0, The double value does not equal NaN.
Parameters
  • x: A double value.

double harp_nan(void)

Retrieve a double value that respresents NaN (Not a Number).

Return
The double value ‘NaN’.

int harp_isinf(double x)

Find out whether a double value equals inf (either positive or negative infinity).

Return
  • 1, The double value equals inf.
  • 0, The double value does not equal inf.
Parameters
  • x: A double value.

int harp_isplusinf(double x)

Find out whether a double value equals +inf (positive infinity).

Return
  • 1, The double value equals +inf.
  • 0, The double value does not equal +inf.
Parameters
  • x: A double value.

int harp_ismininf(double x)

Find out whether a double value equals -inf (negative infinity).

Return
  • 1, The double value equals -inf.
  • 0, The double value does not equal -inf.
Parameters
  • x: A double value.

double harp_plusinf(void)

Retrieve a double value that respresents +inf (positive infinity).

Return
The double value ‘+inf’.

double harp_mininf(void)

Retrieve a double value that respresents -inf (negative infinity).

Return
The double value ‘-inf’.

void harp_str64(int64_t a, char *s)

Write 64 bit signed integer to a string. The string s will be 0 terminated.

Parameters
  • a: A signed 64 bit integer value.
  • s: A character buffer that is at least 21 bytes long.

void harp_str64u(uint64_t a, char *s)

Write 64 bit unsigned integer to a string. The string s will be 0 terminated.

Parameters
  • a: An unsigned 64 bit integer value.
  • s: A character buffer that is at least 21 bytes long.

int harp_set_coda_definition_path(const char *path)

Set the search path for CODA product definition files. This function should be called before harp_init() is called.

The CODA C library is used by the HARP C library for import of products that do not use the HARP format. To access data in a product, the CODA C library requires a definition of the internal structure of the product file (unless the product is stored in a self-describing file format). This information is stored in CODA product definition (.codadef) files.

The path should be a searchpath for CODA .codadef files similar like the PATH environment variable of your system. Path components should be separated by ‘;’ on Windows and by ‘:’ on other systems.

The path may contain both references to files and directories. CODA will load all .codadef files in the path. Any specified files should be valid .codadef files. For directories, CODA will (non-recursively) search the directory for all .codadef files.

If multiple files for the same product class exist in the path, CODA will only use the one with the highest revision number (this is normally equal to a last modification date that is stored in a .codadef file). If there are two files for the same product class with identical revision numbers, CODA will use the definitions of the first .codadef file in the path and ingore the second one.

Specifying a path using this function will prevent CODA from using the CODA_DEFINITION environment variable. If you still want CODA to acknowledge the CODA_DEFINITION environment variable then use something like this in your code: 

if (getenv("CODA_DEFINITION") == NULL)
{
    harp_set_coda_definition_path("<your path>");
}

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • path: Search path for .codadef files

int harp_set_coda_definition_path_conditional(const char *file, const char *searchpath, const char *relative_location)

Set the directory for CODA product definition files based on the location of another file. This function should be called before harp_init() is called.

The CODA C library is used by the HARP C library for import of products that do not use the HARP format. To access data in a product, the CODA C library requires a definition of the internal structure of the product file (unless the product is stored in a self-describing file format). This information is stored in CODA product definition (.codadef) files.

This function will try to find the file with filename file in the provided searchpath searchpath. The first directory in the searchpath where the file file exists will be appended with the relative directory relative_location to determine the CODA product definition path. This path will be used as CODA definition path. If the file could not be found in the searchpath then the CODA definition path will not be set.

If the CODA_DEFINITION environment variable was set then this function will not perform a search or set the definition path (i.e. the CODA definition path will be taken from the CODA_DEFINITION variable).

If you provide NULL for searchpath then the PATH environment variable will be used as searchpath. For instance, you can use harp_set_coda_definition_path_conditional(argv[0], NULL, ”../somedir”) to set the CODA definition path to a location relative to the location of your executable.

The searchpath, if provided, should have a similar format as the PATH environment variable of your system. Path components should be separated by ‘;’ on Windows and by ‘:’ on other systems.

The relative_location parameter can point either to a directory (in which case all .codadef files in this directory will be used) or to a single .codadef file.

Note that this function differs from harp_set_coda_definition_path() in two important ways:

  • it will not modify the definition path if the CODA_DEFINITION variable was set
  • it will set the definition path to just a single location (either a single file or a single directory)

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • file: Filename of the file to search for
  • searchpath: Search path where to look for the file file (can be NULL)
  • relative_location: Filepath relative to the directory from searchpath where file was found that should be used to determine the CODA definition path.

int harp_set_option_enable_aux_afgl86(int enable)

Enable/Disable the use of AFGL86 climatology in variable conversions Enabling this option will allow the derived variable functions to create variables using the built-in AFGL86 profiles. If datetime, latitude, and altitude variables are available then altitude regridded versions of the following climatological quantities can be created:

  • pressure
  • temperature
  • number_density (of air)
  • CH4_number_density
  • CO_number_density
  • CO2_number_density
  • H2O_number_density
  • N2O_number_density
  • NO2_number_density
  • O2_number_density
  • O3_number_density By default the use of AFGL86 is disabled. The use of AFGL86 can also be enabled by setting the HARP_AUX_AFGL86 environment variable.
    Return
    • 0, Success.
    • -1, Error occurred (check harp_errno).
    Parameters
    • enable:
      • 0: Disable use of AFGL86.
      • 1: Enable use of AFGL86.

int harp_get_option_enable_aux_afgl86(void)

Retrieve the current setting for the usage of AFGL86 option.

See
harp_set_option_enable_aux_afgl86()
Return
  • 0, Use of AFGL86 is disabled.
  • 1, Use of AFGL86 is enabled.

int harp_set_option_enable_aux_usstd76(int enable)

Enable/Disable the use of US Standard 76 climatology in variable conversions Enabling this option will allow the derived variable functions to create variables using the built-in US Standard 76 profiles. If an altitude variable is available then altitude regridded versions of the following climatological quantities can be created:

  • pressure
  • temperature
  • number_density (of air)
  • CH4_number_density
  • CO_number_density
  • CO2_number_density
  • H2O_number_density
  • N2O_number_density
  • NO2_number_density
  • O2_number_density
  • O3_number_density By default the use of US Standard 76 is disabled. The use of US Standard 76 can also be enabled by setting the HARP_AUX_USSTD76 environment variable.
    Return
    • 0, Success.
    • -1, Error occurred (check harp_errno).
    Parameters
    • enable:
      • 0: Disable use of US Standard 76.
      • 1: Enable use of US Standard 76.

int harp_get_option_enable_aux_usstd76(void)

Retrieve the current setting for the usage of US Standard 76 option.

See
harp_set_option_enable_aux_usstd76()
Return
  • 0, Use of US Standard 76 is disabled.
  • 1, Use of US Standard 76 is enabled.

int harp_set_option_hdf5_compression(int level)

Set the compression level to use for storing variables in HDF5 files.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • level: The compression level (1=low, ..., 9=high) or 0 to disable compression.

int harp_get_option_hdf5_compression(void)

Retrieve the compression level that is used for storing variables in HDF5 files.

See
harp_set_option_hdf5_compression()
Return
0=disabled, 1=low, ..., 9=high

int harp_set_option_regrid_out_of_bounds(int method)

Set how to treat out of bound values during regridding operations. This is only applicable for point interpolation regridding. Any point that falls outside the target grid can be either set to NaN (the default), set to the nearest edge value, or set based on extrapolation (of two nearest points). This global HARP option determines which of the three cases will be used.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).
Parameters
  • method:
    • 0: Set values outside source grid to NaN
    • 1: Set value outside source grid to edge value (=min/max of source grid)
    • 2: Extrapolate based on nearest two edge values

int harp_get_option_regrid_out_of_bounds(void)

Retrieve the current setting for treating out of bound values during regridding operations.

See
harp_set_option_regrid_out_of_bounds()
Return
  • 0 Set values outside source grid to NaN
  • 1 Set value outside source grid to edge value (=min/max of source grid)
  • 2 Extrapolate based on nearest two edge values

int harp_init(void)

Initializes the HARP C library. This function should be called before any other HARP C library function is called (except for harp_set_coda_definition_path(), harp_set_coda_definition_path_conditional(), and harp_set_warning_handler()).

HARP may at some point after calling harp_init() also initialize the underlying CODA C library that is used for ingestion of products that are not using the HARP format. The CODA C library may require access to .codadef files that describe the formats of certain product files. In order to tell CODA where these .codadef files are located you will have to either set the CODA_DEFINITION environment variable to the proper path, or set the path programmatically using the harp_set_coda_definition_path() or harp_set_coda_definition_path_conditional() function, before calling harp_init() for the first time.

If you use CODA functions directly in combination with HARP functions you should call coda_init() and coda_done() explictly yourself and not rely on HARP having performed the coda_init() for you.

It is valid to perform multiple calls to harp_init() after each other. Only the first call to harp_init() will do the actual initialization and all following calls to harp_init() will only increase an initialization counter. Each call to harp_init() needs to be matched by a call to harp_done() at clean-up time (i.e. the number of calls to harp_done() needs to be equal to the number of calls to harp_init()). Only the final harp_done() call (when the initialization counter has reached 0) will perform the actual clean-up of the HARP C library.

Return
  • 0, Success.
  • -1, Error occurred (check harp_errno).

void harp_done(void)

Finalizes the HARP C library. This function should be called to let the HARP C library free up any resources it has claimed since initialization.

It is valid to perform multiple calls to harp_init() after each other. Only the first call to harp_init() will do the actual initialization and all following calls to harp_init() will only increase an initialization counter. Each call to harp_init() needs to be matched by a call to harp_done() at clean-up time (i.e. the number of calls to harp_done() needs to be equal to the number of calls to harp_init()). Only the final harp_done() call (when the initialization counter has reached 0) will perform the actual clean-up of the HARP C library.

Calling a HARP function other than harp_init() after the final harp_done() call will result in undefined behavior.

union harp_scalar_union

Public Members

int8_t int8_data
int16_t int16_data
int32_t int32_data
float float_data
double double_data
union harp_array_union

Public Members

int8_t *int8_data
int16_t *int16_data
int32_t *int32_data
float *float_data
double *double_data
char **string_data
void *ptr