pyissm.model.classes.inversion

Inversion classes for ISSM.

Classes

adm1qn3([other])	ADM1QN3 inversion parameters for ISSM.
default([other])	Default inversion class for ISSM.
m1qn3([other])	m1qn3 inversion class for ISSM.
tao([other])	tao inversion class for ISSM.

class pyissm.model.classes.inversion.adm1qn3(other=None)

Bases: manage_state

ADM1QN3 inversion parameters for ISSM.

This class configures the ADM1QN3 inversion driver (ISSM inversion type = 4). It is the Python equivalent of the MATLAB adm1qn3inversion class, but follows the same pyISSM conventions as other inversion classes (e.g. inversion.m1qn3, inversion.tao):

• construction via defaults + optional inheritance from other

• check_consistency validation

• marshall_class serialization to ISSM binary format

• a no-op extrude for interface consistency

ADM1QN3 provides a quasi-Newton style optimization loop with tunable iteration limits and convergence thresholds. This class only stores the optimizer-level settings; model-dependent inversion fields (e.g. observations, cost functions, control parameters) are handled by other inversion types/classes.

Parameters:

other (any, optional) – Any other class object that contains common fields to inherit from. If values in other differ from default values, they will override the default values.

iscontrol

Flag enabling inversion (0: off, 1: on). When 0, check_consistency and marshall_class will early-return and write only the minimal fields.

Type:

int

maxsteps

Maximum number of gradient evaluations (outer iterations).

Type:

int

maxiter

Maximum number of function evaluations (forward model runs).

Type:

int

dxmin

Convergence threshold on the parameter update size. Two iterates closer than dxmin in sup-norm are treated as identical (MATLAB parity).

Type:

float

dfmin_frac

Expected fractional reduction of the objective during the first step. Example: 0.3 corresponds to an expected 30% reduction.

Type:

float

gttol

Gradient convergence criterion measured relative to the initial gradient: ||g(X)|| / ||g(X0)||.

Type:

float

Notes

• The M1QN3 availability check uses tools.wrappers.IssmConfig("_HAVE_M1QN3_") when Python wrappers are available. If wrappers are unavailable, the check is skipped with a warning (mirroring patterns elsewhere in pyISSM).

• This class intentionally does not define cost functions, observation vectors, or control parameters: those belong to other inversion formulations in pyISSM.

Examples

check_consistency(md, solution, analyses)

Check consistency of the [inversion.adm1qn3] parameters.

Parameters:

• md (pyissm.model.Model) – The model object to check.

• solution (str) – The solution name to check.

• analyses (list of str) – List of analyses to check consistency for.

Returns:

md – The model object with any consistency errors noted.

Return type:

pyissm.model.Model

marshall_class(fid, prefix, md=None)

Marshall [inversion.adm1qn3] parameters to a binary file.

Parameters:

• fid (file object) – The file object to write the binary data to.

• prefix (str) – Prefix string used for data identification in the binary file.

• md (pyissm.model.Model, optional) – ISSM model object needed in some cases.

Return type:

None

class pyissm.model.classes.inversion.default(other=None)

Bases: manage_state

Default inversion class for ISSM.

This class contains the default parameters for the inversion process in the ISSM framework.

Parameters:

other (any, optional) – Any other class object that contains common fields to inherit from. If values in other differ from default values, they will override the default values.

iscontrol

Is inversion activated? (0: no, 1: yes)

Type:

int, default=0

incomplete_adjoint

1: linear viscosity, 0: non-linear viscosity

Type:

int, default=1

control_parameters

Control parameter(s) for inversion (e.g., ‘FrictionCoefficient’, ‘MaterialsRheologyBbar’)

Type:

str, default=’FrictionCoefficient’

nsteps

Number of optimization searches

Type:

int, default=20

maxiter_per_step

Maximum iterations during each optimization step

Type:

numpy.ndarray, default=20*np.ones(nsteps)

cost_functions

Type of response for each optimization step

Type:

str, default=’List of cost functions’

cost_functions_coefficients

Coefficients applied to the misfit of each vertex and for each control parameter

Type:

numpy.ndarray, default=np.nan

gradient_scaling

Scaling factor on gradient direction during optimization, for each optimization step

Type:

numpy.ndarray, default=50*np.ones((nsteps, 1))

cost_function_threshold

Misfit convergence criterion. Default is 1%, NaN if not applied

Type:

float, default=np.nan

min_parameters

Absolute minimum acceptable value of the inversed parameter on each vertex

Type:

float, default=np.nan

max_parameters

Absolute maximum acceptable value of the inversed parameter on each vertex

Type:

float, default=np.nan

step_threshold

Decrease threshold for misfit, default is 30%

Type:

numpy.ndarray, default=0.7*np.ones(nsteps)

vx_obs

Observed velocity x component [m/yr]

Type:

numpy.ndarray, default=np.nan

vy_obs

Observed velocity y component [m/yr]

Type:

numpy.ndarray, default=np.nan

vz_obs

Observed velocity z component [m/yr]

Type:

numpy.ndarray, default=np.nan

vel_obs

Observed velocity magnitude [m/yr]

Type:

numpy.ndarray, default=np.nan

thickness_obs

Observed thickness [m]

Type:

numpy.ndarray, default=np.nan

surface_obs

Observed surface elevation [m]

Type:

numpy.ndarray, default=np.nan

Examples

>>> md.inversion = pyissm.model.classes.inversion.default()

check_consistency(md, solution, analyses)

Check consistency of the [inversion.default] parameters.

Parameters:

• md (pyissm.model.Model) – The model object to check.

• solution (str) – The solution name to check.

• analyses (list of str) – List of analyses to check consistency for.

Returns:

md – The model object with any consistency errors noted.

Return type:

pyissm.model.Model

marshall_class(fid, prefix, md=None)

Marshall [inversion.default] parameters to a binary file.

Parameters:

• fid (file object) – The file object to write the binary data to.

• prefix (str) – Prefix string used for data identification in the binary file.

• md (pyissm.model.Model, optional) – ISSM model object needed in some cases.

Return type:

None

class pyissm.model.classes.inversion.m1qn3(other=None)

Bases: manage_state

m1qn3 inversion class for ISSM.

This class includes the default parameters for the ISSM inversion process using the m1qn3 optimization algorithm in the ISSM framework.

Parameters:

other (any, optional) – Any other class object that contains common fields to inherit from. If values in other differ from default values, they will override the default values.

iscontrol

Is inversion activated? (0: no, 1: yes)

Type:

int, default=0

incomplete_adjoint

1: linear viscosity, 0: non-linear viscosity

Type:

int, default=1

control_parameters

Control parameter(s) for inversion (e.g., ‘FrictionCoefficient’, ‘MaterialsRheologyBbar’)

Type:

str, default=’FrictionCoefficient’

control_scaling_factors

Order of magnitude of each control (useful for multi-parameter optimization)

Type:

float or numpy.ndarray, default=1

maxsteps

Maximum number of iterations (gradient computation)

Type:

int, default=20

maxiter

Maximum number of function evaluations (forward run)

Type:

int, default=40

dxmin

Convergence criterion: two points less than dxmin from each other (sup-norm) are considered identical

Type:

float, default=0.1

dfmin_frac

Expected reduction of cost function during the first step (e.g., 0.3 = 30% reduction)

Type:

float, default=1.0

gttol

||g(X)||/||g(X0)|| (g(X0): gradient at initial guess X0)

Type:

float, default=1e-4

cost_functions

Type of response for each optimization step

Type:

int or list, default=101

cost_functions_coefficients

Coefficients applied to the misfit of each vertex and for each control parameter

Type:

numpy.ndarray, default=np.nan

min_parameters

Absolute minimum acceptable value of the inversed parameter on each vertex

Type:

float, default=np.nan

max_parameters

Absolute maximum acceptable value of the inversed parameter on each vertex

Type:

float, default=np.nan

vx_obs

Observed velocity x component [m/yr]

Type:

numpy.ndarray, default=np.nan

vy_obs

Observed velocity y component [m/yr]

Type:

numpy.ndarray, default=np.nan

vz_obs

Observed velocity z component [m/yr]

Type:

numpy.ndarray, default=np.nan

vel_obs

Observed velocity magnitude [m/yr]

Type:

numpy.ndarray, default=np.nan

thickness_obs

Observed thickness [m]

Type:

numpy.ndarray, default=np.nan

surface_obs

Observed surface elevation [m]

Type:

numpy.ndarray, default=np.nan

Examples

>>> md.inversion = pyissm.model.classes.inversion.m1qn3()

check_consistency(md, solution, analyses)

Check consistency of the [inversion.m1qn3] parameters.

Parameters:

• md (pyissm.model.Model) – The model object to check.

• solution (str) – The solution name to check.

• analyses (list of str) – List of analyses to check consistency for.

Returns:

md – The model object with any consistency errors noted.

Return type:

pyissm.model.Model

marshall_class(fid, prefix, md=None)

Marshall [inversion.m1qn3] parameters to a binary file.

Parameters:

• fid (file object) – The file object to write the binary data to.

• prefix (str) – Prefix string used for data identification in the binary file.

• md (pyissm.model.Model, optional) – ISSM model object needed in some cases.

Return type:

None

class pyissm.model.classes.inversion.tao(other=None)

Bases: manage_state

tao inversion class for ISSM.

This class contains the default parameters for the ISSM inversion process using the TAO optimization algorithms in the ISSM framework.

Parameters:

other (any, optional) – Any other class object that contains common fields to inherit from. If values in other differ from default values, they will override the default values.

iscontrol

Is inversion activated? (0: no, 1: yes)

Type:

int, default=0

incomplete_adjoint

1: linear viscosity, 0: non-linear viscosity

Type:

int, default=1

control_parameters

Control parameter(s) for inversion (e.g., ‘FrictionCoefficient’, ‘MaterialsRheologyBbar’)

Type:

str, default=’FrictionCoefficient’

maxsteps

Maximum number of iterations (gradient computation)

Type:

int, default=20

maxiter

Maximum number of function evaluations (forward run)

Type:

int, default=30

fatol

Absolute tolerance for cost function convergence (f(X) - f(X*))

Type:

float, default=0

frtol

Relative tolerance for cost function convergence (|f(X) - f(X*)| / |f(X*)|)

Type:

float, default=0

gatol

Absolute tolerance for gradient norm convergence (||g(X)||)

Type:

float, default=0

grtol

Relative tolerance for gradient norm convergence (||g(X)|| / |f(X)|)

Type:

float, default=0

gttol

Tolerance for gradient norm relative to initial (||g(X)|| / ||g(X0)||)

Type:

float, default=1e-4

algorithm

Minimization algorithm: ‘blmvm’, ‘cg’, ‘lmvm’

Type:

str, default=’blmvm’

cost_functions

Type of response for each optimization step

Type:

int or list, default=101

cost_functions_coefficients

Coefficients applied to the misfit of each vertex and for each control parameter

Type:

numpy.ndarray, default=np.nan

min_parameters

Absolute minimum acceptable value of the inversed parameter on each vertex

Type:

float, default=np.nan

max_parameters

Absolute maximum acceptable value of the inversed parameter on each vertex

Type:

float, default=np.nan

vx_obs

Observed velocity x component [m/yr]

Type:

numpy.ndarray, default=np.nan

vy_obs

Observed velocity y component [m/yr]

Type:

numpy.ndarray, default=np.nan

vz_obs

Observed velocity z component [m/yr]

Type:

numpy.ndarray, default=np.nan

vel_obs

Observed velocity magnitude [m/yr]

Type:

numpy.ndarray, default=np.nan

thickness_obs

Observed thickness [m]

Type:

numpy.ndarray, default=np.nan

surface_obs

Observed surface elevation [m]

Type:

numpy.ndarray, default=np.nan

Examples

>>> md.inversion = pyissm.model.classes.inversion.tao()

check_consistency(md, solution, analyses)

Check consistency of the [inversion.tao] parameters.

Parameters:

• md (pyissm.model.Model) – The model object to check.

• solution (str) – The solution name to check.

• analyses (list of str) – List of analyses to check consistency for.

Returns:

md – The model object with any consistency errors noted.

Return type:

pyissm.model.Model

marshall_class(fid, prefix, md=None)

Marshall [inversion.tao] parameters to a binary file.

Parameters:

• fid (file object) – The file object to write the binary data to.

• prefix (str) – Prefix string used for data identification in the binary file.

• md (pyissm.model.Model, optional) – ISSM model object needed in some cases.

Return type:

None