Introduction

This document introduces pyGPlates and covers some advantages over GPlates. It also gives an overview of embedded versus external pyGPlates.

GPlates versus pyGPlates

GPlates is desktop software for the interactive visualisation of plate-tectonics.

It can be used to load geological data, reconstruct it to past geological times and visualise/export the results.

There are two ways to interact with GPlates functionality:

  1. Using the graphical user interface (GUI):

    Here you control GPlates by interacting with a user interface (such as menus and dialogs).

    For example, to export reconstructed data you:

    • open up the Export dialog,

    • select a range of geological times,

    • select the type of export (eg, reconstructed geometries),

    • select some export options, and

    • export the reconstructed results to files.

    To do this you can download the GPlates desktop application (executable).

  2. Using Python:

    Here you access GPlates functionality using the Python programming language.

    For example, to export reconstructed data (the equivalent of the above GPlates example) you can write a small Python script using functions (and classes) provided by pygplates:

    # Import the pyGPlates library.
import pygplates

# Load the coastline features and rotation model.
coastline_features = pygplates.FeatureCollection('coastlines.gpml')
rotation_model = pygplates.RotationModel('rotations.rot')

# Iterate from 200Ma to 0Ma inclusive in steps of 10My.
for reconstruction_time in range(200,-1,-10):

    # Create the output filename using the current reconstruction time.
    reconstructed_coastlines_filename = 'reconstructed_coastlines_{0:0.2f}Ma.shp'.format(reconstruction_time)

    # Reconstruct the coastlines to the current reconstruction time and save to the output file.
    pygplates.reconstruct(coastline_features, rotation_model, reconstructed_coastlines_filename, reconstruction_time)

Why use pyGPlates ?

In general, writing a Python script affords a greater level of flexibility (compared to a graphical user interface) provided you are comfortable using Python as a programming language. Python libraries such as pyGPlates typically provide both high-level and low-level granularity in their functions and classes to enable this kind of flexibility.

High-level functionality enables common tasks (such as reconstructing entire files of geological data) and is typically easier to use but more restrictive in what it can do. For example, pygplates.reconstruct() is a high-level function that can reconstruct geological data to a past geological time:

pygplates.reconstruct('coastlines.gpml', 'rotations.rot', 'reconstructed_coastlines_10Ma.shp', 10)

…but it cannot restrict reconstructed data to a specific region on the globe. To achieve that, some more Python code needs to be written that accesses lower-level pyGPlates functionality as shown in the sample code Find reconstructed features overlapping a polygon.

Also if GPlates is just one node in a research pipeline then it can be easier to process all nodes together in a single script (or collection of scripts) reducing the need to interact with a graphical user interface. In this case external pyGPlates can replace the GPlates desktop application as a node in the pipeline.

External versus embedded pyGPlates

There are two ways to run Python source code that uses pyGPlates. You can run it in either:

  • an external Python interpreter, or

  • a Python interpreter embedded within the GPlates desktop application (NOTE: this option is not yet available).

Note

A Python interpreter executes source code written in the Python programming language.

Using pyGPlates with an external Python interpreter

In this scenario you are running a Python script using an external Python interpreter.

Note

This does not require the GPlates desktop application (executable).

For example you might have a file called my_python_script.py that you execute on the terminal or shell command-line as:

python my_python_script.py

…this starts up the Python interpreter and instructs it to execute Python source code found in the my_python_script.py script.

In your Python script you will need to import pyGPlates before you can access pyGPlates functionality.
For example a script that just prints the pyGPlates version would look like:
import pygplates

print('Imported pyGPlates version: {}'.format(pygplates.Version.get_imported_version()))

Note

You will need to install pyGPlates so that the Python interpreter can find it when you execute python my_python_script.py.

Using pyGPlates with the GPlates embedded Python interpreter

Warning

This option is not yet available.

In this scenario you are running Python source code using a Python interpreter that is embedded inside the GPlates desktop application.

In this case you have started the GPlates desktop application and are loading a python script in the GPlates Python console (accessed via the Open Python Console menu item) or interactively entering Python source code in that console.

Note

You do not need to import pygplates here since it has already been imported/embedded into GPlates (when GPlates started up).