pybacktrack.reconstruct_paleo_bathymetry

pybacktrack.reconstruct_paleo_bathymetry(input_points, oldest_time=None, time_increment=1, *, youngest_time=0.0, lithology_filenames=[pybacktrack.DEFAULT_BUNDLE_LITHOLOGY_FILENAME], age_grid_filename=pybacktrack.BUNDLE_AGE_GRID_FILENAME, topography_filename=pybacktrack.BUNDLE_TOPOGRAPHY_FILENAME, total_sediment_thickness_filename=pybacktrack.BUNDLE_TOTAL_SEDIMENT_THICKNESS_FILENAME, crustal_thickness_filename=pybacktrack.BUNDLE_CRUSTAL_THICKNESS_FILENAME, rotation_filenames=pybacktrack.bundle_data.BUNDLE_RECONSTRUCTION_ROTATION_FILENAMES, static_polygon_filename=pybacktrack.bundle_data.BUNDLE_RECONSTRUCTION_STATIC_POLYGON_FILENAME, dynamic_topography_model=None, sea_level_model=None, lithology_name=pybacktrack.DEFAULT_PALEO_BATHYMETRY_LITHOLOGY_NAME, ocean_age_to_depth_model=pybacktrack.AGE_TO_DEPTH_DEFAULT_MODEL, rifting_period=None, exclude_distances_to_trenches_kms=None, region_plate_ids=None, anchor_plate_id=0, output_positive_bathymetry_below_sea_level=False, output_rift_stretching_factors=False, use_all_cpus=False)

Reconstructs and backtracks sediment-covered crust through time to get paleo bathymetry.

Parameters:

input_points (sequence of (longitude, latitude) tuples) – The point locations to sample bathymetry at present day. Note that any samples outside the masked region of the total sediment thickness grid are ignored.
oldest_time (float, optional) – The oldest time (in Ma) that output is generated back to. Value must not be negative. If not specified then the oldest of oceanic crustal ages (for those input points on oceanic crust) and rift start ages (for those input points on continental crust) is used instead.
time_increment (float) – The time increment (in My) that output is generated (from youngest to oldest time). Value must be positive.
youngest_time (float, default=0.0) – The youngest time (in Ma) that output is generated from. Value must not be negative. Defaults to present day.
lithology_filenames (list of string, optional) – One or more text files containing lithologies.
age_grid_filename (string, optional) – Age grid filename. Used to obtain age of oceanic crust at present day. Crust is oceanic at locations inside masked age grid region, and continental outside.
topography_filename (string, optional) – Topography filename. Used to obtain bathymetry at present day.
total_sediment_thickness_filename (string, optional) – Total sediment thickness filename. Used to obtain total sediment thickness at present day.
crustal_thickness_filename (string, optional) – Crustal thickness filename. Used to obtain crustal thickness at present day.
rotation_filenames (list of string, optional) – List of filenames containing rotation features (to reconstruct sediment-deposited crust). If not specified then defaults to the built-in global rotations associated with the topological model used to generate the built-in rift start/end time grids.
static_polygon_filename (string, optional) – Filename containing static polygon features (to assign plate IDs to points on sediment-deposited crust). If not specified then defaults to the built-in static polygons associated with the topological model used to generate the built-in rift start/end time grids.
dynamic_topography_model (string or tuple, optional) –
Represents a time-dependent dynamic topography raster grid (in mantle frame).

Can be either:
- A string containing the name of a bundled dynamic topography model.
  
  Choices include terra, M1, M2, M3, M4, M5, M6, M7, ngrand, s20rts, smean, AY18, KM16, D10_gmcm9 and gld428.
- A tuple containing the three elements (dynamic topography list filename, static polygon filename, rotation filenames).
  
  The first tuple element is the filename of file containing list of dynamic topography grids (and associated times). Each row in this list file should contain two columns. First column containing filename (relative to list file) of a dynamic topography grid at a particular time. Second column containing associated time (in Ma). The second tuple element is the filename of file containing static polygons associated with dynamic topography model. This is used to assign plate ID to a location so it can be reconstructed. The third tuple element is the filename of the rotation file associated with model. Only the rotation file for static continents/oceans is needed (ie, deformation rotations not needed).
sea_level_model (string, optional) – Used to obtain sea levels relative to present day. Can be either the name of a bundled sea level model, or a sea level filename. Bundled sea level models include Miller2024_SealevelCurve, Haq2024_Hybrid_SealevelCurve, Haq2024_Hybrid_SealevelCurve_Longterm, Haq87_SealevelCurve and Haq87_SealevelCurve_Longterm.
lithology_name (string, optional) – Lithology name of the all sediment (must be present in lithologies file). The total sediment thickness at all sediment locations consists of a single lithology. Defaults to Average_ocean_floor_sediment.
ocean_age_to_depth_model ({pybacktrack.AGE_TO_DEPTH_MODEL_RHCW18, pybacktrack.AGE_TO_DEPTH_MODEL_CROSBY_2007, pybacktrack.AGE_TO_DEPTH_MODEL_GDH1} or function, optional) – The model to use when converting ocean age to depth at a location (if on ocean floor - not used for continental passive margin). It can be one of the enumerated values, or a callable function accepting a single non-negative age parameter and returning depth (in metres).
rifting_period (tuple, optional) – Optional time period of rifting. If specified then overrides rift periods sampled from builtin rift start/end grids. Note that this overrides the spatially varying rift periods (of builtin rift start/end grids) with a constant rift period. Hence it is typically only useful for regional reconstructions (not global). Also, it is only used on continental crust (not oceanic). If specified then should be a 2-tuple (rift_start_age, rift_end_age) where rift_start_age can be None (in which case rifting is considered instantaneous from a stretching point-of-view, not thermal).
exclude_distances_to_trenches_kms (2-tuple of float, optional) – The two distances to present-day trenches (on subducting and overriding sides, in that order) to exclude bathymetry grid points (in kms), or None to use built-in per-trench defaults. Default is None.
region_plate_ids (list of int, optional) – Plate IDs of one or more plates to restrict paleobathymetry reconstruction to. Defaults to global.
anchor_plate_id (int, optional) – The anchor plate id used when reconstructing paleobathymetry grid points. Defaults to zero.
output_positive_bathymetry_below_sea_level (bool, optional) – Whether to output positive bathymetry values below sea level (the same as backtracked water depths at a drill site). However topography/bathymetry grids typically have negative values below sea level (and positive above). So the default (False) matches typical topography/bathymetry grids (ie, outputs negative bathymetry values below sea level).
output_rift_stretching_factors (bool, optional) – Whether to output the rift stretching (beta) factors. These are the optimal stretching factor at each present day grid point where there is submerged continental crust (not just the areas that are rifting). Defaults to False (not output).
use_all_cpus (bool or int, optional) – If False (or zero) then use a single CPU. If True then distribute CPU processing across all CPUs (cores). If a positive integer then use that many CPUs (cores). Defaults to False (single CPU).

Returns:

paleo_bathymetry (dict mapping each time to a list of 3-tuple (longitude, latitude, bathymetry)) – The reconstructed paleo bathymetry points from youngest_time to oldest_time in increments of time_increment. Each key in the returned dict is one of those times and each value in the dict is a list of reconstructed paleo bathymetries represented as a 3-tuple containing reconstructed longitude, reconstructed latitude and paleo bathmetry.
rift_stretching_factors (list of 3-tuple (longitude, latitude, bathymetry)) – Only provided if output_rift_stretching_factors is True. Optimal stretching (beta) factors at present day grid points where there is submerged continental crust (not just the areas that are rifting). Each list entry is a 3-tuple containing present day longitude, present day latitude and optimal stretching (beta) factor.

Raises:

ValueError – If youngest_time or oldest_time is negative (if specified), or if time_increment is not positive.

Notes

The output paleo bathymetry values are negative below sea level by default. Note that this is the inverse of water depth (which is positive below sea level).

Any input points outside the masked region of the total sediment thickness grid are ignored (since bathymetry relies on sediment decompaction over time).

Added in version 1.4.

Changed in version 1.5: The following changes were made:

oldest_time no longer needs to be specified (defaults to oldest of ocean crust ages and continental rift start ages of grid points).
Added optional youngest_time argument.
Added optional rifting_period argument.
Added optional output_rift_stretching_factors argument (and corresponding optional rift_stretching_factors return value).
Some arguments (after *) are now keyword-only (ie, can no longer be specified as positional arguments).