Package: tcpypi
tcpyPI: Potential Intensity Calculations in PythontcpyPI, 'pyPI' for short, 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 theBister and Emanuel 2002algorithm (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:http://texmex.mit.edu/pub/emanuel/TCMAXThe 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 todemonstrate and encourage the use of potential intensity theory in tropical cyclone climatology analysis.If you have any questions, comments, or feedback, pleasecontact the developeror open anIssuein the repository. A paper detailing pyPI is publishedat Geoscientific Model Development.CitationpyPI was developed byDaniel Gilfordand has been archived on Zenodo:If you use pyPI in your work, please include the citations:Gilford, D. M.: pyPI (v1.3): Tropical Cyclone Potential Intensity Calculations in Python, Geosci. Model Dev., 14, 2351–2369,https://doi.org/10.5194/gmd-14-2351-2021, 2021.andGilford, D. M. 2020: pyPI: Potential Intensity Calculations in Python, pyPI v1.3. Zenodo.http://doi.org/10.5281/zenodo.3985975Full pyPI DescriptionPlease readpyPI_Users_Guide_v1.3.pdffor 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.Getting StartedpyPI requiresPython 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.InstallationIs packaged using the python package managerpip.To install tcpypi from the command line:pipinstalltcpypitcpyPI DependenciesNumPyNumbaNot required by tcpyPI---but highly recommended!---is the versatility in calculating PI over large datasets provided byxarray.
Dependancy versions and the associated tcpyPI updates are handled byDependabot.Python Implementation of "pc_min" (BE02 PI Calculator)pi.pyis the Python function which directly computes PI given atmospheric and ocean state variables (akin to the BE02 algorithm MATLAB implementationpc_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 downloadpi.py, organize their data appropriately, and call the function to return outputs, e.g.:(VMAX,PMIN,IFL,TO,LNB)=pi(SST,MSL,P,T,R)Running a pyPI SampleIncluded in the pyPI release is a sample scriptrun_sample.pywhich runs global sample data from MERRA2 (in 2004) through pi.py, vectorizes the output, and performs several simple analyses. To run, simply:python run_sample.pyand examine the outputs locally produced infull_sample_output.nc.File DescriptionsKey filespi.py- The primary function of pyPI, that computes and outputs PI (and associated variables) given atmospheric and ocean state variables.run_sample.py- Example script that computes PI and accompanying analyses over the entire sample datasetDatasample_data.nc- 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 fromGilford et al. (2017)raw_sample_output.nc- Sample outputs from pi.pyonlycreated by run_sample.pyfull_sample_output.nc- Full set of sample outputs from pi.py as well as sample analyses such as PI decompositionValidation and Testing Notebookstest_pi_calc.ipynb- Simple code showing a single call of pi.py and testing the speed of the algorithmverify_pi.ipynb- Notebook validating/verifying pyPI outputs against BE02 MATLAB output datasample_output_analyses.ipynb- Notebook showing examples of pyPI outputs and simple PI analysesMisc.utilities.py- Set of functions used in the pyPI codebaseconstants.py- Set of meteorological constants used in the pyPI codebasereference_calculations.m- Script used to generate sample BE02 MATLAB outout data from original MERRA2 files monthly mean; included for posterity and transperancypc_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 laptopAuthorDaniel M. Gilford, PhD-Creation, Development, & Maintenance-GitHubContributor(s)Daniel Rothenberg, PhD-Numba Optimization & Sample Code-GitHubLicenseThis project is licensed under the MIT License - see theLICENSEfile for detailsAcknowledgmentsKerry Emanuel (MIT) - Development of potential intensity theory; encouragement and permission to pursue Python implementationSusan Solomon (MIT), Paul O'Gorman (MIT), Allison Wing (FSU) - Helpful conversations, advice, and suggestions on TC PI researchDan Chavas (Purdue), Jonathan Lin (MIT), Raphael Rousseau-Rizzi (MIT) - Feedback on pyPI code and documentation