Mondaic

salvus.mesh.layered_meshing.interface.surface

salvus.mesh.layered_meshing.interface.surface salvus mesh layered_meshing interface surface

2-D variable interface.

Classes

Surface

class Surface(salvus.mesh.layered_meshing.interface.Interface):
    def __init__(
        self,
        da: xr.DataArray,
        extender: typing.Callable[
            [xr.DataArray, xr.DataArray], xr.DataArray
        ] = salvus.utils.xarray_tools.extrude_like_and_pad,
        interpolation_method: typing.Literal["nearest", "linear"] = "linear",
    ) -> None: ...

A potentially deformed interface described by two coordinates.

A surface’s independent coordinates must be either “x” and “y”, or “latitude” and “longitude”. Surfaces can be used in 3-D domains only.

A surfaces’s digital elevation model (DEM) should always be specified relative to the “reference_elevation” attribute in its xarray representation. As an example if one wanted to apply a simple sinusoidal topography to a domain’s top surface by they could do so by using Depth(0.0) as the reference coordinate. If no scaling was present, the resultant topography would then have a peak-to-peak range of 2 m, with the highest peak at 1 m above the domain’s top surface and the lowest valley at 1 m below it.

Parameters
  • da xr.DataArray — The interface represented as a DataArray.
  • extender typing.Callable[[xr.DataArray, xr.DataArray], xr.DataArray] — A function that can be used extend the boundaries of the interface past its defined extents.
  • interpolation_method typing.Literal['nearest', 'linear'] — The interpolation method used to evaluate the interface between grid points.
Attributes
attrs dict[str, typing.Any]

The object’s parameters minus its xarray representation.

da_absolute xr.DataArray

Get the DEM in absolute coordinates.

is_flat bool

Query whether the interface is flat.

max_elevation float

Get the interface’s maximum elevation.

min_elevation float

Get the interface’s minimum elevation.

reference_elevation float

Get the interface’s reference elevation.

Methods
from_dataarray()
def from_dataarray(
    da: xr.DataArray,
    extender: typing.Callable[
        [xr.DataArray, xr.DataArray], xr.DataArray
    ] = salvus.utils.xarray_tools.extrude_like_and_pad,
    interpolation_method: typing.Literal["nearest", "linear"] = "linear",
) -> Interface: ...

Construct a generic interface from an xarray DataArray.

Will dispatch to the appropriate interface type based on the DataArray’s dimension and heterogeneity (of lack thereof).

Parameters
  • da xr.DataArray — The data array.
  • extender typing.Callable[[xr.DataArray, xr.DataArray], xr.DataArray] — A function that can be used extend the boundaries of the interface past its defined extents.
  • interpolation_method typing.Literal['nearest', 'linear'] — The interpolation method used to evaluate the interface between grid points.
Returns Interface — A new interface.
from_points()
def from_points(
    x: npt.ArrayLike,
    y: npt.ArrayLike,
    dem: npt.ArrayLike,
    reference_elevation: float | Depth | Height,
    interpolation_method: typing.Literal["nearest", "linear"] = "linear",
    extender: typing.Callable[
        [xr.DataArray, xr.DataArray], xr.DataArray
    ] = salvus.utils.xarray_tools.extrude_like_and_pad,
) -> Surface: ...

Specify a Surface from its independent Cartesian components.

Parameters
  • x npt.ArrayLike — The surface’s x coordinates.
  • y npt.ArrayLike — The surface’s y coordinates.
  • dem npt.ArrayLike — The value of the relative digital elevation model. Must be on the same grid as c.
  • reference_elevation float | Depth | Height — The elevation to which the 0.0 value in the dem parameter refers to. A plain float specifies an absolute reference coordinate, while either a Depth or Height value specifies depth below or height above a domain’s top and bottom bounds respectively.
  • interpolation_method typing.Literal['nearest', 'linear'] — Method to use for interpolating this curve between its defined points.
  • extender typing.Callable[[xr.DataArray, xr.DataArray], xr.DataArray] — Callable to use to extend the curve past its defined domain. Useful, for instance, when absorbing boundaries are used to extend the domain.
Returns Surface — A new Surface.
extrude_like_and_pad()
def extrude_like_and_pad(
    data: XrType,
    like: xr.Dataset | xr.DataArray,
    rel_tol: float = 0.0001,
    update_bounds: bool = False,
) -> XrType: ...

Extrude like another data array and pad if necessary.

Parameters
  • data XrType — The input data array or set.
  • like xr.Dataset | xr.DataArray — The data array to extrude and pad like.
  • rel_tol float — This tolerance is used to determine whether extrusion needs to occur. It will be multiplied by the smallest difference between coordinate value in data. If data does not fully enclose like, but the difference in extents is less than this tolerance, then no extrusion will occur.
  • update_bounds bool — If True, adjust the coordinate bounds of data so that, for each coordinate, the minimum and maximum values are set to the most extreme values found in either data or like. This is useful for ensuring that small numerical differences (less than the threshold set by rel_tol) do not prevent the coordinates from being treated as matching, effectively “snapping” the bounds to a common range.
Returns XrType
interp_like()
def interp_like(self, like: xr.DataArray) -> typing.Self: ...

Interpolate this interface onto another DataArray’s coordinates.

Will call the interface’s extend method to ensure that it spans the coordinates spanned by other with the desired expansion behavior.

Parameters
  • like xr.DataArray — The DataArray on which to interpolate this interface.
Returns typing.Self — A new interpolated interface.
map()
def map(
    self,
    f: typing.Callable[[xr.DataArray], xr.DataArray],
    as_type: type | None = None,
) -> Interface: ...

Apply a function that modifies the DataArray representation.

All attributes of the DataArray will be kept as is.

Parameters
  • f typing.Callable[[xr.DataArray], xr.DataArray] — The function used to modify the DataArray. Must take and return a DataArray.
  • as_type type | None — Modify the type of the mapped DataArray. Useful for upcasting from a Hyperplane to a heterogeneous container, or vice versa.
Returns Interface — A new interface with a (potentially) modified DataArray representation.
map_representation()
def map_representation(
    self, f: typing.Callable[[xr.DataArray], xr.DataArray]
) -> typing.Self: ...

Transform this interface’s DataArray representation.

Parameters
  • f typing.Callable[[xr.DataArray], xr.DataArray] — Function transform with.
Returns typing.Self — A new, transformed interface.

Used in tutorials