Grid Module

The grid module provides utilities for generating and manipulating spatial grids for climate data analysis.

Fekete Points

The FeketeGrid class implements algorithms for generating equidistant points on a sphere, based on the work by [].

class dominosee.grid.grid.FeketeGrid(num_points, num_iter=0, grid=None, parallel=None)

Bases: dominosee.grid.grid.BaseGrid

FeketeGrid creates a equidistance grid on a sphere.

Parameters:

num_points: int

Number of points to generate on the sphere

num_iter: int, optional

Number of iterations for grid optimization. Default: 1000

grid: None, dict, or tuple, optional

Grid initialization method: - None: Create new grid from scratch (default) - dict: Initialize from {‘lat’: […], ‘lon’: […]} dictionary - tuple: Initialize from fekete.bendito output (X, dq)

parallel: bool or None, optional

Whether to use parallel execution. None for auto-detect based on memory

__init__(num_points, num_iter=0, grid=None, parallel=None)

property distance: float

Get the average distance between points in km.

get_distance_equator()

Return distance between points at the equator in km.

Return type:

float

create_grid_from_tuple(grid_tuple)

Create grid from fekete.bendito output tuple.

Parameters:

grid_tuple – Tuple containing (X, dq) where X is 3D Cartesian coordinates and dq is the optimization history

Return type:

Dict[str, ndarray]

Returns:

Dictionary with ‘lat’ and ‘lon’ keys containing grid coordinates

Raises:

ValueError – If tuple format is invalid

create_grid(num_iter=1000, parallel=None)

Create new Fekete grid from scratch.

Parameters:

• num_iter – Number of iterations for grid optimization

• parallel – Whether to use parallel execution (None for auto-detect)

Return type:

None

to_pickle(filepath=None)

Save FeketeGrid to pickle file.

Parameters:

filepath – Path to save file. If None, generates default name.

Return type:

None

save_grid(filepath=None)

Save grid to pickle file. :rtype: None

Deprecated since version Use: to_pickle() instead. This method will be removed in a future version.

classmethod load_grid(filepath=None)

Load grid from pickle file.

Deprecated since version Use: from_pickle() instead. This method will be removed in a future version.

initialize_grid(save=True)

Return type:

Dict[str, ndarray]

improve_grid(num_iter=1000, save=True, parallel=None)

Improve existing grid through optimization iterations.

Parameters:

• num_iter – Number of optimization iterations to perform

• save – Whether to save the improved grid to file

• parallel – Whether to use parallel execution (None for auto-detect)

Return type:

Dict[str, ndarray]

Returns:

Updated grid dictionary with ‘lat’ and ‘lon’ keys

Raises:

RuntimeError – If no grid exists to improve

create_SphericalVoronoi()

to_cdo_gridfile(filepath=None, out_vertex=False)

to_gridfile(filepath=None, out_vertex=False)

align_to_target_grid(target_coords, method='L-BFGS-B', initial_guess=None)

Align Fekete grid to target coordinates by minimizing spherical distances.

This function uses numerical optimization to find the rotation that minimizes the sum of great circle distances between grid points and their targets. Unlike the Wahba solution which minimizes Euclidean distances, this directly optimizes spherical distances.

Parameters:

• target_coords (dict) – Target coordinates with ‘lon’ and ‘lat’ keys containing arrays of target positions. Must have same length as current grid.

• method (str, default=’L-BFGS-B’) – Optimization method. Options: ‘L-BFGS-B’, ‘BFGS’, ‘Powell’, ‘Nelder-Mead’

• initial_guess (array-like, optional) – Initial rotation vector (3,) for optimization. If None, uses Wahba solution as starting point.

Returns:

dict – New grid coordinates {‘lon’: array, ‘lat’: array} after optimal spherical alignment. Also contains optimization info: ‘success’, ‘message’, ‘nfev’, ‘fun’

Notes

Optimization method: Numerical optimization (not theoretical solution) - Uses rotation vector parameterization to avoid matrix constraints - Minimizes: Σ arccos(clamp((R @ current_i) · target_i, -1, 1)) - No closed-form solution exists for this objective function - Convergence depends on initial guess and grid configuration

The rotation vector r represents rotation by ||r|| radians around axis r/||r||.

map_to_regular_grid(target_grid)

Creates a one-to-one mapping between Fekete grid points and regular grid points.

Each Fekete point is mapped to its nearest available regular grid point, ensuring no regular grid point is used twice. Results maintain original Fekete grid order.

Parameters:

target_grid (dict) – Dictionary with ‘lon’ and ‘lat’ keys containing arrays of regular grid coordinates

Returns:

dict – Dictionary containing: - ‘regular_coords’: corresponding regular grid coordinates (lon, lat pairs) - ‘distances’: distances between mapped points - ‘unmapped_indices’: indices of Fekete points that couldn’t be mapped

Raises:

ValueError – If no grid has been created yet