| Name | smcpy JSON |
| Version |
0.1.5
JSON |
| download |
| home_page | https://github.com/nasa/SMCPy |
| Summary | A package for performing uncertainty quantification using a parallelized sequential Monte Carlo sampler. |
| upload_time | 2023-01-31 19:50:05 |
| maintainer | |
| docs_url | None |
| author | Patrick Leser |
| requires_python | ~=3.4 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
|
SMCPy - **S**equential **M**onte **C**arlo with **Py**thon
==========================================================================
[](https://travis-ci.com/nasa/SMCPy) [](https://coveralls.io/github/nasa/SMCPy?branch=master)
## Description
SMCPy is an open-source package for performing uncertainty quantification using
a parallelized sequential Monte Carlo sampler.
## Key Features
* Alternative to Markov chain Monte Carlo for Bayesian inference problems
* Unbiased estimation of marginal likelihood for Bayesian model selection
* Parallelization through either numpy vectorization or mpi4py
# Quick Start
## Installation
To install SMCPy, use pip.
```sh
pip install smcpy
```
## Overview
To operate the code, the user supplies a computational model built in Python
3.6+, defines prior distributions for each of the model parameters to be
estimated, and provides data to be used for probabilistic model calibration. SMC
sampling of the parameter posterior distribution can then be conducted with ease
through instantiation of a sampler class and a call to the sample() method.
The two primary sampling algorithms implemented in this package are MPI-enabled
versions of those presented in the following articles, respectively:
> Nguyen, Thi Le Thu, et al. "Efficient sequential Monte-Carlo samplers for Bayesian
> inference." IEEE Transactions on Signal Processing 64.5 (2015): 1305-1319.
[Link to Article](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7339702) | [BibTeX Reference](https://scholar.googleusercontent.com/scholar.bib?q=info:L7AZJvppx1MJ:scholar.google.com/&output=citation&scisdr=CgUT24-FENXorVVNYK0:AAGBfm0AAAAAXYJIeK1GJKW947imCXoXAkfc7yZjQ7Oo&scisig=AAGBfm0AAAAAXYJIeNYSGEVCrlauowP6jMwVMHB_blTp&scisf=4&ct=citation&cd=-1&hl=en)
> Buchholz, Alexander, Nicolas Chopin, and Pierre E. Jacob. "Adaptive tuning of
> hamiltonian monte carlo within sequential monte carlo." Bayesian Analysis
> 1.1 (2021): 1-27.
[Link to Article](https://projecteuclid.org/journals/bayesian-analysis/advance-publication/Adaptive-Tuning-of-Hamiltonian-Monte-Carlo-Within-Sequential-Monte-Carlo/10.1214/20-BA1222.full) | [BibTeX Reference](https://scholar.googleusercontent.com/scholar.bib?q=info:wkjyyAN3q3UJ:scholar.google.com/&output=citation&scisdr=CgUA1gUaENXokaHu_K0:AAGBfm0AAAAAYXbr5K0e7EUBTRYw-hgqrmqC-G0ghzIo&scisig=AAGBfm0AAAAAYXbr5FfqGNe5PbrfGSvhMKzBoUbwdXDH&scisf=4&ct=citation&cd=-1&hl=en)
The first is a simple likelihood tempering approach in which the tempering
sequence is fixed and user-specified
([FixedSampler](https://github.com/nasa/SMCPy/blob/8b7813106de077c80992ba37d2d85944d6cce40c/smcpy/samplers.py#L44)).
The second is an adaptive approach that chooses the tempering steps based on a
target effective sample size ([AdaptiveSampler](https://github.com/nasa/SMCPy/blob/8b7813106de077c80992ba37d2d85944d6cce40c/smcpy/samplers.py#L92)).
This software was funded by and developed under the High Performance Computing
Incubator (HPCI) at NASA Langley Research Center.
## Example Usage
```python
import numpy as np
from scipy.stats import uniform
from spring_mass_model import SpringMassModel
from smcpy.utils.plotter import plot_pairwise
from smcpy import AdaptiveSampler, VectorMCMC, VectorMCMCKernel
# Load data
std_dev = 0.5
displacement_data = np.genfromtxt('noisy_data.txt')
# Define prior distributions & MCMC kernel
priors = [uniform(0, 10), uniform(0, 10)]
vector_mcmc = VectorMCMC(model.evaluate, displacement_data, priors, std_dev)
mcmc_kernel = VectorMCMCKernel(vector_mcmc, param_order=('K', 'g'))
# SMC sampling
smc = AdaptiveSampler(mcmc_kernel)
step_list, mll_list = smc.sample(num_particles=500, num_mcmc_samples=5, target_ess=0.8)
# Display results
print(f'parameter means = {step_list[-1].compute_mean()}')
plot_pairwise(step_list[-1].params, step_list[-1].weights, save=True,
param_labels=['K', 'g'])
```
The above code produces probabilistic estimates of K, the spring stiffness
divided by mass, and g, the gravitational constant on some unknown planet.
These estimates are in the form of weighted particles and can be visualized by
plotting the pairwise weights as shown below. The mean of each parameter is
marked by the dashed red line. The true values for this example were K = 1.67
and g = 4.62. More details can be found in the [spring mass
example](https://github.com/nasa/SMCPy/blob/main/examples/spring_mass/run_example.py). To run this model in
parallel using MPI, the MCMC kernel just needs to be built with the
ParallelMCMC class in place of VectorMCMC. More details can be found in the
[MPI example](https://github.com/nasa/SMCPy/blob/main/examples/mpi_example/run_example.py).
<p align="center">
<img src="https://github.com/nasa/SMCPy/blob/main/examples/spring_mass/spring_mass_smc_example.png" width="400" alt="Pairwise plot"/>
</p>
To run this model in parallel using MPI, the MCMC kernel just needs to be built
with the ParallelMCMC class in place of VectorMCMC. More details can be found
in the MPI example (smcpy/examples/mpi_example/).
Tests
-----
Clone the repo and move into the package directory:
```sh
git clone https://github.com/nasa/SMCPy.git
cd SMCPy
```
Install requirements necessary to use SMCPy:
```sh
pip install -r requirements.txt
```
Optionally, if you'd like to use the MPI-enabled parallel sampler, install the
associated requirements:
```sh
pip install -r requirements_optional.txt
```
Add SMCPy to your Python path. For example:
```sh
export PYTHONPATH="$PYTHONPATH:/path/to/smcpy"
```
Run the tests to ensure proper installation:
```sh
pytest tests
```
## Contributing
1. Fork (<https://github.com/nasa/SMCPy/fork>)
2. Create your feature branch (`git checkout -b feature/fooBar`)
3. Commit your changes (`git commit -am 'Add some fooBar'`)
4. Push to the branch (`git push origin feature/fooBar`)
5. Create a Pull Request
# Development
NASA Langley Research Center <br />
Hampton, Virginia <br />
This software was funded by and developed under the High Performance Computing Incubator (HPCI) at NASA Langley Research Center. <br />
## Authors
* Patrick Leser
* Michael Wang
# License
Notices:
Copyright 2018 United States Government as represented by the Administrator of
the National Aeronautics and Space Administration. No copyright is claimed in
the United States under Title 17, U.S. Code. All Other Rights Reserved.
Disclaimers
No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF
ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED
TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR
FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE
SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN
ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS,
RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS
RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY
DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF
PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT "AS IS."
Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE
UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY
PRIOR RECIPIENT. IF RECIPIENT'S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY
LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE,
INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S
USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE
UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY
PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT'S SOLE REMEDY FOR
ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS
AGREEMENT.
Raw data
{
"_id": null,
"home_page": "https://github.com/nasa/SMCPy",
"name": "smcpy",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.4",
"maintainer_email": "",
"keywords": "",
"author": "Patrick Leser",
"author_email": "patrick.e.leser@nasa.gov",
"download_url": "https://files.pythonhosted.org/packages/fa/0e/c8b0acd80586bc56aeb60706eb18e45acd3c805445451fb94fda84049c85/smcpy-0.1.5.tar.gz",
"platform": null,
"description": "SMCPy - **S**equential **M**onte **C**arlo with **Py**thon \r\n==========================================================================\r\n[](https://travis-ci.com/nasa/SMCPy) [](https://coveralls.io/github/nasa/SMCPy?branch=master)\r\n\r\n\r\n## Description\r\nSMCPy is an open-source package for performing uncertainty quantification using\r\na parallelized sequential Monte Carlo sampler.\r\n\r\n## Key Features\r\n* Alternative to Markov chain Monte Carlo for Bayesian inference problems\r\n* Unbiased estimation of marginal likelihood for Bayesian model selection\r\n* Parallelization through either numpy vectorization or mpi4py\r\n\r\n# Quick Start\r\n\r\n## Installation\r\nTo install SMCPy, use pip.\r\n```sh\r\npip install smcpy\r\n```\r\n\r\n## Overview\r\nTo operate the code, the user supplies a computational model built in Python\r\n3.6+, defines prior distributions for each of the model parameters to be\r\nestimated, and provides data to be used for probabilistic model calibration. SMC\r\nsampling of the parameter posterior distribution can then be conducted with ease\r\nthrough instantiation of a sampler class and a call to the sample() method.\r\n\r\nThe two primary sampling algorithms implemented in this package are MPI-enabled\r\nversions of those presented in the following articles, respectively:\r\n> Nguyen, Thi Le Thu, et al. \"Efficient sequential Monte-Carlo samplers for Bayesian\r\n> inference.\" IEEE Transactions on Signal Processing 64.5 (2015): 1305-1319.\r\n[Link to Article](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=7339702) | [BibTeX Reference](https://scholar.googleusercontent.com/scholar.bib?q=info:L7AZJvppx1MJ:scholar.google.com/&output=citation&scisdr=CgUT24-FENXorVVNYK0:AAGBfm0AAAAAXYJIeK1GJKW947imCXoXAkfc7yZjQ7Oo&scisig=AAGBfm0AAAAAXYJIeNYSGEVCrlauowP6jMwVMHB_blTp&scisf=4&ct=citation&cd=-1&hl=en)\r\n\r\n\r\n> Buchholz, Alexander, Nicolas Chopin, and Pierre E. Jacob. \"Adaptive tuning of\r\n> hamiltonian monte carlo within sequential monte carlo.\" Bayesian Analysis\r\n> 1.1 (2021): 1-27.\r\n[Link to Article](https://projecteuclid.org/journals/bayesian-analysis/advance-publication/Adaptive-Tuning-of-Hamiltonian-Monte-Carlo-Within-Sequential-Monte-Carlo/10.1214/20-BA1222.full) | [BibTeX Reference](https://scholar.googleusercontent.com/scholar.bib?q=info:wkjyyAN3q3UJ:scholar.google.com/&output=citation&scisdr=CgUA1gUaENXokaHu_K0:AAGBfm0AAAAAYXbr5K0e7EUBTRYw-hgqrmqC-G0ghzIo&scisig=AAGBfm0AAAAAYXbr5FfqGNe5PbrfGSvhMKzBoUbwdXDH&scisf=4&ct=citation&cd=-1&hl=en)\r\n\r\nThe first is a simple likelihood tempering approach in which the tempering\r\nsequence is fixed and user-specified\r\n([FixedSampler](https://github.com/nasa/SMCPy/blob/8b7813106de077c80992ba37d2d85944d6cce40c/smcpy/samplers.py#L44)).\r\nThe second is an adaptive approach that chooses the tempering steps based on a\r\ntarget effective sample size ([AdaptiveSampler](https://github.com/nasa/SMCPy/blob/8b7813106de077c80992ba37d2d85944d6cce40c/smcpy/samplers.py#L92)).\r\n\r\nThis software was funded by and developed under the High Performance Computing\r\nIncubator (HPCI) at NASA Langley Research Center.\r\n\r\n## Example Usage\r\n\r\n```python\r\nimport numpy as np\r\n\r\nfrom scipy.stats import uniform\r\n\r\nfrom spring_mass_model import SpringMassModel\r\nfrom smcpy.utils.plotter import plot_pairwise\r\nfrom smcpy import AdaptiveSampler, VectorMCMC, VectorMCMCKernel\r\n\r\n\r\n# Load data\r\nstd_dev = 0.5\r\ndisplacement_data = np.genfromtxt('noisy_data.txt')\r\n\r\n# Define prior distributions & MCMC kernel\r\npriors = [uniform(0, 10), uniform(0, 10)]\r\nvector_mcmc = VectorMCMC(model.evaluate, displacement_data, priors, std_dev)\r\nmcmc_kernel = VectorMCMCKernel(vector_mcmc, param_order=('K', 'g'))\r\n\r\n# SMC sampling\r\nsmc = AdaptiveSampler(mcmc_kernel)\r\nstep_list, mll_list = smc.sample(num_particles=500, num_mcmc_samples=5, target_ess=0.8)\r\n\r\n# Display results\r\nprint(f'parameter means = {step_list[-1].compute_mean()}')\r\nplot_pairwise(step_list[-1].params, step_list[-1].weights, save=True,\r\n param_labels=['K', 'g'])\r\n```\r\n\r\nThe above code produces probabilistic estimates of K, the spring stiffness\r\ndivided by mass, and g, the gravitational constant on some unknown planet.\r\nThese estimates are in the form of weighted particles and can be visualized by\r\nplotting the pairwise weights as shown below. The mean of each parameter is\r\nmarked by the dashed red line. The true values for this example were K = 1.67\r\nand g = 4.62. More details can be found in the [spring mass\r\nexample](https://github.com/nasa/SMCPy/blob/main/examples/spring_mass/run_example.py). To run this model in\r\nparallel using MPI, the MCMC kernel just needs to be built with the\r\nParallelMCMC class in place of VectorMCMC. More details can be found in the\r\n[MPI example](https://github.com/nasa/SMCPy/blob/main/examples/mpi_example/run_example.py).\r\n\r\n<p align=\"center\">\r\n<img src=\"https://github.com/nasa/SMCPy/blob/main/examples/spring_mass/spring_mass_smc_example.png\" width=\"400\" alt=\"Pairwise plot\"/>\r\n</p>\r\n\r\nTo run this model in parallel using MPI, the MCMC kernel just needs to be built\r\nwith the ParallelMCMC class in place of VectorMCMC. More details can be found\r\nin the MPI example (smcpy/examples/mpi_example/).\r\n\r\nTests\r\n-----\r\n\r\nClone the repo and move into the package directory:\r\n\r\n```sh\r\ngit clone https://github.com/nasa/SMCPy.git\r\ncd SMCPy\r\n```\r\n\r\nInstall requirements necessary to use SMCPy:\r\n\r\n```sh\r\npip install -r requirements.txt\r\n```\r\n\r\nOptionally, if you'd like to use the MPI-enabled parallel sampler, install the\r\nassociated requirements:\r\n\r\n```sh\r\npip install -r requirements_optional.txt\r\n```\r\n\r\nAdd SMCPy to your Python path. For example:\r\n\r\n```sh\r\nexport PYTHONPATH=\"$PYTHONPATH:/path/to/smcpy\"\r\n```\r\n\r\nRun the tests to ensure proper installation:\r\n\r\n```sh\r\npytest tests\r\n```\r\n\r\n## Contributing\r\n1. Fork (<https://github.com/nasa/SMCPy/fork>)\r\n2. Create your feature branch (`git checkout -b feature/fooBar`)\r\n3. Commit your changes (`git commit -am 'Add some fooBar'`)\r\n4. Push to the branch (`git push origin feature/fooBar`)\r\n5. Create a Pull Request\r\n\r\n# Development\r\nNASA Langley Research Center <br /> \r\nHampton, Virginia <br /> \r\n\r\nThis software was funded by and developed under the High Performance Computing Incubator (HPCI) at NASA Langley Research Center. <br /> \r\n\r\n## Authors\r\n* Patrick Leser\r\n* Michael Wang\r\n\r\n# License\r\nNotices:\r\nCopyright 2018 United States Government as represented by the Administrator of\r\nthe National Aeronautics and Space Administration. No copyright is claimed in\r\nthe United States under Title 17, U.S. Code. All Other Rights Reserved.\r\n \r\nDisclaimers\r\nNo Warranty: THE SUBJECT SOFTWARE IS PROVIDED \"AS IS\" WITHOUT ANY WARRANTY OF\r\nANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED\r\nTO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY\r\nIMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR\r\nFREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR\r\nFREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE\r\nSUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN\r\nENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS,\r\nRESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS\r\nRESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY\r\nDISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF\r\nPRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT \"AS IS.\"\r\n \r\nWaiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE\r\nUNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY\r\nPRIOR RECIPIENT. IF RECIPIENT'S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY\r\nLIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE,\r\nINCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S\r\nUSE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE\r\nUNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY\r\nPRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT'S SOLE REMEDY FOR\r\nANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS\r\nAGREEMENT.\r\n\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A package for performing uncertainty quantification using a parallelized sequential Monte Carlo sampler.",
"version": "0.1.5",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fa0ec8b0acd80586bc56aeb60706eb18e45acd3c805445451fb94fda84049c85",
"md5": "5a77a792de0491f24e53b17a621b0e0c",
"sha256": "aefe61a3376a7ec2dca838f7c9741a3e0c15985b55ef51f5e2576eb5019c49ca"
},
"downloads": -1,
"filename": "smcpy-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "5a77a792de0491f24e53b17a621b0e0c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.4",
"size": 32341,
"upload_time": "2023-01-31T19:50:05",
"upload_time_iso_8601": "2023-01-31T19:50:05.069263Z",
"url": "https://files.pythonhosted.org/packages/fa/0e/c8b0acd80586bc56aeb60706eb18e45acd3c805445451fb94fda84049c85/smcpy-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 19:50:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "nasa",
"github_project": "SMCPy",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"requirements": [],
"lcname": "smcpy"
}
