pygplates.RotationModel

class pygplates.RotationModel

Bases: Boost.Python.instance

Query a finite rotation of a moving plate relative to any other plate, optionally between two instants in geological time.

See Plate reconstruction hierarchy.

This class provides an easy way to query rotations in any of the four combinations of total/stage and equivalent/relative rotations using get_rotation(). Reconstruction trees can also be created at any instant of geological time and these are cached internally depending on a user-specified cache size parameter pass to __init__(). The reconstruction_tree_cache_size parameter of those methods controls the size of an internal least-recently-used cache of reconstruction trees (evicts least recently requested reconstruction tree when a new reconstruction time is requested that does not currently exist in the cache). This enables reconstruction trees associated with different reconstruction times to be re-used instead of re-creating them, provided they have not been evicted from the cache. This benefit also applies when querying rotations with get_rotation() since it, in turn, requests reconstruction trees.

__init__(...)

A RotationModel object can be constructed in more than one way…

__init__(rotation_features, [reconstruction_tree_cache_size=150], [extend_total_reconstruction_poles_to_distant_past=False],[default_anchor_plate_id=0])

Create from rotation feature collection(s) and/or rotation filename(s).

param rotation_features:
 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
type rotation_features:
 FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types
param reconstruction_tree_cache_size:
 number of reconstruction trees to cache internally
type reconstruction_tree_cache_size:
 int
param extend_total_reconstruction_poles_to_distant_past:
 extend each moving plate sequence back infinitely far into the distant past such that reconstructed geometries will not snap back to their present day positions when the reconstruction time is older than the oldest times specified in the rotation features (defaults to False)
type extend_total_reconstruction_poles_to_distant_past:
 bool
param default_anchor_plate_id:
 The default anchored plate id to use when get_rotation() and get_reconstruction_tree() are called without specifying their anchor_plate_id parameter. Defaults to 0.
type default_anchor_plate_id:
 int
raises:OpenFileForReadingError if any file is not readable (when filenames specified)
raises:FileFormatNotSupportedError if any file format (identified by the filename extensions) does not support reading (when filenames specified)

Note that rotation_features can be a rotation FeatureCollection or a rotation filename or a rotation Feature or a sequence of rotation features, or a sequence (eg, list or tuple) of any combination of those four types.

If any rotation filenames are specified then this method uses FeatureCollectionFileFormatRegistry internally to read the rotation files.

Load a rotation file and some rotation adjustments (as a collection of rotation features) into a rotation model:

rotation_adjustments = pygplates.FeatureCollection()
...
rotation_model = pygplates.RotationModel(['rotations.rot', rotation_adjustments])

Changed in version 25: Added extend_total_reconstruction_poles_to_distant_past argument and removed clone_rotation_features argument.

Changed in version 26: Added default_anchor_plate_id argument.

__init__(rotation_model)

Create from an existing rotation model as a convenience.

param rotation_model:
 an existing rotation model
type rotation_model:
 RotationModel

This is useful when defining your own function that accepts rotation features or a rotation model. It avoids the hassle of having to explicitly test for each source type:

def my_function(rotation_features_or_model):
    # The appropriate constructor (__init__) overload is chosen depending on argument type.
    rotation_model = pygplates.RotationModel(rotation_features_or_model)
    ...

Note

This constructor just returns a reference to rotation_model because a RotationModel object is immutable (contains no operations or methods that modify its state) and hence a deep copy of rotation_model is not needed.

Methods

__init__(…) A RotationModel object can be constructed in more than one way…
get_reconstruction_tree(reconstruction_time, …) Return the reconstruction tree associated with the specified instant of geological time and anchored plate id.
get_rotation(to_time, moving_plate_id, …) Return the finite rotation that rotates from the fixed_plate_id plate to the moving_plate_id plate and from the time from_time to the time to_time.
get_reconstruction_tree(reconstruction_time[, anchor_plate_id])

Return the reconstruction tree associated with the specified instant of geological time and anchored plate id.

Parameters:
  • reconstruction_time (float or GeoTimeInstant) – time at which to create a reconstruction tree (in Ma)
  • anchor_plate_id (int) – The id of the anchored plate that equivalent rotations are calculated with respect to. If not specified then the default anchor plate id (specified in constructor) is used.
Return type:

ReconstructionTree
Raises:

InterpolationError if reconstruction_time is distant past or distant future

If the reconstruction tree for the specified reconstruction time and anchored plate id is currently in the internal cache then it is returned, otherwise a new reconstruction tree is created and stored in the cache (after evicting the reconstruction tree associated with the least recently requested reconstruction time and anchored plate id if necessary).

Changed in version 26: anchor_plate_id no longer defaults to zero (see default_anchor_plate_id in constructor).

get_rotation(to_time, moving_plate_id[, from_time][, fixed_plate_id][, anchor_plate_id][, use_identity_for_missing_plate_ids=True])

Return the finite rotation that rotates from the fixed_plate_id plate to the moving_plate_id plate and from the time from_time to the time to_time.

Parameters:
  • to_time (float or GeoTimeInstant) – time at which the moving plate is being rotated to (in Ma)
  • moving_plate_id (int) – the plate id of the moving plate
  • from_time (float or GeoTimeInstant) – time at which the moving plate is being rotated from (in Ma)
  • fixed_plate_id (int) – the plate id of the fixed plate (defaults to anchor_plate_id if not specified)
  • anchor_plate_id (int) – The id of the anchored plate. If not specified then the default anchor plate id (specified in constructor) is used.
  • use_identity_for_missing_plate_ids (bool) – whether to return an identity rotation or return None for missing plate ids (default is to use identity rotation)
Return type:

FiniteRotation, or None (if use_identity_for_missing_plate_ids is False)
Raises:

InterpolationError if any time value is distant past or distant future

This method conveniently handles all four combinations of total/stage and equivalent/relative rotations normally handled by:

If fixed_plate_id is not specified then it defaults to anchor_plate_id (which itself defaults to the default anchor plate id specified in constructor). Normally it is sufficient to specify fixed_plate_id (for a relative rotation) and leave anchor_plate_id as its default. However if there is no plate circuit path from the default anchor plate to either moving_plate_id or fixed_plate_id, but there is a path from fixed_plate_id to moving_plate_id, then the correct result will require setting anchor_plate_id to fixed_plate_id. See Plate reconstruction hierarchy for an overview of plate circuit paths.

If there is no plate circuit path from moving_plate_id (and optionally fixed_plate_id) to the anchor plate (at times to_time and optionally from_time) then an identity rotation is returned if use_identity_for_missing_plate_ids is True, otherwise None is returned. See Plate reconstruction hierarchy for details on how a plate id can go missing and how to work around it.

This method essentially does the following:

def get_rotation(rotation_model, to_time, moving_plate_id, from_time=None, fixed_plate_id=None, anchor_plate_id=None):
    
    if from_time is None:
        if fixed_plate_id is None:
            return rotation_model.get_reconstruction_tree(to_time, anchor_plate_id).get_equivalent_total_rotation(moving_plate_id)
        
        return rotation_model.get_reconstruction_tree(to_time, anchor_plate_id).get_relative_total_rotation(moving_plate_id, fixed_plate_id)
    
    if fixed_plate_id is None:
        return pygplates.ReconstructionTree.get_equivalent_stage_rotation(
            rotation_model.get_reconstruction_tree(from_time, anchor_plate_id),
            rotation_model.get_reconstruction_tree(to_time, anchor_plate_id),
            moving_plate_id)
    
    return pygplates.ReconstructionTree.get_relative_stage_rotation(
        rotation_model.get_reconstruction_tree(from_time, anchor_plate_id),
        rotation_model.get_reconstruction_tree(to_time, anchor_plate_id),
        moving_plate_id,
        fixed_plate_id)

Note

Explicitly setting from_time to zero can give a different result than not specifying from_time at all if the moving plate (or fixed plate) has a non-zero finite rotation at present day (relative to the anchor plate). However all present-day finite rotations should ideally be zero (identity), so typically there should not be a difference.

Changed in version 26: anchor_plate_id no longer defaults to zero (see default_anchor_plate_id

Changed in version 27: from_time no longer defaults to zero, and no longer assumes present day rotations are identity (zero) rotations