invert4geom.Inversion

class Inversion(data, model, style='geometry', max_iterations=100, l2_norm_tolerance=0.2, delta_l2_norm_tolerance=1.001, perc_increase_limit=0.2, deriv_type='annulus', jacobian_finite_step_size=1, model_properties_method='itertools', solver_type='scipy least squares', solver_damping=None, apply_weighting_grid=False, weighting_grid=None)

A class which holds the gravity dataset, the model dataset, inversion stopping criteria, parameters which control the inversion, and methods used to run the inversion and cross-validations.

Data and model are both deep copied, so changes to the original datasets will not be reflected by the datasets assigned as attributes to this instance, and changes to the data and model made during an inversion will not affect the original objects.

Parameters:

• data (Dataset) – A dataset containing the gravity data, which has been initialized with create_data, contains variable forward_gravity calculated with DatasetAccessorInvert4Geom.forward_gravity, and contains variables misfit, reg, and res, calculated with DatasetAccessorInvert4Geom.regional_separation.

• model (Dataset) – A dataset containing the prism or tesseroid layer, which has been initialized with create_model.

• style (str) – style of inversion to run, ‘geometry’ for changing the topography of the model, or ‘density’ for changing the density contrast of the model, by default ‘geometry’

• max_iterations (int) – Stop the inversion once this number of iterations is reached, by default 100

• l2_norm_tolerance (float) – Stop the inversion once the L2-norm (square root of the RMS residual misfit) is less than this L2 norm tolerance, by default 0.2 mGal

• delta_l2_norm_tolerance (float) – Stop the inversion once the relative change in L2-norm is less than this tolerance, by default 1.001, which means the L2 norm must decrease by at least 0.1% each iteration.

• perc_increase_limit (float) – Stop the inversion if the L2-norm ever increases above the minimum L2-norm (of an iteration) by this decimal percentage amount, by default 0.20, which means if some iteration had an L2-norm of 1 mGal, if any subsequent iteration has an L2-norm greater than 1.2 mGal the inversion will terminate.

• deriv_type (str) – The method to use for calculated the derivative for the Jacobian matrix. Choose between annulus, for an annular approximation or finite_difference, for a finite difference approximation, by default annulus

• jacobian_finite_step_size (float) – small change in density or thickness of the prisms/tesseroids used to calculate entries of the jacobian, by default 1 or tesseroid for the finite difference approximation, by default 1

• model_properties_method (str) – method to use to extract prism properties while calculating the Jacobian. Choose between itertools, generator, or forloops, by default itertools

• solver_type (str) – method to use for solving Ax=b to find each iteration’s topographic correction grid, by default scipy least squares

• solver_damping (float | None) – Damping factor for the solver, typically between 0 and 1, by default None

• apply_weighting_grid (bool) – Whether to apply a weighting grid to the inversion, by default False

• weighting_grid (DataArray | None) – Weighting grid to apply to the inversion, created through normalized_mindist, by default None

__init__(data, model, style='geometry', max_iterations=100, l2_norm_tolerance=0.2, delta_l2_norm_tolerance=1.001, perc_increase_limit=0.2, deriv_type='annulus', jacobian_finite_step_size=1, model_properties_method='itertools', solver_type='scipy least squares', solver_damping=None, apply_weighting_grid=False, weighting_grid=None)

Initialize the inversion object.

Parameters:

• data (Dataset)

• model (Dataset)

• style (str)

• max_iterations (int)

• l2_norm_tolerance (float)

• delta_l2_norm_tolerance (float)

• perc_increase_limit (float)

• deriv_type (str)

• jacobian_finite_step_size (float)

• model_properties_method (str)

• solver_type (str)

• solver_damping (float | None)

• apply_weighting_grid (bool)

• weighting_grid (DataArray | None)

Methods

__init__(data, model[, style, ...])	Initialize the inversion object.
constraints_cv_score(constraints_df[, ...])	DEPRECATED: use the constraints_score function instead
constraints_score(constraints_df[, ...])	Find the score, represented by the root mean squared error (RMSE), between the constraint point elevation, and the inverted topography at the constraint points.
end_inversion()	check if the inversion should be terminated
grav_cv_score([results_fname, ...])	DEPRECATED: use the gravity_score function instead
gravity_score([results_fname, ...])	Find the score, represented by the root mean (or median) squared error (RMSE), between the testing gravity data, and the predict gravity data after an inversion.
invert([results_fname, progressbar, ...])	Start the inversion, saving the results and parameters as attributes and new variables in the data and model datasets attributes.
jacobian_density()	dispatcher for creating the jacobian matrix for a density inversion
jacobian_geometry()	dispatcher for creating the jacobian matrix for a geometry inversion with 2 method options
optimize_inversion_damping(n_trials, ...[, ...])	Use Optuna to find the optimal damping regularization parameter for a gravity inversion.
optimize_inversion_zref_density_contrast(...)	Run an Optuna optimization to find the optimal zref and or density contrast values for a gravity inversion.
optimize_inversion_zref_density_contrast_kfolds(...)	Perform an optimization for zref and density contrast values same as function optimize_inversion_zref_density_contrast, but pass a dataframe of constraint points and split_kwargs which are both passed split_test_train create K-folds of testing and training constraints.
plot_convergence()	plot a graph of L2-norm and delta L2-norm vs iteration number.
plot_dynamic_convergence()	plot a dynamic graph of L2-norm and delta L2-norm vs iteration number.
plot_inversion_results([iters_to_plot, ...])	plot various results from the inversion
reinitialize_inversion()	reset inversion object attributes, gravity data misfit, and model topography to what it was before the inversion.
solver()	Calculate shift to add to prism top or density for each iteration of the inversion.

Attributes

already_inverted	check if an inversion has already be performed on this instance.
delta_l2_norm	return the current iterations delta l2 norm
l2_norm	return the l2 norm of the current residual misfit
rmse	return the root mean square error of the current residual misfit