search

Jacks0nJ / PyFPT

Stochastic first-passage time (FPT) simulations using importance sampling.
Apache License 2.0
12 stars 1 forks source link
cosmology cython first-passage-times importance-sampling inflation stochastic

readme

PyPI version License example workflow DOI

What is PyFPT?

PyFPT is Python/Cython package to run first-passage time (FPT) simulations using importance sampling. An FPT problem is about finding the time taken to cross some threshold during a stochastic process.

This package will let you numerically investigate the tail of the probability density for first passage times for a general 1D Langevin equation.

The tail of the probability density is investigated using the method of importance sampling, where a bias increases the probability of large FPTs, resulting in a sample distribution, which are then weighted to reproduce the rare events of the target distribution. This allows very rare events (normally needing supercomputers) to be simulated efficiently with just your laptop!

Note, it was originally developed to find the local number of e-folds in slow-roll stochastic inflation. As such, analytical functionality is also included for this particular problem in the analytics module.

(back to top)

Documentation

You can find the latest documentation on PyFPT's ReadTheDocs page.

Requirements

Operating System

As PyFPT uses Cython to optimise the stochastic simulations, a C-compilier is required for installation. Therefore, PyFPT does not currently run (future releases hope to address this issue) on Windows directly. Windows uses can either install PyFPT on a virtual machine or use a cloud-based service such as SciServer.

Mac and Linux user should be able to directly install PyFPT, as these operating systems have a C-compiler. Do feel free to raise an issue or contact us if you have any problems.

Packages

The following packages are required to run PyFPT

Many of which are included in common Python distributions like Anaconda. You can check which packages you already have installed with pip list.

(back to top)

Getting Started

User Guide

The documentation contains a user guide, whose code you can run yourself as interactive Jupyter notebook by downloading them.

Installation

The package can be installed by using the following command

pip install PyFPT

in the command line wherever you have Python installed.

You can also clone the PyFPT repository

git clone https://github.com/Jacks0nJ/PyFPT.git

to work on it locally. This would require compiling the Cython code (the .pyx files) locally as well.

(back to top)

Example Results

The PyFPT package can be used to investigate far into the tail of the probability density (down to 10^-34 and beyond!)

Or even deviations from Gaussianity!

In the above images `N' is the first-passage time in stochastic inflation.

See the user guides for details on how you can make these figures yourself!

(back to top)

Unit Testing

PyFPT uses the unittest module to maintain the code. Almost all functions have some form of basic unit testing, which hopefully will be further developed as the project continues. The tests can all be found in the tests folder.

If unittest is installed, then the tests can be run locally using 

pytest -v

This tests the functions which have been installed using pip. The easiest way to run the test suite on any modified functions is to upload to your branch to the repo, as (the uploaded) tests run every commit on the code uploaded.

(back to top)

Roadmap

See the open issues for a full list of known issues.

(back to top)

Development branches

As different contributors continue to development the code, they will do so in several different branches. Therefore, it cannot be guaranteed that any branch, other than the main, will be fully functional at any one time. The main branch will be the correct release of the code available on PyPI and what you will install using pip.

Contributing

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

And we will review your request!

(back to top)

Bugs

This is the initial release of PyFPT, so it is expected there will be some minor bugs. Feel free to either report by raising an Issue on Github, emailing joseph.jackson@port.ac.uk or fork the repository with your fix.

Your feedback is very much appreciated!

License

Distributed under an Apache-2.0 License. See LICENSE.txt for more information.

(back to top)

Contact

Joe Jackson - joseph.jackson@port.ac.uk

Project Link: https://github.com/Jacks0nJ/PyFPT

(back to top)

Acknowledgments

We would like the following contributors to PyFPT, be it through physical understanding of first-passage time processes or help developing the package

The Physics

Package Development

Logo

Resources

The following resoucres were instrumental in developing the project into a package usable by the community:

(back to top)