==Introduction==

Puffin is a coupling of the programs Puffin (also known as Bent) and 
Puff. Puffin is a theoretical model of a volcanic plume based on applying the equations of 
motion in a plume-centered coordinate system. 
Puff simulates the transport, dispersion and sedimentation of volcanic ash.
Puff also prepares some scripts to turn the cdf files generated into images.
ImageMagick then creates an animated gif using these images, 
so we can see how ash spreads over time.

==Required Preparations==

The tools we use require large databases, too large to be stored on Vhub.
For this reason, you will need to mount onto the irods database in order to be able to run Puffin.
Additionally, for large runs you have the option of sending larger jobs to the cluster.

First of all, you need to join the '''network''' group. 

Once you are accepted, look up the topics page for [http://vhub.org/topics/iRodsforHUBs installing irods] 
to get details on how to set up irods.
For the purposes of running Puffin, I recommend having the irods directory be in your home directory
and to stay logged in as the public user.
All necessary databases are in the public folder.

==Example Run==

When you start Puffin, most of the entries will start out as filled.
The only entries you may need to change for a test run are the locations of the reanalysis
databases on the Database tab.
If you set up irods to be in your home directory, it will automatically set up the locations
in the gui.

In order to run the test run, you just need to press the three buttons on the '''run''' tab in order.
The first button runs puffin, which fills out some information about the plume on the puff input tab.
The second button runs puff, which will create the cdf files representing the ashes.
The third button creates the animations, which will then display on the '''output''' tab.
You can view these various animations by clicking the buttons on the bottom of the output tab.

The prepared run simulates a volcanic plume in Iceland.
The sample runs only 10000 particles over a 72 hour period, so it runs rather quickly.
Running puffin should take less than a minute.
Running puff should take less than five minutes.
Creating the animations should take less than a minute.

Discussing each tab  in more detail:

===Puffin Input===

All the entries here are pretty self expanatory.

If you have the .inp from a previous run, you can load the information from a previous run.
Just select the .inp file, and press load.
All relevant entries will be updated.

===More Puffin Input===

In order to simulate how the ash will move up into the atmosphere,
you need to give information about the air conditions, given by a weather balloon file.
If you have one already, just mark in where the file is, what are the relevant columns,
and what the relevant columns represent.
If you do not have one, select generate weather file in order to automatically generate one
from the databases.
Note that this requires all 3 databases from the database tab to be filled out.

Additionally, you have the choice to specify the mean and standard diviation, or just
select grain random.

===Puff Input===

First of all, having ash output selected is very important.
With no intermediary ash outputs, no images can be made for the animation.

Also, note that the bottom six entries will be filled out by running puffin.
You do not need to fill them out yourself if you are doing a full run through.

===Databases===

There are three databases that may need to be set up.

The wind u and wind v databases (which is in miles per hour) are needed to run puff.

The temperature database (which is in Celcius) is only needed for generating a weather balloon file for puffin.


For each database you need to set:

* MODEL- The name of the model you are using.

* DIR- The directory where your nc file is.

* MASK- The filenames of the data files. YYYY represents where the year would go.

* VAR- What is the name of the variable you are taking from the database. u for uwind, and v for vwind. For temperature, this is unused.

* VARUNAME- The name of variable within the nc file that we use.  This can be found by running `ncdump -h` on the file.

The irods username is only needed for remote runs. The Irods username is used to
   convert the directory paths of an irods mount into the directory paths on 
   the cluster.

===Image Properties===

The images to output button selects which images to create. 
Warning: Ashgmt currently requires some files that are not on Vhub.
Ashgmt will not be able to create an image.


===Run===

First of all, you specify where you want to output in the output folder,
and whether you want to create a new folder to keep the information in with run name.
Every time puffin run, a new folder will be created based on the current time.

Normally, you will want to press run puffin, then run puff, then make animations.

You have the option to send the job to the cluster. 
Puffin runs will always be done locally, but you can send Puff runs and the animation runs to the cluster.

===Output===

If successful, there will be images on the output tab after make animations is run.
Click the tabs on the bottom in order to cycle through the images made.