pygplates.ReconstructedGeometryTimeSpan

class pygplates.ReconstructedGeometryTimeSpan

Bases: instance

A history of geometries reconstructed using topologies over geological time.

See also

Reconstructed geometry time span in the Primer documentation.

Added 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_crustal_stretching_factors`(...)	Returns crustal stretching factors at a specific reconstruction time.
`get_crustal_thicknesses`(reconstruction_time, ...)	Returns crustal thicknesses (in kms) at a specific reconstruction time.
`get_crustal_thinning_factors`(...)	Returns crustal thinning factors at a specific reconstruction time.
`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_strain_rates`(reconstruction_time, ...)	Returns the strain rates at geometry points in resolved topologies at a specific reconstruction time.
`get_strains`(reconstruction_time, ...)	Returns the strains accumulated at geometry points in resolved topologies at a specific reconstruction time.
`get_tectonic_subsidences`(...)	Returns tectonic subsidence values (in kms) at a specific reconstruction time.
`get_time_span`()	Returns the time span of the history of reconstructed geometries.
`get_topology_point_locations`(...)	Returns the locations of geometry points in resolved topologies at a specific reconstruction time.
`get_velocities`(reconstruction_time, ...)	Returns the velocities at geometry points in resolved topologies at a specific reconstruction time.

class DeactivatePoints

Bases: 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__.

See also

Deactivating points in the Primer documentation.

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

See also

Deactivating points in the Primer documentation.

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.

See also

Deactivating points in the Primer documentation.

class DefaultDeactivatePoints

Bases: DeactivatePoints

The default algorithm for deactivating geometry points as they are reconstructed forward and/or backward in time.

See also

Deactivating points in the Primer documentation.

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

See also

Deactivating points in the Primer documentation.

get_crustal_stretching_factors(reconstruction_time[, return_inactive_points=False])

Returns crustal stretching factors at a specific reconstruction time.

Parameters:

reconstruction_time (float or GeoTimeInstant) – Time to extract reconstructed crustal stretching factors. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span).
return_inactive_points (bool) – Whether to return crustal stretching factors associated with inactive points. If True then each crustal stretching factor corresponding to an inactive point stores None and hence the size of the returned list is equal to the number of points in the initial geometry (which are all initially active). By default only crustal stretching factors for active points are returned.

Returns:

list of float, 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

See also

Crustal thickness factors in the Primer documentation.

Added in version 0.50.

get_crustal_thicknesses(reconstruction_time[, return_inactive_points=False])

Returns crustal thicknesses (in kms) at a specific reconstruction time.

Parameters:

reconstruction_time (float or GeoTimeInstant) – Time to extract reconstructed crustal thicknesses. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span).
return_inactive_points (bool) – Whether to return crustal thicknesses associated with inactive points. If True then each crustal thickness corresponding to an inactive point stores None and hence the size of the returned list is equal to the number of points in the initial geometry (which are all initially active). By default only crustal thicknesses for active points are returned.

Returns:

list of float, 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

See also

Crustal thickness factors in the Primer documentation.

Added in version 0.50.

get_crustal_thinning_factors(reconstruction_time[, return_inactive_points=False])

Returns crustal thinning factors at a specific reconstruction time.

Parameters:

reconstruction_time (float or GeoTimeInstant) – Time to extract reconstructed crustal thinning factors. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span).
return_inactive_points (bool) – Whether to return crustal thinning factors associated with inactive points. If True then each crustal thinning factor corresponding to an inactive point stores None and hence the size of the returned list is equal to the number of points in the initial geometry (which are all initially active). By default only crustal thinning factors for active points are returned.

Returns:

list of float, 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

See also

Crustal thickness factors in the Primer documentation.

Added in version 0.50.

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).
return_inactive_points (bool) – Whether to return inactive geometry points. If True then each inactive point stores None instead of a point and hence the size of the 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

See also

Geometry points in the Primer documentation.

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).
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 (bool) – 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

See also

Scalar values in the Primer documentation.

get_strain_rates(reconstruction_time[, return_inactive_points=False])

Returns the strain rates at geometry points in resolved topologies at a specific reconstruction time.

Parameters:

reconstruction_time (float or GeoTimeInstant) – Time to extract strain rates. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span).
return_inactive_points (bool) – Whether to return strain rates associated with inactive points. If True then each strain rate corresponding to an inactive point stores None instead of a strain rate and hence the size of the list of strain rates is equal to the number of points in the initial geometry (which are all initially active). By default only strain rates for active points are returned.

Returns:

list of StrainRate, 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

See also

Strain rates in the Primer documentation.

Note

Strain rates in deforming networks are calculated from the spatial gradients of velocity where the velocities are calculated over a 1 Myr time interval and using the equatorial Earth radius pygplates.Earth.equatorial_radius_in_kms.

Added in version 0.46.

get_strains(reconstruction_time[, return_inactive_points=False])

Returns the strains accumulated at geometry points in resolved topologies at a specific reconstruction time.

Parameters:

reconstruction_time (float or GeoTimeInstant) – Time to extract accumulated strains. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span).
return_inactive_points (bool) – Whether to return strains associated with inactive points. If True then each strain corresponding to an inactive point stores None instead of a strain and hence the size of the list of strains is equal to the number of points in the initial geometry (which are all initially active). By default only strains for active points are returned.

Returns:

list of Strain, 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

See also

Strains in the Primer documentation.

Added in version 0.46.

get_tectonic_subsidences(reconstruction_time[, return_inactive_points=False])

Returns tectonic subsidence values (in kms) at a specific reconstruction time.

Parameters:

reconstruction_time (float or GeoTimeInstant) – Time to extract reconstructed tectonic subsidence values. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span).
return_inactive_points (bool) – Whether to return tectonic subsidence values associated with inactive points. If True then each tectonic subsidence value corresponding to an inactive point stores None and hence the size of the returned list is equal to the number of points in the initial geometry (which are all initially active). By default only tectonic subsidence values for active points are returned.

Returns:

list of float, 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

See also

Tectonic subsidence in the Primer documentation.

Added in version 0.50.

get_time_span()

Returns the time span of the history of reconstructed geometries.

Returns:: the 4-tuple of (oldest time, youngest time, time increment, number of time slots)
Return type:: 4-tuple (float, float, float, int)

The oldest time, youngest time and time increment are the same as were specified in TopologicalModel.reconstruct_geometry(). And the number of time slots is \(\frac{(oldest\_time - youngest\_time)}{time\_increment}\) which is an integer value (since TopologicalModel.reconstruct_geometry() requires the oldest to youngest time period to be an integer multiple of the time increment).

See also

Reconstructed geometry time span in the Primer documentation.

Added in version 0.50.

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).
return_inactive_points (bool) – 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 the 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

See also

Topology locations in the Primer documentation.

get_velocities(reconstruction_time[, velocity_delta_time=1.0][, velocity_delta_time_type=pygplates.VelocityDeltaTimeType.t_plus_delta_t_to_t][, velocity_units=pygplates.VelocityUnits.kms_per_my][, earth_radius_in_kms=pygplates.Earth.mean_radius_in_kms][, return_inactive_points=False])

Returns the velocities at geometry points in resolved topologies at a specific reconstruction time.

Parameters:

reconstruction_time (float or GeoTimeInstant) – Time to extract velocities. Can be any non-negative time (doesn’t have to be an integer and can be outside the time span).
velocity_delta_time (float) – The time delta used to calculate velocities (defaults to 1 Myr).
velocity_delta_time_type (VelocityDeltaTimeType.t_plus_delta_t_to_t, VelocityDeltaTimeType.t_to_t_minus_delta_t or VelocityDeltaTimeType.t_plus_minus_half_delta_t) – How the two velocity times are calculated relative to the reconstruction time. This includes [t+dt, t], [t, t-dt] and [t+dt/2, t-dt/2]. Defaults to [t+dt, t].
velocity_units (VelocityUnits.kms_per_my or VelocityUnits.cms_per_yr) – whether to return velocities as kilometres per million years or centimetres per year (defaults to kilometres per million years)
earth_radius_in_kms (float) – the radius of the Earth in kilometres (defaults to pygplates.Earth.mean_radius_in_kms)
return_inactive_points (bool) – Whether to return velocities associated with inactive points. If True then each velocity corresponding to an inactive point stores None instead of a velocity and hence the size of the list of velocities is equal to the number of points in the initial geometry (which are all initially active). By default only velocities for active points are returned.

Returns:

list of Vector3D, 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

Raises:

ValueError if velocity_delta_time is negative or zero.

See also

Velocities in the Primer documentation.

Added in version 0.46.

Changed in version 0.47: Added earth_radius_in_kms argument (that defaults to pygplates.Earth.mean_radius_in_kms). Previously pygplates.Earth.equatorial_radius_in_kms was hardwired internally).