pygplates.NetRotationModel

class pygplates.NetRotationModel

Bases: instance

Net rotation of topological plates and deforming networks.

A NetRotationModel can also be pickled.

Added in version 0.43.

__init__(topological_model[, velocity_delta_time=1.0][, velocity_delta_time_type=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t][, point_distribution])

Net rotation snapshots will be calculated from the specified topological model, and using the requested parameters.

Parameters:

topological_model (TopologicalModel) – The topological model to calculate net rotations with.
velocity_delta_time (float) – The time delta used to calculate velocities for net rotation (defaults to 1 Myr).
velocity_delta_time_type (VelocityDeltaTimeType.t_plus_delta_t_to_t, VelocityDeltaTimeType.t_to_t_minus_delta_t or VelocityDeltaTimeType.t_plus_minus_half_delta_t) – How the two velocity times are calculated relative to the reconstruction time. This includes [t+dt, t], [t, t-dt] and [t+dt/2, t-dt/2]. Defaults to [t+dt, t].
point_distribution (int, or sequence of tuple (point, float) where point is a PointOnSphere or LatLonPoint or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – Can be an integer N representing the number of uniformly spaced latitude-longitude grid points sampled along each meridian (ie, an N x 2N grid). Or can be a sequence of (point, sample_area) tuples where point is a point that contributes to net rotation and sample_area is the surface area around the point in steradians (square radians). If nothing specified then defaults to a 180 x 360 uniformly spaced latitude-longitude points.

Raises:

ValueError if velocity_delta_time is negative or zero.

The total net rotation of all resolved topologies in a snapshot (NetRotationModel.net_rotation_snapshot()) is:

\[\boldsymbol \omega_{net} = \frac{3}{8\pi} \sum_i \int \boldsymbol r \times (\boldsymbol \omega_i(\boldsymbol r) \times \boldsymbol r) \, dS_i\]

…where \(\sum_i\) is the summation over all resolved topologies, and \(\int ... dS_i\) is integration over the surface area of resolved topology \(i\), and \(\boldsymbol \omega_i(\boldsymbol r)\) is the rotation rate vector for resolved topology \(i\) at location \(\boldsymbol r\). For a rigid plate this is just a constant \(\boldsymbol \omega_i(\boldsymbol r) = \boldsymbol \omega_i\), but for a deforming network this varies spatially across the network (hence the dependency on \(\boldsymbol r\)). Note that if a deforming network overlaps a rigid plate then only the deforming network contributes to the total net rotation (in the overlap region).

The surface integrals are approximated by sampling at points distributed across the surface of the globe. So it’s helpful to think of a single integral over the entire globe (rather than a separate integral for each topology) and then approximate that as a summation over points:

\[\begin{split}\boldsymbol \omega_{net} &= \frac{3}{8\pi} \int \boldsymbol r \times (\boldsymbol \omega(\boldsymbol r) \times \boldsymbol r) \, dS\\ &\approx \frac{3}{8\pi} \sum_p (\boldsymbol r_p \times (\boldsymbol \omega(\boldsymbol r_p) \times \boldsymbol r_p)) \, dS_p\end{split}\]

…where the summation is over all locations \(\boldsymbol r_p\) in the point distribution \(p\), and \(dS_p\) is the surface area contributed at location \(\boldsymbol r_p\) (where \(\sum_p dS_p \approx 4\pi\)), and \(\boldsymbol \omega(\boldsymbol r_p)\) is the rotation rate vector contributed by whichever resolved topology happens to intersect location \(\boldsymbol r_p\) (with preference given to deforming networks when they overlap rigid plates).

The point distribution used to calculate net rotation can be controlled with the point_distribution parameter. If point_distribution is an integer N then a uniform latitude-longitude grid of N x 2N points is used. Otherwise point_distribution can be a sequence of (point, sample area) representing an arbitrary user-specified distribution of points (and their sample areas). For example, if you have a distribution that is uniformly spaced on the surface of the sphere then the sample area will be the same for each point (ie, \(4\pi\) steradians divided by the total number of points). If nothing is specified for point_distribution then a uniform latitude-longitude grid of 180 x 360 points is used.

To create a net rotation snapshot at 0Ma calculated from a net rotation model with a velocity delta from 1Ma (to 0Ma):

net_rotation_model = pygplates.NetRotationModel(
    topological_model, 1.0, pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t)
net_rotation_snapshot = net_rotation_model.net_rotation_snapshot(0)

…which is equivalent to the following code that explicitly specifies a point distribution:

point_distribution = []
num_samples_along_meridian = 180
delta_in_degrees = 180.0 / num_samples_along_meridian
delta_in_radians = math.radians(delta_in_degrees)
for lat_index in range(num_samples_along_meridian):
    lat = -90.0 + (lat_index + 0.5) * delta_in_degrees
    # The cosine is because points near the North/South poles are closer together (latitude parallel small circle radius).
    sample_area_radians = math.cos(math.radians(lat)) * delta_in_radians * delta_in_radians
    for lon_index in range(2*num_samples_along_meridian):
        lon = -180.0 + (lon_index + 0.5) * delta_in_degrees
        point_distribution.append(((lat, lon), sample_area_radians))

net_rotation_model = pygplates.NetRotationModel(
    topological_model, 1.0, pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t, point_distribution)
net_rotation_snapshot = net_rotation_model.net_rotation_snapshot(0)

Note

The anchor plate is that of the specified topological model (see TopologicalModel.get_anchor_plate_id()).

Methods

`__init__`(topological_model, ...)	Net rotation snapshots will be calculated from the specified topological model, and using the requested parameters.
`get_topological_model`()	Return the topological model used internally.
`net_rotation_snapshot`(reconstruction_time)	Returns a snapshot of net rotation at the requested reconstruction time.

get_topological_model()

Return the topological model used internally.

Return type:: TopologicalModel

net_rotation_snapshot(reconstruction_time)

Returns a snapshot of net rotation at the requested reconstruction time.

Parameters:: reconstruction_time (float or GeoTimeInstant) – the geological time of the snapshot
Return type:: NetRotationSnapshot
Raises:: ValueError if reconstruction_time is distant-past (float('inf')) or distant-future (float('-inf')).