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, orFeature
, or sequence ofFeature
, 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
ortuple
) 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
orFeatureCollection
or string or sequence ofFeatureCollection
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 filenamesanchor_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 todefault-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 newTopologicalModel
. However this should only be done if necessary since eachTopologicalModel
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.
Return the anchor plate ID (see
constructor
).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
ofget_rotation_model()
.
- get_rotation_model()
Return the rotation model used internally.
- Return type
Note
The
default anchor plate ID
of the returned rotation model may be different to that of the rotation model passed into theconstructor
if an anchor plate ID was specified in theconstructor
.
- 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
, orPointOnSphere
, or sequence of points (where a point can bePointOnSphere
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 oftime_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 eachScalarType
to a sequence of float, or a sequence of (ScalarType
, sequence of float) tuples) – optional mapping of scalar types to sequences of initial scalar valuesdeactivate_points (
ReconstructedGeometryTimeSpan.DeactivatePoints
or None) – Specify how points are deactivated when reconstructed forward and/or backward in time, or specifyNone
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 fromReconstructedGeometryTimeSpan.DeactivatePoints
or use the provided classReconstructedGeometryTimeSpan.DefaultDeactivatePoints
. Defaults to a default-constructedReconstructedGeometryTimeSpan.DefaultDeactivatePoints
.
- Return type
- Raises
ValueError if initial_time is
distant past
ordistant 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
- Raises
ValueError if reconstruction_time is not an integral value