STILT Model User Guide

[Derek Mallia]

STILT Model User Guide




Introduction:

Welcome to my STILT model user guide! This guide will teach you how to install a forward and backward trajectory model called the Stochastic Time-Inverted Lagrangian Trajectory (STILT) model. This model uses meteorological model data in a ARL format and produces an ensemble of either forward or backward trajectories. This model uses 3D wind vectors to generate the trajectories of air parcels in the free atmosphere. If the air parcel that you are tracking is within the PBL the model will incorporate random turbulent motions using a Markov chain process. This gives it a significant advantage over the HYSPLIT model which this model was originally built off of in 2003. This model can be used with GDAS, EDAS, NAM, ECMWF, and WRF output. A website and papers detailing this model can be found here.

Some applications of this model are: determining potential moisture sources for atmospheric river events and determining how parcels of air from a source will disperse over time. Here is a sample plot that I created when modeling atmospheric motions associated with Hurricane Sandy (backwards in time, note the cyclonic motion associated with this system as this is what you could expect with a northern latitude low pressure system):









Installation:

System Requirements:

Working version of FORTRAN (any compiler should be fine)
Some type of unix based OS
Installed version of R and some additional libraries for plotting
Register at the following page to can access to STILT repository:
www.bgc-jena.mpg.de/bgc-systems/projects/stilt/pmwiki/pmwiki.php?n=Registration.Registration


1) Make a working directory for the local STILT repository:

mkdir STILT_svn


2) Retrieve a working copy of the svn STILT repository with svn from

projects.bgc-jena.mpg.de/STILT/svn/trunk

usage:

cd STILT_svn
svn --username USER checkout projects.bgc-jena.mpg.de/STILT/svn/trunk

if you have no access to the repository please read the
remarks in the registration part.



3) Make a working directory for STILT modelling:

mkdir STILT_modelling



4) Copy the R scripts that are specific for the STILT model that are within the STILT_svn
STILT_svn directory:

cp -R STILT_svn/trunk/stiltR STILT_modelling



5) Copy from the "stiltR" subdirectory the file "setup.sh" inthe created
STILT modelling working directory and set the execution permission:

cp STILT_modelling/stiltR/setup.sh STILT_modelling
chmod +x STILT_modelling/setup.sh



6) Run the script "setup.sh". This script will create some sub-directories
(Output, STILT_Exe) in the STILT modelling working directory and will setup
some files:


The STILT Modelling working directory "must have" now:

- a "stiltR" subdirectory or link containing the R
part of STILT
- Output subdirectory
- STILT_Exe subdirectory
- "setStiltparam.r" with the STILT run parameters
- "stilt.bsub.sh"
- "stilt.qsub.csh"
- 00README_copy.TXT - this contents of this file is not updated



7) Put the following line in either your .bashrc file located
in the home directory. This will set the path for the R libraries once you
have them installed:

export R_LIBS=/uufs/chpc.utah.edu/common/home/<USERNAME>/R/x86_64-unknown-linux-gnu-library/2.15/

Reset your terminal afterwards.



8) Install R, and the following libraries "foreign" and "fields". Since R
has already been instead CHPC you will simply need to consult with
one of the members of John Lin's group to aquire the R libraries. To install
R libraries see the R user guide (super easy to do under R!):

www.cran.r-project.org/doc/manuals/R-intro.pdf



9) Compile an executable "hymodelc" from the sources and Makefile in the
"trunk/merged_stilt_hysplit/" directory. To compile this code simply type in the
following command WHILE IN the merged_stilt_hysplit directory:

make

This will compile the code which will take approximately 30 seconds.


9) Need to make corrections to several of the fortran subroutines in order to
have the STILT model run correctly. Add the following line to the listed
FORTRAN programs: adv2nt.f adv3nt.f adv3ntZML.f

I1P=min(I1+1,size(s,1))
J1P=min(J1+1,size(s,2))


These lines need to be added to each of the listed subroutinesright after
the commented line "!set upper index" and before the commented line
"!cyclinic boundary conditions". Then comment the following lines out with
a leading "!":

!I1P=I1+1
!J1P=J1+1

This seems to only be necessary if using EDAS model data.



10) You will then be able to recompile the code after making the changes. As
like before run the "make" command in the command line.



11) Copy the hymodelc program from your "merged_stilt_hysplit" directory into your
working stilt modelling direction that you created before. In this case the
directory was "STILT_modelling"



12) Within your STILT_modelling directory there should be a STILT_Exe directory.
Copy the hymodelc program into Copy0 directory within the STILT_Exe
directory:

cp hymodelc /uufs/chpc.utah.edu/common/home/lin-group1/dvm/STILT_modelling/STILT_Exe/Copy0/hymodelc



13) Great, you are ready to go! For your first time using STILT simply following the 0stilt_tutorial.r file
within the stiltR directory. Enter the code line by line and make the necessary changes for best results.
You will have to make minor changes to the path names since the geared towards to the JENA settings.





Some IMPORTANT notes:

WRF and ECMWF data can't directly be used with the STILT model as they don't natively come in the ARL format. See the following page with instructions on how to couple the STILT model with WRF output. This essetially requires editing the WRF registry which will require a recompilation of WRF and the need to install the ARL converter program (need PGI compilers for this). See the following webpage for more details:

www.bgc-jena.mpg.de/bgc-systems/projects/stilt/pmwiki/pmwiki.php?n=WRFSTILT.WRF-STILT


I will add a more detailed version of how to the ARL converter and makes changes to the Registry file as this isn't the most trivial thing. 


ARL formated data can be found here:

ready.arl.noaa.gov/archives.php


Also, located below there is a sample R script which will run the STILT model. In this case R acts as an interface between the user and the FORTRAN code (yucky!). You can edit some of the run time variables in the R script in order to run the STILT model with specified settings (such as model data location, output location, time, number of trajectories, ect..). You will need to make adjustments to the script in order to have it run successfully on your computer (simply involves just changing model input and output paths). Also make sure you understand the basics of R before running this script so if you get an error you have an idea what you did wrong!



#################################################################################################################
#################################################################################################################
####                                                                                                                                                    ###########################################
####   This is a script that illustrates how to run STILT and how STILT works                       ###########################################
####   3/17/2004 by John Lin and edited by DVM 5/7/2013                                                      ###########################################
####                                                                                                                                                    ###########################################          
#################################################################################################################
#################################################################################################################

#source necessary scripts and functions, set this to YOUR path

sourcepath<-"/uufs/chpc.utah.edu/common/home/lin-group1/dvm/STILT_modelling/stiltR/"

source("sourceall.r")                              #'sourcepath' specifies the directory where all the scripts and functions are found



################################################################
#set run time parameters needed for STILT (similar to a WRF namelist file)
################################################################

# set directories to where your data is located and where you want your output placed

path<-"/uufs/chpc.utah.edu/common/home/lin-group1/dvm/model_output/"                                    #path where output gets saved,
metpath<-"/uufs/chpc.utah.edu/common/home/lin-group1/dvm/model_input/"                                #where met data are stored in ARL format
rundir<-"/uufs/chpc.utah.edu/common/home/lin-group1/dvm/STILT_modelling/STILT_Exe/"      #specifies main directory where different directories are found to run                                                                                                                                                                             #hymodelc (check on)



#Run time options for the STILT

varstrajec<-c("time","index","lat","lon","agl","grdht","foot","sampt","temp0","swrad","zi","dens","dmass","sigmaw","TL","pres")        #specifies output parameters

overwrite=T                                                            #T: rerun hymodelc, even if particle location object found; F: re-use previously calculated particle location object



#----- basic parameters -----#

nhrs<- -12                            #for how many hours to run (time-backward runs negative, forward runs positive).
nparstilt<-100                     #how many particles per receptor? 100 of for receptor oriented modeling with dynamic grid resolution is ok
veght<-0.5                          #surface layer (for fluxes); if less than 1 then as fraction of mlhgt; 0.5 is a good value.
convect<-F                         #T for convection (RAMS winds: grell convection scheme, EDAS and FNL: simple redistribution within vertical range with CAPE>0)
stepsize<-0                        #Enforces Courant criterion. When >0: maximum horizontal distances travelled by a particle in a single time step, in km.                           
winderrTF<-F                    #transport error due to wind error included as stochastic process?
nummodel<-0                   #which copy of the model to run? Will be in directory named paste(rundir,"Copy",nummodel,sep="")
delt<-30                             #fixed timestep [min]; set =0 for dynamic timestep
numpar<-100                   #number of trajectory paths created

metfile<-c("DATA_MASS.WRF_2011_02_12_06","DATA_MASS.WRF_2011_02_12_12")         #Sets specific met file name


#----- starting times & locations -----#

yr<-11                    # year
mon<-2                  # month
day<-13                 # day of month
hr<-0                      # hour in UTC (0-23)
lat<-40.750           #latitude
lon<--111.8833    #longitude
agl<-150               #height in meters above ground level


###### Run STILT ###### 

info<-Trajec(yr=yr,mon=mon,day=day,hr=hr,lat=lat,lon=lon,agl=agl,nhrs=nhrs,doublefiles=T,metd=c("edas","fnl"),delt=delt,numpar=numpar,veght=
veght,metfile=metfile,nummodel=nummodel,metlib=metpath,conv=convect,overwrite=overwrite,outpath=path,varsout=varstrajec,rundir=rundir)

#get back the object that has been stored in .RData* file (filename is info["outname"]

dat<-getr(info["outname"],path=path)


###### generate map of particles #####

library(maps);flttrack(lon=dat[,"lon"],lat=dat[,"lat"],col=2,cex=0.5,cities=T);map("state",add=T)




# End of script

################################################################################################################################################
################################################################################################################################################


If you have any questions don't hesitate to ask me! I will try to get back to you in a timely fashion (dependent on upcoming deadlines).

[e-mail]



Last edited on 9/3/2013