credit.grid
===========

.. py:module:: credit.grid

.. autoapi-nested-parse::

   scrip_generator.py
   ==================
   Generate SCRIP-format NetCDF files for use with ESMFRegridWeightGen.

   Supports two grid types:
       - Rectilinear  : 1D lon + 1D lat arrays (uniform, regional, or Gaussian spacing)
       - Curvilinear  : 2D lon + 2D lat arrays (HRRR, GOES, ocean tripolar, etc.)

   All functions produce SCRIP files containing both cell centers and cell corners,
   making them compatible with all ESMFRegridWeightGen methods (bilinear, patch,
   nearest-neighbor, 1st- and 2nd-order conservative).

   Entry points
   ------------
       scrip_from_netcdf(nc_file, scrip_file, grid_name=None, mask_var=None)
           Auto-detects grid type from file; preferred entry point.

       scrip_from_rectilinear(lon_1d, lat_1d, grid_name, grid_file, mask=None)
       scrip_from_curvilinear(lon_2d, lat_2d, grid_name, grid_file, mask=None)
           Direct API for when coordinates are already in hand.

   Dependencies
   ------------
       numpy, xarray



Attributes
----------

.. autoapisummary::

   credit.grid._COORD_CANDIDATES
   credit.grid.parser


Functions
---------

.. autoapisummary::

   credit.grid._write_scrip
   credit.grid._corners_rectilinear
   credit.grid._corners_curvilinear
   credit.grid._find_coord_pair
   credit.grid.scrip_from_rectilinear
   credit.grid.scrip_from_curvilinear
   credit.grid.scrip_from_netcdf


Module Contents
---------------

.. py:function:: _write_scrip(lon_centers, lat_centers, lon_corners, lat_corners, grid_name, grid_file, mask=None, grid_dims=None)

   Write a SCRIP-format NetCDF file from pre-computed center and corner arrays.

   :param lon_centers:
   :type lon_centers: np.ndarray, shape (grid_size,)
   :param lat_centers:
   :type lat_centers: np.ndarray, shape (grid_size,)
   :param lon_corners: Corner longitudes in CCW order: SW, SE, NE, NW.
   :type lon_corners: np.ndarray, shape (grid_size, 4)
   :param lat_corners: Corner latitudes in CCW order: SW, SE, NE, NW.
   :type lat_corners: np.ndarray, shape (grid_size, 4)
   :param grid_name:
   :type grid_name: str
   :param grid_file:
   :type grid_file: str
   :param mask: 1 = valid, 0 = masked.  Defaults to all-ones (fully unmasked).
   :type mask: np.ndarray of int32, shape (grid_size,), optional

   :rtype: xr.Dataset written to grid_file.


.. py:function:: _corners_rectilinear(lons_1d, lats_1d)

   Compute cell corners for a rectilinear grid from 1D center arrays.

   Edges are midpoints between adjacent centers.  Boundary edges are
   extrapolated using the nearest interior spacing.  Latitude edges are
   clamped to [-90, 90].  Longitude edges are kept monotonically increasing
   (not wrapped) so that west < east is guaranteed for every cell.

   :returns: **lon_corners, lat_corners** -- CCW order: SW, SE, NE, NW.
   :rtype: np.ndarray, shape (nlat*nlon, 4)


.. py:function:: _corners_curvilinear(lons_2d, lats_2d)

   Compute cell corners for a curvilinear grid from 2D center arrays.

   Interior corners are the average of the four surrounding cell centers.
   Boundary corners are extrapolated using a one-cell ghost layer.

   :returns: **lon_corners, lat_corners** -- CCW order: SW, SE, NE, NW.
   :rtype: np.ndarray, shape (ny*nx, 4)


.. py:data:: _COORD_CANDIDATES
   :value: [('longitude', 'latitude'), ('lon', 'lat')]


.. py:function:: _find_coord_pair(ds)

   Find a lon/lat coordinate pair in an xr.Dataset.

   Searches _COORD_CANDIDATES in order across both ds.coords and ds.data_vars.

   :rtype: (lon_array, lat_array, lon_name, lat_name)

   :raises ValueError if no recognised pair is found.:


.. py:function:: scrip_from_rectilinear(lon_1d, lat_1d, grid_name, grid_file, mask=None)

   Generate a SCRIP file for a rectilinear (regular lat/lon) grid.

   :param lon_1d:
   :type lon_1d: array-like, shape (nlon,)
   :param lat_1d:
   :type lat_1d: array-like, shape (nlat,)
   :param grid_name:
   :type grid_name: str
   :param grid_file:
   :type grid_file: str
   :param mask:
   :type mask: array-like, shape (nlat, nlon), optional  1=valid, 0=masked.

   :rtype: xr.Dataset


.. py:function:: scrip_from_curvilinear(lon_2d, lat_2d, grid_name, grid_file, mask=None)

   Generate a SCRIP file for a curvilinear grid.

   :param lon_2d:
   :type lon_2d: array-like, shape (ny, nx)
   :param lat_2d:
   :type lat_2d: array-like, shape (ny, nx)
   :param grid_name:
   :type grid_name: str
   :param grid_file:
   :type grid_file: str
   :param mask:
   :type mask: array-like, shape (ny, nx), optional  1=valid, 0=masked.

   :rtype: xr.Dataset


.. py:function:: scrip_from_netcdf(nc_file, scrip_file, grid_name=None, mask_var=None)

   Auto-detect grid type from a NetCDF file and write a SCRIP file.

   Coordinate names supported: lon/lat, longitude/latitude.
   1D coordinates → rectilinear.  2D coordinates → curvilinear.

   :param nc_file:
   :type nc_file: str   Path to input NetCDF file.
   :param scrip_file:
   :type scrip_file: str   Path for output SCRIP file.
   :param grid_name:
   :type grid_name: str, optional  Defaults to the input filename stem.
   :param mask_var:
   :type mask_var: str, optional  Variable to use as mask (1=valid, 0=masked).

   :rtype: xr.Dataset


.. py:data:: parser