pybacktrack.InterpolateDynamicTopography

class pybacktrack.InterpolateDynamicTopography(grid_list_filename)

Class that just samples and interpolates time-dependent dynamic topography mantle frame grid files.

This class accepts locations that have already been reconstructed whereas pybacktrack.DynamicTopography accepts present day locations and reconstructs them prior to sampling the dynamic topography grids.

Notes

Added in version 1.4.

__init__(grid_list_filename)

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.
Raises:: 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).

Added in version 1.4.

Methods

`__init__`(grid_list_filename)	Load dynamic topography grid filenames and associated ages from grid list file 'grid_list_filename'.
`convert_from_dynamic_topography_model_or_bundled_model_name`(...)	Convert an argument that would normally be supplied to `pybacktrack.DynamicTopography.create_from_model_or_bundled_model_name()` to an argument suitable for `pybacktrack.InterpolateDynamicTopography.create_from_model_or_bundled_model_name()`.
`create_from_bundled_model`(...)	Create a InterpolateDynamicTopography instance from a bundled dynamic topography model name.
`create_from_model_or_bundled_model_name`(...)	Create a InterpolateDynamicTopography instance from a user-provided model or from a bundled model.
`sample`(time, locations[, fallback_to_oldest])	Samples and interpolates the two time-dependent dynamic topography grids surrounding `time` at the specified point location(s), but optionally falls back to sampling oldest grid (if `time` is too old).

static convert_from_dynamic_topography_model_or_bundled_model_name(dynamic_topography_model_or_bundled_model_name)

Convert an argument that would normally be supplied to pybacktrack.DynamicTopography.create_from_model_or_bundled_model_name() to an argument suitable for pybacktrack.InterpolateDynamicTopography.create_from_model_or_bundled_model_name().

Parameters:: dynamic_topography_model_or_bundled_model_name (str) – An argument that would normally be supplied to pybacktrack.DynamicTopography.create_from_model_or_bundled_model_name().
Return type:: An argument suitable for pybacktrack.InterpolateDynamicTopography.create_from_model_or_bundled_model_name().
Raises:: ValueError – If dynamic_topography_model_or_bundled_model_name is not a str (name of a bundled dynamic topography model) or not a 3-tuple with first entry being the name of a (grid list) file that exists in the file system.

Notes

Added in version 1.5.

static create_from_bundled_model(dynamic_topography_model_name)

Create a InterpolateDynamicTopography 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.
Returns:: The bundled dynamic topography model.
Return type:: pybacktrack.InterpolateDynamicTopography
Raises:: ValueError – If dynamic_topography_model_name is not the name of a bundled dynamic topography model.

Notes

Added in version 1.4.

static create_from_model_or_bundled_model_name(dynamic_topography_model_or_bundled_model_name)

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

Parameters:: dynamic_topography_model_or_bundled_model_name (str) – Either the name of a bundled dynamic topography model (see pybacktrack.InterpolateDynamicTopography.create_from_bundled_model()), or a user-provided model specified as the filename of the grid list file (see parameter of pybacktrack.InterpolateDynamicTopography.__init__()).
Returns:: The dynamic topography model loaded from a user-provided model or from a bundled model.
Return type:: pybacktrack.InterpolateDynamicTopography
Raises:: ValueError – If dynamic_topography_model_or_bundled_model_name is not the name of a bundled dynamic topography model or the filename of an existing grid list file.

Notes

Added in version 1.4.

sample(time, locations, fallback_to_oldest=True)

Samples and interpolates the two time-dependent dynamic topography grids surrounding time at the specified point location(s), but optionally falls back to sampling oldest grid (if time is too old).

Parameters:

time (float) – Time to sample dynamic topography.
locations (sequence of 2-tuple (float, float)) – A sequence of (longitude, latitude) point locations.
fallback_to_oldest (bool) – Whether to fall back to sampling oldest grid (if time is too old) rather than interpolating the two grids surrounding time. Defaults to True.

Returns:

The sampled dynamic topography values (one per location).

When time is older than the oldest dynamic topography grid:

if fallback_to_oldest is True then the oldest dynamic topography grid is sampled, or
if fallback_to_oldest is False then None is returned.

Return type:

list of float, or None

Notes

The point location(s) sample the two grids with ages bounding time and then interpolate between them.

However if time is older than the oldest grid then the oldest grid is sampled (if fallback_to_oldest is True).

All returned sample values are non-NaN.

Added in version 1.4.