pygplates.RotationModel

class pygplates.RotationModel

Bases: instance

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

See also

Plate reconstruction hierarchy in the Primer documentation.

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 the reconstruction_tree_cache_size parameter passed to __init__(). This cache size parameter 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.

A RotationModel can also be pickled.

Changed in version 0.42: Added pickle support.

__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/os.PathLike, 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. Defaults to 150.
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 FeatureCollection 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 0.25: Added extend_total_reconstruction_poles_to_distant_past argument and removed clone_rotation_features argument.

Changed in version 0.26: Added default_anchor_plate_id argument.

Changed in version 0.44: Filenames can be os.PathLike (such as pathlib.Path) in addition to strings.

__init__(rotation_model, [reconstruction_tree_cache_size=2], [default_anchor_plate_id])

Use an existing rotation model but adapt it with a potentially different cache size and/or default anchor plate ID.

param rotation_model:: an existing rotation model
type rotation_model:: RotationModel
param reconstruction_tree_cache_size:: Number of reconstruction trees to cache internally. Defaults to 2 - this is much lower than the usual default cache size since the existing rotation model likely already has a sizeable cache anyway - and if you are leaving this at its default value then you are presumably only interested in changing the default anchor plate ID (not increasing the cache size).
type reconstruction_tree_cache_size:: int
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 the default anchor plate of rotation_model.
type default_anchor_plate_id:: int

This is useful if you want to use an existing rotation model but with a larger cache size or a different default anchor plate ID:

rotation_model = pygplates.RotationModel(rotation_files)
...
rotation_model_anchor_1 = pygplates.RotationModel(rotation_model, default_anchor_plate_id=1)

Note

The above example just changes the default anchor plate ID. You can still explicitly specify any anchor plate ID to get_rotation(). So the following two calls return the same results:

rotation_model.get_rotation(100.0, 802, anchor_plate_id=1)
rotation_model_anchor_1.get_rotation(100.0, 802)

Added in version 0.29.

__init__(rotation_model)

Simply return 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 the existing 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_default_anchor_plate_id`()	Return the default anchor plate ID (see `constructor`).
`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_default_anchor_plate_id()

Return the default anchor plate ID (see constructor).

Return type:: int

Added in version 0.29.

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 0.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:

ReconstructionTree.get_equivalent_total_rotation() - see Equivalent total rotation for rotation math derivation
ReconstructionTree.get_relative_total_rotation() - see Relative total rotation for rotation math derivation
ReconstructionTree.get_equivalent_stage_rotation() - see Equivalent stage rotation for rotation math derivation
ReconstructionTree.get_relative_stage_rotation() - see Relative stage rotation for rotation math derivation

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 0.26: anchor_plate_id no longer defaults to zero (see default_anchor_plate_id)

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