AshDisperse

AshDisperse is a python project to simulate tephra dispersal from explosive volcanic eruptions, using a fast and highly accurate steady-state advection-diffusion-sedimentation model.


## Requirements
python3 with a suitable package manager (pip3 is recommended)

AshDisperse uses a number of python packages, listed in the requirements.txt file.
Importantly, AshDisperse uses numba to produce fast, compiled python code for many of the numerical routines.  AshDisperse.py will work without numba but will be very considerably slower.

AshDisperse can download ERA5 meteorological data files.  This requires a copernicus account -- see https://cds.climate.copernicus.eu/api-how-to

The jupyter notebook, AshDisperse.ipynb, uses the jupyter_contrib_nbextensions 'Python Markdown' extension (https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/python-markdown/readme.html).


## Package contents
README.txt		-- this file
AshDisperse.py  	-- the main AshDisperse code
queryreport.py  	-- python routines for command-line input
AshDisperse.ipynb	-- the AshDisperse jupyter notebook
GVP_Volcano_List.csv	-- a formatted dataset of volcano names and locations, from https://volcano.si.edu/list_volcano_holocene.cfm
Example.nc		-- an example global netcdf meteorological file
requirements.txt	-- required package list for use with pip
ashenv.yml		-- environemt of required packages for use with conda on linux
ashenv_windows.yml	-- environemt of required packages for use with conda on windows


## Install
It is recommended to set up either a pip virtualenv or an anaconda environment to ensure that all required packages and versions are self-contained and do not interfere with other python setups.

# pip install

create a virtualenv and then run

pip install -r requirements.txt

# conda install

from a base anaconda environment, run

conda env create -f ashenv.yml

NOTE: this will create a new conda environment call "ash".  To change the name of the environment, open the ashenv.yml file in a text editor and in the first line set your preferred name.

Once the environment is create, activate and you should be set to go.


## Running the model
There is a detailed jupyter notebook illustrating the application of AshDisperse.  The notebook can be started using the command:

jupyter notebook AshDisperse.ipynb

It is also recommended to experiment with AshDisperse in a ipython session.

AshDisperse.py can be run from the command line -- the command line interface is under development and will have extended functionality soon.