Skip to main content

pyPI: Tropical cyclone potential intensity calculations in Python

Project description

pyPI: Potential Intensity Calculations in Python

pyPI is a set of scripts and notebooks that compute and validate tropical cyclone (TC) potential intensity (PI) calculations in Python. It is a fully documented and improved port of the Bister and Emanuel 2002 algorithm (hereafter BE02) which was originally written in FORTRAN---and then MATLAB---by Prof. Kerry Emanuel (MIT). Kerry's original MATLAB code (pcmin.m) is found at:

The goals in developing and maintaining pyPI are to:

  • supply a freely available validated Python potential intensity calculator,
  • carefully document the BE02 algorithm and its Python implementation, and to
  • demonstrate and encourage the use of potential intensity theory in tropical cyclone climatology analysis.

If you have any questions, comments, or feedback, please contact the developer or open an Issue in the repository.


pyPI was developed by Daniel Gilford and has been archived on Zenodo:


If you use pyPI in your work, please include the citation:

Gilford, D. M. 2020: pyPI: Potential Intensity Calculations in Python, v1.2, Zenodo, doi:10.5281/zenodo.3900548.

Full pyPI Description

Please read pyPI_Users_Guide_v1.3.pdf for a full overview and details on pyPI. The description includes the pyPI background, a PI computation derivation, validation against the commonly-used MATLAB algorithm (pcmin), and a set of sample analyses.

A manuscript detailing the development of pyPI is be prepared for submission.

Getting Started

pyPI requires Python version 3.7+ to run. It was written and tested with Python 3.7.6. To get pyPI up and running on your system, clone the repository and ensure that you have the required dependencies.


Use the python package manager pip to install pyPI (tcpypi) from the command line:

pip install tcpypi

pyPI Dependencies

Python Implementation of "pc_min" (BE02 PI Calculator) is the Python function which directly computes PI given atmospheric and ocean state variables (akin to the BE02 algorithm MATLAB implementation pc_min.m). Given input vector columns of environmental atmospheric temperatures (T) and mixing ratios (R) on a pressure grid (P), sea surface temperatures (SST), and mean sea-level pressures (MSL), the algorithm outputs potential intensity, the outflow level, the outflow temperature, and the minimum central pressure, and a flag that shows the status of the completed PI calculation. pyPI is an improvement on pcmin in that it handles missing values depending on user input flags.

Users who want to apply the PI calculation to a set of local environmental conditions need only to download, organize their data appropriately, and call the function to return outputs, e.g.:


Running a pyPI Sample

Included in the pyPI release is a sample script which runs global sample data from MERRA2 (in 2004) through, vectorizes the output, and performs several simple analyses. To run, simply:


and examine the outputs locally produced in

File Descriptions

Key files

  • - The primary function of pyPI, that computes and outputs PI (and associated variables) given atmospheric and ocean state variables.
  • - Example script that computes PI and accompanying analyses over the entire sample dataset


  • - Sample atmospheric and ocean state variable data and BE02 MATLAB output data; values are monthly averages over the globe from MERRA2 in 2004.
  • mdr.pk1 - Python pickled dictionary containing Main Development Region definitions from Gilford et al. (2017)
  • - Sample outputs from only created by
  • - Full set of sample outputs from as well as sample analyses such as PI decomposition

Validation and Testing Notebooks


  • - Set of functions used in the pyPI codebase
  • - Set of meteorological constants used in the pyPI codebase
  • reference_calculations.m - Script used to generate sample BE02 MATLAB outout data from original MERRA2 files monthly mean; included for posterity and transperancy
  • pc_min.m - Original BE02 algorithm from MATLAB, adapted and used to produce analyses of Gilford et al. (2017; 2019)
  • clock_pypi.ipynb - Notebook estimating the time it takes to run pyPI on a laptop


  • Daniel M. Gilford, PhD - Development & Maintenance - GitHub


  • Daniel Rothenberg, PhD - Numba Optimization & Sample Code - GitHub


This project is licensed under the MIT License - see the LICENSE file for details


  • Kerry Emanuel (MIT) - Development of potential intensity theory; encouragement and permission to pursue Python implementation
  • Susan Solomon (MIT), Paul O'Gorman (MIT), Allison Wing (FSU) - Helpful conversations, advice, and suggestions on TC PI research
  • Dan Chavas (Purdue), Jonathan Lin (MIT), Raphael Rousseau-Rizzi (MIT) - Feedback on pyPI code and documentation

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tcpypi, version 1.3.1
Filename, size File type Python version Upload date Hashes
Filename, size tcpypi-1.3.1-py3-none-any.whl (14.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size tcpypi-1.3.1.tar.gz (15.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page