1"""
  2Introduction
  3============
  4
  5grib2io_interp is a component package to the parent package, [grib2io](https://github.com/NOAA-MDL/grib2io).
  6This package provides interfaces to the Fortran-based [NCEPLIBS-ip](https://github.com/NOAA-EMC/NCEPLIBS-ip)
  7general interpolation library. The interface supports performing scalar and vector interpolation. `grib2io_interp.interpolate`
  8is a F2PY extension module that contains 2 subroutines: `interpolate_scalar` and `interpolate_vector`.  These
  9subroutines serve as wrappers to the NCEPLIBS-ip subroutines `ipolates_grib2` and `ipolatev_grib2` respectively.
 10
 11It is **recommended** that you access these interpolation subroutines via [`grib2io.interpolate()`](https://noaa-mdl.github.io/grib2io/grib2io.html#interpolate).
 12
 13OpenMP Support
 14==============
 15
 16NCEPLIBS-ip can be built with support for OpenMP threading. This is also supported in grib2io-interp. The
 17F2PY signatures for `interpolate_scalar` and `interpolate_vector` subroutines contain the keyword `threadsafe`
 18which unlocks Python's global interpretor lock (gil) and allows for threading. grib2io-interp contains a
 19second F2PY extension module, `grib2io_interp.openmp_handler`, that allows the user to get and set the number
 20of OpenMP threads.  These functions are made public by `grib2io_interp.get_openmp_threads()` and 
 21`grib2io_interp.set_openmp_threads()`.
 22
 23NCEP Grid Template 32769
 24========================
 25
 26[NCEPLIBS-ip v5.1.0](https://github.com/NOAA-EMC/NCEPLIBS-ip/releases/tag/v5.1.0) allows for interpolation
 27from Rotated Latitude/Longitude Arakawa Grids, specifically grid templates [32768](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp3-32768.shtml)
 28and [32769](https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp3-32769.shtml). In order to interpolate
 29from this grid, the `ncep_post_arakawa` logical scalar in the ip::ip_grid_mod needs to be set to `.true.`. In grib2io_interp,
 30we have an interface to set this flag with `grib2io_interp.set_ncep_post_arakawa_flag()`. Note that is is only
 31necessary for template 32769.
 32"""
 33
 34from .__config__ import grib2io_interp_version as __version__
 35from .__config__ import has_openmp_support
 36
 37def set_ncep_post_arakawa_flag(flag: bool):
 38    """
 39    Set the value of the ncep_post_arakawa logical scalar from
 40    ip::ip_grid_mod.
 41
 42    Parameters
 43    ----------
 44    flag
 45        Set to `True` or `False` to use the NCEP post method for
 46        Arakawa grids.
 47    """
 48    try:
 49        from . import interpolate
 50        interpolate.set_ncep_post_arakawa_flag(flag)
 51    except(ImportError):
 52        pass
 53
 54def get_ncep_post_arakawa_flag():
 55    """
 56    Get the value of the ncep_post_arakawa logical scalar from
 57    ip::ip_grid_mod.
 58
 59    Returns
 60    -------
 61    bool
 62    """
 63    try:
 64        from . import interpolate
 65        value = interpolate.get_ncep_post_arakawa_flag()
 66        return True if value == 1 else False
 67    except(ImportError):
 68        pass
 69
 70def get_openmp_threads():
 71    """
 72    Return the number of OpenMP threads.
 73
 74    Returns
 75    -------
 76    int
 77        The number of OpenMP threads.
 78    """
 79    try:
 80        from . import openmp_handler
 81        return openmp_handler.get_openmp_threads()
 82    except(ImportError):
 83        pass
 84
 85def set_openmp_threads(n: int):
 86    """
 87    Set the number of OpenMP threads.
 88
 89    Parameters
 90    ----------
 91    n
 92        The number of OpenMP threads.
 93    """
 94    if n < 1:
 95        raise ValueError(f'Number of threads must be > 0.')
 96    try:
 97        from . import openmp_handler
 98        openmp_handler.set_openmp_threads(n)
 99    except(ImportError):
100        pass