ATSC595AirPollutionModellingHYSPLITModelQuickGuide-OSX,Linux

Feb.2016M.Fung

TheNOAAAirresearchlabHYSPLITmodelcomesbothinexecutableform,aswellassourcecodeformdependingontheOperatingSystem.ThisguidewillcoverinstallationofHYSPLITonMacusingprecompiledfiles,andonLinuxusingsourcecode.ObtainingtheHYSPLITairpollutionmodelrequiresregistrationwithNOAAARL.Thisusuallytakesabusinessdaybutcanextendtoaweek.PleasefollowtheproceduresforregistrationontheARLwebsitepromptlybeforeinstallingHYSPLIT(ForthosewhodesiretocompilethroughUNIXsourcecode,pleasementionthatinyourregistrationemail).Eachmethodhasitsprosandcons,pleaserefertothegraphicbelowtofindoutthemethodthatbestsuitsyourneeds.

Contents

1. ARLRegistration

2. DownloadandInstalla. MacPrecompiledRoute

i. Installationii. UsingMansonServertoconvertWRF

b. UNIXSourceRoutei. Installation

3. Commonbugs&hints

InstallOption Compatiblewith RequiresAdmin

Rights

WRFInput

Compatible

PC PC Y? N*

MacPrecompiled Mac N N

UNIXSource Linux Y Y

1. Download&ARLRegistration(all)

DownloadsforWindowsPCHysplitdoesnotrequireanARLaccount,butforOSXandlinuxbinaryfiledownload,registrationisneeded.SinceweareusingHysplitforeducationalpurposes,theonly‘credentials’neededisaEOASletterhead,andareferralfromapersonwhoalreadyhasanaccount.

i. RegisterforanNOAAARLaccountathttp://ready.arl.noaa.gov/HYSPLIT_register.phpAfterareadthroughofthedocuments,youwillbepromptedtofillandemailaformtothewebmaster.

ii. Theformrequiresanattachmentofaletterheadoftheaffiliatedinstitution.Forthosewhohaveanmyeosaccount,theEOASletterheadcouldbedownloadedunder“Tools->Downloads”andatthebottom,“EOASletterhead”.

iii. Ifascannerisaccessible,byallmeansprint,fillandscantheform.Thisis

probablythemostlogicalwaybecausetheformalsorequiredasignature.Theformcouldalsobefilledwithanypdfviewer.Adobereaderisprobablytheeasiestwayoffillingthetextsintheform,howeverwhenItrieddoingthatontheWFRTiMacs,adobereaderseemstodistorttheletterhead,notthatitistoobigofanissue.

yuck

Fireofftheemailthearl.webmaster@noaa.govandyouwillreceiveanaccountconfirmationinafewdays.(Forthosewhowantsourcecode,pleasementionthatyourequirethe“UNIXsourcecodeinstructions

2ai.MacDownload&Installation

i. Onceaccountisgranted,gotoARL,Apple-basedHYSPLIT,anddownload“ApplediskimageFile”.

ii. OncediskimageHYSPLIT_mac.dmgisdownloaded,doubleclickandopenthe.dmg.ThereshouldbeadrivepoppinguponyourdesktopcontainingtheHysplitfiles.

iii. Afterinspectingthefolder,copyHysplit4tohomedirectory.Thiscouldbedonebyeithercopy-pastingthroughfinder.Toaccesshomedirectory,gotoanyfolderandclickcmd+upuntilyouhithomeΩ

Or,todothesamethinginterminal,run:

“cp–r/Volumes/Disk\image/Hysplit4~/“

iv. Onelastthingrecommendedinthehysplittutorialsistocopytheguilinktotheafolderinhysplit4.TakealookintheHysplit4directory,goto/Hysplit4/working:Ifyoudonotsee“hysplit4.tcl”,youneedtocreateasymlinkDothisbygoingtoterminalandtyping:

“cd~/Hysplit4/working”“ln–s~/Hysplit4/guicode/hysplit4.tclhysplit4.tcl”

(Thisassumesyou’veputHysplit4intoyourhomedirectory).Toconfirm,type:

“ls~/Hysplit4/working“ Andyoushouldseehysplit4.tcl*inyour/working/directory.

v. Executetheguiwiththefollowingcommand

“(cd~/Hysplit4/working&&./hysplit4.tcl)”

WhenIclickonthewindow,thebuttonsbecomedim/unreadable,butjustclickatabrowser window other than the hysplit window, and the buttons should becomereadableagain.

vi. Simpletest:

Inthemenusinterface,click “Trajectory ->QuickStart->RunExample”“Concentration->QuickStart->RunExample”

2aii.UsingMansonServertoConvertWRFinputfiles

i. WRFinputisformallynotsupportedforMacandPCversionsofHYSPLIT.Thatsaid,sincethe“manson.eos.ubc.ca”classserverrunsonLinux,wecanfirstconverttheWRFfilesonmanson,thenrunHYSPLITonourlocalcomputersForinformationonaccesstomanson,pleasereferto“MansonUserGuide”ForinformationonaccessingUBCWRFdata,referto“WFRTWRFdataGuide”

ii. FiletypePrimer:WRFrunsoutputfilesoftype“netCDF”TheUBCforecastsproducehourlynetCDFdatafiles.ThenetCDFfilesshouldbeavailableunder/scratch/datadirectory.

HYSPLITmeteorologyinputuses.BINbinaryasitsfiletype.

InordertoconvertnetCDFfilesinto.BINfiles,therearetwoexecutablefilesinManson,“prepARW.py,andarw2arl”locatedin/scratch/models/hysplit/exec

iii. PrepareDirectoryConnecttomanson.eos.ubc.ca

“ssh[username]@manson.eos.ubc.ca”CreateadirectorytostoreWRFfiles

Ex.“mkdir~/hysplit“CopyasetofWRFdatatoyourdirectory

“cp–r/scratch/data/wrf_sample~/hysplit/.”RunExecutablesonthefolder“cd~/hysplit/wrf_sample&&python/scratch/models/hysplit/exec/prepARW.py““cd~/hysplit/wrf_sample&&/scratch/models/hysplit/exec/arw2arlwrfout.nc”Thisproducesa.BINfilenamedARLDATA.BIN,whichyoucaninputtoHYSPLIT

iv. TransferfilestolocalcomputerBringyourterminalbacktothelocalcomputer,cdtothefolderwhichyouwanttocopythe.BINfile.

“cd/path/to/folder”Securecopythefilebytyping“scp[user]@manson.eos.ubc.ca:hysplit/wrf_sample/ARLDATA.BIN.“

2b.DownloadandInstallationfromSourceCode

i. UponregisteringwithARL,youshouldreceiveanemailwiththenecessaryinstructionstodownloadthesourcecodeeitherthrough‘svn’or‘wget’,somethinglike:

“wget-r--reject"index.html"-nH--cut-dirs=1--secure-protocol=auto--no-parent--no-check-certificate–user=XXXXX--password=XXXXXhttps://svn.arl.noaa.gov:8443/svn/hysplit/”

ii. Openterminal,changedirectorytothefolderofyourchoice:

“cd~/path/to/folder”

iii. Inputthe‘wget’commandwiththegivenusernameandpassword.Thiswillpromptthedownload.

Inspectthefilebytyping‘ls’ontheterminal.Youshouldseeanewfoldercalled“hysplit”

iv. CheckingDependenciesThis part is rather important for the installation process. Please refer to thefollowinggraphsandmakesurethatyourdependenciesareinstalled.Forthefollowingguide,IwillbeusingMacportsorHomebrewasMacpackagemanager,andpipaspythonpackager.Hereisthelistofdependenciesforthosewhoarecomfortableinchecking/downloadingdependenciesthroughothermeans.

\

b. CheckifXCodeandMacportisinstalled(OSXonly)“xcode-select”“port”Ifnothingpopsuponeithercommand,pleaserefertotheXCode&gfortraninstallationguideonATSC595website

c. VerifyPythonisinstalledbytyping“python--version”

Thecurrentscriptssupportpython2.7andpython3(testedwith3.5)

Compilation(forWRFinputsupport):-netcdflibrary(cxx,fortran)-nco(netcdfoperator)-pythonncopackage

Checksifyouhavepip(pythonmodulemanager)installed.

“pip--version” Ifnot,refertoyourpythonversionfound.Ifyouhavepython2.7,type: “portinstallpy27-pip” Similiarly,python3.4pipwouldbe‘py34-pip’

d. VerifythatnetCDFlibrariesareinstalled:

OnMac,type: “portinstalled|grepnetCDF"Ifyousee“netcdf,netcdf-cxx4,netcdf-fortran”listedonyourterminal,youdonotneedtoinstalladditionalpackages.Otherwise,installanymissingpackagebytyping:

“portinstall[nameofmissingpackage]”OnUbuntuLinux,type:

“aptitudesearch“~i”|grepnetcdf” Ifyousee“libnetcdf-dev”installed,youaregoodtogo. Otherwise,typethefollowinginterminaltoinstallthepackagesneeded.

“sudoapt-getinstalllibnetcdf-dev”

e. Verifythatncolibraryisinstalled:“ncatted”

Ifcommandisnotfound,pleaseinstallncobytyping:“portinstallnco”(Mac)“sudoapt-getinstallnco”(Linux)

f. Finally,verifypythonncopackageisinstalledbytyping:“piplist|grepnco”

Ifnot,installncomodulebytyping: “sudopipinstallnco”*

(mightnotneedsudoinfrontdependingonthefolderpermissionsonyourmachine)

Summary:

Packagename Checkifinstalled,typeinterminal: Shouldsee: InstallCommand:

macports(Maconly) port--version versiontext seegccmacportsetup

xcode(Maconly) xcode--version versiontext seegccmacportsetup

pip pip--version versiontext portinstallpy[version]-pip(eg."py27-pip")

netcdf(mac) portinstalled|grepnetcdf

netcdf

netcdf-cxx4

netcdf-fortran portinstall[packagename]

netcdf(linux) aptitudesearch"~i"|grepnetcdf

libnetcdf-dev

... sudoapt-getinstalllibnetcdf-dev

nco ncatted functioninfo

portinstallnco

(ncoisavailableinhombrew/science)

pythonnco piplist|grepnco nco(version) sudopipinstallnco

v. CompilingHYSPLITsourcecode:a.Updatesourcecode

Runupdate.shbytyping:“shupdate.sh”select“server”,“checkout”

choose‘r’foralltheotheroptions.

b.Checkversion&librarylocations

Inordertocompilethesourcecode,youneedtoknowthefollowinginformation:- nameofthefortrancompilerused- locationofnetcdflibraries(installedearlier)

I. Youshouldknowtheformerifyouhavehadinstalledmodelsbefore(eg. AERMOD)

Type “gfortran--version” “g95--version”

“pg95--version” Interminalandnotethefirstonethatdoesnotgivea“commandnotfound” Ifallofthemarenotfound,pleasereferto“gccMacportsOSXsetupguide”

II. InordertofindthelocationofthenetCDFlibrarypleasedothefollowing.Ifyouhaveinstallednetcdfthroughmacports,type:

“portcontentsnetcdf”ForLinux,type

“dpkg–Lnetcdf”

Pleasenotethelocationsofthefollowingfiles:“netcdf.inc”“libnetcdf.aorlibnetcdff.a”(Alsotakenotewhich.afileyourmachinehas.[1for2f’s(orboth)]Itwillbeimportantlateron)

vi. Compilationprocess

Again,withfinderorterminal,openthenewlydownloaded‘hysplit’directory.Wewillneedtomakechangestothreecompilationfiles.a) In/hysplit/trunk/compile.sh

Opencompile.shwiththetexteditorofyourchoice.

Inline139,lookfor:

ChangeNETLIBtothelocationwhere“libnetcdf.aorlibnetcdff.a”islocated(defaultformacportis/opt/local/lib)ChangeNETINCtothelocationwhere“netcdf.inc”islocated(defaultformacportis/opt/local/include)

Exitthetexteditoruponcompletion

b) In/trunk/data2arl/arw2arl/MakefileOpencompile.shwiththetexteditorofyourchoice.Gotoline20

Ifpreviously,youhave“libnetcdf.a”,orbothofthetwo,makenochangeHowever,ifyouhave“libnetcdff.a”,commentthefirstoneanduncommentthesecondone.

(ifyouhavelibnetcdff.a)

c) Makethesamechangesin/trunk/cmaq/Makefileline23

vii.

Toactuallycompilethecode,youhaveanoptionto‘compile’,or‘install’. Installcreatesaseparatefolderwiththeprogramwhilecompilecreatesthe programinthedownloadeddirectory.

(ifyou’renotshortinspace,I’dsuggestinstall)Toinstall,cdto/path/to/hysplit/,typeinterminal:“shinstall.sh”createanewfolder,“../hysp_new”isokaysay“yes”toupdatesay“yes”toUpdateVersionNumbersay“no”tosoftlinksay“yes”tohardlinkToinstall,cdto/path/to/hysplit/trunk,typeinterminal:“shcompile.sh”

vii. viii.Executetheguiwiththefollowingcommand“(cd~/Hysplit4/working&&./hysplit4.tcl)”

WhenIclickonthewindow,thebuttonsbecomedim/unreadable,butjustclickatabrowser window other than the hysplit window, and the buttons should becomereadableagain.

viii. Simpletest:

Inthemenusinterface,click “Trajectory ->QuickStart->RunExample”“Concentration->QuickStart->RunExample”