# PyTorch Implementation of Differentiable Laplace Reconstructions
[](https://samholt.github.io/NeuralLaplace/)
[](https://github.com/samholt/NeuralLaplace/actions/workflows/test.yml)
[](https://arxiv.org/abs/2206.04843)
[](https://opensource.org/licenses/MIT)
This library provides Inverse Laplace Transform (ILT) algorithms implemented in PyTorch. Backpropagation through differential equation (DE) solutions in the Laplace domain is supported using the Riemann stereographic projection for better global representation of the complex Laplace domain. For usage for DE representations in the Laplace domain in deep learning applications, see reference [[1]](https://arxiv.org/abs/2206.04843).
## Installation
To install latest stable version:
```
pip install torchlaplace
```
To install the latest on GitHub:
```
pip install git+https://github.com/samholt/NeuralLaplace.git
```
## Tutorials
1. Tutorial: Laplace Reconstruct [](https://colab.research.google.com/drive/1JCakl2DFzHnBh_C6YXBpnGYKUmBVPN3Y?usp=sharing)
2. Tutorial: Inverse Laplace Transform Algorithms [](https://colab.research.google.com/drive/1ZNAA9CdXbA8B-Vp3r5Zqx3mM4CojtI6V?usp=sharing)
## Examples
Examples are placed in the [`examples`](./examples) directory.
We encourage those who are interested in using this library to take a look at [`examples/simple_demo.py`](./examples/simple_demo.py) for understanding how to use `torchlaplace` to fit a DE system.
<p align="center">
<img align="middle" src="./assets/lotka_volterra_dde.gif" alt="Lotka Volterra DDE Demo" width="800" />
</p>
## Basic usage
This library provides one main interface `laplace_reconstruct` which uses a selected inverse Laplace transform algorithm to reconstruct trajectories from a provided parameterized Laplace representation functional $\mathbf{F}(\mathbf{p},\mathbf{s})$,
$$\mathbf{x}(t) = \text{inverse laplace transform}(\mathbf{F}(\mathbf{p},\mathbf{s}), t)$$
Where $\mathbf{p}$ is a Tensor encoding the initial system state as a latent variable, and $t$ is the time points to reconstruct trajectories for.
This can be used by
```
from torchlaplace import laplace_reconstruct
laplace_reconstruct(laplace_rep_func, p, t)
```
where `laplace_rep_func` is any callable implementing the parameterized Laplace representation functional $\mathbf{F}(\mathbf{p},\mathbf{s})$, `p` is a Tensor encoding the initial state of shape $(\text{MiniBatchSize},\text{K})$.
Where $\text{K}$ is a hyperparameter, and can be set by the user.
Finally, `t` is a Tensor of shape $(\text{MiniBatchSize},\text{SeqLen})$
or $(\text{SeqLen})$ containing the time points to reconstruct the trajectories for.
Note that this is not numerically stable for all ILT methods, however should probably be fine with the default `fourier` (fourier series inverse) ILT algorithm.
The parameterized Laplace representation functional `laplace_rep_func`, $\mathbf{F}(\mathbf{p},\mathbf{s})$
also takes an input complex value $\mathbf{s}$.
This $\mathbf{s}$ is used internally when reconstructing a specified time point with the selected inverse Laplace transform algorithm `ilt_algorithm`.
The biggest **gotcha** is that `laplace_rep_func` must be a `nn.Module` when using the `laplace_rep_func` function. This is due to internally needing to collect the parameters of the parameterized Laplace representation.
To replicate the experiments in [1] see the in the [`experiments`](./experiments) directory.
### Keyword arguments for `laplace_rep_func`
#### Keyword arguments:
- `recon_dim` (int): trajectory dimension for a given time point. Corresponds to dim $d_{\text{obs}}$. If not explicitly specified, will use the same last dimension of `p`, i.e. $\text{K}$.
- `ilt_algorithm` (str): inverse Laplace transform algorithm to use. Default: `fourier`. Available are {`fourier`, `dehoog`, `cme`, `fixed_tablot`, `stehfest`}. See api documentation on ILTs for further details.
- `use_sphere_projection` (bool): this uses the `laplace_rep_func` in the stereographic projection of the Riemann sphere. Default `True`.
- `ilt_reconstruction_terms` (int): number of ILT reconstruction terms, i.e. the number of complex $s$ points in `laplace_rep_func` to reconstruct a single time point.
#### List of ILT Algorithms:
ILT algorithms implemented:
- `fourier` Fourier Series Inverse **[default]**.
- `dehoog` DeHoog (Accelerated version of Fourier) - Slower inference in comparison.
- `cme` Concentrated Matrix Exponentials.
- `fixed_tablot` Fixed Tablot.
- `stehfest` Gaver-Stehfest.
For most problems, good choices are the default `fourier`. However other ILT algorithms may be more appropriate when using higher ILT reconstruction terms, such as the `cme` algorithm. Some allow trade-offs between speed and accuracy, for example `dehoog` is very accurate if the representation is known or exact, however is slow and can be unstable to use when learning the correct representation.
## Detailed documentation
For detailed documentation see the [official docs](https://samholt.github.io/NeuralLaplace/).
## Frequently Asked Questions
Take a look at our [FAQ](FAQ.md) for frequently asked questions.
## References
For usage for DE representations in the Laplace domain and leveraging the stereographic projection and other applications see:
[1] Samuel Holt, Zhaozhi Qian, and Mihaela van der Schaar. "Neural laplace: Learning diverse classes of
differential equations in the laplace domain." _International Conference on Machine Learning._ 2022. [[arxiv]](https://arxiv.org/abs/2206.04843)
---
If you found this library useful in your research, please consider citing.
```
@inproceedings{holt2022neural,
title={Neural Laplace: Learning diverse classes of differential equations in the Laplace domain},
author={Holt, Samuel I and Qian, Zhaozhi and van der Schaar, Mihaela},
booktitle={International Conference on Machine Learning},
pages={8811--8832},
year={2022},
organization={PMLR}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/samholt/NeuralLaplace",
"name": "torchlaplace",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Sam Holt",
"author_email": "samuel.holt.direct@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/07/8a/d3da0507dcf757aa57971f73810ae85edd75676e3a279d987b8ed8ad5551/torchlaplace-0.0.3.tar.gz",
"platform": "any",
"description": "# PyTorch Implementation of Differentiable Laplace Reconstructions\n\n[](https://samholt.github.io/NeuralLaplace/)\n[](https://github.com/samholt/NeuralLaplace/actions/workflows/test.yml)\n[](https://arxiv.org/abs/2206.04843)\n[](https://opensource.org/licenses/MIT)\n\n\nThis library provides Inverse Laplace Transform (ILT) algorithms implemented in PyTorch. Backpropagation through differential equation (DE) solutions in the Laplace domain is supported using the Riemann stereographic projection for better global representation of the complex Laplace domain. For usage for DE representations in the Laplace domain in deep learning applications, see reference [[1]](https://arxiv.org/abs/2206.04843).\n\n## Installation\n\nTo install latest stable version:\n\n```\npip install torchlaplace\n```\n\nTo install the latest on GitHub:\n\n```\npip install git+https://github.com/samholt/NeuralLaplace.git\n```\n\n## Tutorials\n1. Tutorial: Laplace Reconstruct [](https://colab.research.google.com/drive/1JCakl2DFzHnBh_C6YXBpnGYKUmBVPN3Y?usp=sharing)\n2. Tutorial: Inverse Laplace Transform Algorithms [](https://colab.research.google.com/drive/1ZNAA9CdXbA8B-Vp3r5Zqx3mM4CojtI6V?usp=sharing)\n## Examples\n\nExamples are placed in the [`examples`](./examples) directory.\n\nWe encourage those who are interested in using this library to take a look at [`examples/simple_demo.py`](./examples/simple_demo.py) for understanding how to use `torchlaplace` to fit a DE system.\n\n<p align=\"center\">\n<img align=\"middle\" src=\"./assets/lotka_volterra_dde.gif\" alt=\"Lotka Volterra DDE Demo\" width=\"800\" />\n</p>\n\n## Basic usage\n\nThis library provides one main interface `laplace_reconstruct` which uses a selected inverse Laplace transform algorithm to reconstruct trajectories from a provided parameterized Laplace representation functional $\\mathbf{F}(\\mathbf{p},\\mathbf{s})$,\n\n$$\\mathbf{x}(t) = \\text{inverse laplace transform}(\\mathbf{F}(\\mathbf{p},\\mathbf{s}), t)$$\n\nWhere $\\mathbf{p}$ is a Tensor encoding the initial system state as a latent variable, and $t$ is the time points to reconstruct trajectories for.\n\nThis can be used by\n\n```\nfrom torchlaplace import laplace_reconstruct\n\nlaplace_reconstruct(laplace_rep_func, p, t)\n```\n\nwhere `laplace_rep_func` is any callable implementing the parameterized Laplace representation functional $\\mathbf{F}(\\mathbf{p},\\mathbf{s})$, `p` is a Tensor encoding the initial state of shape $(\\text{MiniBatchSize},\\text{K})$.\nWhere $\\text{K}$ is a hyperparameter, and can be set by the user.\nFinally, `t` is a Tensor of shape $(\\text{MiniBatchSize},\\text{SeqLen})$\nor $(\\text{SeqLen})$ containing the time points to reconstruct the trajectories for.\n\nNote that this is not numerically stable for all ILT methods, however should probably be fine with the default `fourier` (fourier series inverse) ILT algorithm.\n\nThe parameterized Laplace representation functional `laplace_rep_func`, $\\mathbf{F}(\\mathbf{p},\\mathbf{s})$\nalso takes an input complex value $\\mathbf{s}$.\nThis $\\mathbf{s}$ is used internally when reconstructing a specified time point with the selected inverse Laplace transform algorithm `ilt_algorithm`.\n\nThe biggest **gotcha** is that `laplace_rep_func` must be a `nn.Module` when using the `laplace_rep_func` function. This is due to internally needing to collect the parameters of the parameterized Laplace representation.\n\nTo replicate the experiments in [1] see the in the [`experiments`](./experiments) directory.\n\n### Keyword arguments for `laplace_rep_func`\n\n#### Keyword arguments:\n\n- `recon_dim` (int): trajectory dimension for a given time point. Corresponds to dim $d_{\\text{obs}}$. If not explicitly specified, will use the same last dimension of `p`, i.e. $\\text{K}$.\n- `ilt_algorithm` (str): inverse Laplace transform algorithm to use. Default: `fourier`. Available are {`fourier`, `dehoog`, `cme`, `fixed_tablot`, `stehfest`}. See api documentation on ILTs for further details.\n- `use_sphere_projection` (bool): this uses the `laplace_rep_func` in the stereographic projection of the Riemann sphere. Default `True`.\n- `ilt_reconstruction_terms` (int): number of ILT reconstruction terms, i.e. the number of complex $s$ points in `laplace_rep_func` to reconstruct a single time point.\n\n#### List of ILT Algorithms:\n\nILT algorithms implemented:\n\n- `fourier` Fourier Series Inverse **[default]**.\n- `dehoog` DeHoog (Accelerated version of Fourier) - Slower inference in comparison.\n- `cme` Concentrated Matrix Exponentials.\n- `fixed_tablot` Fixed Tablot.\n- `stehfest` Gaver-Stehfest.\n\nFor most problems, good choices are the default `fourier`. However other ILT algorithms may be more appropriate when using higher ILT reconstruction terms, such as the `cme` algorithm. Some allow trade-offs between speed and accuracy, for example `dehoog` is very accurate if the representation is known or exact, however is slow and can be unstable to use when learning the correct representation.\n\n## Detailed documentation\n\nFor detailed documentation see the [official docs](https://samholt.github.io/NeuralLaplace/).\n\n## Frequently Asked Questions\n\nTake a look at our [FAQ](FAQ.md) for frequently asked questions.\n\n## References\n\nFor usage for DE representations in the Laplace domain and leveraging the stereographic projection and other applications see:\n\n[1] Samuel Holt, Zhaozhi Qian, and Mihaela van der Schaar. \"Neural laplace: Learning diverse classes of\ndifferential equations in the laplace domain.\" _International Conference on Machine Learning._ 2022. [[arxiv]](https://arxiv.org/abs/2206.04843)\n\n---\n\nIf you found this library useful in your research, please consider citing.\n\n```\n@inproceedings{holt2022neural,\n title={Neural Laplace: Learning diverse classes of differential equations in the Laplace domain},\n author={Holt, Samuel I and Qian, Zhaozhi and van der Schaar, Mihaela},\n booktitle={International Conference on Machine Learning},\n pages={8811--8832},\n year={2022},\n organization={PMLR}\n}\n\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Differentiable Laplace Reconstructions in PyTorch",
"version": "0.0.3",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "90e530509a538b3a2cbf5dda614de2de",
"sha256": "ec5e4be851c35e901bf2e502e3fd8c3d52e62605b4fc03a61716a0cd16a97b59"
},
"downloads": -1,
"filename": "torchlaplace-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90e530509a538b3a2cbf5dda614de2de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 3066944,
"upload_time": "2022-12-23T15:07:34",
"upload_time_iso_8601": "2022-12-23T15:07:34.506196Z",
"url": "https://files.pythonhosted.org/packages/c0/d8/7bfcfbdb437f73d8e64dd79187b578da64a357a9eb16bb7a250b6a2756ce/torchlaplace-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "fa1b007e01e9ab762059b563a11e7f44",
"sha256": "dcbf5e50ec8583b0320cf7d336347306ae2877c1c41f78663ecaba006155d0a5"
},
"downloads": -1,
"filename": "torchlaplace-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "fa1b007e01e9ab762059b563a11e7f44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3000894,
"upload_time": "2022-12-23T15:07:36",
"upload_time_iso_8601": "2022-12-23T15:07:36.327246Z",
"url": "https://files.pythonhosted.org/packages/07/8a/d3da0507dcf757aa57971f73810ae85edd75676e3a279d987b8ed8ad5551/torchlaplace-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-23 15:07:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "samholt",
"github_project": "NeuralLaplace",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "torchlaplace"
}
JSON
