General — HARP 1.13 documentation

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

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `path`: Absolute path to the udunits2.xml file

  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.

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

  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.

  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’.

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

    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_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.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `enable`:

        - 0: Disable creation of collocation_datetime variables.

        - 1: Enable creation of collocation_datetime variables.

  int `harp_get_option_create_collocation_datetime`(void)

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

    See

      harp_set_option_create_collocation_datetime()

    Return

      - `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.

      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_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.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `method`:

        - 0: Assume uncertainties to be uncorrelated.

        - 1: Assume uncertainties to be fully correlated.

  int `harp_get_option_propagate_uncertainty`(void)

    Retrieve the current setting for how to propagate uncertainty.

    See

      harp_set_option_propagate_uncertainty()

    Return

      - `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.

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

    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`