Metadata-Version: 2.1
Name: paratc
Version: 0.1.2
Summary: Functions for creating parametric tropical cyclone models.
Home-page: https://github.com/davbyr/ParaTC
Author: David Byrne
Author-email: dbyrne@woodwellclimate.org
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: xarray
Requires-Dist: netcdf4
Requires-Dist: jupyterlab
Requires-Dist: pip
Requires-Dist: xesmf

## ParaTC: Parametric Tropical Cyclones

Statistical tropical cyclone models are frequently used in modelling wind and storm surge risk for coastal communities. This package makes their generation easier, and exposes equations to generate pressure profiles, wind profiles, apply inflow angles, add background fields and scale winds. The package also provides functions for converting generated windfields into a forcing file for the ROMS ocean model.

You can either interact with the equations and modules to generate storms directly, or you can use the TCModel class to automate it.

See the example notebooks in docs/ for some basic tutorials.

This package is only for the generation of storm wind fields, stress and pressure with flexibility. If you want to do risk analyses, other great packages exist such as Climada and TCRM.

<p align="center">
	<img src="https://raw.githubusercontent.com/davbyr/ParaTC/master/docs/example_2D.png" alt="Example 2D storm"/>
</p>

### Installation

For development:

1. Clone this repository and change directory into it.
2. Install dependencies using `environment.yml`: `conda env create -n paratc_env -f environment.yml`.
3. Activate the environment: `conda activate paratc_env`
4. Install the package: `pip install -e .`

### Modules

1. `bg_models`: Functions for the generation of background flow fields. 
2. `inflow_models`: Functions for the generation of gridded inflow angles, to apply to tropical cyclone fields.
3. `rmw_models`: Statistical models of radius of maximum winds.
4. `stress_models`: Functions for the conversion of wind vectors into wind stress.

### TC Models

All tropical cyclone models are children of the `TCModel()` class. Therefore, the functionality available to `TCModel` is also available to other cyclone models.

1. `TCModel()`: Stores the cyclone dataset and processed track information. Contains functions for automatically applying inflow angles, background models, wind scaling, interpolation and conversion to model forcing.
2. `Holland1980()`: The (Holland, 1980) model is one of the most prominent tropical cyclone models. This class provides functions for generating pressure and wind profiles, and estimating the shape parameter `B`. 

## Example Useage

For more in depth examples see docs/.

### Basic Equations
You can generate a Holland pressure and gradient wind profile as follows:

```python
# Imports...
import numpy as np
from paratc.tc_models import Holland1980 as h80

# Make 1D array of storm center distances ... out to 1000km
rdist = np.arange( 0, 1000, 0.5 )
B = h80.B_vickery00( 1015-900, 50 )

# Make pressure / gradient winds
pressure = h80.pressure_equation( rdist, rmw = 50, B = B, penv = 1015,
                                         pcen = 900, lat = 35 )
windspeed = h80.gradient_wind_equation( rdist, rmw = 50, B = B, pdelta = 1015-900,
                                        lat = 35 ) 
```

<p align="left">
	<img src="https://raw.githubusercontent.com/davbyr/ParaTC/master/docs/example_profiles.png" alt="Example storm profiles"/>
</p>


### Functions for inflow angle, background flow and wind stress

You can access models for inflow angle, background flow and wind stress:
```python
from paratc import inflow_models, bg_models, stress_models

# Make inflow angle using piecewise function of distance
angle = inflow_angle.wang20( rdist, rmw = 50 )

# Make background wind field that decays with distance from storm center
u_bg, v_bg = bg_models.MN05( rdist, utrans = 1, vtrans = 1, rmw = 50 )

# Make wind stress as quadratic function of wind speed
drag_coef = stress_models.cd_garratt77( 10 )
stress = stress_models.quadratic_stress_equation( windspeed = 10, cd = drag_coef )
```

### Using a TCModel to automate storm generation
We can generate entire 2D storm fields, with an added time dimension as follows:

```python
# Imports. We only need h80 for the class based approach
from paratc.tc_models import Holland1980 as h80
from paratc import make_example_data

# Open example track and generate example grid
track, grid_lon, grid_lat = make_example_data()

# Create storm instance and look at dataset
storm = h80( track, grid_lon, grid_lat, B_model='vickery00' )

# Scale winds to surface level
storm.scale_winds( 0.91 )

# Apply piecewise inflow angle model
storm.make_wind_vectors( inflow_model = 'wang20' )

# Add background winds using reciprocal relationship
storm.add_background_winds( bg_alpha = .55, bg_beta = 20 )
```

When the instance of `Holland1980()` is created, the class will check the track inputs, generate B and rmw (where missing), then create a new xarray dataset containing the grid coordinates (`grid_lon` and `grid_lat`), pressure and wind vectors. This can be accessed using `storm.data`.

### Export a TCModel instance to model forcing file (ROMS)

```python
# Read in ROMS grid file
grd = xr.open_dataset('ROMS_grd.nc')

# Convert storm dataset to ROMS forcing
storm.to_ROMS( grd, rotate_to_grid = True )
storm.to_netcdf( 'roms_frc.nc' )
```

## Contribution
At the moment this package only have functionality for the Holland model. Please feel free to contact me if you would like to contribute to the package.
