API Reference

PlateModelManager

The plate_model_manager.PlateModelManager class manages the plate reconstruction models. You can use this class to do the things listed below.

• Get a list of available model names.

• Get a plate_model_manager.PlateModel object for a specific model name.

• Download all models into a folder.

class plate_model_manager.PlateModelManager(model_manifest: str = '', timeout=(None, None))

Bases: object

Manage discovery and loading of plate reconstruction model metadata.

Model manifests can be loaded from a local file or an HTTP(S) endpoint. Retrieved model configurations are used to construct PlateModel instances.

__init__(model_manifest: str = '', timeout=(None, None))

Create a PlateModelManager instance.

If model_manifest is omitted, the manager probes known PMM manifest endpoints and uses the first reachable URL.

Parameters:

• model_manifest – Local path or HTTP(S) URL for a models.json manifest. Use this when hosting a custom model repository.

• timeout – Timeout tuple passed to HTTP requests.

Raises:

• InvalidConfigFile – If the manifest path/URL is invalid or does not contain valid JSON.

• ServerUnavailable – If the manifest URL cannot be reached.

download_all_models(data_dir: str = './') → None

Download layer data for all available models into data_dir.

Parameters:

data_dir (str) – Destination directory for downloaded model data.

get_available_model_names()

Return all model keys from the loaded manifest.

Returns:

Available model names and aliases.

Return type:

list[str]

static get_default_repo_url()

Return the first reachable default model-manifest URL.

Endpoints are probed in order using HTTP HEAD requests.

Returns:

Reachable manifest URL.

Return type:

str

Raises:

ServerUnavailable – If none of the default endpoints are reachable.

static get_local_available_model_names(local_dir: str)

Return locally available model names from local_dir.

Parameters:

local_dir (str) – The local folder containing models.

Returns:

Names of subdirectories that look like valid local PMM models (contain .metadata.json).

Return type:

list[str]

get_model(model_name: str = 'default', data_dir: str = '.', reference_frame: ReferenceFrame | None = None) → PlateModel | None

Return a PlateModel for model_name.

The method resolves aliases, applies optional reference-frame handling, and instantiates PlateModel with the resolved configuration.

Parameters:

• model_name – Model name or alias (case-insensitive). Defaults to "default".

• data_dir – Parent directory for model downloads and cache files.

• reference_frame – Optional reference frame. When PMAG is requested and a _pmag_ref variant exists, that variant is selected automatically.

Returns:

A configured PlateModel, or None if the model is unavailable or incompatible with the requested reference frame.

Raises:

InvalidConfigFile – If alias resolution detects an invalid alias chain.

PlateModel

The plate_model_manager.PlateModel class manages the files in a plate reconstruction model. You can use this class to do the things listed below.

• Get a list of available layers in a plate model.

• Download the rotation file(s).

• Download the layer file(s) for a specific layer.

• Download time-dependent raster files.

• Download all files in a plate model.

class plate_model_manager.PlateModel(model_name: str, model_cfg=None, data_dir: str = '.', reference_frame: ReferenceFrame | None = None, readonly=False, timeout=(None, None))

Bases: object

Download and manage files for a plate reconstruction model.

In most workflows, create instances through PlateModelManager.get_model() so model configuration and metadata are resolved automatically. Direct instantiation is primarily intended for advanced or offline use (for example, readonly=True with pre-downloaded local files).

See also

Use PlateModel class in readonly mode.

__init__(model_name: str, model_cfg=None, data_dir: str = '.', reference_frame: ReferenceFrame | None = None, readonly=False, timeout=(None, None))

Create a PlateModel instance.

Parameters:

• model_name (str) – Model name to load.

• model_cfg – Model configuration dictionary. This is typically provided by PlateModelManager.get_model(), or loaded from local metadata in readonly mode.

• data_dir (str, default=".") – Parent directory used to store model files.

• reference_frame (ReferenceFrame or None) – Default reference frame associated with this instance.

• readonly (bool, default=False) – If True, use only local files and do not perform downloads or updates.

• timeout – Network timeout tuple passed to file downloads.

Raises:

Exception – If readonly=True and the local model directory is invalid.

create_model_dir()

Ensure the model folder exists and refresh local metadata files.

This method creates self.model_dir when missing, then always rewrites .metadata.json and readme.txt from the current in-memory model configuration, even if the folder already exists.

Returns:

The model folder path.

Return type:

str

Raises:

Exception – If running in readonly mode, if self.model_dir is invalid/empty, or if the model path exists as a file.

download_all()

Download all layers and all configured time-dependent rasters.

download_all_layers()

Download all configured layers for this model.

This includes Rotations when available, plus every entry under model["Layers"].

download_time_dependent_rasters(raster_name, times=None)

Download and cache a time series of rasters for raster_name.

Parameters:

• raster_name – Raster key in model["TimeDepRasters"].

• times – Iterable of reconstruction times (Ma). If omitted, download every integer time from SmallTime to BigTime inclusive.

Raises:

Exception – If called in readonly mode or raster configuration is missing.

get_COBs(return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the COBs layer.

get_age_grid(time: int | float, reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → str

Return a local path for an AgeGrids raster at time Ma.

get_age_grids(times: List[int | float], reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → List[str]

Return local paths for AgeGrids rasters at multiple times.

get_anchor_id_for_pmag_reference_frame() → int | None

Return the PMAG anchor plate ID when this model supports PMAG.

Models that expose PMAG through Attributes.PmagReferenceFrameAnchorPID return that configured anchor plate ID. Dedicated _pmag_ref models use 0 as the implicit PMAG anchor plate ID. Mantle-only models return None.

Returns:

PMAG anchor plate ID, or None when PMAG is unsupported.

Return type:

int or None

get_avail_layers()

Return all available geometry layer names in this model.

Returns:

Layer names.

Return type:

list[str]

Raises:

Exception – If model configuration is missing.

get_avail_time_dependent_raster_names()

Return configured names of time-dependent rasters.

Returns:

Raster names from TimeDepRasters, or an empty list when the model defines none.

Return type:

list[str]

get_big_time()

Return the maximum reconstruction time in Ma.

get_cfg()

Return the model configuration dictionary.

Returns:

Model metadata dictionary.

Return type:

Dict

get_coastlines(return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the Coastlines layer.

get_continental_polygons(return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the ContinentalPolygons layer.

get_data_dir()

Return the parent directory containing downloaded models.

Returns:

Data directory path.

Return type:

str

get_layer(layer_name: str, return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for a geometry layer in this model.

In writable mode, this function will check if the layer files exist on the local computer. If the files don’t exist or need to be updated, they are downloaded or updated before paths are returned.

In readonly mode, paths are resolved from the local model folder without checking for updates.

Note

This function is for accessing geometry layers(vector data), such as Coastlines, Topologies, StaticPolygons, etc. Call get_avail_layers() to get a list of available layer names. For accessing time-dependent rasters, use get_raster() or get_rasters().

Parameters:

• layer_name – Layer name. Call get_avail_layers() to get a list of available layer names.

• return_none_if_not_exist – If True, return None instead of raising exception when the layer does not exist.

Returns:

List of matching layer file paths, or None when return_none_if_not_exist=True and the layer does not exist.

Raises:

LayerNotFoundInModel – If the layer does not exist and return_none_if_not_exist is False.

get_layer_metadata(layer_name: str, return_none_if_not_exist: bool = False) → Dict | None

Return metadata for a layer as a dictionary.

In writable mode, this method ensures the layer is downloaded/updated before reading metadata. In readonly mode, it reads from the local layer folder directly.

Parameters:

• layer_name – The layer name of interest.

• return_none_if_not_exist – If set to True, return None when the layer does not exist in the model.

Returns:

Layer metadata dictionary, or None if return_none_if_not_exist is set to True and the layer is not found.

Raises:

• LayerNotFoundInModel – Raise this exception if the layer name does not exist in this model.

• Exception – If the layer metadata file is missing.

get_model_dir()

Return the local directory path for this model.

In writable mode, the model directory is created when missing.

Returns:

Absolute or relative path to this model folder.

Return type:

str

Raises:

Exception – If the folder is missing in readonly mode.

get_raster(raster_name: str, time: int | float, reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → str

Return a local path for a single time-dependent raster.

The final raster key is built from raster_name and optional suffixes from generated_from and reference_frame (in that order), matching the naming convention used in model["TimeDepRasters"].

Parameters:

• raster_name – Base raster name in TimeDepRasters (for example, "AgeGrids").

• time – Reconstruction time (Ma) to fetch.

• reference_frame – Optional reference-frame suffix to append to the raster name.

• generated_from – Optional generation-method suffix to append to the raster name.

Returns:

Local file path for the requested raster at time.

Raises:

Exception – If this model has no TimeDepRasters entry, if the constructed raster name is not configured, if the file is missing in readonly mode, or if a download fails in writable mode.

get_rasters(raster_name: str, times: List[int | float], reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → List[str]

Return local paths for a sequence of time-dependent rasters.

The final raster key is built from raster_name and optional suffixes from generated_from and reference_frame (in that order), matching the naming convention used in model["TimeDepRasters"].

Parameters:

• raster_name – Base raster name in TimeDepRasters (for example, "AgeGrids").

• times – Reconstruction times (Ma) to fetch.

• reference_frame – Optional reference-frame suffix to append to the raster name.

• generated_from – Optional generation-method suffix to append to the raster name.

Returns:

Local file paths for the requested times, in the same order as times.

Raises:

Exception – If this model has no TimeDepRasters entry, if the constructed raster name is not configured, if a requested file is missing in readonly mode, or if a download fails in writable mode.

get_rotation_model(reference_frame: ReferenceFrame | None = None)

Return rotation files, and optionally a PMAG anchor plate ID.

Rotation files are read from the local model directory in readonly mode, or downloaded/updated first in writable mode.

When reference_frame is ReferenceFrame.PmagReferenceFrame, this method also returns the anchor plate ID required by consumers that need PMAG reference frame rotations. The anchor ID is read from model["Attributes"]["PmagReferenceFrameAnchorPID"] when present. If that value is missing but this model is already under PMAG reference frame, set the anchor ID to 0, such as matthews2016_pmag_ref model.

Parameters:

reference_frame – Optional reference frame for the returned rotation model. (since version 1.4.0)

Returns:

If reference_frame is PMAG, returns (rotation_files, anchor_pid) where rotation_files is a list of .rot/.grot file paths and anchor_pid is an integer. Otherwise returns only rotation_files.

Raises:

Exception – If PMAG is requested but the model is not PMAG and Attributes.PmagReferenceFrameAnchorPID is not defined.

get_small_time()

Return the minimum reconstruction time in Ma.

get_spreading_rate_grid(time: int | float, reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → str

Return a local path for a SpreadingRate raster at time Ma.

get_spreading_rate_grids(times: List[int | float], reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → List[str]

Return local paths for SpreadingRate rasters at multiple times.

get_static_polygons(return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the StaticPolygons layer.

get_supported_reference_frames() → List[ReferenceFrame]

Return the reference frames which this model supports.

If the model name ends with “pmag_ref”, we will consider it as a PMAG reference frame model. Otherwise, it is a mantle reference frame model by default.

If the model configuration has a PmagReferenceFrameAnchorPID attribute, we will consider this model supports both PMAG and mantle reference frame, such as Zahirovic2022 model. The same rotation files can be used for both reference frames, but with different default anchor plate ID. For mantle reference frame, the anchor plate ID is usually 0. For PMAG reference frame, the anchor plate ID is usually a non-zero integer defined in the model configuration as PmagReferenceFrameAnchorPID attribute.

Returns:

A list of supported reference frames.

Return type:

list[ReferenceFrame]

get_topologies(return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the Topologies layer.

get_vector_data(name: str, return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the vector data in this model.

This is an alias for get_layer() to access vector data layers such as Coastlines, Topologies, StaticPolygons, etc. The purpose of this function is to provide a more intuitive API for users who may wonder whether the term “layer” means vector layer or raster layer. You can use this function to get file paths for vector data available in this model by specifying its name.

Call get_avail_layers() to get a list of available names for vector data.

Parameters:

• name – The vector data name which is the same with the layer_name in get_layer(). Call get_avail_layers() to get a list of available vector layer names.

• return_none_if_not_exist – If True, return None instead of raising exception when the vector data doesn’t exist.

Returns:

List of vector data file paths, or None when return_none_if_not_exist=True and the vector data doesn’t exist.

static is_model_dir(folder_path: str)

Return whether folder_path looks like a local model directory.

property model_dir

Return the model folder path under data_dir.

purge()

Delete the model directory and all files under it, if present.

purge_layer(layer_name)

Delete a local layer directory for layer_name, if present.

purge_time_dependent_rasters(raster_name)

Delete local cached rasters for raster_name, if present.

set_data_dir(new_dir)

Set a new parent directory for this model.

Parameters:

new_dir – New data directory path.

PresentDayRasterManager

The plate_model_manager.PresentDayRasterManager class manages the present-day rasters. You can use this class to do the things listed below.

• Get a list of available present-day raster names.

• Download a specific present-day raster.

class plate_model_manager.PresentDayRasterManager(data_dir='present-day-rasters', raster_manifest=None)

Bases: object

Manage present-day raster metadata retrieval and local raster access.

__init__(data_dir='present-day-rasters', raster_manifest=None)

Create a PresentDayRasterManager instance.

The raster manifest can be provided either as a local file path or as an HTTP(S) URL. If omitted, the default PMM raster manifest endpoint is used.

Parameters:

• data_dir – Directory where raster files and metadata are stored.

• raster_manifest – Local path or URL to a present_day_rasters.json manifest. Provide this only when using a custom raster service.

Raises:

Exception – If the manifest source is invalid or cannot be fetched.

get_raster(_name: str, width=1800, height=800, bbox=[-180, -80, 180, 80], large_file_hint=True)

Download or fetch a raster and return its local file path.

For file-based rasters, this method downloads and caches files under self.data_dir. For WMS rasters, it requests a GeoTIFF with the given output dimensions and bounding box, and caches the result using a hash of the WMS request URL.

Call list_present_day_rasters() to inspect available raster names.

Parameters:

• _name (str) – The raster name of interest.

• width (int) – Output raster width in pixels for WMS requests.

• height (int) – Output raster height in pixels for WMS requests.

• bbox (list[float]) – Geographic bounding box [min_lon, min_lat, max_lon, max_lat] used for WMS requests.

• large_file_hint (bool) – Passed to file downloader to optimize large-file handling for non-WMS rasters.

Returns:

Local path to the downloaded or cached raster file.

Return type:

str

Raises:

• RasterNameNotFound – If the raster name is not in the manifest.

• Exception – If raster retrieval fails.

is_wms(_name: str, check_raster_avail_flag=True)

Return whether a raster is served through WMS metadata.

Parameters:

• _name (str) – The raster name of interest.

• check_raster_avail_flag (bool) – If True, validate the raster name against the loaded manifest before checking service type.

Returns:

True when the raster metadata marks the service as WMS; otherwise False.

Return type:

bool

list_present_day_rasters()

Return the list of available present-day raster names.

Returns:

Available raster names from the manifest.

Return type:

list[str]

set_data_dir(data_dir)

Set the directory used to store downloaded raster files.

Parameters:

data_dir – Directory path for local raster data.

Auxiliary Function

Auxiliary functon for users’ convenience.

plate_model_manager.get_plate_model(model_name: str, data_dir: str | PathLike) → PlateModel | None

Return a plate model instance using online lookup with local fallback.

This helper first attempts to resolve model_name through PlateModelManager. If the PMM servers are unavailable, it falls back to creating a local, read-only PlateModel from files already present in data_dir.

Parameters:

• model_name – Name of the plate model to resolve.

• data_dir – Directory containing downloaded plate model data.

Returns:

A PlateModel instance, or None if the model name cannot be resolved.

Example usage:

from plate_model_manager import get_plate_model

model = get_plate_model("Muller2025", data_dir="plate-models-data-dir")
if model is not None:
    print(model.get_rotation_model())
else:
    print("Model not found.")