General

group harp_general

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

Defines

HARP_NUM_DATA_TYPES

HARP_NUM_DIM_TYPES

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:

enumerator harp_type_int8: BYTE

enumerator harp_type_int16: INTEGER

enumerator harp_type_int32: LONG

enumerator harp_type_float: FLOAT

enumerator harp_type_double: DOUBLE

enumerator harp_type_string: STRING

enum harp_dimension_type_enum

Values:

enumerator harp_dimension_independent

enumerator harp_dimension_time

enumerator harp_dimension_latitude

enumerator harp_dimension_longitude

enumerator harp_dimension_vertical

enumerator harp_dimension_spectral

Functions

int harp_set_udunits2_xml_path(const char *path)

Set the location of the udunits2 unit conversion xml configuration file.

This function should be called before harp_init() is called.

The HARP C library uses the udunits2 library to perform unit conversions. The xml configuration files for udunits2 are included with a HARP installation and a default absolute path to these xml files is built into the library.

If the HARP installation ends up in a different location on disk compared to what was provided at build time then you will either need to set the UDUNITS2_XML_PATH environment variable or call one of the functions harp_set_udunits2_xml_path() or harp_set_udunits2_xml_path_conditional() to set the path programmatically.

The path should be an absolute path to the udunits2.xml file that was included with the HARP installation.

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

if (getenv("UDUNITS2_XML_PATH") == NULL)
{
    harp_set_udunits2_xml_path("<your path>");
}

Parameters:

path – Absolute path to the udunits2.xml file

Returns:

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

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

Set the location of the udunits2 xml configuration file based on the location of another file.

This function should be called before harp_init() is called.

The HARP C library uses the udunits2 library to perform unit conversions. The xml configuration files for udunits2 are included with a HARP installation and a default absolute path to the main xml file is built into the library.

If the HARP installation ends up in a different location on disk compared to what was provided at build time then you will either need to set the UDUNITS2_XML_PATH environment variable or call one of the functions harp_set_udunits2_xml_path() or harp_set_udunits2_xml_path_conditional() to set the path programmatically.

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 location relative_location to determine the udunits2 xml path. If the file to search for could not be found in the searchpath then the HARP udunits2 xml path will not be set.

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

If you provide NULL for searchpath then the PATH environment variable will be used as searchpath. For instance, you can use harp_set_udunits2_xml_path_conditional(argv[0], NULL, “../somedir/udunits2.xml”) to set the udunits2 xml 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 should point to the udunits2.xml file itself (and not the directory that the file is in).

Note that this function differs from harp_set_udunits2_xml_path() in that it will not modify the udunits2 xml path if the UDUNITS2_XML_PATH variable was set.

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 provides the location of the udunits2.xml file.

Returns:

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

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.

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.

Returns:

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

const char *harp_basename(const char *path)

Remove everything but the last pathname component from path.

Parameters:: path – Path to compute the basename of.
Returns:: 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).

const char *harp_get_data_type_name(harp_data_type data_type)

Returns the name of a data type.

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

long harp_get_size_for_type(harp_data_type data_type)

Retrieve the byte size for a HARP data type.

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

harp_scalar harp_get_fill_value_for_type(harp_data_type data_type)

Retrieve the fill value for a HARP data type.

Parameters:: data_type – Data type for which to retrieve the fill value.
Returns:: The fill value for the data type.

harp_scalar harp_get_valid_min_for_type(harp_data_type data_type)

Retrieve the minimum valid value for a HARP data type.

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

harp_scalar harp_get_valid_max_for_type(harp_data_type data_type)

Retrieve the maximum valid value for a HARP data type.

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

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.

Parameters:

data_type – Data type corresponding to the value of value.
value – Value to test.

Returns:

0, Value is not equal to the fill value.
1, Value equals the fill value.

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.

Parameters:

data_type – Data type corresponding to the value of value.
value – Value to test.

Returns:

0, Value is not equal to the minimum valid value.
1, Value equals the minimum valid value.

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.

Parameters:

data_type – Data type corresponding to the value of value.
value – Value to test.

Returns:

0, Value is not equal to the maximum valid value.
1, Value equals the maximum valid value.

int harp_isfinite(double x)

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

Parameters:

x – A double value.

Returns:

1, The double value is a finite number.
0, The double value is not a finite number.

int harp_isnan(double x)

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

Parameters:

x – A double value.

Returns:

1, The double value equals NaN.
0, The double value does not equal NaN.

double harp_nan(void)

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

Returns:: The double value ‘NaN’.

int harp_isinf(double x)

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

Parameters:

x – A double value.

Returns:

1, The double value equals inf.
0, The double value does not equal inf.

int harp_isplusinf(double x)

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

Parameters:

x – A double value.

Returns:

1, The double value equals +inf.
0, The double value does not equal +inf.

int harp_ismininf(double x)

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

Parameters:

x – A double value.

Returns:

1, The double value equals -inf.
0, The double value does not equal -inf.

double harp_plusinf(void)

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

Returns:: The double value ‘+inf’.

double harp_mininf(void)

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

Returns:: The double value ‘-inf’.

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 ignore 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>");
}

Parameters:

path – Search path for .codadef files

Returns:

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

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)

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.

Returns:

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

int harp_set_option_create_collocation_datetime(int enable)

Enable/Disable the creation of collocation_datetime variables Enabling this option will create a collocation_datetime variable when a collocate_left or collocation_right operation is performed. The collocation_datetime variable will contain the datetime of the sample from the other dataset for the collocated pair. The variable will only be created if the collocation result file contains a datetime_diff column. By default the creation of the collocation_datetime variable is disabled.

Parameters:

enable –

0: Disable creation of collocation_datetime variables.
1: Enable creation of collocation_datetime variables.

Returns:

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

int harp_get_option_create_collocation_datetime(void)

Retrieve the current setting for the creation of collocation_datetime variables option.

Returns:

0, Creation of collocation_datetime variables is disabled.
1, Ceation of collocation_datetime variables is enabled.

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.

Parameters:

enable –

0: Disable use of AFGL86.
1: Enable use of AFGL86.

Returns:

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

int harp_get_option_enable_aux_afgl86(void)

Retrieve the current setting for the usage of AFGL86 option.

See also

harp_set_option_enable_aux_afgl86()

Returns:

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.

Parameters:

enable –

0: Disable use of US Standard 76.
1: Enable use of US Standard 76.

Returns:

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

int harp_get_option_enable_aux_usstd76(void)

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

See also

harp_set_option_enable_aux_usstd76()

Returns:

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.

Parameters:

level – The compression level (1=low, …, 9=high) or 0 to disable compression.

Returns:

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

int harp_get_option_hdf5_compression(void)

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

See also

harp_set_option_hdf5_compression()

Returns:: 0=disabled, 1=low, …, 9=high

int harp_set_option_propagate_uncertainty(int method)

Set how to propagate uncertainty. This is only applicable for operations that support propagation of uncertainties. And then only if there is a choice. The propagation can either assume uncertainties to be fully uncorrelated (the default) or fully correlated.

Parameters:

method –

0: Assume uncertainties to be uncorrelated.
1: Assume uncertainties to be fully correlated.

Returns:

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

int harp_get_option_propagate_uncertainty(void)

Retrieve the current setting for how to propagate uncertainty.

See also

harp_set_option_propagate_uncertainty()

Returns:

0 Assume uncertainties to be uncorrelated.
1 Assume uncertainties to be fully correlated.

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.

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

Returns:

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

int harp_get_option_regrid_out_of_bounds(void)

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

See also

harp_set_option_regrid_out_of_bounds()

Returns:

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() explicitly 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.

Returns:

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