pybacktrack.DynamicTopography

class pybacktrack.DynamicTopography(grid_list_filename, static_polygon_filename, rotation_filenames, longitude, latitude, age=None)

Class that reconstructs point location(s) and samples (and interpolates) time-dependent dynamic topography mantle frame grid files.

longitude

Longitude of the point location, or list of longitudes (if multiple point locations).

Type:: float or list of float

latitude

Latitude of the point location, or list of latitudes (if multiple point locations).

Type:: float or list of float

age

The age of the crust that the point location is on, or list of ages (if multiple point locations).

Note

If no age(s) was supplied then the age(s) of the static polygon(s) containing location(s) is used (or zero when no polygon contains a location).

Type:: float or list of float

interpolate_dynamic_topography

Used to sample and interpolate time-dependent dynamic topography mantle frame grid files.

Type:: pybacktrack.InterpolateDynamicTopography

Notes

Changed in version 1.4: Can have multiple point locations (version 1.3 allowed only one location). So longitude, latitude and age can all have either a single value or multiple values (same number for each).

__init__(grid_list_filename, static_polygon_filename, rotation_filenames, longitude, latitude, age=None)

Load dynamic topography grid filenames and associated ages from grid list file ‘grid_list_filename’.

Parameters:

grid_list_filename (str) – The filename of the grid list file.
static_polygon_filename (str) – The filename of the static polygons file.
rotation_filenames (list of str) – The list of rotation filenames.
longitude (float or list of float) – Longitude of the point location, or list of longitudes (if multiple point locations).
latitude (float or list of float) – Latitude of the point location, or list of latitudes (if multiple point locations).
age (float or list of float, optional) – The age of the crust that the point location is on, or list of ages (if multiple point locations). If not specified then the appearance age(s) of the static polygon(s) containing the point(s) is used.

Raises:

ValueError – If any age is negative (if specified).
ValueError – If longitude and latitude (and age if specified) are all not a single value or all not a sequence (of same length).
ValueError – If grid_list_filename does not contain a grid at present day, or grid_list_filename contains fewer than two grids, or not all rows in grid_list_filename contain a grid filename followed by an age, or there are two ages in grid_list_filename with same age.

Notes

Each dynamic topography grid should be in the mantle reference frame (not plate reference frame) and should have global coverage (such that no sample location will return NaN).

Each row in the grid list file should contain two columns. First column containing filename (relative to directory of list file) of a dynamic topography grid at a particular time. Second column containing associated time (in Ma).

Each present day location is also assigned a plate ID using the static polygons, and the rotations are used to reconstruct each location when sampling the grids at a reconstructed time.

Changed in version 1.4: The following changes were made:

Added ability to specify a list of point locations (as an alternative to specifying a single location).
Raises ValueError if there’s no present day grid or if any age is negative.

Methods

`__init__`(grid_list_filename, ...[, age])	Load dynamic topography grid filenames and associated ages from grid list file 'grid_list_filename'.
`create_from_bundled_model`(...[, age])	Create a DynamicTopography instance from a bundled dynamic topography model name.
`create_from_model_or_bundled_model_name`(...)	Create a DynamicTopography instance from a user-provided model or from a bundled model.
`get_bundled_model`(dynamic_topography_model_name)	Get the bundled model files for the specified dynamic topography model name.
`sample`(time[, fallback])	Samples and interpolates the two time-dependent dynamic topography grids surrounding `time` at point location(s) reconstructed to `time`, but optionally falls back to a non-optimal sampling if necessary (depending on `time`)

static create_from_bundled_model(dynamic_topography_model_name, longitude, latitude, age=None)

Create a DynamicTopography instance from a bundled dynamic topography model name.

Parameters:

dynamic_topography_model_name (str) – Name of a bundled dynamic topography model. Choices include terra, M1, M2, M3, M4, M5, M6, M7, ngrand, s20rts, smean, AY18, KM16, D10_gmcm9 and gld428.
longitude (float or list of float) – Longitude of the point location, or list of longitudes (if multiple point locations).
latitude (float or list of float) – Latitude of the point location, or list of latitudes (if multiple point locations).
age (float or list of float, optional) – The age of the crust that the point location is on, or list of ages (if multiple point locations). If not specified then the appearance age(s) of the static polygon(s) containing the point(s) is used.

Returns:

The bundled dynamic topography model.

Return type:

pybacktrack.DynamicTopography

Raises:

ValueError – If dynamic_topography_model_name is not the name of a bundled dynamic topography model.

Notes

Added in version 1.2.

Changed in version 1.4: Added ability to specify a list of point locations (as an alternative to specifying a single location).

static create_from_model_or_bundled_model_name(dynamic_topography_model_or_bundled_model_name, longitude, latitude, age=None)

Create a DynamicTopography instance from a user-provided model or from a bundled model.

Parameters:

dynamic_topography_model_or_bundled_model_name (str or 3-tuple (str, str, list of str)) – Either the name of a bundled dynamic topography model (see pybacktrack.DynamicTopography.create_from_bundled_model()), or a user-provided model specified as a 3-tuple (filename of the grid list file, filename of the static polygons file, list of rotation filenames) (see first three parameters of pybacktrack.DynamicTopography.__init__()).
longitude (float or list of float) – Longitude of the point location, or list of longitudes (if multiple point locations).
latitude (float or list of float) – Latitude of the point location, or list of latitudes (if multiple point locations).
age (float or list of float, optional) – The age of the crust that the point location is on, or list of ages (if multiple point locations). If not specified then the appearance age(s) of the static polygon(s) containing the point(s) is used.

Returns:

The dynamic topography model loaded from a user-provided model or from a bundled model.

Return type:

pybacktrack.DynamicTopography

Raises:

ValueError – If dynamic_topography_model_or_bundled_model_name is not the name of a bundled dynamic topography model or is not a 3-tuple (filename of the grid list file, filename of the static polygons file, list of rotation filenames).

Notes

Added in version 1.4.

static get_bundled_model(dynamic_topography_model_name)

Get the bundled model files for the specified dynamic topography model name.

Parameters:

dynamic_topography_model_name (str) – Name of a bundled dynamic topography model. Choices include terra, M1, M2, M3, M4, M5, M6, M7, ngrand, s20rts, smean, AY18, KM16, D10_gmcm9 and gld428.

Returns:

The bundled dynamic topography model files (see first three parameters of pybacktrack.DynamicTopography.__init__()). This consists of a 3-tuple of:

Filename of the grid list file.
Filename of the static polygons file.
List of rotation filenames.

Return type:

3-tuple of (grid_list_filename, static_polygon_filename, rotation_filenames)

Raises:

ValueError – If dynamic_topography_model_name is not the name of a bundled dynamic topography model.

Notes

The returned model information is obtained from pybacktrack.BUNDLE_DYNAMIC_TOPOGRAPHY_MODELS (see Bundle data).

Added in version 1.5.

sample(time, fallback=True)

Samples and interpolates the two time-dependent dynamic topography grids surrounding time at point location(s) reconstructed to time, but optionally falls back to a non-optimal sampling if necessary (depending on time)

Parameters:

time (float) – Time to sample dynamic topography.
fallback (bool) – Whether to fall back to a non-optimal sampling if neccessary (see notes below). Defaults to True.

Returns:

The sampled dynamic topography value or list of values. If constructed with a single location then returns a single value, otherwise returns a list of values (one per location).

When fallback is True then float('NaN`) will never be returned (see notes below). When fallback is False then float('NaN`) will be returned:

for all points when the oldest dynamic topography grid is younger than time, or
for each point location whose age is younger than time (ie, has not yet appeared).

Return type:

float or list of float

Notes

Each point location is first reconstructed to time before sampling the two grids surrounding time at the reconstructed location and interpolating between them.

For each point location, if time is older than its appearance age then it is still reconstructed to time when fallback is True, otherwise float('NaN`) is returned (for that location) when fallback is False.

If time is older than the oldest grid then the oldest grid is sampled when fallback is True, otherwise float('NaN`) is returned for all locations when fallback is False.

Changed in version 1.2: Previously this method was called sample_interpolated and did not fall back to non-optimal sampling when necessary.

Changed in version 1.4: The following changes were made:

Merged sample, sample_interpolated and sample_oldest methods into one method (this method).
Added fallback parameter (where False behaves like removed sample_interpolated method).
Added ability to specify a list of point locations (as an alternative to specifying a single location).
Changed how grids are interpolated:
- Version 1.3 (and earlier) reconstructed each location to two times (of the two grids surrounding time) to get two reconstructed locations. Then each reconstructed location sampled its respective grid (ie, each grid was sampled at a different reconstructed location). Then these two samples were interpolated (based on time).
- Version 1.4 reconstructs each location to the single time to get a single reconstructed location. Then that single reconstructed location samples both grids surrounding time (ie, each grid is sampled at the same reconstructed location). Then these two samples are interpolated (based on time).
…note that there is no difference at grid times (only between grid times).