pysecs.make_grid#

pysecs.make_grid(obs_loc: ndarray, r_shell: float, spacing: float | tuple[float, float] | None = None, padding: float | None = None, min_distance: float | None = None) → ndarray#

Build a regular SECS grid covering an observation network.

A grid that is too small clips currents at its edges and biases the fit everywhere, and a grid coarser than the station spacing cannot resolve the structure the stations actually see. This lays out a regular latitude/longitude grid with a station-informed spacing and padding beyond the station footprint, following the standard SECS grid design (e.g. Amm & Viljanen 1999; Vanhamaki & Juusola 2020).

Parameters:

  • obs_loc (ndarray (nobs, 3 [lat, lon, r])) – The observation locations the grid should cover.

  • r_shell (float) – The radius of the SEC shell (e.g. R_Earth + ionospheric altitude for an external/ionospheric shell, or a radius below R_Earth for an internal/induced image shell). See make_image_grid() to build a matching shell at a different radius.

  • spacing (float or (float, float), optional) – The grid spacing in degrees. A single float is treated as an angular spacing and the longitude step is scaled by 1 / cos(mean observation latitude) so grid cells stay roughly square in physical distance. A (lat_spacing, lon_spacing) tuple sets both steps directly with no scaling. Default: the median nearest-neighbor separation between the observation locations, which is a reasonable minimum – finer grids are generally safe since regularization in fit() controls the effective degrees of freedom, but grids much coarser than the station spacing cannot resolve what the stations see. Requires at least 2 observation locations.

  • padding (float, optional) – Extra margin in degrees added around the observation bounding box before gridding (longitude padding is scaled the same way as the longitude spacing). A grid clipped tightly to the station footprint aliases currents outside the data region onto its boundary poles and biases the whole fit; padding several grid cells beyond the stations avoids this. Default: 3 * lat spacing.

  • min_distance (float, optional) – Any grid node within this angular distance (degrees) of an observation location is nudged away by shifting its latitude. A SEC pole is not actually singular for ground observations of a divergence-free system at a shell above the ground, but it is singular when the SEC and observation are on the same shell, and for a curl-free system observed from above the shell (e.g. satellites). This nudge is cheap insurance against those cases and against evaluating currents exactly at a grid node. Default: 1% of the (effective) latitude spacing. Pass 0 to disable.

Returns:

The generated grid locations, all at radius r_shell.

Return type:

ndarray (n, 3 [lat, lon, r])