pygplates.TopologicalModel

class pygplates.TopologicalModel

Bases: Boost.Python.instance

A history of topologies over geological time.

New in version 0.30.

__init__(topological_features, rotation_model[, anchor_plate_id][, default_resolve_topology_parameters])

Create from topological features, a rotation model and a time span.

Parameters

topological_features (FeatureCollection, or string, or Feature, or sequence of Feature, or sequence of any combination of those four types) – The topological boundary and/or network features and the topological section features they reference (regular and topological lines) 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. Note: Each sequence entry can optionally be a 2-tuple (entry, ResolveTopologyParameters) to override default_resolve_topology_parameters for that entry.
rotation_model (RotationModel or FeatureCollection or string or sequence of FeatureCollection instances and/or strings) – A rotation model or a rotation feature collection or a rotation filename or a sequence of rotation feature collections and/or rotation filenames
anchor_plate_id (int) – The anchored plate id used for all reconstructions (resolving topologies, and reconstructing regular features and geometries). Defaults to the default anchor plate of rotation_model.
default_resolve_topology_parameters (ResolveTopologyParameters) – Default parameters used to resolve topologies. Note that these can optionally be overridden in topological_features. Defaults to default-constructed ResolveTopologyParameters).

Load a topological model (and its associated rotation model):

rotation_model = pygplates.RotationModel('rotations.rot')
topological_model = pygplates.TopologicalModel('topologies.gpml', rotation_model)

…or alternatively just:

topological_model = pygplates.TopologicalModel('topologies.gpml', 'rotations.rot')

Note

All reconstructions (including resolving topologies and reconstructing regular features and geometries) use anchor_plate_id. So if you need to use a different anchor plate ID then you’ll need to create a new TopologicalModel. However this should only be done if necessary since each TopologicalModel created can consume a reasonable amount of CPU and memory (since it caches resolved topologies and reconstructed geometries over geological time).

Changed in version 0.31: Added default_resolve_topology_parameters argument.

Methods

`__init__`(topological_features, ...)	Create from topological features, a rotation model and a time span.
`get_anchor_plate_id`()	Return the anchor plate ID (see `constructor`).
`get_rotation_model`()	Return the rotation model used internally.
`reconstruct_geometry`(geometry, initial_time, ...)	Reconstruct a geometry (and optional scalars) over a time span.
`topological_snapshot`(reconstruction_time)	Returns a snapshot of resolved topologies at the requested reconstruction time.

get_anchor_plate_id()

Return the anchor plate ID (see constructor).

Return type: int

Note

This is the same as the default anchor plate ID of get_rotation_model().

get_rotation_model()

Return the rotation model used internally.

Return type: RotationModel

Note

The default anchor plate ID of the returned rotation model may be different to that of the rotation model passed into the constructor if an anchor plate ID was specified in the constructor.

reconstruct_geometry(geometry, initial_time[, oldest_time][, youngest_time=0][, time_increment=1][, reconstruction_plate_id][, initial_scalars][, deactivate_points=ReconstructedGeometryTimeSpan.DefaultDeactivatePoints()])

Reconstruct a geometry (and optional scalars) over a time span.

Parameters

geometry (MultiPointOnSphere, or PointOnSphere, or sequence of points (where a point can be PointOnSphere or (x,y,z) tuple or (latitude,longitude) tuple in degrees)) – The geometry to reconstruct (using topologies). Currently limited to a multipoint, or a point or sequence of points. Polylines and polygons to be introduced in future.
initial_time (float or GeoTimeInstant) – The time that reconstruction by topologies starts at.
oldest_time (float or GeoTimeInstant) – Oldest time in the history of topologies (must have an integral value). Defaults to initial_time.
youngest_time (float or GeoTimeInstant.) – Youngest time in the history of topologies (must have an integral value). Defaults to present day.
time_increment (float) – Time step in the history of topologies (must have an integral value, and oldest_time - youngest_time must be an integer multiple of time_increment). Defaults to 1My.
reconstruction_plate_id (int) – Used to rotate geometry (assumed to be in its present day position) to its initial position at time initial_time. Defaults to the anchored plate (specified in constructor).
initial_scalars (dict mapping each ScalarType to a sequence of float, or a sequence of (ScalarType, sequence of float) tuples) – optional mapping of scalar types to sequences of initial scalar values
deactivate_points (ReconstructedGeometryTimeSpan.DeactivatePoints or None) – Specify how points are deactivated when reconstructed forward and/or backward in time, or specify None to disable deactivation of points (which is useful if you know your points are on continental crust where they’re typically always active, as opposed to oceanic crust that is produced at mid-ocean ridges and consumed at subduction zones). Note that you can use your own class derived from ReconstructedGeometryTimeSpan.DeactivatePoints or use the provided class ReconstructedGeometryTimeSpan.DefaultDeactivatePoints. Defaults to a default-constructed ReconstructedGeometryTimeSpan.DefaultDeactivatePoints.

Return type

ReconstructedGeometryTimeSpan

Raises

ValueError if initial_time is distant past or distant future

Raises

ValueError if initial_scalars is specified but: is empty, or each scalar type is not mapped to the same number of scalar values, or the number of scalars is not equal to the number of points in geometry

Raises

ValueError if oldest or youngest time is distant-past (float('inf')) or distant-future (float('-inf')), or if oldest time is later than (or same as) youngest time, or if time increment is not positive, or if oldest to youngest time period is not an integer multiple of the time increment, or if oldest time or youngest time or time increment are not integral values.

The reconstruction_plate_id is used for any rigid reconstructions of geometry. This includes the initial rigid rotation of geometry (assumed to be in its present day position) to its initial position at time initial_time. If a reconstruction plate ID is not specified, then geometry is assumed to already be at its initial position at time initial_time. In addition, the reconstruction plate ID is also used when incrementally reconstructing from the initial time to other times for any geometry points that fail to intersect topologies (dynamic plates and deforming networks). This can happen either due to small gaps/cracks in a global topological model or when using a topological model that does not cover the entire globe. And finally, the reconstruction plate ID is also used when ReconstructedGeometryTimeSpan.get_geometry_points() is called with a reconstruction_time that is outside the time range [oldest_time, youngest_time], in which case it is used to rigidly reconstruct from reconstruction_time to oldest_time or from youngest_time to reconstruction_time (but typically you would specify a time range that includes all desired reconstruction times).

To reconstruct points in a geometry forward in time from 100Ma to present day in increments of 1 Myr using default deactivation (in this case subduction of oceanic points), noting that the geometry is specified at its initial position at 100Ma:

topological_model.reconstruct_geometry(geometry, 100)

To do the same but with no deactivation (in this case continental points):

topological_model.reconstruct_geometry(geometry, 100, deactivate_points=None)

To reconstruct points in a geometry backward in time from present day to 100Ma in increments of 1 Myr using default deactivation (in this case oceanic points produced at mid-ocean ridges disappear for times prior to their creation), noting that the geometry is specified at its initial position at present day:

topological_model.reconstruct_geometry(geometry, 0, oldest_time=100)

To do the same but with no deactivation (in this case continental points):

topological_model.reconstruct_geometry(geometry, 0, oldest_time=100, deactivate_points=None)

Changed in version 0.31: Added deactivate_points argument.

topological_snapshot(reconstruction_time)

Returns a snapshot of resolved topologies at the requested reconstruction time.

Parameters: reconstruction_time (float or GeoTimeInstant) – the geological time of the snapshot (must have an integral value)
Return type: TopologicalSnapshot
Raises: ValueError if reconstruction_time is not an integral value