pygmt.clib.Session

class pygmt.clib.Session

A GMT API session where most operations involving the C API happen.

Works as a context manager (for use in a with block) to create a GMT C API session and destroy it in the end to clean up memory.

Functions of the shared library are exposed as methods of this class. Most methods MUST be used with an open session (inside a with block). If creating GMT data structures to communicate data, put that code inside the same with block as the API calls that will use the data.

By default, will let ctypes try to find the GMT shared library (libgmt). If the environment variable GMT_LIBRARY_PATH is set, will look for the shared library in the directory specified by it.

A GMTVersionError exception will be raised if the GMT shared library reports a version older than the required minimum GMT version.

The session_pointer attribute holds a ctypes pointer to the currently open session.

Raises

• GMTCLibNotFoundError – If there was any problem loading the library (couldn’t find it or couldn’t access the functions).

• GMTCLibNoSessionError – If you try to call a method outside of a ‘with’ block.

• GMTVersionError – If the minimum required version of GMT is not found.

Examples

>>> from pygmt.datasets import load_earth_relief
>>> from pygmt.helpers import GMTTempFile
>>> grid = load_earth_relief()
>>> type(grid)
<class 'xarray.core.dataarray.DataArray'>
>>> # Create a session and destroy it automatically when exiting the "with"
>>> # block.
>>> with Session() as ses:
...     # Create a virtual file and link to the memory block of the grid.
...     with ses.virtualfile_from_grid(grid) as fin:
...         # Create a temp file to use as output.
...         with GMTTempFile() as fout:
...             # Call the grdinfo module with the virtual file as input
...             # and the temp file as output.
...             ses.call_module(
...                 "grdinfo", "{} -C ->{}".format(fin, fout.name)
...             )
...             # Read the contents of the temp file before it's deleted.
...             print(fout.read().strip())
...
-180 180 -90 90 -8182 5651.5 1 1 360 180 1 1

Methods Summary

Session.call_module(module, args)	Call a GMT module with the given arguments.
Session.create(name)	Create a new GMT C API session.
Session.create_data(family, geometry, mode, …)	Create an empty GMT data container.
Session.destroy()	Destroy the currently open GMT API session.
Session.extract_region()	Extract the WESN bounding box of the currently active figure.
Session.get_default(name)	Get the value of a GMT default parameter (library version, paths, etc).
Session.get_libgmt_func(name[, argtypes, …])	Get a ctypes function from the libgmt shared library.
Session.open_virtual_file(family, geometry, …)	Open a GMT Virtual File to pass data to and from a module.
Session.put_matrix(dataset, matrix[, pad])	Attach a numpy 2D array to a GMT dataset.
Session.put_strings(dataset, family, strings)	Attach a numpy 1D array of dtype str as a column on a GMT dataset.
Session.put_vector(dataset, column, vector)	Attach a numpy 1D array as a column on a GMT dataset.
Session.virtualfile_from_data([check_kind, …])	Store any data inside a virtual file.
Session.virtualfile_from_grid(grid)	Store a grid in a virtual file.
Session.virtualfile_from_matrix(matrix)	Store a 2d array as a table inside a virtual file.
Session.virtualfile_from_vectors(*vectors)	Store 1d arrays as columns of a table inside a virtual file.
Session.write_data(family, geometry, mode, …)	Write a GMT data container to a file.