gplately.subduction_convergence

gplately.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 pygplates.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:

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

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:

list of tuples

Note

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.