Module `gplately.ptt.subduction_convergence`

Find the convergence rate of trenches (subduction zones).

Functions

def convert_old_convergence_output(old_convergence_data, **kwargs)

Converts the output of the old "convergence.py" script to the current output format of the subduction_convergence() function.

This function's purpose is to help transition workflows that use "convergence.py" to use this script instead. At the time this function was implemented, both scripts have essentially the same output with just minor format differences (as seen below). However in the future this script will generate additional outputs (such as deformation strain rates) that the old script will not.

Parameters

old_convergence_data : list of tuples: The subduction convergence data output from the old "convergence.py" script. Each tuple in the list contains the data for a single sample point on a trench line.
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

list of tuples

The converted results for all input points from the old "convergence.py" script. The size of the returned list is equal to the number of input points. Each tuple in the list corresponds to a point and has the following tuple items:

longitude of sample point
latitude of sample point
subducting convergence (relative to trench) velocity magnitude (in cm/yr)
subducting convergence velocity obliquity angle (angle between trench normal vector and convergence velocity vector)
trench absolute (relative to anchor plate) velocity magnitude (in cm/yr)
trench absolute velocity obliquity angle (angle between trench normal vector and trench absolute velocity vector)
length of arc segment (in degrees) that current point is on
trench normal azimuth angle (clockwise starting at North, ie, 0 to 360 degrees) at current point
subducting plate ID
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.

Notes

The optional 'output_*' parameters are the same as that of the subduction_convergence() function , which is used to append extra data to the output of each sample point.

def create_coverage_feature_from_convergence_data(subduction_convergence_data, time, **kwargs)

Create a feature with a coverage geometry containing the calculated convergence and absolute velocity data.

Parameters

subduction_convergence_data : list of tuples: The subduction convergence data calculated by :func:subduction_convergence(). Each tuple in the list contains the calculated data for a single sample point on a trench line.
time : float: The reconstruction time associated with the subduction convergence data.
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

pygplates.Feature: The feature with a coverage geometry containing the calculated convergence and absolute velocity data.

Notes

The optional 'output_*' parameters are the same as that of the subduction_convergence() function , which is used to append extra data to the output of each sample point. Here it is used to interpret the same output data and create scalar coverages.

def find_subducting_plate(subduction_shared_sub_segment, include_slab_topologies=False)

Determine the subducting plate of the subduction shared sub-segment.

def subduction_convergence(rotation_features_or_model, topology_features, threshold_sampling_distance_radians, time, velocity_delta_time=1.0, anchor_plate_id=None, include_slab_topologies=False, include_network_boundaries=False, **kwargs)

Find the convergence and absolute velocities sampled along trenches (subduction zones) at a particular geological time.

Each sampled point along trench returns the following information:

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

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

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 absolute velocity magnitude is negative if the trench (subduction zone) is moving towards the overriding plate (if 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).

Parameters

rotation_features_or_model : pygplates.RotationModel, or any combination of str, pygplates.FeatureCollection, pygplates.Feature: The rotation model can be specified as a RotationModel. Or it can be specified as a rotation feature collection, or rotation filename, or rotation feature, or sequence of rotation features, or a sequence (eg, list or tuple) of any combination of those four types.
topology_features : any combination of str, pygplates.FeatureCollection, pygplates.Feature: The topological boundary and network features and the topological section features they reference (regular and topological lines). Can be specified 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.
threshold_sampling_distance_radians : float: Threshold sampling distance along trench (in radians).
time : float: The reconstruction time at which to query subduction convergence.
velocity_delta_time : float, optional: The delta time interval used for velocity calculations. Defaults to 1My.
anchor_plate_id : int, optional: Anchor plate ID for reconstruction. If not specified then uses the default anchor plate of rotation_model if it's a pygplates.RotationModel (otherwise uses zero).
include_slab_topologies : bool, default False: Include slab topologies (gpml:TopologicalSlabBoundary) in analysis.
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.
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

list of tuples

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

longitude of sample point
latitude of sample point
subducting convergence (relative to trench) velocity magnitude (in cm/yr)
subducting convergence velocity obliquity angle (angle between trench normal vector and convergence velocity vector)
trench absolute (relative to anchor plate) velocity magnitude (in cm/yr)
trench absolute velocity obliquity angle (angle between trench normal vector and trench absolute velocity vector)
length of arc segment (in degrees) that current point is on
trench normal azimuth angle (clockwise starting at North, ie, 0 to 360 degrees) at current point
subducting plate ID
trench plate ID

Notes

Each point in the output is the midpoint of a great circle arc between two adjacent points in the trench polyline. The trench normal vector used in the obliquity calculations is perpendicular to the great circle arc of each point (arc midpoint) and pointing towards the overriding plate (rather than away from it).

Each trench is sampled at approximately uniform intervals along its length (specified via a threshold sampling distance). The sampling along the entire length of a trench is not exactly uniform. Each segment along a trench is sampled such that the samples have a uniform spacing that is less than or equal to the threshold sampling distance. However each segment in a trench might have a slightly different spacing distance (since segment lengths are not integer multiples of the threshold sampling distance).

The trench normal (at each arc segment mid-point) always points towards the overriding plate.

def subduction_convergence_over_time(output_filename_prefix, output_filename_extension, rotation_filenames, topology_filenames, threshold_sampling_distance_radians, time_young, time_old, time_increment, velocity_delta_time=1.0, anchor_plate_id=None, output_gpml_filename=None, include_slab_topologies=False, **kwargs)

calculate subduction convergence over time