Metadata-Version: 2.4
Name: ilt-py-lib
Version: 1.0b9
Summary: A python library for inverse Laplace transform of one dimensional and multidimensional data.
Home-page: https://apps.fz-juelich.de/iltpy
Author: Davis Thomas Daniel, Josef Granwehr
Author-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>, Josef Granwehr <j.granwehr@fz-juelich.de>
Maintainer-email: Davis Thomas Daniel <davisthomasdaniel@gmail.com>
License-Expression: LGPL-3.0-or-later
Project-URL: Homepage, https://apps.fz-juelich.de/iltpy
Project-URL: Documentation, https://apps.fz-juelich.de/iltpy
Project-URL: Repository, https://jugit.fz-juelich.de/iet-1/iltpy
Project-URL: Issues, https://jugit.fz-juelich.de/iet-1/iltpy/-/issues
Project-URL: Changelog, https://jugit.fz-juelich.de/iet-1/iltpy/-/blob/main/CHANGELOG
Keywords: EPR,NMR,DRT,Inverse Laplace transform,Laplace inversion,Relaxation,Impedance
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9, <3.14
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COPYING.LESSER.txt
License-File: COPYING.txt
Requires-Dist: scipy<=1.16.0,>=1.13.1
Requires-Dist: numpy<=2.3.1,>1.25.1
Requires-Dist: joblib<=1.5.1,>=1.4.2
Requires-Dist: tqdm
Provides-Extra: develop
Requires-Dist: matplotlib; extra == "develop"
Requires-Dist: pytest; extra == "develop"
Requires-Dist: pytest-cov; extra == "develop"
Requires-Dist: sphinx; extra == "develop"
Requires-Dist: nbsphinx==0.9.5; extra == "develop"
Requires-Dist: sphinx_rtd_theme==3.0.1; extra == "develop"
Requires-Dist: sphinx-togglebutton==0.3.2; extra == "develop"
Requires-Dist: sphinx_design==0.6.1; extra == "develop"
Requires-Dist: sphinx-copybutton==0.5.2; extra == "develop"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ILTpy 1.0b9

<img src="logo/iltpy_logo.png" width="35%" alt="iltpy_logo">

[![ILTpy_test](https://jugit.fz-juelich.de/iet-1/iltpy/badges/main/pipeline.svg?key_text=IltPy%20Tests&key_width=80)](https://jugit.fz-juelich.de/iet-1/iltpy/main/pipelines) [![Website](https://img.shields.io/website?url=https%3A%2F%2Fapps.fz-juelich.de%2Filtpy%2F&up_message=online&label=Docs)](https://apps.fz-juelich.de/iltpy/)
[![coverage_report](https://jugit.fz-juelich.de/iet-1/iltpy/badges/main/coverage.svg?key_text=Test%20coverage&key_width=90)]( https://jugit.fz-juelich.de/iet-1/iltpy/-/pipelines)

## Introduction

**ILTpy** (/ɪltˈpaɪ/) is a python package for performing regularized inversion of one-dimensional or multi-dimensional data without non-negativity constraint. Contributions to respective distributions with both positive and negative sign are determined. Primary applications include magnetic resonance (NMR, EPR), and electrochemical impedance spectroscopy (distribution of relaxation times; DRT). Algorithmic details and parametrization are described in : [J. Granwehr, P.J. Roberts, J. Chem. Theory Comput. 8, 3473­3482 (2012)](https://doi.org/10.1021/ct3001393)

## Documentation

Documentation can be found [here](https://apps.fz-juelich.de/iltpy/index.html).  
Documentation can also be built locally using sphinx with the source files provided in docs/source .

## Installation

### Prerequisites
* To install and use **ILTpy**, Python must be installed on your device and be available on system PATH. 
* **ILTpy** is compatible with Python 3.9, 3.10, 3.11, 3.12 and 3.13.
* **ILTpy** can be installed using python's package manager, pip.
* A python virtual environment is recommended.

### Installing from a pre-built distribution

* Run the following command in a terminal:

```python
python -m pip install --extra-index-url https://apps.fz-juelich.de/iltpy/packages/ ilt-py-lib
```

### Installing from source

* Clone this repository.
* Navigate to the local directory where ILTpy was downloaded/extracted. The **ILTpy** directory should contain a `setup.py` file along with other folders.
* While inside the **ILTpy** directory, run the following command in a terminal (or command prompt) :

```python
python -m pip install .
```

### Dependencies

* python >=3.9,<3.14
* scipy>=1.13.1,<=1.16.0 
* numpy>1.25.1,<=2.3.1 
* joblib>=1.4.2,<=1.5.1
* tqdm

More information on using **ILTpy** can be found [here](https://apps.fz-juelich.de/ILTpy). 

## ⚡ Quick-start
A workflow using ILTpy and synthetic exponential decay data wth noise is shown below. 
First, we generate some synthetic data for analysis :

<details>
<summary> Click to show</summary>

```python
# --- Simulate synthetic data ---
import numpy as np

def kww(t, taus, betas, amps, baseline=0.0):

    """Kohlrausch–Williams–Watts function"""
    
    t = np.asarray(t)
    return sum(a * np.exp(-(t / tau) ** b) for tau, b, a in zip(taus, betas, amps)) + baseline

# Time vector (input sampling points)
t_syn = np.linspace(0, 1024,1024) 

# Simulate data with two components at 10 and 100 with different amplitudes
data_syn = kww(t_syn, taus=[10,100], betas=[1, 1], amps=[1, 0.5])

# Add noise to the simulated data
noise_level = 0.01
data_syn = data_syn + np.random.randn(t_syn.size)*noise_level

# scale data so that noise variance is 1 before analysis using ILTpy
data_syn = data_syn/noise_level
```

</details>
<br>
The synthetic data consists of two components with time constants 10 and 100, which is reproduced in the distribution after inversion.
The residuals obtained after inversion are random and devoid of systematic features, indicating a good fit to the data and a compatible kernel.

#### ILTpy Workflow
```python
# --- ILTpy workflow ---
# assuming data_syn and t_syn are numpy arrays with the data and the sampling vector.

# Import ILTpy
import iltpy as ilt

# Load the data into iltpy using iltload
synILT = ilt.iltload(data=data_syn, t=t_syn)

# Specify parameters and  initialize inversion
tau = np.logspace(-1, 4, 100) # output sampling points
synILT.init(tau=tau, kernel=ilt.Exponential())

# Perform inversion
synILT.invert()
```
```bash
Starting iterations.
100%|██████████| 100/100
Done.
```
```python
## Reporting

# Save the results
synILT.report(filepath='syn_data_ILT.txt')

# Plot the results
from iltpy.output.plotting import iltplot
iltplot(synILT)
```

![workflow_out](docs/source/images/getting_started_example_syn_data.png){width=60%}


## Team
* [Dr. Davis Thomas Daniel](https://davistdaniel.github.io/introduction/) (Lead developer)
* Christian Bartsch
* Franz Philipp Bereck
* Dr. Simone Köcher
* Dr. Christoph Scheurer
* Prof. Dr. Josef Granwehr (Project lead)

## License

Copyright (c) 2025 Davis Thomas Daniel, Josef Granwehr and ![other contributors](https://jugit.fz-juelich.de/iet-1/iltpy#team).

ILTpy is licensed under the GNU Lesser General Public License v3.0.
See the [LICENSE](./LICENSE) file for details.

## Citation

If you use **ILTpy** in your work, please cite it (using the appropriate version):

```bibtex
@software{iltpy,
  author       = {Davis Thomas Daniel and Christian Bartsch and Franz Philipp Bereck and Simone Köcher and Christoph Scheurer and Josef Granwehr},
  title        = {ILTpy},
  year         = {2025},
  version      = {1.0b9},
  url          = {https://apps.fz-juelich.de/iltpy/},
  doi          = {10.26165/JUELICH-DATA/6AG3NI}
}
