pygplates.ReconstructedGeometryTimeSpan
- class pygplates.ReconstructedGeometryTimeSpan
Bases:
Boost.Python.instance
A history of geometries reconstructed using topologies over geological time.
New in version 0.29.
- __init__()
Raises an exception This class cannot be instantiated from Python
Methods
Raises an exception This class cannot be instantiated from Python
get_geometry_points
(reconstruction_time, ...)Returns geometry points at a specific reconstruction time.
get_scalar_values
(reconstruction_time, ...)Returns scalar values at a specific reconstruction time either for a single scalar type (as a
list
) or for all scalar types (as adict
).Returns the locations of geometry points in resolved topologies at a specific reconstruction time.
- class DeactivatePoints
Bases:
Boost.Python.instance
The base class interface for deactivating geometry points as they are reconstructed forward and/or backward in time.
To create your own class that inherits this base class and overrides its
deactivate method
and then use that whenreconstructing a geometry using topologies
:class MyDeactivatePoints(pygplates.ReconstructedGeometryTimeSpan.DeactivatePoints): def __init__(self): super(MyDeactivatePoints, self).__init__() # Other initialisation you may want... ... def deactivate(self, prev_point, prev_location, prev_time, current_point, current_location, current_time): # Implement your deactivation algorithm here... ... return ... # Reconstruct points in 'geometry' from 100Ma to present day using class MyDeactivatePoints to deactivate them (in this case subduct). topological_model.reconstruct_geometry(geometry, 100, deactivate_points=MyDeactivatePoints())
Warning
If you create your own Python class that inherits this base class then you must call the base class __init__ method otherwise you will get a Boost.Python.ArgumentError exception. Note that if you do not define an __init__ method in your derived class then Python will call the base class __init__ (so you don’t have to do anything). However if you do define __init__ in your derived class then it must explicitly call the base class __init__.
New in version 0.31.
- __init__()
Default constructor - must be explicitly called by derived class.
- deactivate(prev_point, prev_location, current_point, current_location, current_time, reverse_reconstruct)
Return true if the point should be deactivated.
prev_point (
PointOnSphere
): the previous position of the pointprev_location (
TopologyPointLocation
): the previous location of the point in the topologiesprev_time (float or
GeoTimeInstant
): the time associated with the previous position of the pointcurrent_point (
PointOnSphere
): the current position of the pointcurrent_location (
TopologyPointLocation
): the current location of the point in the topologiescurrent_time (float or
GeoTimeInstant
): the time associated with the current position of the pointReturn type: bool
The above parameters represent the previous and current position/location-in-topologies/time of a single point in the
geometry being reconstructed
. If you returnTrue
then the point will be deactivated and will not have a position at the next time (wherenext_time = current_time + (current_time - prev_time)
).Note
If the current time is younger than the previous time (
current_time < prev_time
) then we are reconstructing forward in time and the next time will be younger than the current time (next_time < current_time
). Conversely, if the current time is older than the previous time (current_time > prev_time
) then we are reconstructing backward in time and the next time will be older than the current time (next_time > current_time
).Note
This function is called for each point that is reconstructed using
TopologicalModel.reconstruct_geometry()
at each time step.Note
This function might be inadvertently documented twice.
- deactivate(prev_point, prev_location, current_point, current_location, current_time, reverse_reconstruct)
Return true if the point should be deactivated.
prev_point (
PointOnSphere
): the previous position of the pointprev_location (
TopologyPointLocation
): the previous location of the point in the topologiesprev_time (float or
GeoTimeInstant
): the time associated with the previous position of the pointcurrent_point (
PointOnSphere
): the current position of the pointcurrent_location (
TopologyPointLocation
): the current location of the point in the topologiescurrent_time (float or
GeoTimeInstant
): the time associated with the current position of the pointReturn type: bool
The above parameters represent the previous and current position/location-in-topologies/time of a single point in the
geometry being reconstructed
. If you returnTrue
then the point will be deactivated and will not have a position at the next time (wherenext_time = current_time + (current_time - prev_time)
).
Note
If the current time is younger than the previous time (
current_time < prev_time
) then we are reconstructing forward in time and the next time will be younger than the current time (next_time < current_time
). Conversely, if the current time is older than the previous time (current_time > prev_time
) then we are reconstructing backward in time and the next time will be older than the current time (next_time > current_time
).Note
This function is called for each point that is reconstructed using
TopologicalModel.reconstruct_geometry()
at each time step.Note
This function might be inadvertently documented twice.
- class DefaultDeactivatePoints
Bases:
pygplates.DeactivatePoints
The default algorithm for deactivating geometry points as they are reconstructed forward and/or backward in time.
New in version 0.31.
- __init__([threshold_velocity_delta=0.7], [threshold_distance_to_boundary=10], [deactivate_points_that_fall_outside_a_network=False])
Create default algorithm for deactivating points using the specified parameters.
threshold_velocity_delta (float): A point that transitions from one plate/network to another can disappear if the change in velocity exceeds this threshold (in units of cms/yr). Defaults to
0.7
cms/yr.threshold_distance_to_boundary (float): Only those transitioning points exceeding the threshold velocity delta and that are close enough to a plate/network boundary can disappear. The distance is proportional to the relative velocity (change in velocity), plus a constant offset based on the threshold distance to boundary (in units of kms/myr) to account for plate boundaries that change shape significantly from one time step to the next (note that some boundaries are meant to do this and others are a result of digitisation). The actual distance threshold used is
(threshold_distance_to_boundary + relative_velocity) * time_increment
. Defaults to10
kms/myr.deactivate_points_that_fall_outside_a_network (bool): Whether to have points inside a deforming network disappear as soon as they fall outside all deforming networks. This is useful for initial crustal thickness points that have been generated inside a deforming network and where subsequently deformed points should be limited to the deformed network regions. In this case sudden large changes to the deforming network boundary can progressively exclude points over time. However in the case where the topologies (deforming networks and rigid plates) have global coverage this option should generally be left disabled so that points falling outside deforming networks can then be reconstructed using rigid plates. And these rigidly reconstructed points may even re-enter a subsequent deforming network. Defaults to
False
.
Note
This is the default algorithm used internally.
To use the default deactivation algorithm (this class) but with some non-default parameters, and then use that when
reconstructing a geometry using topologies
:# Reconstruct points in 'geometry' from 100Ma to present day using this class to deactivate them (in this case subduct). topological_model.reconstruct_geometry( geometry, 100, deactivate_points = pygplates.ReconstructedGeometryTimeSpan.DefaultDeactivatePoints( # Choose our own parameters that are different than the defaults. threshold_velocity_delta = 0.9, # cms/yr threshold_distance_to_boundary = 15, # kms/myr deactivate_points_that_fall_outside_a_network = True))
- get_geometry_points(reconstruction_time[, return_inactive_points=False])
Returns geometry points at a specific reconstruction time.
- Parameters
reconstruction_time (float or
GeoTimeInstant
) – Time to extract reconstructed geometry points. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span specified inTopologicalModel.reconstruct_geometry()
.return_inactive_points – Whether to return inactive geometry points. If
True
then each inactive point storesNone
instead of a point and hence the size of eachlist
of points is equal to the number of points in the initial geometry (which are all initially active). By default only active points are returned.
- Returns
list of
PointOnSphere
, orNone
if no points are active at reconstruction_time- Return type
list
orNone
- Raises
ValueError if reconstruction_time is
distant past
ordistant future
- get_scalar_values(reconstruction_time[, scalar_type][, return_inactive_points=False])
Returns scalar values at a specific reconstruction time either for a single scalar type (as a
list
) or for all scalar types (as adict
).- Parameters
reconstruction_time (float or
GeoTimeInstant
) – Time to extract reconstructed scalar values. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span specified inTopologicalModel.reconstruct_geometry()
.scalar_type (
ScalarType
) – Optional scalar type to retrieve scalar values for (returned as alist
). If not specified then all scalar values for all scalar types are returned (returned as adict
).return_inactive_points – Whether to return scalars associated with inactive points. If
True
then each scalar corresponding to an inactive point storesNone
instead of a scalar and hence the size of eachlist
of scalars is equal to the number of points (and scalars) in the initial geometry (which are all initially active). By default only scalars for active points are returned.
- Returns
If scalar_type is specified then a
list
of scalar values associated with scalar_type at reconstruction_time (orNone
if no matching scalar type), otherwise adict
mapping available scalar types with their associated scalar valueslist
at reconstruction_time (orNone
if no scalar types are available). ReturnsNone
if no points are active at reconstruction_time.- Return type
list
ordict
orNone
- Raises
ValueError if reconstruction_time is
distant past
ordistant future
- get_topology_point_locations(reconstruction_time[, return_inactive_points=False])
Returns the locations of geometry points in resolved topologies at a specific reconstruction time.
- Parameters
reconstruction_time (float or
GeoTimeInstant
) – Time to extract topology point locations. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span specified inTopologicalModel.reconstruct_geometry()
.return_inactive_points – Whether to return topology locations associated with inactive points. If
True
then each topology location corresponding to an inactive point storesNone
instead of a topology location and hence the size of eachlist
of topology locations is equal to the number of points in the initial geometry (which are all initially active). By default only topology locations for active points are returned.
- Returns
list of
TopologyPointLocation
, orNone
if no points are active at reconstruction_time- Return type
list
orNone
- Raises
ValueError if reconstruction_time is
distant past
ordistant future