| Name | linfa-vi JSON |
| Version |
1.6.6
JSON |
| download |
| home_page | None |
| Summary | A Python library for inference with normalizing flow and annealing |
| upload_time | 2024-04-04 15:35:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | Copyright © 2023 <copyright holders> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE 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 AND NONINFRINGEMENT. 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. |
| keywords |
variational inference
normalizig flow
adaptive annealing
physics-based modeling
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://opensource.org/licenses/MIT)
[](https://linfa-vi.readthedocs.io/en/latest/?badge=latest)
## LINFA
LINFA is a library for variational inference with normalizing flow and adaptive annealing. It is designed to accommodate computationally expensive models and difficult-to-sample posterior distributions with dependent parameters.
The code for the masked autoencoders for density estimation (MADE), masked autoregressive flow (MAF) and real non volume-preserving transformation (RealNVP) is based on the implementation provided by [Kamen Bliznashki](https://github.com/kamenbliznashki/normalizing_flows).
### Installation
To install LINFA type
```
pip install linfa-vi
```
### Documentation
The documentation can be found on [readthedocs](https://linfa-vi.readthedocs.io/en/latest/)
### References
Background theory and examples for LINFA are discussed in the two papers:
- Y. Wang, F. Liu and D.E. Schiavazzi, *[Variational Inference with NoFAS: Normalizing Flow with Adaptive Surrogate for Computationally Expensive Models](https://www.sciencedirect.com/science/article/abs/pii/S0021999122005162)*
- E.R. Cobian, J.D. Hauenstein, F. Liu and D.E. Schiavazzi, *[AdaAnn: Adaptive Annealing Scheduler for Probability Density Approximation](https://www.dl.begellhouse.com/journals/52034eb04b657aea,796f39cb1acf1296,6f85fe1149ff41d9.html?sgstd=1)*
### Requirements
* PyTorch 1.13.1
* Numpy 1.22
* Matplotlib 3.6 (only plot functionalities `linfa.plot_res`)
### Numerical Benchmarks
LINFA includes five numerical benchmarks:
* Trivial example.
* High dimensional example (Sobol' function).
* Two-element Windkessel model (a.k.a. RC model).
* Three-element Windkessel model (a.k.a. RCR model).
* Friedman 1 dataset example.
The implementation of the lumped parameter network models (RC and RCR models) follows closely from the code developed by [the Schiavazzi Lab at the University of Notre Dame](https://github.com/desResLab/supplMatHarrod20).
To run the tests type
```sh
python -m unittest linfa.linfa_test_suite.NAME_example
```
To run a limited number of iterations (say 100), you can instead type
```sh
it=100 python3 -m unittest linfa.linfa_test_suite.NAME_example
```
where `NAME` need to be replaced by
* `trivial` for the trivial example (Ex 1).
* `highdim` for the high-dimensional example (Ex 2).
* `rc` for the RC model (Ex 3).
* `rcr` for the RCR model (Ex 4).
* `adaann` for the Friedman model example (Ex 5).
* `rcr_nofas_adaann` for the RCR model, combining NoFAS with adaptive annealing (AdaAnn)
If used with adaptive annealing (AdaAnn) the `it=100` option runs 100 iterations only at `T=1` (i.e., to approximate the untempered posterior distribution). Therefore the total number of iterations is generally higher than specified through the `it` option.
At regular intervals, set by the parameter `experiment.save_interval`, LINFA writes a few results files. The sub-string `NAME` refers to the experiment name specified in the `experiment.name` variable, and `IT` indicates the iteration at which the file is written. The results files are
* `log.txt` contains the log profile information, i.e.
* Iteration number.
* Annealing temperature at each iteration.
* Loss function at each iteration.
* `NAME_grid_IT` contains the inputs where the true model was evaluated.
* `NAME_params_IT` contains the batch of input parameters $\boldsymbol{z}_{K}$ in the physical space generated at iteration `IT`.
* `NAME_samples_IT` contains the batch of normalized parameters (parameter values before the coordinate transformation) generated at iteration `IT`.
* `NAME_logdensity_IT` contains the value of the log posterior density corresponding to each parameter realization.
* `NAME_outputs_IT` contains the true model (or surrogate model) outputs for each batch sample at iteration `IT`.
* `NAME_IT.nf` contains a backup of the normalizing flow parameters at iteration `IT`.
A post processing script is also available to plot all results. To run it type
```sh
python -m linfa.plot_res -n NAME -i IT -f FOLDER
```
where `NAME` and `IT` are again the experiment name and iteration number corresponding to the result file of interest, while `FOLDER` is the name of the folder with the results of the inference task are kept. Also the file format can be specified throught the `-p` option (options: `pdf`, `png`, `jpg`) and images with dark background can be generated using the `-d` flag.
The coverage resulting from these tests can be found at [this link](https://app.codecov.io/gh/desResLab/LINFA)
### Usage
To use LINFA with your model you need to specify the following components:
* A computational model.
* A surrogate model.
* A log-likelihood model.
* An optional transformation.
In addition you need to specify a list of options as discussed in the [documentation](https://linfa-vi.readthedocs.io/en/latest/content/linfa_options.html).
### Tutorial
Two step-by-step tutorials ([tutorial 1](docs/content/tutorial/tutorial_linfa_2d.ipynb) and [tutorial 2](docs/content/tutorial/tutorial_linfa_3d.ipynb)) are also available which will guide you through an inference problem for a ballistic simulation.
### Contributing
If you are interested in contributing to this project, plase take a look at the [contributed guide](CONTRIBUTING.md) provided with LINFA.
### Citation
Did you use LINFA? Please cite our paper using:
```
@article{linfa-vi-paper,
title={LINFA: a Python library for variational inference with normalizing flow and annealing},
author={Wang, Yu and Cobian, Emma R and Lee, Jubilee and Liu, Fang and Hauenstein, Jonathan D and Schiavazzi, Daniele E},
journal={arXiv preprint arXiv:2307.04675},
year={2023}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "linfa-vi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "variational inference, normalizig flow, adaptive annealing, physics-based modeling",
"author": null,
"author_email": "resDesLab <daniele.schiavazzi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6a/7a/9ce4b180b600df75359a6a194e568cc3b2ba0eae35f9f5d2dea2debb0874/linfa_vi-1.6.6.tar.gz",
"platform": null,
"description": "[](https://opensource.org/licenses/MIT) \n  \n[](https://linfa-vi.readthedocs.io/en/latest/?badge=latest)\n\n## LINFA\n\nLINFA is a library for variational inference with normalizing flow and adaptive annealing. It is designed to accommodate computationally expensive models and difficult-to-sample posterior distributions with dependent parameters.\n\nThe code for the masked autoencoders for density estimation (MADE), masked autoregressive flow (MAF) and real non volume-preserving transformation (RealNVP) is based on the implementation provided by [Kamen Bliznashki](https://github.com/kamenbliznashki/normalizing_flows). \n\n### Installation\n\nTo install LINFA type\n\n```\npip install linfa-vi\n```\n\n### Documentation \n\nThe documentation can be found on [readthedocs](https://linfa-vi.readthedocs.io/en/latest/)\n\n### References\n\nBackground theory and examples for LINFA are discussed in the two papers: \n\n- Y. Wang, F. Liu and D.E. Schiavazzi, *[Variational Inference with NoFAS: Normalizing Flow with Adaptive Surrogate for Computationally Expensive Models](https://www.sciencedirect.com/science/article/abs/pii/S0021999122005162)*\n- E.R. Cobian, J.D. Hauenstein, F. Liu and D.E. Schiavazzi, *[AdaAnn: Adaptive Annealing Scheduler for Probability Density Approximation](https://www.dl.begellhouse.com/journals/52034eb04b657aea,796f39cb1acf1296,6f85fe1149ff41d9.html?sgstd=1)*\n\n### Requirements\n\n* PyTorch 1.13.1\n* Numpy 1.22\n* Matplotlib 3.6 (only plot functionalities `linfa.plot_res`)\n\n### Numerical Benchmarks\n\nLINFA includes five numerical benchmarks:\n\n* Trivial example.\n* High dimensional example (Sobol' function).\n* Two-element Windkessel model (a.k.a. RC model).\n* Three-element Windkessel model (a.k.a. RCR model).\n* Friedman 1 dataset example.\n\nThe implementation of the lumped parameter network models (RC and RCR models) follows closely from the code developed by [the Schiavazzi Lab at the University of Notre Dame](https://github.com/desResLab/supplMatHarrod20).\n\nTo run the tests type\n```sh\npython -m unittest linfa.linfa_test_suite.NAME_example\n```\nTo run a limited number of iterations (say 100), you can instead type\n```sh\nit=100 python3 -m unittest linfa.linfa_test_suite.NAME_example\n```\nwhere `NAME` need to be replaced by\n* `trivial` for the trivial example (Ex 1).\n* `highdim` for the high-dimensional example (Ex 2).\n* `rc` for the RC model (Ex 3).\n* `rcr` for the RCR model (Ex 4).\n* `adaann` for the Friedman model example (Ex 5).\n* `rcr_nofas_adaann` for the RCR model, combining NoFAS with adaptive annealing (AdaAnn)\n\nIf used with adaptive annealing (AdaAnn) the `it=100` option runs 100 iterations only at `T=1` (i.e., to approximate the untempered posterior distribution). Therefore the total number of iterations is generally higher than specified through the `it` option.\n\nAt regular intervals, set by the parameter `experiment.save_interval`, LINFA writes a few results files. The sub-string `NAME` refers to the experiment name specified in the `experiment.name` variable, and `IT` indicates the iteration at which the file is written. The results files are\n\n* `log.txt` contains the log profile information, i.e.\n * Iteration number.\n * Annealing temperature at each iteration.\n * Loss function at each iteration.\n* `NAME_grid_IT` contains the inputs where the true model was evaluated. \n* `NAME_params_IT` contains the batch of input parameters $\\boldsymbol{z}_{K}$ in the physical space generated at iteration `IT`. \n* `NAME_samples_IT` contains the batch of normalized parameters (parameter values before the coordinate transformation) generated at iteration `IT`.\n* `NAME_logdensity_IT` contains the value of the log posterior density corresponding to each parameter realization. \n* `NAME_outputs_IT` contains the true model (or surrogate model) outputs for each batch sample at iteration `IT`.\n* `NAME_IT.nf` contains a backup of the normalizing flow parameters at iteration `IT`.\n\nA post processing script is also available to plot all results. To run it type\n\n```sh\npython -m linfa.plot_res -n NAME -i IT -f FOLDER\n```\nwhere `NAME` and `IT` are again the experiment name and iteration number corresponding to the result file of interest, while `FOLDER` is the name of the folder with the results of the inference task are kept. Also the file format can be specified throught the `-p` option (options: `pdf`, `png`, `jpg`) and images with dark background can be generated using the `-d` flag. \n\nThe coverage resulting from these tests can be found at [this link](https://app.codecov.io/gh/desResLab/LINFA)\n\n### Usage\n\nTo use LINFA with your model you need to specify the following components:\n\n* A computational model.\n* A surrogate model.\n* A log-likelihood model.\n* An optional transformation. \n\nIn addition you need to specify a list of options as discussed in the [documentation](https://linfa-vi.readthedocs.io/en/latest/content/linfa_options.html).\n\n### Tutorial\n\nTwo step-by-step tutorials ([tutorial 1](docs/content/tutorial/tutorial_linfa_2d.ipynb) and [tutorial 2](docs/content/tutorial/tutorial_linfa_3d.ipynb)) are also available which will guide you through an inference problem for a ballistic simulation.\n\n### Contributing\n\nIf you are interested in contributing to this project, plase take a look at the [contributed guide](CONTRIBUTING.md) provided with LINFA.\n\n### Citation\n\nDid you use LINFA? Please cite our paper using:\n```\n@article{linfa-vi-paper,\n title={LINFA: a Python library for variational inference with normalizing flow and annealing},\n author={Wang, Yu and Cobian, Emma R and Lee, Jubilee and Liu, Fang and Hauenstein, Jonathan D and Schiavazzi, Daniele E},\n journal={arXiv preprint arXiv:2307.04675},\n year={2023}\n}\n```\n",
"bugtrack_url": null,
"license": "Copyright \u00a9 2023 <copyright holders> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 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.",
"summary": "A Python library for inference with normalizing flow and annealing",
"version": "1.6.6",
"project_urls": {
"Homepage": "https://github.com/desResLab/LINFA"
},
"split_keywords": [
"variational inference",
" normalizig flow",
" adaptive annealing",
" physics-based modeling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f505a8c236d2c5b6e54e8fed8f490d6b9c7889cbff9322eee0b2358ef4e9611",
"md5": "f4759aa7b26d38c1ea2ac51a96c2500d",
"sha256": "24af38a494b3f671d7e8c8859cd30b99fea60b1beb4f68628bab98504f8bb9b5"
},
"downloads": -1,
"filename": "linfa_vi-1.6.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4759aa7b26d38c1ea2ac51a96c2500d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 61585,
"upload_time": "2024-04-04T15:35:09",
"upload_time_iso_8601": "2024-04-04T15:35:09.608248Z",
"url": "https://files.pythonhosted.org/packages/2f/50/5a8c236d2c5b6e54e8fed8f490d6b9c7889cbff9322eee0b2358ef4e9611/linfa_vi-1.6.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a7a9ce4b180b600df75359a6a194e568cc3b2ba0eae35f9f5d2dea2debb0874",
"md5": "0613141b582858aea2b350e97c8aca55",
"sha256": "2503fad88faa0c63aa8c2fdc71e51c5de5327da2a28af5764600acd60eb4fb87"
},
"downloads": -1,
"filename": "linfa_vi-1.6.6.tar.gz",
"has_sig": false,
"md5_digest": "0613141b582858aea2b350e97c8aca55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 40573,
"upload_time": "2024-04-04T15:35:11",
"upload_time_iso_8601": "2024-04-04T15:35:11.621087Z",
"url": "https://files.pythonhosted.org/packages/6a/7a/9ce4b180b600df75359a6a194e568cc3b2ba0eae35f9f5d2dea2debb0874/linfa_vi-1.6.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 15:35:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "desResLab",
"github_project": "LINFA",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "linfa-vi"
}
