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

`__init__`	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 a `dict`).
`get_topology_point_locations`(...)	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 when reconstructing 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 point

prev_location (TopologyPointLocation): the previous location of the point in the topologies

prev_time (float or GeoTimeInstant): the time associated with the previous position of the point

current_point (PointOnSphere): the current position of the point

current_location (TopologyPointLocation): the current location of the point in the topologies

current_time (float or GeoTimeInstant): the time associated with the current position of the point

Return 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 return True then the point will be deactivated and will not have a position at the next time (where next_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 point
prev_location (TopologyPointLocation): the previous location of the point in the topologies
prev_time (float or GeoTimeInstant): the time associated with the previous position of the point
current_point (PointOnSphere): the current position of the point
current_location (TopologyPointLocation): the current location of the point in the topologies
current_time (float or GeoTimeInstant): the time associated with the current position of the point
Return 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 return True then the point will be deactivated and will not have a position at the next time (where next_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 to 10 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 in TopologicalModel.reconstruct_geometry().
return_inactive_points – Whether to return inactive geometry points. If True then each inactive point stores None instead of a point and hence the size of each list 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, or None if no points are active at reconstruction_time

Return type

list or None

Raises

ValueError if reconstruction_time is distant past or distant 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 a dict).

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 in TopologicalModel.reconstruct_geometry().
scalar_type (ScalarType) – Optional scalar type to retrieve scalar values for (returned as a list). If not specified then all scalar values for all scalar types are returned (returned as a dict).
return_inactive_points – Whether to return scalars associated with inactive points. If True then each scalar corresponding to an inactive point stores None instead of a scalar and hence the size of each list 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 (or None if no matching scalar type), otherwise a dict mapping available scalar types with their associated scalar values list at reconstruction_time (or None if no scalar types are available). Returns None if no points are active at reconstruction_time.

Return type

list or dict or None

Raises

ValueError if reconstruction_time is distant past or distant 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 in TopologicalModel.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 stores None instead of a topology location and hence the size of each list 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, or None if no points are active at reconstruction_time

Return type

list or None

Raises

ValueError if reconstruction_time is distant past or distant future