tidy3d.components.data.data_array.AbstractSpatialDataArray

class AbstractSpatialDataArray

Bases: DataArray, ABC

Spatial distribution.

Attributes

plot	Plot the spatial data.

Methods

does_cover(bounds[, rtol, atol])	Check whether data fully covers specified by bounds spatial region.
interp_within_domain(interp_coords, clip_bounds)	Interpolate to interp_coords, clipping source data to clip_bounds.
interpolate_to_grid(grid, *[, offset, ...])	Interpolate onto a target grid, with optional spatial offset and output ordering.
item(*args)	Copy an element of an array to a standard Python scalar and return it.
searchsorted(v[, side, sorter])	Find indices where elements of v should be inserted in a to maintain order.
sel_inside(bounds, *[, include_interp_padding])	Return a new SpatialDataArray that contains the minimal amount data necessary to cover a spatial region defined by bounds.
shifted_spatial_coords(center)	Return a copy with spatial coordinates shifted by center.

property plot

Plot the spatial data.

Accepts the same arguments as xarray’s DataArray.plot(). The extra grid and field keyword arguments are accepted for API compatibility with TriangularGridDataset.plot(), but grid overlay is not supported on structured data.

Parameters:

• field (bool = True) – Whether to plot the data field. Must be True for structured data.

• grid (bool = False) – Not supported for structured data. Raises DataError if True.

shifted_spatial_coords(center)

Return a copy with spatial coordinates shifted by center.

interpolate_to_grid(grid, *, offset=None, method='linear', target_dims=None)

Interpolate onto a target grid, with optional spatial offset and output ordering.

interp_within_domain(interp_coords, clip_bounds, assume_sorted=False)

Interpolate to interp_coords, clipping source data to clip_bounds.

This is a bounds-aware variant of interp() that:

1. Clips the source data to clip_bounds, keeping only data points whose coordinates lie on or within the bounds.

2. Clamps all target coordinates to the clipped data range, so any target outside that range receives the nearest edge value.

3. Interpolates on the clipped data using the clamped coordinates.

4. Zeros the result at target coordinates that are strictly outside clip_bounds.

These steps allow for regular interpolation for strictly interior points, while points on the clip_bounds effectively choose the nearest value from the source data, and points strictly outside the bounds are set to 0.

Each of the six bounds (min/max for x/y/z) is independently optional. A None value leaves that side unclipped.

Parameters:

• interp_coords (dict) – Target interpolation coordinates, keyed by dimension name ("x", "y", "z").

• clip_bounds (BoundOptional) – (min_tuple, max_tuple) where each element is a 3-tuple of Optional[float]. Axes set to None are not clipped.

• assume_sorted (bool = False) – If True, skip sorting of coordinates.

Returns:

Interpolated data with coordinates matching interp_coords. Values outside clip_bounds are zero.

Return type:

Self

sel_inside(bounds, *, include_interp_padding=True)

Return a new SpatialDataArray that contains the minimal amount data necessary to cover a spatial region defined by bounds. Note that the returned data is sorted with respect to spatial coordinates.

Parameters:

bounds (Tuple[float, float, float], Tuple[float, float float]) – Min and max bounds packaged as (minx, miny, minz), (maxx, maxy, maxz).

Returns:

• SpatialDataArray – Extracted spatial data array.

• include_interp_padding (bool = True) – If True (default), include neighbor points around bounds to support interpolation. If False, keep only points whose coordinates are inside bounds.

does_cover(bounds, rtol=0.0, atol=0.0)

Check whether data fully covers specified by bounds spatial region. If data contains only one point along a given direction, then it is assumed the data is constant along that direction and coverage is not checked.

Parameters:

• bounds (Tuple[float, float, float], Tuple[float, float float]) – Min and max bounds packaged as (minx, miny, minz), (maxx, maxy, maxz).

• rtol (float = 0.0) – Relative tolerance for comparing bounds

• atol (float = 0.0) – Absolute tolerance for comparing bounds

Returns:

Full cover check outcome.

Return type:

bool

item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args (Arguments (variable number and type)) –

• none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.

• int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.

• tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns:

z – A copy of the specified element of the array as a suitable Python scalar

Return type:

Standard Python scalar object

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> import numpy as np
>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

For an array with object dtype, elements are returned as-is.

>>> a = np.array([np.int64(1)], dtype=object)
>>> a.item() #return np.int64
np.int64(1)

searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted

equivalent function