pygplates.TopologicalModel

class pygplates.TopologicalModel

Bases: instance

A history of topologies over geological time.

See also

Topological model in the Primer documentation.

A TopologicalModel can also be pickled.

Added in version 0.30.

Changed in version 0.42: Added pickle support.

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

Create from topological features and a rotation model.

Parameters:

topological_features (FeatureCollection, or string/os.PathLike, 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 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/os.PathLike, or Feature, or sequence of Feature, or sequence of any combination of those four types) – A rotation model. Or a rotation feature collection, or a rotation filename, or a rotation feature, or a sequence of rotation features, or a sequence of any combination of those four types.
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 (or zero if rotation_model is not a RotationModel).
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).
topological_snapshot_cache_size (int) – Number of topological snapshots to cache internally. Defaults to unlimited.

See also

Topological model in the Primer documentation.

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).

Note

The topological_snapshot_cache_size parameter controls the size of an internal least-recently-used cache of topological snapshots (evicts least recently requested topological snapshot when a new reconstruction time is requested that does not currently exist in the cache). This enables topological snapshots 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 reconstructing geometries with reconstruct_geometry() since it, in turn, requests topological snapshots.

Changed in version 0.31: Added default_resolve_topology_parameters argument.

Changed in version 0.43: Added topological_snapshot_cache_size argument.

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

Methods

`__init__`(topological_features, ...)	Create from topological features and a rotation model.
`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.

Note

The reconstruction tree cache size of the returned rotation model is equal to the topological_snapshot_cache_size argument specified in the constructor plus one (or unlimited if not specified).

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

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. Defaults to initial_time.
youngest_time (float or GeoTimeInstant) – Youngest time in the history of topologies. Defaults to present day.
time_increment (float) – Time step in the history of topologies (oldest_time - youngest_time must be an integer multiple of time_increment). Defaults to 1My.
reconstruction_plate_id (int) – If specified then geometry is assumed to be a snapshot at present day, and this will rotate it to initial_time. If not specified then geometry is assumed to already be a snapshot at initial_time - this is the default.
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.
deformation_uses_natural_neighbour_interpolation (bool) – If True then any point that lies (at any time) within a deforming region of a resolved topological network will be reconstructed using natural neighbour interpolation (otherwise barycentric interpolation will be used) - see ResolvedTopologicalNetwork.reconstruct_point(). Defaults to True.

Return type:

ReconstructedGeometryTimeSpan

Raises:

ValueError if initial time, oldest time or youngest time is distant-past (float('inf')) or distant-future (float('-inf')).

Raises:

ValueError if oldest time is later than (or same as) youngest time.

Raises:

ValueError if time increment is negative or zero.

Raises:

ValueError if oldest to youngest time period is not an integer multiple of the time increment.

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

See also

Topologically reconstruct geometries in the Primer documentation.

Changed in version 0.31: Added deactivate_points argument.

Changed in version 0.43: Oldest time, youngest time and time increment no longer required to be integral values.

Changed in version 0.50: Added deformation_uses_natural_neighbour_interpolation argument. Previously it was hardwired to True.

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
Return type:: TopologicalSnapshot
Raises:: ValueError if reconstruction_time is distant-past (float('inf')) or distant-future (float('-inf')).

See also

Topological snapshot in the Primer documentation.

Changed in version 0.43: reconstruction_time no longer required to be integral.