pyissm.model.io

Functions for reading and writing ISSM models.

This module contains functions for reading and writing ISSM models to and from files.

Functions

`export_gridded_model`(md, out_file, grid_x, ...)	Export gridded model variables to a NetCDF file based on a variable mapping specification.
`issm_scp_in`(host, login, port, path, packages)	Transfer files from a remote host to the current working directory using SCP or local copy.
`issm_scp_out`(host, path, login, port, packages)	Copy files to a remote host using SCP or create symbolic links for local transfers.
`issm_ssh`(host, login, port, command)	Execute a command on a remote host via SSH or locally if on the same machine.
`load_model`(path)	Load an ISSM model from a NetCDF file.
`save_model`(md, path[, verbose])	Save an ISSM model to a NetCDF file.

pyissm.model.io.export_gridded_model(md, out_file, grid_x, grid_y, variable_map=None, method='linear', domain_mask=None, fill_value=nan)

Export gridded model variables to a NetCDF file based on a variable mapping specification.

This function interpolates ISSM model output variables onto a regular 2D grid and writes the results to a NetCDF file. Variables are defined in a variable map which specifies the desired output name, source location in the model, and optional unit conversions.

Parameters:

md (object) – The ISSM model object containing simulation results and mesh information.
out_file (str) – Path to the output NetCDF file.
grid_x (ndarray) – 2D array of X coordinates for the regular grid.
grid_y (ndarray) – 2D array of Y coordinates for the regular grid.
variable_map (str or pd.DataFrame, optional) – Custom variable mapping specification. If a string, it should be the path to a CSV file mapping model variables to output variable names and metadata. If a DataFrame, it should contain the same columns as the CSV file. If not provided, a default variable map will be used located in ../assets/default_variable_map.csv relative to this script.
method (str, optional) – Interpolation method used to grid model data. Specific variables override this option. Options are ‘linear’, ‘nearest’, etc. Default is ‘linear’.
domain_mask (ndarray, optional) – A boolean or numerical mask to apply to the output grid. If provided, values outside the domain are masked or set to fill_value.
fill_value (float, optional) – Value to use for missing or masked data in the NetCDF output. Default is np.nan.

Raises:

FileNotFoundError – If the variable map CSV file does not exist.
ValueError – If the variable map file contains duplicate output variable names.
Exception – If any unexpected error occurs during export. The output file is removed in this case.

Notes

Supports both static and time-dependent model fields.
Handles custom unit conversions as defined in the variable map.
Includes ISMIP-specific variable logic where applicable.
Output NetCDF will contain grid_x, grid_y, and optionally time dimensions.

pyissm.model.io.issm_scp_in(host, login, port, path, packages)

Transfer files from a remote host to the current working directory using SCP or local copy.

This function transfers specified packages (files) from a remote path to the current working directory. If the host is the same as the local hostname, it performs a local copy operation. Otherwise, it uses SCP (Secure Copy Protocol) to transfer files from the remote host.

Parameters:

host (str) – The hostname or IP address of the remote host.
login (str) – The username for authentication on the remote host.
port (int or None) – The SSH port number for the remote connection. If None, uses default port 22.
path (str) – The remote directory path where the packages are located.
packages (list of str) – List of filenames to transfer from the remote host.

Raises:

Exception – If the SCP command fails with an error.
OSError – If a package does not exist after the transfer operation.

Warning

UserWarning: If a package does not exist on the local host during local copy operation.

Notes

The function first attempts standard SCP commands. If those fail, it retries with legacy SSH options (-OT flags) to handle compatibility issues with different SSH configurations. For local transfers (when host matches local hostname), the function uses shutil.copy and ignores any OSError exceptions that may occur during the copy operation.

pyissm.model.io.issm_scp_out(host, path, login, port, packages)

Copy files to a remote host using SCP or create symbolic links for local transfers. This function transfers files either by creating symbolic links (for local transfers where host matches hostname) or by using the SCP protocol for remote transfers. For remote transfers, it attempts standard SCP first and falls back to legacy SSH options if the initial attempt fails.

Parameters:

host (str) – Target hostname or IP address for file transfer.
path (str) – Destination directory path on the target host.
login (str) – Username for authentication on the remote host.
port (int or None) – SSH port number for connection. If None, uses default port 22.
packages (list of str) – List of file/package names to transfer from current working directory.

Raises:

Exception – If SCP transfer fails after attempting both standard and legacy options.

Warning

UserWarning: When a package file does not exist and will be skipped during local transfer.

Notes

For local transfers (same hostname), the function: - Creates symbolic links in the destination path - Removes existing files with same names before linking - Skips non-existent packages with warnings For remote transfers, the function: - Attempts standard SCP first - Falls back to SCP with legacy SSH options (-OT) if standard fails - Supports custom port specification with -P flag

Examples

>>> # Local transfer
>>> issm_scp_out('localhost', '/tmp/dest', 'user', None, ['file1.txt', 'file2.dat'])
>>> # Remote transfer with custom port
>>> issm_scp_out('remote.server.com', '/home/user/data', 'username', 2222, ['data.bin'])

pyissm.model.io.issm_ssh(host, login, port, command)

Execute a command on a remote host via SSH or locally if on the same machine.

This function determines whether to run a command locally or remotely based on hostname comparison. For remote execution, it uses platform-specific SSH clients: plink.exe on Windows and standard ssh on Mac/Linux. Includes a workaround for macOS file descriptor blocking issues.

Parameters:

host (str) – The hostname or IP address of the target machine.
login (str) – The username for SSH authentication.
port (int or None) – The SSH port number. If None, uses default SSH port (22).
command (str) – The command to execute on the target machine.

Notes

On Windows, requires plink.exe in the ISSM external packages directory
Prompts for username and password interactively on Windows
On macOS, applies file descriptor flags to prevent “Resource temporarily unavailable” errors
Uses shell=True for subprocess calls, which may have security implications

pyissm.model.io.load_model(path)

Load an ISSM model from a NetCDF file.

This function reads an ISSM model that has been saved in NetCDF format, reconstructing all model components including mesh, materials, geometry, boundary conditions, and results. The function handles nested objects and properly deserializes the complete model state.

Parameters:

path (str) – Path to the NetCDF file containing the ISSM model data.

Returns:

The reconstructed ISSM model object with all components loaded from the NetCDF file.

Return type:

model.Model

Raises:

FileNotFoundError – If the specified NetCDF file does not exist.
ValueError – If the NetCDF file is corrupted or missing required metadata.

Notes

The function automatically handles different data types and converts NaN values to numpy.nan for consistency
TransientSolution results are automatically expanded from collapsed format back to individual timesteps
Missing or corrupted groups are skipped with warning messages