inv_toolbox

🐍 A toolbox for inverse problem resolution.

The complete and up to date documentation can be found here: https://inv-toolbox.readthedocs.io.

🎯 Motivations

Solving an inverse problem (calibrating a geoscience model against observed data, for instance) usually means minimizing a cost function made of a data-misfit term and one or several regularization terms, then checking that the gradients fed to the optimizer are actually correct. Each of these steps relies on a handful of recurring numerical building blocks: spatial regularizators, parameter pre-transformations (preconditioners), finite-difference approximations to validate analytical gradients, and a few plotting helpers to inspect the result.

inv_toolbox gathers these building blocks behind a small, consistent, object-oriented API so that they don’t have to be reimplemented for every new inversion project. It builds on quickpaver for the regular grids used by the local regularizators, and on covmats for the covariance matrix representations used by the geostatistical regularizator.

🚀 Quick start

To install inv_toolbox, the easiest way is through pip:

pip install inv_toolbox

Or alternatively using conda

conda install inv_toolbox

You might also clone the repository and install from source

pip install -e .

Once the installation is done, inv_toolbox is straightforward to use and proposes three submodules: regularization, utils and plot.

Let’s start by importing numpy, quickpaver and inv_toolbox for the tests:

import numpy as np
import quickpaver
import inv_toolbox

grid = quickpaver.RectilinearGrid(nx=15, ny=26, dx=3.6, dy=7.5)
reg = inv_toolbox.regularization.TikhonovRegularizator(grid)

rng = np.random.default_rng(2026)
values = rng.random(grid.nx * grid.ny)
reg.eval_loss(values)

3.2932279607534594

inv_toolbox.utils.is_gradient_correct(
    values, reg.eval_loss, reg.eval_loss_gradient_analytical
)

True

import covmats

cov_m = covmats.CovViaDiagonal([1.0, 2.0, 3.0])
reg = inv_toolbox.regularization.GeostatisticalRegularizator(cov_m)
reg.eval_loss(np.array([4.0, -2.0, 5.0]))

13.166666666666666

from inv_toolbox.utils.preconditioner import LogTransform

LogTransform()(np.array([1.0, 10.0, 100.0]))

array([0.        , 2.30258509, 4.60517019])

🔑 License

This project is released under the BSD 3-Clause License.

Copyright (c) 2026, Antoine COLLET. All rights reserved.

For more details, see the LICENSE file included in this repository.

⚠️ Disclaimer

This software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, or non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

By using this software, you agree to accept full responsibility for any consequences, and you waive any claims against the authors or contributors.

📧 Contact

For questions, suggestions, or contributions, you can reach out via:

• Email: antoine.collet5@gmail.com

• GitHub: https://github.com/antoinecollet5/inv_toolbox

We welcome contributions!

📚 References

TODO

• Free software: SPDX-License-Identifier: BSD-3-Clause