pyissm.tools.config

Configuration functions for ISSM

This module contains various functions that relate to the configuration of the ISSM codebase.

Functions

`gamg_gpu_options`(**kwargs)	Set GPU-accelerated PETSc GAMG options for linear solver configuration.
`get_hostname`()	Get the hostname of the current machine.
`get_issm_dir`()	Return the ISSM installation directory, or None if not configured.
`get_username`()	Get the username of the current user.
`hypre_boomeramg_gpu_options`(**kwargs)	Set GPU-accelerated Hypre BoomerAMG options for PETSc linear solver configuration.
`iluasm_options`(**kwargs)	Set the ILU-ASM options for PETSc linear solver configuration.
`is_pc`()	Check if the current operating system is Windows.
`issm_gsl_solver`(**kwargs)	Set the GSL solver options for ISSM linear solver configuration.
`issm_mumps_solver`(**kwargs)	Set the ISSM MUMPS solver options.
`mumps_options`(**kwargs)	Set the MUMPS options for PETSc linear solver configuration.

pyissm.tools.config.gamg_gpu_options(**kwargs)

Set GPU-accelerated PETSc GAMG options for linear solver configuration.

This function configures a BiCGStab solve preconditioned by PETSc’s native GAMG algebraic multigrid, using cuSPARSE matrices and CUDA vectors. Requires ISSM to be built with CUDA support (+cuda).

Parameters:: **kwargs (dict) – Additional PETSc options to override or supplement the defaults.
Returns:: Dictionary containing the GPU GAMG configuration options with defaults updated with any user-provided options.
Return type:: collections.OrderedDict

Notes

The *_backend_cpu false flags force the Galerkin triple products used to build the multigrid hierarchy onto the device; without them PETSc falls back to host assembly and the setup phase dominates the runtime.

Examples

>>> md.toolkits.DefaultAnalysis = gamg_gpu_options()
>>> opts = gamg_gpu_options(pc_gamg_threshold=0.05)

pyissm.tools.config.get_hostname()

Get the hostname of the current machine.

This function retrieves the hostname of the machine on which the code is running.

Returns:: The hostname of the current machine.
Return type:: str

Examples

>>> hostname = get_hostname()

pyissm.tools.config.get_issm_dir()

Return the ISSM installation directory, or None if not configured.

This function checks the appropriate ISSM_DIR environment variable (ISSM_DIR_WIN on Windows, ISSM_DIR otherwise). If the variable is not set, it issues a warning with instructions and returns None.

pyissm.tools.config.get_username()

Get the username of the current user.

This function retrieves the username of the user currently logged into the system by querying the appropriate environment variable based on the operating system.

Returns:: The username of the current user. Returns an empty string if the username cannot be determined.
Return type:: str

Examples

>>> username = get_username()
>>> print(username)
'john_doe'

pyissm.tools.config.hypre_boomeramg_gpu_options(**kwargs)

Set GPU-accelerated Hypre BoomerAMG options for PETSc linear solver configuration.

This function configures a GMRES solve preconditioned by Hypre’s BoomerAMG algebraic multigrid, with matrices and vectors resident on the GPU. Requires ISSM to be built with both CUDA and Hypre support (+cuda +hypre).

Parameters:: **kwargs (dict) – Additional PETSc options to override or supplement the defaults.
Returns:: Dictionary containing the GPU BoomerAMG configuration options with defaults updated with any user-provided options.
Return type:: collections.OrderedDict

Notes

The hypre matrix type keeps the operator in Hypre’s own device format, which avoids a PETSc-to-Hypre conversion on every solve. mat_block_size 2 reflects the two velocity components of the SSA/HO stress balance.

Examples

>>> md.toolkits.DefaultAnalysis = hypre_boomeramg_gpu_options()
>>> opts = hypre_boomeramg_gpu_options(pc_hypre_boomeramg_strong_threshold=0.5)

pyissm.tools.config.iluasm_options(**kwargs)

Set the ILU-ASM options for PETSc linear solver configuration.

This function configures ILU (Incomplete LU factorization) with ASM (Additive Schwarz Method) preconditioner options for PETSc. It provides default settings for iterative solving and allows user customization through keyword arguments.

Parameters:: **kwargs (dict) – Additional ILU-ASM options to override or supplement the defaults.
Returns:: Dictionary containing ILU-ASM configuration options with defaults updated with any user-provided options.
Return type:: collections.OrderedDict

Notes

The function sets up an iterative solver configuration with: - AIJ matrix type for sparse matrices - GMRES Krylov subspace method - Additive Schwarz Method (ASM) preconditioner with ILU subdomain solver - 5-level overlap between subdomains - Maximum 100 iterations with relative tolerance of 1e-15

Examples

>>> opts = iluasm_options()
>>> opts = iluasm_options(ksp_max_it=200)
>>> opts = iluasm_options(pc_asm_overlap=10, ksp_rtol=1e-12)

pyissm.tools.config.is_pc()

Check if the current operating system is Windows.

This function determines whether the code is running on a Windows operating system.

Returns:: True if the operating system is Windows, False otherwise.
Return type:: bool

Examples

>>> is_windows = is_pc()
>>> print(is_windows)
True

pyissm.tools.config.issm_gsl_solver(**kwargs)

Set the GSL solver options for ISSM linear solver configuration.

This function configures GSL (GNU Scientific Library) solver options for use with the ISSM toolkit. It provides default settings optimized for ISSM’s native GSL solver interface and allows user customization through keyword arguments.

Parameters:: **kwargs (dict) – Additional GSL solver options to override or supplement the defaults.
Returns:: Dictionary containing GSL solver configuration options with defaults updated with any user-provided options.
Return type:: collections.OrderedDict

Notes

This function sets up ISSM’s native GSL solver interface with: - ‘dense’ matrix type for dense matrix operations - ‘seq’ vector type for sequential vector operations - ‘gsl’ solver type for GSL-based solving

Examples

>>> opts = issm_gsl_solver()
>>> opts = issm_gsl_solver(solver_type='gsl')

pyissm.tools.config.issm_mumps_solver(**kwargs)

Set the ISSM MUMPS solver options.

This function configures MUMPS (MUltifrontal Massively Parallel sparse direct Solver) options for use with the ISSM toolkit. It provides default settings optimized for ISSM’s native solver interface and allows user customization through keyword arguments.

Parameters:: **kwargs (dict) – Additional MUMPS options to override or supplement the defaults.
Returns:: Dictionary containing ISSM MUMPS solver configuration options with defaults updated with any user-provided options.
Return type:: collections.OrderedDict

Notes

This function sets up ISSM’s native MUMPS solver interface with: - ‘mpisparse’ matrix type for ISSM’s sparse matrix format - ‘mpi’ vector type for parallel vector operations - ‘mumps’ solver type for direct factorization

Examples

>>> opts = issm_mumps_solver()
>>> opts = issm_mumps_solver(solver_type='mumps')

pyissm.tools.config.mumps_options(**kwargs)

Set the MUMPS options for PETSc linear solver configuration.

This function configures MUMPS (MUltifrontal Massively Parallel sparse direct Solver) options based on the PETSc version detected in the system. It provides version-specific defaults and allows user customization through keyword arguments.

Parameters:: **kwargs (dict) – Additional MUMPS options to override or supplement the defaults.
Returns:: Dictionary containing MUMPS configuration options with PETSc version-specific defaults updated with any user-provided options.
Return type:: collections.OrderedDict

Notes

The function automatically detects PETSc major and minor versions and sets appropriate defaults: - PETSc v2.x: Uses ‘aijumps’ matrix type - PETSc v3.x: Uses ‘mpiaij’ matrix type with additional solver package configuration For PETSc v3.9+, uses ‘pc_factor_mat_solver_type’, otherwise uses the deprecated ‘pc_factor_mat_solver_package’.

Examples

>>> opts = mumps_options()
>>> opts = mumps_options(mat_mumps_icntl_14=200)
>>> opts = mumps_options(mat_mumps_icntl_28=2, mat_mumps_icntl_29=1)