gplately.PlateReconstruction

class gplately.PlateReconstruction(rotation_model, topology_features=None, static_polygons=None, anchor_plate_id: int | None = None, plate_model: PlateModel | None = None)[source]

Bases: object

Reconstruct topology features to specific geological times given a rotation_model, a set of topology_features and a set of static_polygons. Topological plate velocity data at specific geological times can also be calculated from these reconstructed features.

__init__(rotation_model, topology_features=None, static_polygons=None, anchor_plate_id: int | None = None, plate_model: PlateModel | None = None)[source]

Parameters:

rotation_model (str/os.PathLike, or instance of pygplates.FeatureCollection, or pygplates.Feature, or sequence of pygplates.Feature, or instance of pygplates.RotationModel) – A rotation model to query equivalent and/or relative topological plate rotations from a time in the past relative to another time in the past or to present day. Can be provided as a rotation filename, or rotation feature collection, or rotation feature, or sequence of rotation features, or a sequence (eg, a list or tuple) of any combination of those four types.
topology_features (str/os.PathLike, or a sequence (eg, list or tuple) of instances of pygplates.Feature, or a single instance of pygplates.Feature, or an instance of pygplates.FeatureCollection, default None) – Reconstructable topological features like trenches, ridges and transforms. Can be provided as an optional topology-feature filename, or sequence of features, or a single feature.
static_polygons (str/os.PathLike, or instance of pygplates.Feature, or sequence of pygplates.Feature, or an instance of pygplates.FeatureCollection, default None) – Present-day polygons whose shapes do not change through geological time. They are used to cookie-cut dynamic polygons into identifiable topological plates (assigned an ID) according to their present-day locations. Can be provided as a static polygon feature collection, or optional filename, or a single feature, or a sequence of features.
anchor_plate_id (int, optional) – Default anchor plate ID for reconstruction. If not specified then uses the default anchor plate of rotation_model.
plate_model (PlateModel, optional) – Only if users would like the PlateReconstruction object tracks the PlateModel.

Methods

`__init__`(rotation_model[, ...])
`create_flowline`(lons, lats, time_array, ...)	Create a path of points to track plate motion away from spreading ridges over time using half-stage rotations.
`create_motion_path`(lons, lats, time_array[, ...])	Create a path of points to mark the trajectory of a plate's motion through geological time.
`crustal_production_destruction_rate`(time[, ...])	Calculates the total crustal production and destruction rates (in km²/yr) of divergent and convergent plate boundaries at the specified geological time (Ma).
`divergent_convergent_plate_boundaries`(time)	Samples points uniformly along plate boundaries and calculates statistics at diverging/converging locations at a particular geological time.
`get_point_velocities`(lons, lats, time[, ...])	Calculates the north and east components of the velocity vector (in kms/myr) for each specified point (from `lons` and `lats`) at a particular geological `time`.
`reconstruct`(feature, to_time[, from_time, ...])	Reconstructs regular geological features, motion paths or flowlines to a specific geological time.
`reconstruct_snapshot`(...[, anchor_plate_id, ...])	Create a snapshot of reconstructed regular features (including motion paths and flowlines) at a specific geological time.
`static_polygons_snapshot`(time, *[, ...])	Create a reconstructed snapshot of the static polygons at the specified reconstruction time.
`tessellate_mid_ocean_ridges`(time[, ...])	Samples points along resolved spreading features (e.g. mid-ocean ridges) and calculates spreading rates and lengths of ridge segments at a particular geological time.
`tessellate_subduction_zones`(time[, ...])	Samples points along subduction zone trenches and obtains subduction data at a particular geological time.
`topological_snapshot`(time, *[, ...])	Create a snapshot of resolved topologies at the specified reconstruction time.
`total_continental_arc_length`(time, ...[, ...])	Calculates the total length of all global continental arcs (km) at the specified geological time (Ma).
`total_ridge_length`(time[, use_ptt, ...])	Calculates the total length of all resolved spreading features (e.g. mid-ocean ridges) at the specified geological time (Ma).
`total_subduction_zone_length`(time[, ...])	Calculates the total length of all subduction zones (km) at the specified geological time (Ma).

Attributes

`anchor_plate_id`	Default anchor plate ID for reconstruction.
`rotation_model`	A pygplates.RotationModel object to query equivalent and/or relative topological plate rotations from a time in the past relative to another time in the past or to present day.
`topology_features`	A pygplates.FeatureCollection object containing topological features like trenches, ridges and transforms.
`static_polygons`	A pygplates.FeatureCollection object containing the present-day static polygons whose shapes do not change through geological time when reconstructed.
`plate_model`	Optional PlateModel object

property anchor_plate_id: Default anchor plate ID for reconstruction. Must be an integer >= 0.

create_flowline(lons, lats, time_array, left_plate_ID, right_plate_ID, return_rate_of_motion=False)[source]

Create a path of points to track plate motion away from spreading ridges over time using half-stage rotations.

Parameters:

lons (arr) – An array of longitudes of points along spreading ridges.
lats (arr) – An array of latitudes of points along spreading ridges.
time_array (arr) – A list of times to obtain seed point locations at.
left_plate_ID (int) – The plate ID of the polygon to the left of the spreading ridge.
right_plate_ID (int) – The plate ID of the polygon to the right of the spreading ridge.
return_rate_of_motion (bool, default False) – Choose whether to return a step time and step rate array for a step plot of motion.

Returns:

left_lon (ndarray) – The longitudes of the left flowline for n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.
left_lat (ndarray) – The latitudes of the left flowline of n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.
right_lon (ndarray) – The longitudes of the right flowline of n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.
right_lat (ndarray) – The latitudes of the right flowline of n seed points. There are n columns for n seed points, and m rows for m time steps in time_array.

Examples

To access the i^th seed point’s left and right latitudes and longitudes:

for i in np.arange(0,len(seed_points)):
    left_flowline_longitudes = left_lon[:,i]
    left_flowline_latitudes = left_lat[:,i]
    right_flowline_longitudes = right_lon[:,i]
    right_flowline_latitudes = right_lat[:,i]

create_motion_path(lons, lats, time_array, plate_id=None, anchor_plate_id=None, return_rate_of_motion=False)[source]

Create a path of points to mark the trajectory of a plate’s motion through geological time.

Parameters:

lons (arr) – An array containing the longitudes of seed points on a plate in motion.
lats (arr) – An array containing the latitudes of seed points on a plate in motion.

time_array (arr) –

An array of reconstruction times at which to determine the trajectory of a point on a plate. For example:

import numpy as np
min_time = 30
max_time = 100
time_step = 2.5
time_array = np.arange(min_time, max_time + time_step, time_step)

plate_id (int, optional) – The ID of the moving plate. If this is not passed, the plate ID of the seed points are ascertained using pygplates’ PlatePartitioner.
anchor_plate_id (int, optional) – The ID of the anchor plate. Defaults to the default anchor plate (specified in __init__ or set with anchor_plate_id attribute).
return_rate_of_motion (bool, default=False) – Choose whether to return the rate of plate motion through time for each step.

Returns:

rlons (ndarray) – An n-dimensional array with columns containing the longitudes of the seed points at each timestep in time_array. There are n columns for n seed points.
rlats (ndarray) – An n-dimensional array with columns containing the latitudes of the seed points at each timestep in time_array. There are n columns for n seed points.
StepTimes (ndarray) – Time interval for each step.
StepRates (ndarray) – The rate of plate motion for each step.

Raises:

ValueError – If plate_id is None and topology features have not been set in this PlateReconstruction.

Examples

To access the latitudes and longitudes of each seed point’s motion path:

for i in np.arange(0,len(seed_points)):
    current_lons = lon[:,i]
    current_lats = lat[:,i]

crustal_production_destruction_rate(time, uniform_point_spacing_radians=0.001, divergence_velocity_threshold_in_cms_per_yr=0.0, convergence_velocity_threshold_in_cms_per_yr=0.0, *, first_uniform_point_spacing_radians=None, velocity_delta_time=1.0, velocity_delta_time_type=pygplates.pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t, include_network_boundaries=False, include_topological_slab_boundaries=False, boundary_section_filter=None)[source]

Calculates the total crustal production and destruction rates (in km²/yr) of divergent and convergent plate boundaries at the specified geological time (Ma).

Resolves topologies at time and uniformly samples all plate boundaries into divergent and convergent boundary points.

Total crustal production (and destruction) rate is then calculated by accumulating divergent (and convergent) orthogonal velocities multiplied by their local boundary lengths. Velocities and lengths are scaled using the geocentric radius (at each divergent and convergent sampled point).

Parameters:

time (float) – The reconstruction time (Ma) at which to query divergent/convergent plate boundaries.
uniform_point_spacing_radians (float, default=0.001) – The spacing between uniform points along plate boundaries (in radians).
divergence_velocity_threshold_in_cms_per_yr (float, default=0.0) – Orthogonal (ie, in the direction of boundary normal) velocity threshold for diverging sample points. Points with an orthogonal diverging velocity above this value will accumulate crustal production. The default is 0.0 which removes all converging sample points (leaving only diverging points). This value can be negative which means a small amount of convergence is allowed for the diverging points. The units should be in cm/yr.
convergence_velocity_threshold_in_cms_per_yr (float, default=0.0) – Orthogonal (ie, in the direction of boundary normal) velocity threshold for converging sample points. Points with an orthogonal converging velocity above this value will accumulate crustal destruction. The default is 0.0 which removes all diverging sample points (leaving only converging points). This value can be negative which means a small amount of divergence is allowed for the converging points. The units should be in cm/yr.
first_uniform_point_spacing_radians (float, optional) – Spacing of first uniform point in each resolved topological section (in radians) - see divergent_convergent_plate_boundaries() for more details. Defaults to half of uniform_point_spacing_radians.
velocity_delta_time (float, default=1.0) – The time delta used to calculate velocities (defaults to 1 Myr).
velocity_delta_time_type (pygplates.VelocityDeltaTimeType, default=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t) – How the two velocity times are calculated relative to time (defaults to [time + velocity_delta_time, time]).
include_network_boundaries (bool, default=False) – Whether to sample along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option.
include_topological_slab_boundaries (bool, default=False) – Whether to sample along slab boundaries (features of type gpml:TopologicalSlabBoundary). By default they are not sampled since they are not plate boundaries.
boundary_section_filter – Same as the boundary_section_filter argument in divergent_convergent_plate_boundaries(). Defaults to None (meaning all plate boundaries are included by default).

Returns:

total_crustal_production_rate_in_km_2_per_yr (float) – The total rate of crustal production at divergent plate boundaries (in km²/yr) at the specified time.
total_crustal_destruction_rate_in_km_2_per_yr (float) – The total rate of crustal destruction at convergent plate boundaries (in km²/yr) at the specified time.

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.

Examples

To calculate total crustal production/destruction along plate boundaries at 50Ma:

(
    total_crustal_production_rate_in_km_2_per_yr,
    total_crustal_destruction_rate_in_km_2_per_yr,
) = plate_reconstruction.crustal_production_destruction_rate(50)

To do the same, but restrict convergence to points where orthogonal converging velocities are greater than 0.2 cm/yr (with divergence remaining unchanged with the default 0.0 threshold):

(
    total_crustal_production_rate_in_km_2_per_yr,
    total_crustal_destruction_rate_in_km_2_per_yr,
) = plate_reconstruction.crustal_production_destruction_rate(
    50, convergence_velocity_threshold_in_cms_per_yr=0.2
)

divergent_convergent_plate_boundaries(time, uniform_point_spacing_radians=0.001, divergence_velocity_threshold=0.0, convergence_velocity_threshold=0.0, *, first_uniform_point_spacing_radians=None, anchor_plate_id=None, velocity_delta_time=1.0, velocity_delta_time_type=pygplates.pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t, velocity_units=pygplates.pygplates.VelocityUnits.cms_per_yr, earth_radius_in_kms=6371.009, include_network_boundaries=False, include_topological_slab_boundaries=False, boundary_section_filter=None)[source]

Samples points uniformly along plate boundaries and calculates statistics at diverging/converging locations at a particular geological time.

Resolves topologies at time, uniformly samples all plate boundaries into points and returns two lists of pygplates.PlateBoundaryStatistic. The first list represents sample points where the plates are diverging, and the second where plates are converging.

Parameters:

time (float) – The reconstruction time (Ma) at which to query divergent/convergent plate boundaries.
uniform_point_spacing_radians (float, default=0.001) – The spacing between uniform points along plate boundaries (in radians).
divergence_velocity_threshold (float, default=0.0) – Orthogonal (ie, in the direction of boundary normal) velocity threshold for diverging sample points. Points with an orthogonal diverging velocity above this value will be returned in diverging_data. The default is 0.0 which removes all converging sample points (leaving only diverging points). This value can be negative which means a small amount of convergence is allowed for the diverging points. The units should match the units of velocity_units (eg, if that’s cm/yr then this threshold should also be in cm/yr).
convergence_velocity_threshold (float, default=0.0) – Orthogonal (ie, in the direction of boundary normal) velocity threshold for converging sample points. Points with an orthogonal converging velocity above this value will be returned in converging_data. The default is 0.0 which removes all diverging sample points (leaving only converging points). This value can be negative which means a small amount of divergence is allowed for the converging points. The units should match the units of velocity_units (eg, if that’s cm/yr then this threshold should also be in cm/yr).
first_uniform_point_spacing_radians (float, optional) – Spacing of first uniform point in each resolved topological section (in radians) - see pygplates.TopologicalSnapshot.calculate_plate_boundary_statistics() for more details. Defaults to half of uniform_point_spacing_radians.
anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (anchor_plate_id attribute).
velocity_delta_time (float, default=1.0) – The time delta used to calculate velocities (defaults to 1 Myr).
velocity_delta_time_type (pygplates.VelocityDeltaTimeType, default=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t) – How the two velocity times are calculated relative to time (defaults to [time + velocity_delta_time, time]).
velocity_units (pygplates.VelocityUnits, default=pygplates.VelocityUnits.cms_per_yr) – Whether to return velocities in centimetres per year or kilometres per million years (defaults to centimetres per year).
earth_radius_in_kms (float, default=pygplates.Earth.mean_radius_in_kms) – Radius of the Earth in kilometres. This is only used to calculate velocities (strain rates always use pygplates.Earth.equatorial_radius_in_kms).
include_network_boundaries (bool, default=False) – Whether to sample along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option.
include_topological_slab_boundaries (bool, default=False) – Whether to sample along slab boundaries (features of type gpml:TopologicalSlabBoundary). By default they are not sampled since they are not plate boundaries.
boundary_section_filter – Same as the boundary_section_filter argument in pygplates.TopologicalSnapshot.calculate_plate_boundary_statistics(). Defaults to None (meaning all plate boundaries are included by default).

Returns:

diverging_data (list of pygplates.PlateBoundaryStatistic) – The results for all uniformly sampled points along plate boundaries that are diverging relative to divergence_threshold. The size of the returned list is equal to the number of sampled points that are diverging. Each pygplates.PlateBoundaryStatistic is guaranteed to have a valid (ie, not None) convergence velocity.
converging_data (list of pygplates.PlateBoundaryStatistic) – The results for all uniformly sampled points along plate boundaries that are converging relative to convergence_threshold. The size of the returned list is equal to the number of sampled points that are converging. Each pygplates.PlateBoundaryStatistic is guaranteed to have a valid (ie, not None) convergence velocity.

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.

Examples

To sample diverging/converging points along plate boundaries at 50Ma:

diverging_data, converging_data = (
    plate_reconstruction.divergent_convergent_plate_boundaries(50)
)

To do the same, but restrict converging data to points where orthogonal converging velocities are greater than 0.2 cm/yr (with diverging data remaining unchanged with the default 0.0 threshold):

diverging_data, converging_data = (
    plate_reconstruction.divergent_convergent_plate_boundaries(
        50, convergence_velocity_threshold=0.2
    )
)

Notes

If you want to access all sampled points regardless of their convergence/divergence you can call topological_snapshot() and then use it to directly call pygplates.TopologicalSnapshot.calculate_plate_boundary_statistics(). Then you can do your own analysis on the returned data:

plate_boundary_statistics = plate_reconstruction.topological_snapshot(
    time, include_topological_slab_boundaries=False
).calculate_plate_boundary_statistics(uniform_point_spacing_radians=0.001)

for stat in plate_boundary_statistics:
    if np.isnan(stat.convergence_velocity_orthogonal):
        continue  # missing left or right plate
    latitude, longitude = stat.boundary_point.to_lat_lon()

get_point_velocities(lons, lats, time, delta_time=1.0, *, velocity_delta_time_type=pygplates.pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t, velocity_units=pygplates.pygplates.VelocityUnits.kms_per_my, earth_radius_in_kms=6371.009, include_networks=True, include_topological_slab_boundaries=False, anchor_plate_id=None, return_east_north_arrays=False)[source]

Calculates the north and east components of the velocity vector (in kms/myr) for each specified point (from lons and lats) at a particular geological time.

Parameters:

lons (array) – A 1D array of point data’s longitudes.
lats (array) – A 1D array of point data’s latitudes.
time (float) – The specific geological time (Ma) at which to calculate plate velocities.
delta_time (float, default=1.0) – The time interval used for velocity calculations. 1.0Ma by default.
velocity_delta_time_type (pygplates.VelocityDeltaTimeType, default=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t) – How the two velocity times are calculated relative to time (defaults to [time + velocity_delta_time, time]).
velocity_units (pygplates.VelocityUnits, default=pygplates.VelocityUnits.kms_per_my) – Whether to return velocities in centimetres per year or kilometres per million years (defaults to kilometres per million years).
earth_radius_in_kms (float, default=pygplates.Earth.mean_radius_in_kms) – Radius of the Earth in kilometres. This is only used to calculate velocities (strain rates always use pygplates.Earth.equatorial_radius_in_kms).
include_networks (bool, default=True) – Whether to include deforming networks when calculating velocities. By default they are included (and also given precedence since they typically overlay a rigid plate).
include_topological_slab_boundaries (bool, default=False) – Whether to include features of type gpml:TopologicalSlabBoundary when calculating velocities. By default they are not included (they tend to overlay a rigid plate which should instead be used to calculate plate velocity).
anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (anchor_plate_id attribute).
return_east_north_arrays (bool, default=False) – Return the velocities as arrays separately containing the east and north components of the velocities. Note that setting this to True matches the output of Points.plate_velocity().

Returns:

north_east_velocities (2D ndarray) – Only provided if return_east_north_arrays is False. Each array element contains the (north, east) velocity components of a single point.
east_velocities, north_velocities (1D ndarray) – Only provided if return_east_north_arrays is True. The east and north components of velocities as separate arrays. These are also ordered (east, north) instead of (north, east).

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.

Note

The velocities are in kilometres per million years by default (not centimetres per year, the default in Points.plate_velocity()). This difference is maintained for backward compatibility.

For each velocity, the north component is first followed by the east component. This is different to Points.plate_velocity() where the east component is first. This difference is maintained for backward compatibility.

plate_model: Optional PlateModel object

reconstruct(feature, to_time, from_time=0, anchor_plate_id=None, *, reconstruct_type=pygplates.pygplates.ReconstructType.feature_geometry, group_with_feature=False)[source]

Reconstructs regular geological features, motion paths or flowlines to a specific geological time.

Parameters:

feature (str/os.PathLike, or pygplates.FeatureCollection, or pygplates.Feature, or sequence of pygplates.Feature) – The geological features to reconstruct. It can be provided as a feature collection, or filename, or feature, or sequence of features, or a sequence (eg, a list or tuple) of any combination of those four types.
to_time (float, or pygplates.GeoTimeInstant) – The specific geological time to reconstruct to.
from_time (float, default=0) – The specific geological time to reconstruct from. By default, this is set to present day. If not set to 0 Ma (present day) then the geometry in feature is assumed to be a reconstructed snapshot at from_time, in which case it is reverse reconstructed to present day before reconstructing to to_time. Usually features should contain present day geometry but might contain reconstructed geometry in some cases, such as those generated by the reconstruction export in GPlates.
anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (anchor_plate_id attribute).
reconstruct_type (pygplates.ReconstructType, default=pygplates.ReconstructType.feature_geometry) – The specific reconstruction type to generate based on input feature geometry type. It can be provided as pygplates.ReconstructType.feature_geometry to only reconstruct regular feature geometries, or pygplates.ReconstructType.motion_path to only reconstruct motion path features, or pygplates.ReconstructType.flowline to only reconstruct flowline features. Generates pygplates.ReconstructedFeatureGeometry, or pygplates.ReconstructedMotionPath, or pygplates.ReconstructedFlowline respectively.
group_with_feature (bool, default=False) – Used to group reconstructed geometries with their features. This can be useful when a feature has more than one geometry and hence more than one reconstructed geometry. The returned list then becomes a list of tuples where each tuple contains a pygplates.Feature and a list of reconstructed geometries.

Returns:

reconstructed_features – The reconstructed geological features. The reconstructed geometries are output in the same order as that of their respective input features (in the parameter features). This includes the order across any input feature collections or files. If group_with_feature is True then the list contains tuples that group each pygplates.Feature with a list of its reconstructed geometries.

Return type:

list

See also

reconstruct_snapshot

reconstruct_snapshot(reconstructable_features, time, *, anchor_plate_id=None, from_time=0)[source]

Create a snapshot of reconstructed regular features (including motion paths and flowlines) at a specific geological time.

Parameters:

reconstructable_features (str/os.PathLike, or a sequence (eg, list or tuple) of instances of pygplates.Feature,) – or a single instance of pygplates.Feature, or an instance of pygplates.FeatureCollection Regular reconstructable features (including motion paths and flowlines). It can be provided as a feature collection, or filename, or feature, or sequence of features, or a sequence (eg, list or tuple) of any combination of those four types.
time (float, or pygplates.GeoTimeInstant) – The specific geological time to reconstruct to.
anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (anchor_plate_id attribute).
from_time (float, default=0) – The specific geological time to reconstruct from. By default, this is set to present day. If not set to 0 Ma (present day) then the geometry in feature is assumed to be a reconstructed snapshot at from_time, in which case it is reverse reconstructed to present day before reconstructing to to_time. Usually features should contain present day geometry but might contain reconstructed geometry in some cases, such as those generated by the reconstruction export in GPlates.

Returns:

reconstruct_snapshot – A pygplates.ReconstructSnapshot of the specified reconstructable features reconstructed using the internal rotation model to the specified reconstruction time.

Return type:

pygplates.ReconstructSnapshot

rotation_model: RotationModel | None: A pygplates.RotationModel object to query equivalent and/or relative topological plate rotations from a time in the past relative to another time in the past or to present day.

static_polygons: FeatureCollection | None: A pygplates.FeatureCollection object containing the present-day static polygons whose shapes do not change through geological time when reconstructed.

static_polygons_snapshot(time, *, anchor_plate_id=None)[source]

Create a reconstructed snapshot of the static polygons at the specified reconstruction time.

Return a pygplates.ReconstructSnapshot from which you can extract reconstructed static polygons, find reconstructed polygons containing points and calculate velocities at point locations, etc.

Parameters:

time (float, int or pygplates.GeoTimeInstant) – The geological time at which to create the reconstructed static polygons snapshot.
anchor_plate_id (int, optional) – The anchored plate id to use when reconstructing the static polygons. If not specified then uses the current anchor plate (anchor_plate_id attribute).

Returns:

static_polygons_snapshot – The reconstructed static polygons snapshot at the specified time (and anchor plate).

Return type:

pygplates.ReconstructSnapshot

Raises:

ValueError – If static polygons have not been set in this PlateReconstruction object.

tessellate_mid_ocean_ridges(time, tessellation_threshold_radians=0.001, ignore_warnings=False, return_geodataframe=False, *, use_ptt=False, spreading_feature_types=[<pygplates.pygplates.FeatureType object>], transform_segment_deviation_in_radians=1.2217304763960306, include_network_boundaries=False, divergence_threshold_in_cm_per_yr=None, output_obliquity_and_normal_and_left_right_plates=False, anchor_plate_id=None, velocity_delta_time=1.0)[source]

Samples points along resolved spreading features (e.g. mid-ocean ridges) and calculates spreading rates and lengths of ridge segments at a particular geological time.

Resolves topologies at time and tessellates all resolved spreading features into points.

The transform segments of spreading features are ignored (unless transform_segment_deviation_in_radians is None).

Returns a 4-column vertically stacked tuple with the following data per sampled ridge point (depending on output_obliquity_and_normal_and_left_right_plates):

If output_obliquity_and_normal_and_left_right_plates is False (the default):

Col. 0 - longitude of sampled ridge point
Col. 1 - latitude of sampled ridge point
Col. 2 - spreading velocity magnitude (in cm/yr)
Col. 3 - length of arc segment (in degrees) that current point is on

If output_obliquity_and_normal_and_left_right_plates is True:

Col. 0 - longitude of sampled ridge point
Col. 1 - latitude of sampled ridge point
Col. 2 - spreading velocity magnitude (in cm/yr)
Col. 3 - spreading obliquity in degrees (deviation from normal line in range 0 to 90 degrees)
Col. 4 - length of arc segment (in degrees) that current point is on
Col. 5 - azimuth of vector normal to the arc segment in degrees (clockwise starting at North, ie, 0 to 360 degrees)
Col. 6 - left plate ID
Col. 7 - right plate ID

Parameters:

time (float) – The reconstruction time (Ma) at which to query spreading rates.
tessellation_threshold_radians (float, default=0.001) – The threshold sampling distance along the plate boundaries (in radians).
ignore_warnings (bool, default=False) – Choose to ignore warnings from Plate Tectonic Tools’ gplately.ridge_spreading_rate() workflow (if use_ptt is True).
return_geodataframe (bool, default=False) – Choose to return data in a geopandas.GeoDataFrame.
use_ptt (bool, default=False) – If set to True then uses Plate Tectonic Tools’ gplately.ridge_spreading_rate() workflow to calculate ridge spreading rates (which uses the spreading stage rotation of the left/right plate IDs calculate spreading velocities). If set to False then uses plate divergence to calculate ridge spreading rates (which samples velocities of the two adjacent boundary plates at each sampled point to calculate spreading velocities). Plate divergence is the more general approach that works along all plate boundaries (not just mid-ocean ridges).
spreading_feature_types (pygplates.FeatureType or sequence of pygplates.FeatureType, default=pygplates.FeatureType.gpml_mid_ocean_ridge) – Only sample points along plate boundaries of the specified feature types. Default is to only sample mid-ocean ridges. You can explicitly specify None to sample all plate boundaries, but note that if use_ptt is True then only plate boundaries that are spreading feature types are sampled (since Plate Tectonic Tools only works on spreading plate boundaries, eg, mid-ocean ridges).
transform_segment_deviation_in_radians (float, default=<implementation-defined>) – How much a spreading direction can deviate from the segment normal before it’s considered a transform segment (in radians). The default value has been empirically determined to give the best results for typical models. If None then the full feature geometry is used (ie, it is not split into ridge and transform segments with the transform segments getting ignored).
include_network_boundaries (bool, default=False) – Whether to calculate spreading rate along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option. Since spreading features occur along plate boundaries this would only be an issue if an intra-plate network boundary was incorrectly labelled as spreading.
divergence_threshold_in_cm_per_yr (float, optional) – Only return sample points with an orthogonal (ie, in the spreading geometry’s normal direction) diverging velocity above this value (in cm/yr). For example, setting this to 0.0 would remove all converging sample points (leaving only diverging points). This value can be negative which means a small amount of convergence is allowed. If None then all (diverging and converging) sample points are returned. This is the default since spreading_feature_types is instead used (by default) to include only plate boundaries that are typically diverging (eg, mid-ocean ridges). However, setting spreading_feature_types to None (and transform_segment_deviation_in_radians to None) and explicitly specifying this parameter (eg, to 0.0) can be used to find points along all plate boundaries that are diverging. However, this parameter can only be specified if use_ptt is False.
output_obliquity_and_normal_and_left_right_plates (bool, default=False) – Whether to also return spreading obliquity, normal azimuth and left/right plates.
anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (anchor_plate_id attribute)..
velocity_delta_time (float, default=1.0) – Velocity delta time used in spreading velocity calculations (defaults to 1 Myr).

Returns:

ridge_data – The results for all tessellated points sampled along the mid-ocean ridges. The size of the returned list is equal to the number of tessellated points. Each tuple in the list corresponds to a tessellated point and has the following tuple items (depending on output_obliquity_and_normal_and_left_right_plates):

If output_obliquity_and_normal_and_left_right_plates is False (the default):

longitude of sampled point
latitude of sampled point
spreading velocity magnitude (in cm/yr)
length of arc segment (in degrees) that sampled point is on

If output_obliquity_and_normal_and_left_right_plates is True:

longitude of sampled point
latitude of sampled point
spreading velocity magnitude (in cm/yr)
spreading obliquity in degrees (deviation from normal line in range 0 to 90 degrees)
length of arc segment (in degrees) that sampled point is on
azimuth of vector normal to the arc segment in degrees (clockwise starting at North, ie, 0 to 360 degrees)
left plate ID
right plate ID

Return type:

a list of vertically-stacked tuples

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.
ValueError – If use_ptt is True and divergence_threshold_in_cm_per_yr is not None.

Notes

If use_ptt is False then each ridge segment is sampled at exactly uniform intervals along its length such that the sampled points have a uniform spacing (along each ridge segment polyline) that is equal to tessellation_threshold_radians. If use_ptt is True then each ridge segment is sampled at approximately uniform intervals along its length such that the sampled points have a uniform spacing (along each ridge segment polyline) that is less than or equal to tessellation_threshold_radians.

Examples

To sample points along mid-ocean ridges at 50Ma, but ignoring the transform segments (of the ridges):

ridge_data = plate_reconstruction.tessellate_mid_ocean_ridges(50)

To do the same, but instead of ignoring transform segments include both ridge and transform segments, but only where orthogonal diverging velocities are greater than 0.2 cm/yr:

ridge_data = plate_reconstruction.tessellate_mid_ocean_ridges(
    50,
    transform_segment_deviation_in_radians=None,
    divergence_threshold_in_cm_per_yr=0.2,
)

tessellate_subduction_zones(time, tessellation_threshold_radians=0.001, ignore_warnings=False, return_geodataframe=False, *, use_ptt=False, include_network_boundaries=False, convergence_threshold_in_cm_per_yr=None, anchor_plate_id=None, velocity_delta_time=1.0, output_distance_to_nearest_edge_of_trench=False, output_distance_to_start_edge_of_trench=False, output_convergence_velocity_components=False, output_trench_absolute_velocity_components=False, output_subducting_absolute_velocity=False, output_subducting_absolute_velocity_components=False, output_trench_normal=False)[source]

Samples points along subduction zone trenches and obtains subduction data at a particular geological time.

Resolves topologies at time and tessellates all resolved subducting features into points.

Returns a 10-column vertically-stacked tuple with the following data per sampled trench point:

Col. 0 - longitude of sampled trench point
Col. 1 - latitude of sampled trench point
Col. 2 - subducting convergence (relative to trench) velocity magnitude (in cm/yr)
Col. 3 - subducting convergence velocity obliquity angle in degrees (angle between trench normal vector and convergence velocity vector)
Col. 4 - trench absolute (relative to anchor plate) velocity magnitude (in cm/yr)
Col. 5 - trench absolute velocity obliquity angle in degrees (angle between trench normal vector and trench absolute velocity vector)
Col. 6 - length of arc segment (in degrees) that current point is on
Col. 7 - trench normal (in subduction direction, ie, towards overriding plate) azimuth angle (clockwise starting at North, ie, 0 to 360 degrees) at current point
Col. 8 - subducting plate ID
Col. 9 - trench plate ID

The optional output_* parameters can be used to append extra data to the output tuple of each sampled trench point. The order of any extra data is the same order in which the parameters are listed below.

Parameters:

time (float) – The reconstruction time (Ma) at which to query subduction convergence.
tessellation_threshold_radians (float, default=0.001) – The threshold sampling distance along the plate boundaries (in radians).
ignore_warnings (bool, default=False) – Choose to ignore warnings from gplately.subduction_convergence() (if use_ptt is True).
return_geodataframe (bool, default=False) – Choose to return data in a geopandas.GeoDataFrame.
use_ptt (bool, default=False) – If set to True then uses gplately.subduction_convergence() to calculate subduction convergence (which uses the subducting stage rotation of the subduction/trench plate IDs calculate subducting velocities). If set to False then uses plate convergence to calculate subduction convergence (which samples velocities of the two adjacent boundary plates at each sampled point to calculate subducting velocities). Both methods ignore plate boundaries that do not have a subduction polarity (feature property), which essentially means they only sample subduction zones.
include_network_boundaries (bool, default=False) – Whether to calculate subduction convergence along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option. Since subduction zones occur along plate boundaries this would only be an issue if an intra-plate network boundary was incorrectly labelled as subducting.
convergence_threshold_in_cm_per_yr (float, optional) – Only return sample points with an orthogonal (ie, in the subducting geometry’s normal direction) converging velocity above this value (in cm/yr). For example, setting this to 0.0 would remove all diverging sample points (leaving only converging points). This value can be negative which means a small amount of divergence is allowed. If None then all (converging and diverging) sample points are returned. This is the default. Note that this parameter can only be specified if use_ptt is False.
anchor_plate_id (int, optional) – Anchor plate ID. Defaults to the current anchor plate ID (PlateReconstruction.anchor_plate_id attribute).
velocity_delta_time (float, default=1.0) – Velocity delta time used in convergence velocity calculations (defaults to 1 Myr).
output_distance_to_nearest_edge_of_trench (bool, default=False) – Append the distance (in degrees) along the trench line to the nearest trench edge to each returned sample point. A trench edge is the farthermost location on the current trench feature that contributes to a plate boundary.
output_distance_to_start_edge_of_trench (bool, default=False) – Append the distance (in degrees) along the trench line from the start edge of the trench to each returned sample point. The start of the trench is along the clockwise direction around the overriding plate.
output_convergence_velocity_components (bool, default=False) – Append the convergence velocity orthogonal and parallel components (in cm/yr) to each returned sample point. Orthogonal is normal to trench (in direction of overriding plate when positive). Parallel is along trench (90 degrees clockwise from trench normal when positive).
output_trench_absolute_velocity_components (bool, default=False) – Append the trench absolute velocity orthogonal and parallel components (in cm/yr) to each returned sample point. Orthogonal is normal to trench (in direction of overriding plate when positive). Parallel is along trench (90 degrees clockwise from trench normal when positive).
output_subducting_absolute_velocity (bool, default=False) – Append the subducting plate absolute velocity magnitude (in cm/yr) and obliquity angle (in degrees) to each returned sample point.
output_subducting_absolute_velocity_components (bool, default=False) – Append the subducting plate absolute velocity orthogonal and parallel components (in cm/yr) to each returned sample point. Orthogonal is normal to trench (in direction of overriding plate when positive). Parallel is along trench (90 degrees clockwise from trench normal when positive).
output_trench_normal (bool, default=False) – Append the x, y and z components of the trench normal unit-length 3D vectors. These vectors are normal to the trench in the direction of subduction (towards overriding plate). These are global 3D vectors which differ from trench normal azimuth angles (ie, angles relative to North).

Returns:

subduction_data – The results for all tessellated points sampled along the trench. The size of the returned list is equal to the number of tessellated points. Each tuple in the list corresponds to a tessellated point and has the following tuple items:

Col. 0 - longitude of sampled trench point
Col. 1 - latitude of sampled trench point
Col. 2 - subducting convergence (relative to trench) velocity magnitude (in cm/yr)
Col. 3 - subducting convergence velocity obliquity angle in degrees (angle between trench normal vector and convergence velocity vector)
Col. 4 - trench absolute (relative to anchor plate) velocity magnitude (in cm/yr)
Col. 5 - trench absolute velocity obliquity angle in degrees (angle between trench normal vector and trench absolute velocity vector)
Col. 6 - length of arc segment (in degrees) that current point is on
Col. 7 - trench normal (in subduction direction, ie, towards overriding plate) azimuth angle (clockwise starting at North, ie, 0 to 360 degrees) at current point
Col. 8 - subducting plate ID
Col. 9 - trench plate ID

The optional output_* parameters can be used to append extra data to the tuple of each sampled trench point. The order of any extra data is the same order in which the parameters are listed in this function.

Return type:

a list of vertically-stacked tuples

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.
ValueError – If use_ptt is True and convergence_threshold_in_cm_per_yr is not None.

Notes

If use_ptt is False then each trench is sampled at exactly uniform intervals along its length such that the sampled points have a uniform spacing (along each trench polyline) that is equal to tessellation_threshold_radians. If use_ptt is True then each trench is sampled at approximately uniform intervals along its length such that the sampled points have a uniform spacing (along each trench polyline) that is less than or equal to tessellation_threshold_radians.

The trench normal (at each sampled trench point) always points towards the overriding plate. The obliquity angles are in the range (-180, 180). The range (0, 180) goes clockwise (when viewed from above the Earth) from the trench normal direction to the velocity vector. The range (0, -180) goes counter-clockwise. You can change the range (-180, 180) to the range (0, 360) by adding 360 to negative angles. The trench normal is perpendicular to the trench and pointing toward the overriding plate.

Note that the convergence velocity magnitude is negative if the plates are diverging (if convergence obliquity angle is greater than 90 or less than -90). And note that the trench absolute velocity magnitude is negative if the trench (subduction zone) is moving towards the overriding plate (if trench absolute obliquity angle is less than 90 and greater than -90) - note that this ignores the kinematics of the subducting plate. Similiarly for the subducting plate absolute velocity magnitude (if keyword argument output_subducting_absolute_velocity is True).

The trench plate ID at each sample point can differ from the overriding plate ID. This is because, even in a non-deforming model, the smaller plates (not modelled by topologies) can move differently than the larger topological plate. So the trench line has the plate IDs of the smaller plates.

Examples

To sample points along subduction zones at 50Ma:

subduction_data = plate_reconstruction.tessellate_subduction_zones(50)

To sample points along subduction zones at 50Ma, but only where there’s convergence:

subduction_data = plate_reconstruction.tessellate_subduction_zones(
    50, convergence_threshold_in_cm_per_yr=0.0
)

topological_snapshot(time, *, anchor_plate_id=None, include_topological_slab_boundaries=True)[source]

Create a snapshot of resolved topologies at the specified reconstruction time.

This returns a pygplates.TopologicalSnapshot from which you can extract resolved topologies, calculate velocities at point locations, calculate plate boundary statistics, etc.

Parameters:

time (float, int or pygplates.GeoTimeInstant) – The geological time at which to create the topological snapshot.
anchor_plate_id (int, optional) – The anchored plate id to use when resolving topologies. If not specified then uses the current anchor plate (PlateReconstruction.anchor_plate_id attribute).
include_topological_slab_boundaries (bool, default=True) – Include topological boundary features of type gpml:TopologicalSlabBoundary. By default all features passed into constructor __init__() are included in the snapshot. However setting this to False is useful when you’re only interested in plate boundaries.

Returns:

topological_snapshot – The topological snapshot at the specified time (and anchor plate).

Return type:

pygplates.TopologicalSnapshot

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.

topology_features: FeatureCollection | None: A pygplates.FeatureCollection object containing topological features like trenches, ridges and transforms.

total_continental_arc_length(time, continental_grid, trench_arc_distance, ignore_warnings=True, *, use_ptt=False, include_network_boundaries=False, convergence_threshold_in_cm_per_yr=None)[source]

Calculates the total length of all global continental arcs (km) at the specified geological time (Ma).

Resolves topologies at time and tessellates all resolved subducting features into points (see tessellate_subduction_zones()). The resolved points then are projected out by the trench_arc_distance (towards overriding plate) and their new locations are linearly interpolated onto the supplied continental_grid. If the projected trench points lie in the grid, they are considered continental arc points, and their arc segment lengths are appended to the total continental arc length for the specified time. The total length is scaled to kilometres using the geocentric radius (at each sampled point).

Parameters:

time (int) – The geological time at which to calculate total continental arc lengths.
continental_grid (Raster, array_like, or str) – The continental grid used to identify continental arc points. Must be convertible to Raster. For an array, a global extent is assumed [-180,180,-90,90]. For a filename, the extent is obtained from the file.
trench_arc_distance (float) – The trench-to-arc distance (in kilometres) to project sampled trench points out by in the direction of the overriding plate.
ignore_warnings (bool, default=True) – Choose whether to ignore warning messages from gplately.subduction_convergence() (if use_ptt is True) that alerts the user of subduction sub-segments that are ignored due to unidentified polarities and/or subducting plates.
use_ptt (bool, default=False) – If set to True then uses gplately.subduction_convergence() to sample subducting features and their subduction polarities. If set to False then uses plate convergence instead. Plate convergence is the more general approach that works along all plate boundaries (not just subduction zones).
include_network_boundaries (bool, default=False) – Whether to sample subducting features along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option. Since subduction zones occur along plate boundaries this would only be an issue if an intra-plate network boundary was incorrectly labelled as subducting.
convergence_threshold_in_cm_per_yr (float, optional) – Only sample points with an orthogonal (ie, in the subducting geometry’s normal direction) converging velocity above this value (in cm/yr). For example, setting this to 0.0 would remove all diverging sample points (leaving only converging points). This value can be negative which means a small amount of divergence is allowed. If None then all (converging and diverging) points are sampled. This is the default. Note that this parameter can only be specified if use_ptt is False.

Returns:

total_continental_arc_length_kms – The continental arc length (in km) at the specified time.

Return type:

float

Raises:

ValueError – If topology features have not been set in this gplately.PlateReconstruction object.
ValueError – If use_ptt is True and convergence_threshold_in_cm_per_yr is not None.

Examples

To calculate the total length of continental arcs at 50Ma:

total_continental_arc_length_kms = plate_reconstruction.total_continental_arc_length(50)

To calculate the total length of subduction zones adjacent to continents at 50Ma, but only where there’s actual convergence:

total_continental_arc_length_kms = (
    plate_reconstruction.total_continental_arc_length(
        50, convergence_threshold_in_cm_per_yr=0.0
    )
)

total_ridge_length(time, use_ptt=False, ignore_warnings=False, *, spreading_feature_types=[<pygplates.pygplates.FeatureType object>], transform_segment_deviation_in_radians=1.2217304763960306, include_network_boundaries=False, divergence_threshold_in_cm_per_yr=None)[source]

Calculates the total length of all resolved spreading features (e.g. mid-ocean ridges) at the specified geological time (Ma).

Resolves topologies at time and tessellates all resolved spreading features into points (see tessellate_mid_ocean_ridges()).

The transform segments of spreading features are ignored (unless transform_segment_deviation_in_radians is None).

Total length is calculated by sampling points along the resolved spreading features (e.g. mid-ocean ridges) and accumulating their lengths (see tessellate_mid_ocean_ridges()). Scales lengths to kilometres using the geocentric radius (at each sampled point).

Parameters:

time (int) – The geological time at which to calculate total mid-ocean ridge lengths.
use_ptt (bool, default=False) – If set to True then uses gplately.ridge_spreading_rate() to calculate total ridge length (which uses the spreading stage rotation of the left/right plate IDs to calculate spreading directions - see transform_segment_deviation_in_radians). If set to False then uses plate divergence to calculate total ridge length (which samples velocities of the two adjacent boundary plates at each sampled point to calculate spreading directions - see transform_segment_deviation_in_radians). Plate divergence is the more general approach that works along all plate boundaries (not just mid-ocean ridges).
ignore_warnings (bool, default=False) – Choose to ignore warnings from gplately.ridge_spreading_rate() (if use_ptt is True).
spreading_feature_types (pygplates.FeatureType or sequence of pygplates.FeatureType, default=pygplates.FeatureType.gpml_mid_ocean_ridge) – Only count lengths along plate boundaries of the specified feature types. Default is to only sample mid-ocean ridges. You can explicitly specify None to sample all plate boundaries, but note that if use_ptt is True then only plate boundaries that are spreading feature types are sampled (since Plate Tectonic Tools only works on spreading plate boundaries, eg, mid-ocean ridges).
transform_segment_deviation_in_radians (float, default=<implementation-defined>) – How much a spreading direction can deviate from the segment normal before it’s considered a transform segment (in radians). The default value has been empirically determined to give the best results for typical models. If None then the full feature geometry is used (ie, it is not split into ridge and transform segments with the transform segments getting ignored).
include_network_boundaries (bool, default=False) – Whether to count lengths along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option. Since spreading features occur along plate boundaries this would only be an issue if an intra-plate network boundary was incorrectly labelled as spreading.
divergence_threshold_in_cm_per_yr (float, optional) – Only count lengths associated with sample points that have an orthogonal (ie, in the spreading geometry’s normal direction) diverging velocity above this value (in cm/yr). For example, setting this to 0.0 would remove all converging sample points (leaving only diverging points). This value can be negative which means a small amount of convergence is allowed. If None then all (diverging and converging) sample points are counted. This is the default since spreading_feature_types is instead used (by default) to include only plate boundaries that are typically diverging (eg, mid-ocean ridges). However, setting spreading_feature_types to None (and transform_segment_deviation_in_radians to None) and explicitly specifying this parameter (eg, to 0.0) can be used to count points along all plate boundaries that are diverging. However, this parameter can only be specified if use_ptt is False.

Returns:

total_ridge_length_kms – The total length of global mid-ocean ridges (in kilometres) at the specified time.

Return type:

float

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.
ValueError – If use_ptt is True and divergence_threshold_in_cm_per_yr is not None.

Examples

To calculate the total length of mid-ocean ridges at 50Ma, but ignoring the transform segments (of the ridges):

total_ridge_length_kms = plate_reconstruction.total_ridge_length(50)

To do the same, but instead of ignoring transform segments include both ridge and transform segments, but only where orthogonal diverging velocities are greater than 0.2 cm/yr:

total_ridge_length_kms = plate_reconstruction.total_ridge_length(50,
        transform_segment_deviation_in_radians=None,
        divergence_threshold_in_cm_per_yr=0.2)

total_subduction_zone_length(time, use_ptt=False, ignore_warnings=False, *, include_network_boundaries=False, convergence_threshold_in_cm_per_yr=None)[source]

Calculates the total length of all subduction zones (km) at the specified geological time (Ma).

Resolves topologies at time and tessellates all resolved subducting features into points (see tessellate_subduction_zones()).

Total length is calculated by sampling points along the resolved subducting features (e.g. subduction zones) and accumulating their lengths (see tessellate_subduction_zones()). Scales lengths to kilometres using the geocentric radius (at each sampled point).

Parameters:

time (int) – The geological time at which to calculate total subduction zone lengths.
use_ptt (bool, default=False) – If set to True then uses gplately.subduction_convergence() to calculate total subduction zone length. If set to False then uses plate convergence instead. Plate convergence is the more general approach that works along all plate boundaries (not just subduction zones).
ignore_warnings (bool, default=False) – Choose to ignore warnings from gplately.subduction_convergence() (if use_ptt is True).
include_network_boundaries (bool, default=False) – Whether to count lengths along network boundaries that are not also plate boundaries (defaults to False). If a deforming network shares a boundary with a plate then it’ll get included regardless of this option. Since subduction zones occur along plate boundaries this would only be an issue if an intra-plate network boundary was incorrectly labelled as subducting.
convergence_threshold_in_cm_per_yr (float, optional) – Only count lengths associated with sample points that have an orthogonal (ie, in the subducting geometry’s normal direction) converging velocity above this value (in cm/yr). For example, setting this to 0.0 would remove all diverging sample points (leaving only converging points). This value can be negative which means a small amount of divergence is allowed. If None then all (converging and diverging) sample points are counted. This is the default. Note that this parameter can only be specified if use_ptt is False.

Returns:

total_subduction_zone_length_kms – The total subduction zone length (in km) at the specified time.

Return type:

float

Raises:

ValueError – If topology features have not been set in this PlateReconstruction object.
ValueError – If use_ptt is True and convergence_threshold_in_cm_per_yr is not None.

Examples

To calculate the total length of subduction zones at 50Ma:

total_subduction_zone_length_kms = plate_reconstruction.total_subduction_zone_length(50)

To calculate the total length of subduction zones at 50Ma, but only where there’s actual convergence:

total_subduction_zone_length_kms = plate_reconstruction.total_subduction_zone_length(50,
        convergence_threshold_in_cm_per_yr=0.0)