pyissm.model.execute

ISSM execution commands to handle model marshalling and execution.

Functions

format_to_code(datatype)

Convert format string to integer code.

is_model_self_consistent(md)

Check that all relevant model classes in the given model are self-consistent. This function iterates over the model classes returned by md.model_class_names(), skips a small set of classes that are not subject to consistency checking ('results', 'debug', 'radaroverlay'), and invokes a consistency check on each model class that provides a check_consistency method. The routine: - Initializes md.private.isconsistent to True. - Retrieves the model solution and any associated analyses. - For each model class: - If the class does not expose a callable check_consistency it is skipped (a message is printed to stdout). - Otherwise, calls obj.check_consistency(md, solution, analyses). - If that call raises an exception, records a message via md.check_message and sets md.private.isconsistent to False. - If any consistency check fails (md.private.isconsistent becomes False), raises a RuntimeError to indicate the overall model is not consistent.

load_results_from_cluster(md[, no_log, ...])

Load results from cluster after job completion.

load_results_from_disk(md, filename)

Load simulation results from disk into a model object.

marshall(md)

Marshall the model data for execution.

parse_results_from_disk(md, filename)

Parse and load results from an ISSM binary file.

postprocess_qmu(md)

preprocess_qmu(md)

solve(md, solution_string[, batch, ...])

Solve an ISSM model with the specified solution type.

wait_on_lock(md)

Wait for a running ISSM job to complete by polling for a lock file.
pyissm.model.execute.format_to_code(datatype)

Convert format string to integer code.

This function maps data type strings to their corresponding integer codes used for data serialization and format identification.

Parameters:

datatype (str) – The data type string to convert. Supported types are: ‘Boolean’, ‘Integer’, ‘Double’, ‘String’, ‘BooleanMat’, ‘IntMat’, ‘DoubleMat’, ‘MatArray’, ‘StringArray’, ‘CompressedMat’.

Returns:

The integer code corresponding to the input data type.

Return type:

int

Raises:

IOError – If the provided datatype is not supported.

Examples

>>> format_to_code('Double')
3
>>> format_to_code('StringArray')
9
pyissm.model.execute.is_model_self_consistent(md)

Check that all relevant model classes in the given model are self-consistent. This function iterates over the model classes returned by md.model_class_names(), skips a small set of classes that are not subject to consistency checking (‘results’, ‘debug’, ‘radaroverlay’), and invokes a consistency check on each model class that provides a check_consistency method. The routine: - Initializes md.private.isconsistent to True. - Retrieves the model solution and any associated analyses. - For each model class:

  • If the class does not expose a callable check_consistency it is skipped

    (a message is printed to stdout).

  • Otherwise, calls obj.check_consistency(md, solution, analyses).

  • If that call raises an exception, records a message via md.check_message

    and sets md.private.isconsistent to False.

  • If any consistency check fails (md.private.isconsistent becomes False),

    raises a RuntimeError to indicate the overall model is not consistent.

Parameters:

md (object) –

The model object to validate. The object is expected to provide: - md.private, an attribute with at least isconsistent (bool) and

solution attributes;

  • md.model_class_names(), a callable that returns an iterable of model

    class name strings;

  • for each name returned by md.model_class_names(), an attribute on md

    with that name, representing the model class object;

  • md.check_message(msg: str), a callable used to record consistency

    failure messages.

Returns:

This function performs in-place updates to md (notably md.private.isconsistent) and does not return a value.

Return type:

None

Raises:

RuntimeError – If any per-class consistency check fails. In that case, md.private.isconsistent will be set to False and a RuntimeError is raised after the failing check(s) so callers are made aware that the model is not consistent.

Notes

  • Classes named ‘results’, ‘debug’, and ‘radaroverlay’ are intentionally skipped.

  • If a model class does not provide a callable check_consistency attribute,

    a message will be printed to stdout and the class will be skipped.

  • Consistency checks are expected to follow the signature:

    check_consistency(md, solution, analyses). Any exception raised by a check_consistency implementation will be caught, recorded via md.check_message, and treated as a failure.

  • This function mutates md.private.isconsistent; callers can inspect that value

    to determine consistency state prior to handling the RuntimeError.

pyissm.model.execute.load_results_from_cluster(md, no_log=False, runtime_name=None)

Load results from cluster after job completion.

Downloads output files from a remote cluster, loads the results into the model, and cleans up temporary files. Handles both standard ISSM runs and Dakota uncertainty quantification runs.

Parameters:

  • md (model) – ISSM model object containing cluster configuration and run parameters.

  • no_log (bool, optional) – If True, skip downloading log files (.outlog and .errlog). Default is False.

  • runtime_name (str, optional) – Name of the runtime directory on the cluster. If None, uses md.private.runtimename. Default is None.

Returns:

Updated model object with loaded results from the cluster run.

Return type:

model

Notes

This function performs the following operations: 1. Downloads output files from the cluster including: - Log files (.outlog, .errlog) unless no_log=True - Binary output files (.outbin or multiple files for Dakota sampling) - Dakota-specific files (qmu.err, qmu.out, dakota_tabular.dat, .stats) 2. Loads results from the binary output file into the model object 3. Cleans up downloaded files and removes temporary files 4. If run on the same platform as the cluster, removes input files (.bin, .toolkits, qmu.in, .queue/.bat) The function handles different file patterns depending on whether Dakota uncertainty quantification is used and what type of Dakota method is employed. Warnings are issued if expected files are not found during cleanup.

pyissm.model.execute.load_results_from_disk(md, filename)

Load simulation results from disk into a model object.

This function loads results from a binary file or processes QMU (Quantification of Margins and Uncertainties) results depending on the model configuration. It handles result parsing, error checking, log file reading, and result organization within the model structure.

Parameters:

  • md (object) – Model object containing simulation parameters, results structure, and configuration settings. Must have attributes like qmu, results, miscellaneous, and private.

  • filename (str) – Path to the binary file containing simulation results to be loaded.

Returns:

The modified model object with results loaded into the md.results attribute and solution type set in md.private.solution.

Return type:

object

Raises:

ValueError – If no results are found in the specified file.

Warning

UserWarning

  • If SolutionType field cannot be found in results

  • If errors are detected in the error log during solution

Notes

The function performs different operations based on whether QMU is enabled: - Non-QMU mode: Parses binary results, loads error/output logs, and

organizes results by solution type

  • QMU mode: Delegates to QMU-specific postprocessing

For non-QMU results, the function: 1. Verifies the result file exists 2. Initializes the results structure if needed 3. Parses results and determines solution type 4. Loads associated log files (.errlog and .outlog) 5. Extracts single solutions from lists for user convenience Log files are read as lists of strings with newlines removed. If no log files exist, empty strings are assigned to the respective log attributes.

Examples

>>> md = load_results_from_disk(md, 'simulation_results.bin')
>>> print(md.results.StressbalanceSolution.Vel)
pyissm.model.execute.marshall(md)

Marshall the model data for execution.

Parameters:

md (object) – The model data object to be marshalled. Must contain miscellaneous.name attribute and model classes with marshall_class methods.

Return type:

None

Raises:

  • IOError – If the binary output file cannot be opened or closed.

  • RuntimeError – If an error occurs while marshalling a model class.

Notes

This function iterates through all model classes in the md object and calls their marshall_class methods to serialize the data to a binary file. Certain classes (‘results’, ‘radaroverlay’, ‘toolkits’, ‘cluster’, ‘private’) are skipped during marshalling. The function writes an EOF marker at the end of the file to ensure data integrity.

pyissm.model.execute.parse_results_from_disk(md, filename)

Parse and load results from an ISSM binary file.

This function reads an ISSM binary results file and organizes all fields by solution step. It handles sequential reading of field records, groups them by time step, and returns a structured results object containing all solution data.

Parameters:

  • md (object) – Model data structure containing simulation parameters and configuration. Must have a constants attribute with yts (years to seconds conversion).

  • filename (str) – Path to the binary results file to be parsed.

Returns:

Structured results object containing all solution steps. Each step contains the fields and metadata for that particular solution time. Fields are organized as attributes accessible via dot notation.

Return type:

model.classes.results.solution

Raises:

  • IOError – If the specified results file cannot be opened for reading.

  • Exception – If no results are found in the binary file or if there are issues reading the binary data format.

Notes

The function performs the following operations: 1. Opens and sequentially reads all field records from the binary file 2. Extracts unique solution steps and organizes fields by step 3. Applies unit conversions and data formatting (e.g., flattening column vectors) 4. Returns a results object with fields accessible by step index

The binary file format is expected to contain field records with names, time stamps, step numbers, and data arrays in ISSM-specific format.

pyissm.model.execute.postprocess_qmu(md)
pyissm.model.execute.preprocess_qmu(md)
pyissm.model.execute.solve(md, solution_string, batch=False, check_consistency=True, restart=None, load_only=False, no_log=False, runtime_name=True)

Solve an ISSM model with the specified solution type.

This function configures and executes a solution for an ISSM Model. It maps solution strings to their corresponding solution classes, performs model consistency checks, and manages runtime naming conventions.

Parameters:

  • md (object) – Model data structure containing the ISSM model configuration.

  • solution_string (str) – String identifier for the solution type. Supported values include: - ‘sb’, ‘stressbalance’ : Stress balance solution - ‘mt’, ‘masstransport’ : Mass transport solution - ‘oceant’, ‘oceantransport’ : Ocean transport solution - ‘th’, ‘thermal’ : Thermal solution - ‘st’, ‘steadystate’ : Steady state solution - ‘tr’, ‘transient’ : Transient solution - ‘mc’, ‘balancethickness’ : Balance thickness solution - ‘mcsoft’ : Balance thickness soft solution - ‘bv’, ‘balancevelocity’ : Balance velocity solution - ‘bsl’, ‘bedslope’ : Bed slope solution - ‘ssl’, ‘surfaceslope’ : Surface slope solution - ‘hy’, ‘hydrology’ : Hydrology solution - ‘da’, ‘damageevolution’ : Damage evolution solution - ‘gia’ : GIA solution - ‘lv’, ‘love’ : Love solution - ‘esa’ : ESA solution - ‘smp’, ‘sampling’ : Sampling solution

  • batch (bool, optional) – Whether to run in batch mode, by default False.

  • check_consistency (bool, optional) – Whether to perform model consistency checks before solving, by default True.

  • restart (str, optional) – Directory name (relative to execution directory) where restart file is located, by default None.

  • load_only (bool, optional) – Whether to only load the solution without executing, by default False.

  • no_log (bool, optional) – Whether to suppress loading logs, by default False.

  • runtime_name (bool, optional) – Whether to generate a unique runtime name based on timestamp and process ID, by default True. If False, uses md.miscellaneous.name as runtime name.

Raises:

ValueError – If the provided solution_string is not recognized or supported.

Notes

The function modifies the model structure in-place by setting the solution type and runtime name. When runtime_name is True, a unique identifier is generated using the current timestamp and process ID to avoid clobbering existing runs.

Examples

>>> solve(md, 'stressbalance')
>>> solve(md, 'transient', check_consistency = False)
>>> solve(md, 'thermal', runtime_name = False)
pyissm.model.execute.wait_on_lock(md)

Wait for a running ISSM job to complete by polling for a lock file.

After the ISSM executable finishes, it writes a lock file {model_name}.lock inside the job’s execution directory on the cluster. This function polls for that file at a fixed interval until it appears (success) or the configured timeout is reached (failure).

Parameters:

md (object) –

Model data structure. The following attributes are used:

  • md.cluster.name — hostname of the cluster.

  • md.cluster.login — SSH login name.

  • md.cluster.port — SSH port (0 means default).

  • md.cluster.executionpath — root execution directory on the cluster.

  • md.private.runtimename — subdirectory for this particular run.

  • md.miscellaneous.name — model name (stem of the lock file).

  • md.settings.waitonlock — maximum number of minutes to wait.

  • md.verbose.solution — whether to print progress messages.

Returns:

True if the lock file was detected within the timeout period, False if the timeout expired before the lock file appeared.

Return type:

bool

Notes

The expected lock file path is:

{cluster.executionpath}/{runtimename}/{model_name}.lock

When the cluster hostname matches the local hostname the check is performed with os.path.exists(). Otherwise an SSH test -f command is used so that no output is produced on success or failure.

The poll interval is fixed at 5 seconds. A progress message is printed every minute when md.verbose.solution is True.