61class open():
 62    """
 63    GRIB2 File Object.
 64
 65    A physical file can contain one or more GRIB2 messages.  When instantiated,
 66    class `grib2io.open`, the file named `filename` is opened for reading (`mode
 67    = 'r'`) and is automatically indexed.  The indexing procedure reads some of
 68    the GRIB2 metadata for all GRIB2 Messages.  A GRIB2 Message may contain
 69    submessages whereby Section 2-7 can be repeated.  grib2io accommodates for
 70    this by flattening any GRIB2 submessages into multiple individual messages.
 71
 72    It is important to note that GRIB2 files from some Meteorological agencies
 73    contain other data than GRIB2 messages.  GRIB2 files from ECMWF can contain
 74    GRIB1 and GRIB2 messages.  grib2io checks for these and safely ignores them.
 75
 76    Attributes
 77    ----------
 78    closed : bool
 79        `True` is file handle is close; `False` otherwise.
 80    current_message : int
 81        Current position of the file in units of GRIB2 Messages.
 82    levels : tuple
 83        Tuple containing a unique list of wgrib2-formatted level/layer strings.
 84    messages : int
 85        Count of GRIB2 Messages contained in the file.
 86    mode : str
 87        File IO mode of opening the file.
 88    name : str
 89        Full path name of the GRIB2 file.
 90    size : int
 91        Size of the file in units of bytes.
 92    variables : tuple
 93        Tuple containing a unique list of variable short names (i.e. GRIB2
 94        abbreviation names).
 95    """
 96
 97    __slots__ = ('_fileid', '_filehandle', '_hasindex', '_index', '_nodata',
 98                 '_pos', 'closed', 'current_message', 'messages', 'mode',
 99                 'name', 'size')
100
101    def __init__(self, filename: str, mode: Literal["r", "w", "x"] = "r", **kwargs):
102        """
103        Initialize GRIB2 File object instance.
104
105        Parameters
106        ----------
107        filename
108            File name containing GRIB2 messages.
109        mode: default="r"
110            File access mode where "r" opens the files for reading only; "w"
111            opens the file for overwriting and "x" for writing to a new file.
112        """
113        # Manage keywords
114        if "_xarray_backend" not in kwargs:
115            kwargs["_xarray_backend"] = False
116            self._nodata = False
117        else:
118            self._nodata = kwargs["_xarray_backend"]
119
120        # All write modes are read/write.
121        # All modes are binary.
122        if mode in ("a", "x", "w"):
123            mode += "+"
124        mode = mode + "b"
125
126        # Some GRIB2 files are gzipped, so check for that here, but
127        # raise error when using xarray backend.
128        if 'r' in mode:
129            self._filehandle = builtins.open(filename, mode=mode)
130            # Gzip files contain a 2-byte header b'\x1f\x8b'.
131            if self._filehandle.read(2) == b'\x1f\x8b':
132                self._filehandle.close()
133                if kwargs["_xarray_backend"]:
134                    raise RuntimeError('Gzip GRIB2 files are not supported by the Xarray backend.')
135                import gzip
136                self._filehandle = gzip.open(filename, mode=mode)
137            else:
138                self._filehandle = builtins.open(filename, mode=mode)
139        else:
140            self._filehandle = builtins.open(filename, mode=mode)
141
142        self.name = os.path.abspath(filename)
143        fstat = os.stat(self.name)
144        self._hasindex = False
145        self._index = {}
146        self.mode = mode
147        self.messages = 0
148        self.current_message = 0
149        self.size = fstat.st_size
150        self.closed = self._filehandle.closed
151        self._fileid = hashlib.sha1((self.name+str(fstat.st_ino)+
152                                     str(self.size)).encode('ASCII')).hexdigest()
153        if 'r' in self.mode:
154            self._build_index()
155        # FIX: Cannot perform reads on mode='a'
156        #if 'a' in self.mode and self.size > 0: self._build_index()
157
158
159    def __delete__(self, instance):
160        self.close()
161        del self._index
162
163
164    def __enter__(self):
165        return self
166
167
168    def __exit__(self, atype, value, traceback):
169        self.close()
170
171
172    def __iter__(self):
173        yield from self._index['msg']
174
175
176    def __len__(self):
177        return self.messages
178
179
180    def __repr__(self):
181        strings = []
182        for k in self.__slots__:
183            if k.startswith('_'): continue
184            strings.append('%s = %s\n'%(k,eval('self.'+k)))
185        return ''.join(strings)
186
187
188    def __getitem__(self, key):
189        if isinstance(key,int):
190            if abs(key) >= len(self._index['msg']):
191                raise IndexError("index out of range")
192            else:
193                return self._index['msg'][key]
194        elif isinstance(key,str):
195            return self.select(shortName=key)
196        elif isinstance(key,slice):
197            return self._index['msg'][key]
198        else:
199            raise KeyError('Key must be an integer, slice, or GRIB2 variable shortName.')
200
201
202    def _build_index(self):
203        """Perform indexing of GRIB2 Messages."""
204        # Initialize index dictionary
205        if not self._hasindex:
206            self._index['sectionOffset'] = []
207            self._index['sectionSize'] = []
208            self._index['msgSize'] = []
209            self._index['msgNumber'] = []
210            self._index['msg'] = []
211            self._index['isSubmessage'] = []
212            self._hasindex = True
213
214        # Iterate
215        while True:
216            try:
217                # Initialize
218                bmapflag = None
219                pos = self._filehandle.tell()
220                section2 = b''
221                trailer = b''
222                _secpos = dict.fromkeys(range(8))
223                _secsize = dict.fromkeys(range(8))
224                _isSubmessage = False
225
226                # Ignore headers (usually text) that are not part of the GRIB2
227                # file.  For example, NAVGEM files have a http header at the
228                # beginning that needs to be ignored.
229
230                # Read a byte at a time until "GRIB" is found.  Using
231                # "wgrib2" on a NAVGEM file, the header was 421 bytes and
232                # decided to go to 2048 bytes to be safe. For normal GRIB2
233                # files this should be quick and break out of the first
234                # loop when "test_offset" is 0.
235                for test_offset in range(2048):
236                    self._filehandle.seek(pos + test_offset)
237                    header = struct.unpack(">I", self._filehandle.read(4))[0]
238                    if header.to_bytes(4, "big") == b"GRIB":
239                        pos = pos + test_offset
240                        break
241                else:
242                    # NOTE: Coming here means that no "GRIB" message identifier
243                    # was found in the previous 2048 bytes. So here we continue
244                    # the while True loop.
245                    continue
246
247                # Read the rest of Section 0 using struct.
248                _secpos[0] = self._filehandle.tell()-4
249                _secsize[0] = 16
250                secmsg = self._filehandle.read(12)
251                section0 = np.concatenate(([header],list(struct.unpack('>HBBQ',secmsg))),dtype=np.int64)
252
253                # Make sure message is GRIB2.
254                if section0[3] != 2:
255                    # Check for GRIB1 and ignore.
256                    if secmsg[3] == 1:
257                        warnings.warn("GRIB version 1 message detected.  Ignoring...")
258                        grib1_size = int.from_bytes(secmsg[:3],"big")
259                        self._filehandle.seek(self._filehandle.tell()+grib1_size-16)
260                        continue
261                    else:
262                        raise ValueError("Bad GRIB version number.")
263
264                # Read and unpack sections 1 through 8 which all follow a
265                # pattern of section size, number, and content.
266                while 1:
267                    # Read first 5 bytes of the section which contains the size
268                    # of the section (4 bytes) and the section number (1 byte).
269                    secmsg = self._filehandle.read(5)
270                    secsize, secnum = struct.unpack('>iB',secmsg)
271
272                    # Record the offset of the section number and "append" the
273                    # rest of the section to secmsg.
274                    _secpos[secnum] = self._filehandle.tell()-5
275                    _secsize[secnum] = secsize
276                    if secnum in {1,3,4,5}:
277                        secmsg += self._filehandle.read(secsize-5)
278                    grbpos = 0
279
280                    # Unpack section
281                    if secnum == 1:
282                        # Unpack Section 1
283                        section1, grbpos = g2clib.unpack1(secmsg,grbpos,np.empty)
284                    elif secnum == 2:
285                        # Unpack Section 2
286                        section2 = self._filehandle.read(secsize-5)
287                    elif secnum == 3:
288                        # Unpack Section 3
289                        gds, gdt, deflist, grbpos = g2clib.unpack3(secmsg,grbpos,np.empty)
290                        gds = gds.tolist()
291                        gdt = gdt.tolist()
292                        section3 = np.concatenate((gds,gdt))
293                        section3 = np.where(section3==4294967295,-1,section3)
294                    elif secnum == 4:
295                        # Unpack Section 4
296                        numcoord, pdt, pdtnum, coordlist, grbpos = g2clib.unpack4(secmsg,grbpos,np.empty)
297                        pdt = pdt.tolist()
298                        section4 = np.concatenate((np.array((numcoord,pdtnum)),pdt))
299                    elif secnum == 5:
300                        # Unpack Section 5
301                        drt, drtn, npts, self._pos = g2clib.unpack5(secmsg,grbpos,np.empty)
302                        section5 = np.concatenate((np.array((npts,drtn)),drt))
303                        section5 = np.where(section5==4294967295,-1,section5)
304                    elif secnum == 6:
305                        # Unpack Section 6 - Just the bitmap flag
306                        bmapflag = struct.unpack('>B',self._filehandle.read(1))[0]
307                        if bmapflag == 0:
308                            bmappos = self._filehandle.tell()-6
309                        elif bmapflag == 254:
310                            # Do this to keep the previous position value
311                            pass
312                        else:
313                            bmappos = None
314                        self._filehandle.seek(self._filehandle.tell()+secsize-6)
315                    elif secnum == 7:
316                        # Do not unpack section 7 here, but move the file pointer
317                        # to after section 7.
318                        self._filehandle.seek(self._filehandle.tell()+secsize-5)
319
320                        # Update the file index.
321                        self.messages += 1
322                        self._index['sectionOffset'].append(copy.deepcopy(_secpos))
323                        self._index['sectionSize'].append(copy.deepcopy(_secsize))
324                        self._index['msgSize'].append(section0[-1])
325                        self._index['msgNumber'].append(self.messages)
326                        self._index['isSubmessage'].append(_isSubmessage)
327
328                        # Create Grib2Message with data.
329                        msg = Grib2Message(section0,section1,section2,section3,section4,section5,bmapflag)
330                        msg._msgnum = self.messages-1
331                        msg._deflist = deflist
332                        msg._coordlist = coordlist
333                        if not self._nodata:
334                            msg._ondiskarray = Grib2MessageOnDiskArray((msg.ny,msg.nx), 2,
335                                                                TYPE_OF_VALUES_DTYPE[msg.typeOfValues],
336                                                                self._filehandle,
337                                                                msg, pos, _secpos[6], _secpos[7])
338                        self._index['msg'].append(msg)
339
340                        # If here, then we have moved through GRIB2 section 1-7.
341                        # Now we need to check the next 4 bytes after section 7.
342                        trailer = struct.unpack('>i',self._filehandle.read(4))[0]
343
344                        # If we reach the GRIB2 trailer string ('7777'), then we
345                        # can break begin processing the next GRIB2 message.  If
346                        # not, then we continue within the same iteration to
347                        # process a GRIB2 submessage.
348                        if trailer.to_bytes(4, "big") == b'7777':
349                            break
350                        else:
351                            # If here, trailer should be the size of the first
352                            # section of the next submessage, then the next byte
353                            # is the section number.  Check this value.
354                            nextsec = struct.unpack('>B',self._filehandle.read(1))[0]
355                            if nextsec not in {2,3,4}:
356                                raise ValueError("Bad GRIB2 message structure.")
357                            self._filehandle.seek(self._filehandle.tell()-5)
358                            _isSubmessage = True
359                            continue
360                    else:
361                        raise ValueError("Bad GRIB2 section number.")
362
363            except(struct.error):
364                if 'r' in self.mode:
365                    self._filehandle.seek(0)
366                break
367
368
369    @property
370    def levels(self):
371        if self._hasindex and not self._nodata:
372            return tuple(sorted(set([msg.level for msg in self._index['msg']])))
373        else:
374            return None
375
376
377    @property
378    def variables(self):
379        if self._hasindex and not self._nodata:
380            return tuple(sorted(set([msg.shortName for msg in self._index['msg']])))
381        else:
382            return None
383
384
385    def close(self):
386        """Close the file handle."""
387        if not self._filehandle.closed:
388            self.messages = 0
389            self.current_message = 0
390            self._filehandle.close()
391            self.closed = self._filehandle.closed
392
393
394    def read(self, size: Optional[int]=None):
395        """
396        Read size amount of GRIB2 messages from the current position.
397
398        If no argument is given, then size is None and all messages are returned
399        from the current position in the file. This read method follows the
400        behavior of Python's builtin open() function, but whereas that operates
401        on units of bytes, we operate on units of GRIB2 messages.
402
403        Parameters
404        ----------
405        size: default=None
406            The number of GRIB2 messages to read from the current position. If
407            no argument is give, the default value is None and remainder of
408            the file is read.
409
410        Returns
411        -------
412        read
413            ``Grib2Message`` object when size = 1 or a list of Grib2Messages
414            when size > 1.
415        """
416        if size is not None and size < 0:
417            size = None
418        if size is None or size > 1:
419            start = self.tell()
420            stop = self.messages if size is None else start+size
421            if size is None:
422                self.current_message = self.messages-1
423            else:
424                self.current_message += size
425            return self._index['msg'][slice(start,stop,1)]
426        elif size == 1:
427            self.current_message += 1
428            return self._index['msg'][self.current_message]
429        else:
430            None
431
432
433    def seek(self, pos: int):
434        """
435        Set the position within the file in units of GRIB2 messages.
436
437        Parameters
438        ----------
439        pos
440            The GRIB2 Message number to set the file pointer to.
441        """
442        if self._hasindex:
443            self._filehandle.seek(self._index['sectionOffset'][0][pos])
444            self.current_message = pos
445
446
447    def tell(self):
448        """Returns the position of the file in units of GRIB2 Messages."""
449        return self.current_message
450
451
452    def select(self, **kwargs):
453        """Select GRIB2 messages by `Grib2Message` attributes."""
454        # TODO: Added ability to process multiple values for each keyword (attribute)
455        idxs = []
456        nkeys = len(kwargs.keys())
457        for k,v in kwargs.items():
458            for m in self._index['msg']:
459                if hasattr(m,k) and getattr(m,k) == v: idxs.append(m._msgnum)
460        idxs = np.array(idxs,dtype=np.int32)
461        return [self._index['msg'][i] for i in [ii[0] for ii in collections.Counter(idxs).most_common() if ii[1] == nkeys]]
462
463
464    def write(self, msg):
465        """
466        Writes GRIB2 message object to file.
467
468        Parameters
469        ----------
470        msg
471            GRIB2 message objects to write to file.
472        """
473        if isinstance(msg,list):
474            for m in msg:
475                self.write(m)
476            return
477
478        if issubclass(msg.__class__,_Grib2Message):
479            if hasattr(msg,'_msg'):
480                self._filehandle.write(msg._msg)
481            else:
482                if msg._signature != msg._generate_signature():
483                    msg.pack()
484                    self._filehandle.write(msg._msg)
485                else:
486                    if hasattr(msg._data,'filehandle'):
487                        msg._data.filehandle.seek(msg._data.offset)
488                        self._filehandle.write(msg._data.filehandle.read(msg.section0[-1]))
489                    else:
490                        msg.pack()
491                        self._filehandle.write(msg._msg)
492            self.flush()
493            self.size = os.path.getsize(self.name)
494            self._filehandle.seek(self.size-msg.section0[-1])
495            self._build_index()
496        else:
497            raise TypeError("msg must be a Grib2Message object.")
498        return
499
500
501    def flush(self):
502        """Flush the file object buffer."""
503        self._filehandle.flush()
504
505
506    def levels_by_var(self, name: str):
507        """
508        Return a list of level strings given a variable shortName.
509
510        Parameters
511        ----------
512        name
513            Grib2Message variable shortName
514
515        Returns
516        -------
517        levels_by_var
518            A list of unique level strings.
519        """
520        return list(sorted(set([msg.level for msg in self.select(shortName=name)])))
521
522
523    def vars_by_level(self, level: str):
524        """
525        Return a list of variable shortName strings given a level.
526
527        Parameters
528        ----------
529        level
530            Grib2Message variable level
531
532        Returns
533        -------
534        vars_by_level
535            A list of unique variable shortName strings.
536        """
537        return list(sorted(set([msg.shortName for msg in self.select(level=level)])))

29def show_config():
30    """Print grib2io build configuration information."""
31    print(f'grib2io version {__version__} Configuration:\n')
32    print(f'\tg2c library version: {__g2clib_version__}')
33    print(f'\tJPEG compression support: {has_jpeg_support}')
34    print(f'\tPNG compression support: {has_png_support}')
35    print(f'\tAEC compression support: {has_aec_support}')
36    print(f'')
37    print(f'\tNCEP GRIB2 Table Version: {_ncep_grib2_table_version}')

1507def interpolate(a, method: Union[int, str], grid_def_in, grid_def_out,
1508                method_options=None, num_threads=1):
1509    """
1510    This is the module-level interpolation function.
1511
1512    This interfaces with the grib2io_interp component package that interfaces to
1513    the [NCEPLIBS-ip library](https://github.com/NOAA-EMC/NCEPLIBS-ip).
1514
1515    Parameters
1516    ----------
1517    a : numpy.ndarray or tuple
1518        Input data.  If `a` is a `numpy.ndarray`, scalar interpolation will be
1519        performed.  If `a` is a `tuple`, then vector interpolation will be
1520        performed with the assumption that u = a[0] and v = a[1] and are both
1521        `numpy.ndarray`.
1522
1523        These data are expected to be in 2-dimensional form with shape (ny, nx)
1524        or 3-dimensional (:, ny, nx) where the 1st dimension represents another
1525        spatial, temporal, or classification (i.e. ensemble members) dimension.
1526        The function will properly flatten the (ny,nx) dimensions into (nx * ny)
1527        acceptable for input into the interpolation subroutines.
1528    method
1529        Interpolate method to use. This can either be an integer or string using
1530        the following mapping:
1531
1532        | Interpolate Scheme | Integer Value |
1533        | :---:              | :---:         |
1534        | 'bilinear'         | 0             |
1535        | 'bicubic'          | 1             |
1536        | 'neighbor'         | 2             |
1537        | 'budget'           | 3             |
1538        | 'spectral'         | 4             |
1539        | 'neighbor-budget'  | 6             |
1540
1541    grid_def_in : grib2io.Grib2GridDef
1542        Grib2GridDef object for the input grid.
1543    grid_def_out : grib2io.Grib2GridDef
1544        Grib2GridDef object for the output grid or station points.
1545    method_options : list of ints, optional
1546        Interpolation options. See the NCEPLIBS-ip documentation for
1547        more information on how these are used.
1548    num_threads : int, optional
1549        Number of OpenMP threads to use for interpolation. The default
1550        value is 1. If grib2io_interp was not built with OpenMP, then
1551        this keyword argument and value will have no impact.
1552
1553    Returns
1554    -------
1555    interpolate
1556        Returns a `numpy.ndarray` when scalar interpolation is performed or a
1557        `tuple` of `numpy.ndarray`s when vector interpolation is performed with
1558        the assumptions that 0-index is the interpolated u and 1-index is the
1559        interpolated v.
1560    """
1561    import grib2io_interp
1562    from grib2io_interp import interpolate
1563
1564    prev_num_threads = 1
1565    try:
1566        import grib2io_interp
1567        if grib2io_interp.has_openmp_support:
1568            prev_num_threads = grib2io_interp.get_openmp_threads()
1569            grib2io_interp.set_openmp_threads(num_threads)
1570    except(AttributeError):
1571        pass
1572
1573    if isinstance(method,int) and method not in _interp_schemes.values():
1574        raise ValueError('Invalid interpolation method.')
1575    elif isinstance(method,str):
1576        if method in _interp_schemes.keys():
1577            method = _interp_schemes[method]
1578        else:
1579            raise ValueError('Invalid interpolation method.')
1580
1581    if method_options is None:
1582        method_options = np.zeros((20),dtype=np.int32)
1583        if method in {3,6}:
1584            method_options[0:2] = -1
1585
1586    ni = grid_def_in.npoints
1587    no = grid_def_out.npoints
1588
1589    # Adjust shape of input array(s)
1590    a,newshp = _adjust_array_shape_for_interp(a,grid_def_in,grid_def_out)
1591
1592    # Set lats and lons if stations, else create array for grids.
1593    if grid_def_out.gdtn == -1:
1594        rlat = np.array(grid_def_out.lats,dtype=np.float32)
1595        rlon = np.array(grid_def_out.lons,dtype=np.float32)
1596    else:
1597        rlat = np.zeros((no),dtype=np.float32)
1598        rlon = np.zeros((no),dtype=np.float32)
1599
1600    # Call interpolation subroutines according to type of a.
1601    if isinstance(a,np.ndarray):
1602        # Scalar
1603        if np.any(np.isnan(a)):
1604            ibi = np.zeros((a.shape[0]),dtype=np.int32)+1
1605            li = np.where(np.isnan(a),0,1).astype(np.int8)
1606        else:
1607            ibi = np.zeros((a.shape[0]),dtype=np.int32)
1608            li = np.zeros(a.shape,dtype=np.int8)
1609        go = np.zeros((a.shape[0],no),dtype=np.float32)
1610        no,ibo,lo,iret = interpolate.interpolate_scalar(method,method_options,
1611                                                 grid_def_in.gdtn,grid_def_in.gdt,
1612                                                 grid_def_out.gdtn,grid_def_out.gdt,
1613                                                 ibi,li.T,a.T,go.T,rlat,rlon)
1614        lo = lo.T.reshape(newshp)
1615        out = go.reshape(newshp)
1616        out = np.where(lo==0,np.nan,out)
1617    elif isinstance(a,tuple):
1618        # Vector
1619        if np.any(np.isnan(a)):
1620            ibi = np.zeros((a.shape[0]),dtype=np.int32)+1
1621            li = np.where(np.isnan(a),0,1).astype(np.int8)
1622        else:
1623            ibi = np.zeros((a.shape[0]),dtype=np.int32)
1624            li = np.zeros(a.shape,dtype=np.int8)
1625        uo = np.zeros((a[0].shape[0],no),dtype=np.float32)
1626        vo = np.zeros((a[1].shape[0],no),dtype=np.float32)
1627        crot = np.ones((no),dtype=np.float32)
1628        srot = np.zeros((no),dtype=np.float32)
1629        no,ibo,lo,iret = interpolate.interpolate_vector(method,method_options,
1630                                                 grid_def_in.gdtn,grid_def_in.gdt,
1631                                                 grid_def_out.gdtn,grid_def_out.gdt,
1632                                                 ibi,li.T,a[0].T,a[1].T,uo.T,vo.T,
1633                                                 rlat,rlon,crot,srot)
1634        del crot
1635        del srot
1636        lo = lo[:,0].reshape(newshp)
1637        uo = uo.reshape(new)
1638        vo = vo.reshape(new)
1639        uo = np.where(lo==0,np.nan,uo)
1640        vo = np.where(lo==0,np.nan,vo)
1641        out = (uo,vo)
1642
1643    del rlat
1644    del rlon
1645
1646    try:
1647        if grib2io_interp.has_openmp_support:
1648            grib2io_interp.set_openmp_threads(prev_num_threads)
1649    except(AttributeError):
1650        pass
1651
1652    return out

1655def interpolate_to_stations(a, method, grid_def_in, lats, lons,
1656                            method_options=None, num_threads=1):
1657    """
1658    Module-level interpolation function for interpolation to stations.
1659
1660    Interfaces with the grib2io_interp component package that interfaces to the
1661    [NCEPLIBS-ip
1662    library](https://github.com/NOAA-EMC/NCEPLIBS-ip). It supports scalar and
1663    vector interpolation according to the type of object a.
1664
1665    Parameters
1666    ----------
1667    a : numpy.ndarray or tuple
1668        Input data.  If `a` is a `numpy.ndarray`, scalar interpolation will be
1669        performed.  If `a` is a `tuple`, then vector interpolation will be
1670        performed with the assumption that u = a[0] and v = a[1] and are both
1671        `numpy.ndarray`.
1672
1673        These data are expected to be in 2-dimensional form with shape (ny, nx)
1674        or 3-dimensional (:, ny, nx) where the 1st dimension represents another
1675        spatial, temporal, or classification (i.e. ensemble members) dimension.
1676        The function will properly flatten the (ny,nx) dimensions into (nx * ny)
1677        acceptable for input into the interpolation subroutines.
1678    method
1679        Interpolate method to use. This can either be an integer or string using
1680        the following mapping:
1681
1682        | Interpolate Scheme | Integer Value |
1683        | :---:              | :---:         |
1684        | 'bilinear'         | 0             |
1685        | 'bicubic'          | 1             |
1686        | 'neighbor'         | 2             |
1687        | 'budget'           | 3             |
1688        | 'spectral'         | 4             |
1689        | 'neighbor-budget'  | 6             |
1690
1691    grid_def_in : grib2io.Grib2GridDef
1692        Grib2GridDef object for the input grid.
1693    lats : numpy.ndarray or list
1694        Latitudes for station points
1695    lons : numpy.ndarray or list
1696        Longitudes for station points
1697    method_options : list of ints, optional
1698        Interpolation options. See the NCEPLIBS-ip documentation for
1699        more information on how these are used.
1700    num_threads : int, optional
1701        Number of OpenMP threads to use for interpolation. The default
1702        value is 1. If grib2io_interp was not built with OpenMP, then
1703        this keyword argument and value will have no impact.
1704
1705    Returns
1706    -------
1707    interpolate_to_stations
1708        Returns a `numpy.ndarray` when scalar interpolation is performed or a
1709        `tuple` of `numpy.ndarray`s when vector interpolation is performed with
1710        the assumptions that 0-index is the interpolated u and 1-index is the
1711        interpolated v.
1712    """
1713    import grib2io_interp
1714    from grib2io_interp import interpolate
1715
1716    prev_num_threads = 1
1717    try:
1718        import grib2io_interp
1719        if grib2io_interp.has_openmp_support:
1720            prev_num_threads = grib2io_interp.get_openmp_threads()
1721            grib2io_interp.set_openmp_threads(num_threads)
1722    except(AttributeError):
1723        pass
1724
1725    if isinstance(method,int) and method not in _interp_schemes.values():
1726        raise ValueError('Invalid interpolation method.')
1727    elif isinstance(method,str):
1728        if method in _interp_schemes.keys():
1729            method = _interp_schemes[method]
1730        else:
1731            raise ValueError('Invalid interpolation method.')
1732
1733    if method_options is None:
1734        method_options = np.zeros((20),dtype=np.int32)
1735        if method in {3,6}:
1736            method_options[0:2] = -1
1737
1738    # Check lats and lons
1739    if isinstance(lats,list):
1740        nlats = len(lats)
1741    elif isinstance(lats,np.ndarray) and len(lats.shape) == 1:
1742        nlats = lats.shape[0]
1743    else:
1744        raise ValueError('Station latitudes must be a list or 1-D NumPy array.')
1745    if isinstance(lons,list):
1746        nlons = len(lons)
1747    elif isinstance(lons,np.ndarray) and len(lons.shape) == 1:
1748        nlons = lons.shape[0]
1749    else:
1750        raise ValueError('Station longitudes must be a list or 1-D NumPy array.')
1751    if nlats != nlons:
1752        raise ValueError('Station lats and lons must be same size.')
1753
1754    ni = grid_def_in.npoints
1755    no = nlats
1756
1757    # Adjust shape of input array(s)
1758    a,newshp = _adjust_array_shape_for_interp_stations(a,grid_def_in,no)
1759
1760    # Set lats and lons if stations
1761    rlat = np.array(lats,dtype=np.float32)
1762    rlon = np.array(lons,dtype=np.float32)
1763
1764    # Use gdtn = -1 for stations and an empty template array
1765    gdtn = -1
1766    gdt = np.zeros((200),dtype=np.int32)
1767
1768    # Call interpolation subroutines according to type of a.
1769    if isinstance(a,np.ndarray):
1770        # Scalar
1771        ibi = np.zeros((a.shape[0]),dtype=np.int32)
1772        li = np.zeros(a.shape,dtype=np.int32)
1773        go = np.zeros((a.shape[0],no),dtype=np.float32)
1774        no,ibo,lo,iret = interpolate.interpolate_scalar(method,method_options,
1775                                                 grid_def_in.gdtn,grid_def_in.gdt,
1776                                                 gdtn,gdt,
1777                                                 ibi,li.T,a.T,go.T,rlat,rlon)
1778        out = go.reshape(newshp)
1779    elif isinstance(a,tuple):
1780        # Vector
1781        ibi = np.zeros((a[0].shape[0]),dtype=np.int32)
1782        li = np.zeros(a[0].shape,dtype=np.int32)
1783        uo = np.zeros((a[0].shape[0],no),dtype=np.float32)
1784        vo = np.zeros((a[1].shape[0],no),dtype=np.float32)
1785        crot = np.ones((no),dtype=np.float32)
1786        srot = np.zeros((no),dtype=np.float32)
1787        no,ibo,lo,iret = interpolate.interpolate_vector(method,method_options,
1788                                                 grid_def_in.gdtn,grid_def_in.gdt,
1789                                                 gdtn,gdt,
1790                                                 ibi,li.T,a[0].T,a[1].T,uo.T,vo.T,
1791                                                 rlat,rlon,crot,srot)
1792        del crot
1793        del srot
1794        out = (uo.reshape(newshp),vo.reshape(newshp))
1795
1796    del rlat
1797    del rlon
1798
1799    try:
1800        if grib2io_interp.has_openmp_support:
1801            grib2io_interp.set_openmp_threads(prev_num_threads)
1802    except(AttributeError):
1803        pass
1804
1805    return out