Mondaic
This API reference is not for the latest stable Salvus version.

salvus.project.configuration.topography.cartesian

Classes

GenericTopography

class GenericTopography(
    salvus.project.configuration.topography.cartesian._CartesianBase
):
    def __init__(self) -> None: ...

Generic topography - currently not implemented.

Attributes
coordinates Union[numpy.ndarray, Tuple[numpy.ndarray, numpy.ndarray]]

Coordinates of the data values.

ds xarray.core.dataset.Dataset

The actual dataset representing the model.

name str

Name of the topography configuration.

no_deformation_above float

Don’t deform above this values.

no_deformation_below Optional[float]

Don’t deform below this value.

reference_elevation float

Reference elevation height.

relative_elevation_model numpy.ndarray

Relative elevation model.

Methods
from_json()
def from_json(parent_folder: pathlib.Path, d: Dict) -> _ModelBase: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • parent_folder pathlib.Path — Path to which the serialized model is relative to.
  • d Dict — Dictionary containing its init parameters and a few other things.
Returns _ModelBase
to_json()
def to_json(self, parent_folder: Union[str, pathlib.Path]) -> Dict: ...

Serialize the model to JSON (and an associated NetCDF file).

Parameters
  • parent_folder Union[str, pathlib.Path] — Parent folder where the JSON + NetCDF files should be stored.
Returns Dict

SurfaceTopography

class SurfaceTopography(
    salvus.project.configuration.topography.cartesian._CartesianBase
):
    def __init__(
        self,
        name: str,
        data: Union[pathlib.Path, str, xarray.core.dataset.Dataset],
        no_deformation_below: Optional[float] = None,
        no_deformation_above: Optional[float] = None,
        use_symlink: bool = False,
    ) -> None: ...

Surface topography.

Parameters
  • name str — Name for this topography model.
  • data Union[pathlib.Path, str, xarray.core.dataset.Dataset] — xarray dataset, or path to a NetCDF file saved by xarray, which contains the digital elevation model (DEM).
  • no_deformation_below Optional[float] — Do not deform the mesh below this value.
  • no_deformation_above Optional[float] — Usually not necessary for the users to set, as it will be auto-derived from the topography model in most cases. However, if special requirements are present (for instance: the presence of an atmospheric layer above the surface topography), one may benefit from setting this value.
  • use_symlink bool — Don’t copy the data to the project but only use a symlink. Only works if the data is passed as a filename or path.
Attributes
coordinates Union[numpy.ndarray, Tuple[numpy.ndarray, numpy.ndarray]]

Coordinates of the data values.

ds xarray.core.dataset.Dataset

The actual dataset representing the model.

name str

Name of the topography configuration.

no_deformation_above float

Don’t deform above this values.

no_deformation_below Optional[float]

Don’t deform below this value.

reference_elevation float

Reference elevation height.

relative_elevation_model numpy.ndarray

Relative elevation model.

Methods
from_appeears_request()
def from_appeears_request(
    name: str,
    data: pathlib.Path,
    utm: pyproj.crs.crs.CRS,
    resample_topo_nx: int = 100,
    decimate_topo_factor: int = 1,
    gaussian_std_in_meters: float = 100.0,
    no_deformation_below: Optional[float] = None,
    no_deformation_above: Optional[float] = None,
    dem_variable_name: Optional[str] = None,
) -> SurfaceTopography: ...

Create a surface topography from an APPEEARS data file.

The APPEEARS (https://lpdaacsvc.cr.usgs.gov/appeears/) service is a webservice that allows, among other things, researchers to download high-resolution digital elevation models (up to 30m resolution) for much of the globe. This helper function allows Salvus users to transform the APPEEARS topography files into a Salvus “Topography Model” for use in waveform simulations.

Parameters
  • name str — Name for this topography model.
  • data pathlib.Path — Path to the APPEEARS NetCDF file.
  • utm pyproj.crs.crs.CRS — A pyproj.CRS object describing the UTM projection to which the elevation data should be transformed. The APPEEARS data is assumed to be referenced to the WGS84 ellipsoid by convention. This can usually be gathered from the target UtmDomain object.
  • resample_topo_nx int — The elevation model is re-sampled onto a regular grid in UTM coordinate. This parameter controls the number of points per dimension in the re-sampled dataset. Resample the elevation model to this many points. If the interpolation stage is taking very long, you can consider decreasing this value.
  • decimate_topo_factor int — Decimate the provided topography model this factor (before conversion to UTM). If the interpolation stage is taking very long, you can consider increasing this value.
  • gaussian_std_in_meters float — Apply a Gaussian filter to the topography model once it has been transformed into UTM coordinates. This serves to smooth the model, and may be necessary if there are very sharp changes in elevation relative to the size of an element.
  • no_deformation_below Optional[float] — Do not deform the mesh below this value. Useful if you have a 1-D model which need to place at a specific depth below the WGS84 sea level.
  • no_deformation_above Optional[float] — Do not deform the mesh above this value. Useful in special circumstances (i.e. if an atmosphere layer is desired).
  • dem_variable_name Optional[str] — The variable name of the actual topography data in the netcdf file. In most cases Salvus will be able to automatically determine this. If not, please specify it.
Returns SurfaceTopography
from_gmrt_file()
def from_gmrt_file(
    name: str,
    utm: pyproj.crs.crs.CRS,
    data: pathlib.Path,
    resample_topo_nx: int = 100,
    decimate_topo_factor: int = 1,
    gaussian_std_in_meters: float = 100.0,
    no_deformation_below: Optional[float] = None,
    no_deformation_above: Optional[float] = None,
) -> SurfaceTopography: ...

Create a surface topography from a GMRT data file.

The GMRT (https://www.gmrt.org/) service is a webservice that allows, among other things, researchers to download high-resolution digital elevation and bathymetry models (up to 30m resolution) for much of the globe. This helper function allows Salvus users to transform the GMRT topography files into a Salvus “Topography Model” for use in waveform simulations.

Parameters
  • name str — Name for this topography model.
  • utm pyproj.crs.crs.CRS — A pyproj.CRS object describing the UTM projection to which the elevation data should be transformed. The GMRT data is assumed to be referenced to the WGS84 ellipsoid by convention. This can usually be gathered from the target UtmDomain object.
  • data pathlib.Path — Path to the GMRT NetCDF file.
  • resample_topo_nx int — The elevation model is re-sampled onto a regular grid in UTM coordinate. This parameter controls the number of points per dimension in the re-sampled dataset. Resample the elevation model to this many points. If the interpolation stage is taking very long, you can consider decreasing this value.
  • decimate_topo_factor int — Decimate the provided topography model this factor (before conversion to UTM). If the interpolation stage is taking very long, you can consider increasing this value.
  • gaussian_std_in_meters float — Apply a Gaussian filter to the topography model once it has been transformed into UTM coordinates. This serves to smooth the model, and may be necessary if there are very sharp changes in elevation relative to the size of an element.
  • no_deformation_below Optional[float] — Do not deform the mesh below this value. Useful if you have a 1-D model which need to place at a specific depth below the WGS84 sea level.
  • no_deformation_above Optional[float] — Do not deform the mesh above this value. Useful in special circumstances (i.e. if an atmosphere layer is desired).
Returns SurfaceTopography
from_json()
def from_json(parent_folder: pathlib.Path, d: Dict) -> _ModelBase: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • parent_folder pathlib.Path — Path to which the serialized model is relative to.
  • d Dict — Dictionary containing its init parameters and a few other things.
Returns _ModelBase
extract_2d_line()
def extract_2d_line(
    self,
    name: str,
    p0: Tuple[float, float],
    p1: Tuple[float, float],
    buffer_in_meters: float = 0.0,
    n_points: int,
) -> SurfaceTopography: ...

Extract a 1-D profile from a 2-D topography model.

When considering the computational cost of waveform simulations it is often desireable to run run 2-D simulations instead of 3-D ones. This function allows users to extract 1-D lines from 2-D topography models (such as those generated with the from_apppears_request or from_gmrt_file functions), and use these lines to deform the surface of a 2-D mesh according to the topographic profile along the chosen line.

Additional keyword arguments are passed to the internal interpolation function. We currently use RectBivariateSpline from scipy.

Parameters
  • name str — Name for this topography model.
  • p0 Tuple[float, float] — A tuple of points (x0, y0) defining the start of the profile.
  • p1 Tuple[float, float] — A tuple of points (x1, y1) defining the end of the profile.
  • buffer_in_meters float — A length in meters on each side of the profile to extend the topography model by. This can be useful, for instance, if you will eventually attach absorbing boundaries to the 2-D mesh and require the topography model to extend into the absorbing region.
  • n_points int — The number of points with which to perform the interpolation.
Returns SurfaceTopography
to_json()
def to_json(self, parent_folder: Union[str, pathlib.Path]) -> Dict: ...

Serialize the model to JSON (and an associated NetCDF file).

Parameters
  • parent_folder Union[str, pathlib.Path] — Parent folder where the JSON + NetCDF files should be stored.
Returns Dict