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 forsearchpath
: 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 NaN1
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
-
int8_t
-
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
-
int8_t *
-