pyissm.tools.general

Utility functions for ISSM

This module contains various utility functions that are used throughout the ISSM codebase.

Functions

`compare_bin_files`(file1, file2[, out_file, ...])	Compare two ISSM binary files.
`convert_units`(input_units, output_units, data)	Convert numerical data between supported geophysical units.
`extract_field_layer`(md, field, layer)	Extract a 2D horizontal layer from a 3D field defined on the model's vertices.
`has_nested_attr`(obj, *attrs)	Check whether an object has a chain of nested attributes.
`ll_to_xy`(lat, lon, sign[, central_meridian, ...])	Convert geographic coordinates (latitude, longitude) to Cartesian coordinates (x, y) using the polar stereographic projection.
`planetradius`(planet)	Return the mean radius of a specified planetary body.
`summarize_solution`(solution)	Print a summary of field names, types, and sizes for an ISSM solution object.
`xy_to_ll`(x, y, sign[, central_meridian, ...])	Convert Cartesian coordinates (x, y) to geographic coordinates (latitude, longitude) using the polar stereographic projection.

pyissm.tools.general.compare_bin_files(file1, file2, out_file=None, *, compare_data=False, compare_shape=False, compare_format=False, compare_mattype=False)

Compare two ISSM binary files.

This function compares two binary files in ISSM format and reports differences based on the selected comparison mode. Exactly one of the comparison modes must be enabled.

Parameters:

file1 (str) – Path to the first binary file to compare.
file2 (str) – Path to the second binary file to compare.
out_file (str, optional) – Path to write the comparison report. If not provided, output is printed to the console. Default is None.
compare_data (bool, optional) – If True, compare the actual data values in the files. Default is False.
compare_shape (bool, optional) – If True, compare the shape of array fields. Default is False.
compare_format (bool, optional) – If True, compare the data type format of fields. Default is False.
compare_mattype (bool, optional) – If True, compare the matrix type codes of fields. Default is False.

Returns:

Output is either written to a file (if out_file is specified) or printed to the console.

Return type:

None

Raises:

ValueError – If exactly one of the compare_* options is not True.
TypeError – If an unsupported type code is encountered in the binary file.
struct.error – If there is an error reading the binary file format.

Notes

Exactly ONE of the compare_data, compare_shape, compare_format, or compare_mattype options must be True. An error will be raised if zero or more than one option is enabled.

The comparison report displays fields that are missing in either file, along with a status indicating whether values are the same or different based on the selected comparison mode.

pyissm.tools.general.convert_units(input_units, output_units, data, yts=31536000, rho_ice=917)

Convert numerical data between supported geophysical units.

This function supports a variety of conversions commonly required when working with ISSM input/output entities. Required constants are consistent with those used in the Ice sheet and Sea Level System Model (ISSM).

Parameters:

input_units (str) – Units of the input data. Must be one of: ‘m’, ‘km’, ‘ms-1’, ‘myr-1’, ‘m2’, ‘km2’, ‘Gt’, ‘km3’, ‘Gtyr-1’, ‘kgs-1’.
output_units (str) – Desired units for the output data. Must be one of: ‘m’, ‘km’, ‘ms-1’, ‘myr-1’, ‘m2’, ‘km2’, ‘Gt’, ‘km3’, ‘Gtyr-1’, ‘kgs-1’.
data (float, list, or ndarray) – Numerical value(s) to convert. Data are converted to array for computation.
yts (float or int, optional) – Seconds in a year (default = 365 * 24 * 60 * 60)
rho_ice (float or int, optional) – Ice density in kg/m3 (default: 917)

Returns:

converted_data – The data converted from input_units to output_units.

Return type:

float or ndarray

Raises:

ValueError – If input_units or output_units are not among the accepted units, or if the requested unit conversion is not supported.

Notes

The following unit conversions are supported:

Length: m <-> km
Area: m² <-> km²
Speed: m/s <-> m/yr
Volume: m³ <-> km³
Mass: Gt <-> km³ (using ice density 917 kg/m³)
Rate: Gt/yr <-> kg/s
Rate: kg/m²/s-1 <-> myr-1
Rate: kg/m²/s-1 <-> myr-1ie

pyissm.tools.general.extract_field_layer(md, field, layer)

Extract a 2D horizontal layer from a 3D field defined on the model’s vertices.

This function isolates a specific horizontal layer from a field defined over all 3D vertices of a model. Only vertex-based fields are supported; element-based fields will raise an error.

Parameters:

md (ISSM Model object) – ISSM Model object containing mesh. Must be compatible with process_mesh().
field (np.ndarray) – A 1D array of shape ‘md.mesh.numberofvertices’ representing a 3D field defined on vertices.
layer (int) – The vertical layer index to extract (1-based). Must be a single integer. Layer indexing starts from 1 (base) to ‘md.mesh.numberoflayers’ (surface).

Returns:

select_layer (np.ndarray) – A 1D array of shape ‘md.mesh.numberofvertices2d’ or ‘md.mesh.numberofelements2d’ containing the field values at the specified layer.
select_indices (np.ndarray) – A 1D array of shape ‘md.mesh.numberofvertices2d’ or ‘md.mesh.numberofelements2d’ containing the indices of vertices/elements associated with the specified layer.

Notes

This function assumes that the 3D vertex/element ordering in ‘field’ is layer-major: i.e., all vertices/elements in layer 1 come first, then layer 2, and so on.
Depth-averaging functionality (e.g., specifying a range of layers) is not yet implemented.

Example

field_2d, select_indices = extract_field_layer(md, md.results.TransientSolution.Temperature[0], layer = 1) field_2d, select_indices = extract_field_layer(md, md.materials.rheology_n, layer = 6)

pyissm.tools.general.has_nested_attr(obj, *attrs)

Check whether an object has a chain of nested attributes.

This function tests whether an object has a sequence of attributes, each accessible from the previous one, such as obj.a.b.c.

Parameters:

obj (object) – The base object from which to start the attribute lookup.
*attrs (str) – A sequence of attribute names representing the path to check. Each string in attrs should be a valid attribute of the previous one.

Returns:

has_attr – True if all nested attributes exist, False otherwise.

Return type:

bool

pyissm.tools.general.ll_to_xy(lat, lon, sign, central_meridian=None, standard_parallel=None)

Convert geographic coordinates (latitude, longitude) to Cartesian coordinates (x, y) using the polar stereographic projection.

Parameters:

lat (array_like) – The latitude in degrees.
lon (array_like) – The longitude in degrees.
sign (int) – The hemisphere indicator, where 1 indicates the northern hemisphere and -1 indicates the southern hemisphere.
central_meridian (float, optional) – The central meridian in degrees. If not specified, defaults are used based on the hemisphere.
standard_parallel (float, optional) – The standard parallel in degrees. If not specified, defaults are used based on the hemisphere.

Returns:

x (ndarray) – The x-coordinates in meters.
y (ndarray) – The y-coordinates in meters.

Raises:

ValueError – If sign is not 1 or -1. If only one of central_meridian or standard_parallel is specified.

Notes

The function uses the WGS84 ellipsoid parameters for the conversion. Special handling is included for the case when standard_parallel is 90 degrees.

pyissm.tools.general.planetradius(planet)

Return the mean radius of a specified planetary body.

Parameters:: planet (str) – Name of the planet. Supported values are: - ‘earth’ : Earth’s mean radius in meters. - ‘europa’ : Europa’s mean radius in meters.
Returns:: radius – Planetary radius in meters.
Return type:: float
Raises:: TypeError – If the input planet is not one of the supported values.

pyissm.tools.general.summarize_solution(solution): Print a summary of field names, types, and sizes for an ISSM solution object.

pyissm.tools.general.xy_to_ll(x, y, sign, central_meridian=None, standard_parallel=None)

Convert Cartesian coordinates (x, y) to geographic coordinates (latitude, longitude) using the polar stereographic projection.

Parameters:

x (array_like) – The x-coordinates in meters.
y (array_like) – The y-coordinates in meters.
sign (int) – The hemisphere indicator, where 1 indicates the northern hemisphere and -1 indicates the southern hemisphere.
central_meridian (float, optional) – The central meridian in degrees. If not specified, defaults are used based on the hemisphere.
standard_parallel (float, optional) – The standard parallel in degrees. If not specified, defaults are used based on the hemisphere.

Returns:

lat (ndarray) – The latitude in degrees.
lon (ndarray) – The longitude in degrees, adjusted by the central meridian.

Raises:

ValueError – If sign is not 1 or -1. If only one of central_meridian or standard_parallel is specified.

Notes

The function uses the WGS84 ellipsoid parameters for the conversion. Special handling is included for the case when standard_parallel is 90 degrees.