easy_vic_build.tools.geo_func.search_grids

Grid-search utilities for matching source and destination coordinates.

This module provides exact-match, nearest-neighbor, and radius/overlap-based search methods, plus helper converters for transforming search results into array-friendly indices.

Functions

`Uniform_precision`(coord, percision)	Round coordinates to a uniform precision.
`parallel_function`()	Placeholder for future parallel search implementation.
`print_ret`(searched_grids_index, src_lat, src_lon)	Print one search result tuple with corresponding source coordinates.
`search_grids_equal`(dst_lat, dst_lon, ...)	Search for grids with matching coordinates (src_lat == dst_lat and src_lon == dst_lon).
`search_grids_nearest`(dst_lat, dst_lon, ...)	Search nearest source grids for each destination point.
`search_grids_radius`(dst_lat, dst_lon, ...)	Search source grids within circular distance from destination points.
`search_grids_radius_rectangle`(dst_lat, ...)	Search source grids inside latitude/longitude radius rectangles.
`search_grids_radius_rectangle_overlap`(...[, ...])	Search source grids whose extents overlap destination grid extents.
`search_grids_radius_rectangle_reverse`(...)	Rectangle-radius search variant using prebuilt source meshes.
`searched_grids_index_to_bool_index`(...)	Converts searched grid indices to boolean index arrays.
`searched_grids_index_to_point_indices`(...)	Convert searched_grids_index (lat_idx, lon_idx) into flat point indices when src_lat and src_lon are both length-n arrays representing n points.
`searched_grids_index_to_rows_cols_index`(...)	Converts searched grid indices to row and column indices.

easy_vic_build.tools.geo_func.search_grids.parallel_function()[source]: Placeholder for future parallel search implementation.

easy_vic_build.tools.geo_func.search_grids.Uniform_precision(coord, percision)[source]

Round coordinates to a uniform precision.

Parameters:

coord (array_like) – 1D array containing latitude or longitude values for grids.
percision (int) – Minimum precision to which values should be rounded.

Returns:

Array with values rounded to the specified precision.

Return type:

ndarray

easy_vic_build.tools.geo_func.search_grids.search_grids_equal(dst_lat, dst_lon, src_lat, src_lon, **tqdm_kwargs)[source]

Search for grids with matching coordinates (src_lat == dst_lat and src_lon == dst_lon).

Parameters:

dst_lat (array_like) – 1D array of latitude values for the destination grids.
dst_lon (array_like) – 1D array of longitude values for the destination grids.
src_lat (array_like) – 1D array of latitude values for the source grids. Must be a sorted set (e.g., sorted(list(set(coord.lat)))), ensuring unique values.
src_lon (array_like) – 1D array of longitude values for the source grids. Must be a sorted set (e.g., sorted(list(set(coord.lon)))), ensuring unique values.
lat_radius (optional) – Not used in this function but reserved for potential extensions.
lon_radius (optional) – Not used in this function but reserved for potential extensions.
**tqdm_kwargs (dict, optional) – Additional keyword arguments passed to tqdm. For nested progress bars, set leave=False, keeping leave=True only for the outermost tqdm.

Returns:

A list of tuples with length equal to len(dst_lat), where each tuple contains two arrays: (lat_index, lon_index). These represent the indices of the destination grid points found in the source grid.

lat_index: 1D array of latitude indices.
lon_index: 1D array of longitude indices.

Example output: (array([0, 1, 1, 2], dtype=int64), array([0, 0, 1, 0], dtype=int64)) corresponds to: ` lat_index = array([0, 1, 1, 2], dtype=int64) # Row indices lon_index = array([0, 0, 1, 0], dtype=int64) # Column indices `

Return type:

list of tuple

Notes

The returned (lat_index, lon_index) pairs are one-to-one, meaning len(lat_index) == len(lon_index), ensuring accurate matching.
When using netCDF4.Dataset.variable[:, lat_index, lon_index], it is recommended to first convert the dataset variable into a numpy.ndarray to avoid potential errors, e.g., array = netCDF4.Dataset.variable[:, :, :], then use array[:, lat_index, lon_index].

easy_vic_build.tools.geo_func.search_grids.search_grids_radius(dst_lat, dst_lon, src_lat, src_lon, search_radius, **tqdm_kwargs)[source]

Search source grids within circular distance from destination points.

Parameters:

dst_lat (array-like) – Destination latitudes.
dst_lon (array-like) – Destination longitudes.
src_lat (array-like) – Source latitudes.
src_lon (array-like) – Source longitudes.
search_radius (float) – Search radius in coordinate units.
**tqdm_kwargs (dict, optional) – Extra keyword arguments passed to tqdm.

Returns:

For each destination point, a tuple (lat_indices, lon_indices).

Return type:

list of tuple

easy_vic_build.tools.geo_func.search_grids.search_grids_radius_rectangle(dst_lat, dst_lon, src_lat, src_lon, lat_radius, lon_radius, src_type='mesh', **tqdm_kwargs)[source]

Search source grids inside latitude/longitude radius rectangles.

Parameters:

dst_lat (array-like) – Destination latitudes.
dst_lon (array-like) – Destination longitudes.
src_lat (array-like) – Source latitudes.
src_lon (array-like) – Source longitudes.
lat_radius (float) – Latitude half-width of search window.
lon_radius (float) – Longitude half-width of search window.
src_type ({"mesh", "points"}, optional) – Source representation type.
**tqdm_kwargs (dict, optional) – Extra keyword arguments passed to tqdm.

Returns:

For each destination point, a tuple (lat_indices, lon_indices).

Return type:

list of tuple

easy_vic_build.tools.geo_func.search_grids.search_grids_radius_rectangle_reverse(dst_lat, dst_lon, src_lat, src_lon, lat_radius, lon_radius, **tqdm_kwargs)[source]

Rectangle-radius search variant using prebuilt source meshes.

Parameters:

dst_lat (array-like) – Destination latitudes.
dst_lon (array-like) – Destination longitudes.
src_lat (array-like) – Source latitudes.
src_lon (array-like) – Source longitudes.
lat_radius (float) – Latitude half-width of search window.
lon_radius (float) – Longitude half-width of search window.
**tqdm_kwargs (dict, optional) – Extra keyword arguments passed to tqdm.

Returns:

For each destination point, a tuple (lat_indices, lon_indices).

Return type:

list of tuple

easy_vic_build.tools.geo_func.search_grids.search_grids_radius_rectangle_overlap(dst_lat, dst_lon, dst_dlat, dst_dlon, src_lat, src_lon, src_dlat, src_dlon, src_type='points', **tqdm_kwargs)[source]

Search source grids whose extents overlap destination grid extents.

Parameters:

dst_lat (array-like) – Destination latitudes.
dst_lon (array-like) – Destination longitudes.
dst_dlat (float) – Destination latitude resolution.
dst_dlon (float) – Destination longitude resolution.
src_lat (array-like) – Source latitudes.
src_lon (array-like) – Source longitudes.
src_dlat (float) – Source latitude resolution.
src_dlon (float) – Source longitude resolution.
src_type ({"mesh", "points"}, optional) – Source representation type.
**tqdm_kwargs (dict, optional) – Reserved keyword arguments.

Returns:

For each destination point, a tuple (lat_indices, lon_indices).

Return type:

list of tuple

easy_vic_build.tools.geo_func.search_grids.search_grids_nearest(dst_lat, dst_lon, src_lat, src_lon, search_num=4, move_src_lat=None, move_src_lon=None, src_type='mesh', **tqdm_kwargs)[source]

Search nearest source grids for each destination point.

Parameters:

dst_lat (array-like) – Destination latitudes.
dst_lon (array-like) – Destination longitudes.
src_lat (array-like) – Source latitudes.
src_lon (array-like) – Source longitudes.
search_num (int, optional) – Number of nearest source points to keep.
move_src_lat (float, optional) – Latitude shift applied to all source points before distance search.
move_src_lon (float, optional) – Longitude shift applied to all source points before distance search.
src_type ({"mesh", "points"}, optional) – Source representation type.
**tqdm_kwargs (dict, optional) – Extra keyword arguments passed to tqdm.

Returns:

For each destination point, a tuple (lat_indices, lon_indices).

Return type:

list of tuple

easy_vic_build.tools.geo_func.search_grids.print_ret(searched_grids_index, src_lat, src_lon)[source]

Print one search result tuple with corresponding source coordinates.

Parameters:

searched_grids_index (list of tuple) – Search result list returned by grid-search functions.
src_lat (array-like) – Source latitudes.
src_lon (array-like) – Source longitudes.

Return type:

None

easy_vic_build.tools.geo_func.search_grids.searched_grids_index_to_rows_cols_index(searched_grids_index)[source]

Converts searched grid indices to row and column indices.

This function transforms a list of grid indices (latitude and longitude indices) into separate row and column index arrays. It is designed for cases where each destination grid corresponds to exactly one source grid (i.e., a one-to-one mapping).

Parameters:

searched_grids_index (list of tuple) – A list where each element is a tuple containing two arrays: (lat_index, lon_index). Each tuple represents the indices of the nearest source grid point for a given destination grid. Note: This function assumes that len(searched_grids_index[0]) == 1, meaning that each destination grid has exactly one matched source grid.

Returns:

rows_index (ndarray) – A 1D array of row indices corresponding to the latitude indices.
cols_index (ndarray) – A 1D array of column indices corresponding to the longitude indices.

Notes

This function is only valid for one-to-one searches, where each destination grid has exactly one matched source grid.
The output can be directly used for indexing a 2D array, such as:

`python grids_array[rows_index, cols_index] = list_values `

easy_vic_build.tools.geo_func.search_grids.searched_grids_index_to_bool_index(searched_grids_index, src_lat, src_lon)[source]

Converts searched grid indices to boolean index arrays.

This function generates boolean masks for latitude and longitude indices based on the searched grid indices. The boolean masks can be used for advanced indexing to extract the corresponding grid points efficiently.

Parameters:

searched_grids_index (list of tuple) – A list where each element is a tuple containing two arrays: (lat_indices, lon_indices). Each tuple represents the indices of the matched source grid points for a given destination grid.
src_lat (array-like) – A 1D array of latitude values corresponding to the source grid.
src_lon (array-like) – A 1D array of longitude values corresponding to the source grid.

Returns:

searched_grids_bool_index – A list where each element is a tuple containing two boolean arrays: (lat_bool_mask, lon_bool_mask). - lat_bool_mask is a boolean mask for latitude indices. - lon_bool_mask is a boolean mask for longitude indices.

Return type:

list of tuple

Notes

Using integer indexing on a dataset with multiple matches results in retrieving all cross-points, leading to an array of shape (N, N), where N is the number of matched grids.
Using boolean indexing ensures that only the exact matched points are selected, preserving a one-to-one mapping. This results in a more compact array of shape (M, K), where M * K = N.

easy_vic_build.tools.geo_func.search_grids.searched_grids_index_to_point_indices(searched_grids_index, src_lat, src_lon)[source]

Convert searched_grids_index (lat_idx, lon_idx) into flat point indices when src_lat and src_lon are both length-n arrays representing n points.

Parameters:

searched_grids_index (list of tuple) – Each element is (lat_idx, lon_idx), indices from np.where or search.
src_lat (array_like) – 1D arrays of length n representing coordinates of points.
src_lon (array_like) – 1D arrays of length n representing coordinates of points.

Returns:

Each element is a 1D array of flat indices (0..n-1) corresponding to the matched points.

Return type:

list of ndarray