Difference between revisions of "ROMS Cygwin"

From WikiROMS
Jump to navigationJump to search
m (Text replacement - "ocean_(.*)\.in" to "roms_$1\.in")   (change visibility)
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div class="title">Tutorial: Installing ROMS in Windows XP / Vista (via Cygwin)</div>
<div class="title">Tutorial: Installing ROMS in Windows XP / Vista / 7 (via Cygwin)</div>


{{note}}'''Disclaimer:''' This post was written for the very beginners. Some parts may be a bit tedious for more advanced users or people with solid Linux knowledge.
{{note}}'''Disclaimer:''' This post was written for the very beginners. Some parts may be a bit tedious for more advanced users or people with solid Linux knowledge.
{{note}}'''NOTE:''' This tutorial no longer uses <span class="forestGreen">g95</span> because <span class="forestGreen">gfortran</span> is now available from Cygwin's setup. If you are looking for the <span class="forestGreen">g95</span> instructions, those deprecated sections have been moved to the [[Talk:ROMS_Cygwin|Contributions]] section of this page.


The following recipe will guide you through the steps required to download, compile and run ROMS on Windows XP or Vista.
The following recipe will guide you through the steps required to download, compile and run ROMS on Windows XP or Vista.
Line 19: Line 23:
:*Select to 'Install from Internet'
:*Select to 'Install from Internet'
:*Keep the selected defaults (''i.e.'' 'All Users' and 'Unix / Binary')
:*Keep the selected defaults (''i.e.'' 'All Users' and 'Unix / Binary')
:*Choose a path where to save Cygwin, I chose: <span class="red">C:\Program Files\cygwin</span>
:*Choose a path where to save Cygwin installation packages, I chose: <span class="red">C:\cygwinfiles</span>
:*Select Internet Connection... likely 'Direct Connection' if you have high speed internet.
:*Select Internet Connection... likely 'Direct Connection' if you have high speed internet.
:*Select a download mirror-site. Choose one close to you... University sites are usually reliable.
:*Select a download mirror-site. Choose one close to you... University sites are usually reliable.
Line 40: Line 44:




:*'''Install gcc-g++:''' Scroll down and find 'gcc-g++' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
:*'''Install diffutils:''' Scroll down and find 'diffutils' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
:*'''Install gcc4:''' Scroll down and find 'gcc4' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
:*'''Install gcc4-core:''' Scroll down and find 'gcc4-core' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
:*'''Install gcc4-fortran:''' Scroll down and find 'gcc4-fortran' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
:*'''Install GNUmake:''' Similarly, scroll down and find 'make' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See below.
:*'''Install GNUmake:''' Similarly, scroll down and find 'make' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See below.


Line 47: Line 54:




:*'''Install Subversion:''' Scroll down and find 'subversion' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X).
:*'''Install wget:''' Scroll down and find 'wget' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X).
:*Click next. A list of dependencies will show. Install them all by making sure the tick-mark (bottom left) is on and click 'next'
:*Click next. A list of dependencies will show. Install them all by making sure the tick-mark (bottom left) is on and click 'next'
:*Make a cup of coffee. Sit back. The download/installation took about 30 min on my machine.
:*Make a cup of coffee. Sit back. The download/installation may tage about 30 min.
 
==Install g95==
This Fortran compiler works in cygwin/Windows. In theory, you should be able to install other Fortran compilers instead, but I just didn't have luck with the others I tried. If you don't know what compiling is, read [[#Compile ROMS|Compile ROMS]] below.
 
 
:*Go to the [http://ftp.g95.org/ g95-project website] and download the G95 binaries. Or simply [http://ftp.g95.org/g95-x86-cygwin.tgz click here] to start the download.
:*Save it inside the cygwin folder (<span class="red">C:\cygwin</span> in this tutorial).
:*Now you have to open cygwin and go to the place where you saved the <span class="red">g95-x86-cygwin.tgz</span> file. Here you need to know that cygwin uses the folder <span class="red">C:\cygwin\cygdrive</span> as a pseudo-drive. When cygwin starts, you will be able to see all your files and folders that you have in your Windows-user root (''i.e.'' <span class="red">C:\Users\Administrator\</span>), but they will appear to be in a different location (i.e. <span class="red">/cygwin/cygdrive/c/Users/Administrator/</span> ). This is just cygwin's way to emulate a Linux-type hard-drive inside Windows.


==Helpful Cygwin notes==


{{warning}}<span class="red">IMPORTANT</span> to keep in mind:
{{warning}}<span class="red">IMPORTANT</span> to keep in mind:


:*Cygwin's home directory, which is where cygwin opens by default is, in this example, <span class="red">/cygwin/cygdrive/c/Users/Administrator/</span> but when in it, cygwin abbreviates it as <span class="red">~</span>
:*Cygwin's home directory, which is where cygwin opens by default is, in this example, <span class="red">/cygwin/cygdrive/c/Users/Administrator/</span> but when in cygwin, this directory abbreviated it as <span class="red">~</span>
:*Cygwin's HOME directory (i.e. <span class="red">~</span>) = <span class="red">C:\Users\Administrator\</span> in Windows Explorer
:*Cygwin's HOME directory (i.e. <span class="red">~</span>) = <span class="red">C:\Users\Administrator\</span> in Windows Explorer
:*Cygwin's ROOT directory (i.e. <span class="red">/</span>) = <span class="red">C:\cygwin\</span> in Windows Explorer
:*Cygwin's ROOT directory (i.e. <span class="red">/</span>) = <span class="red">C:\cygwin\</span> in Windows Explorer


{{note}}'''Useful Notes:'''
{{note}}'''Useful Notes:'''
Line 72: Line 73:
:**[http://www.tuxfiles.org/linuxhelp/cli.html http://www.tuxfiles.org/linuxhelp/cli.html]
:**[http://www.tuxfiles.org/linuxhelp/cli.html http://www.tuxfiles.org/linuxhelp/cli.html]


==Install NetCDF==
ROMS needs NetCDF to read input files and to write output files. NetCDF is free to download from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-3_6_2/index.jsp Unidata]. However, the executable file available is not good for ROMS. We need get the source code and recompile an executable file that is ROMS-friendly. Here are the step-by-step instructions:


Ok back to g95. Open cygwin and go to the root directory. To do this type <span class="forestGreen">cd /</span> (cd = command for: 'change directory'). Now that you are in the root directory, type <span class="forestGreen">ls</span> (command for: "show contents of this directory"), you should see our recently downloaded <span class="red">g95-x86-cygwin.tgz</span> file.
:*In cygwin change into your <span class="red">software</span> directory and download the NetCDF source code.
 
::<div class="box"><span class="forestGreen">cd ~/software<br />wget <nowiki>http://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf.tar.Z</nowiki></span></div>
:*Extract (or unzip) <span class="red">g95-x86-cygwin.tgz</span> by typing:
::<div class="box"><span class="forestGreen">tar -xvzf g95-x86-cygwin.tgz</span></div>
:*This should install g95 in <span class="red">/usr/local/bin</span> and its documentation in <span class="red">/usr/local/doc/g95</span>
 
==Install NetCDF==
ROMS needs NetCDF to read input files and to write output files. NetCDF is free to download from Unidata. However, the executable file available is not good for ROMS. We need get the source code and recompile an executable file that is ROMS-friendly. Here are the step-by-step instructions:


:*Go to the [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-3_6_2/index.jsp Unidata website] and download the NetCDF C/C++/Fortran Source Code and Documentation. Or simply [http://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf.tar.Z click here] to start the download.
:*Unpack it and change into the resulting directory (at the time of this writing this is <span class="forestGreen">netcdf-3.6.2</span>).
:*Same as before, save the file in the cygwin folder <span class="red">C:\cygwin</span>
::<div class="box"><span class="forestGreen">tar -xvzf netcdf.tar.Z<br />cd netcdf-3.6.2</span></div>
:*Unpack it by typing:
:*Start the compilation by typing the line below. It will take about 10 minutes. Enough to start a fresh batch of coffee.
::<div class="box"><span class="forestGreen">tar -xvzf netcdf.tar.Z</span></div>
::<div class="box"><span class="forestGreen">CC=gcc FC=gfortran-4 F77=gfortran-4 CPPFLAGS=-DpgiFortran ./configure</span></div>
:*Go to the location where it unpacked by typing <span class="forestGreen">cd netcdf-3.6.2</span> and start the compilation by typing the line below. It will take about 10 minutes. Enough to start a fresh batch of coffee.
::<div class="box"><span class="forestGreen">CC=gcc FC=g95 CPPFLAGS=-DpgiFortran FFLAGS=-fno-second-underscore FCFLAGS=-fno-second-underscore ./configure</span></div>
:*Then, type the text below. This will take just about enough the time for the coffee to brew.
:*Then, type the text below. This will take just about enough the time for the coffee to brew.
::<div class="box"><span class="forestGreen">make check</span></div>
::<div class="box"><span class="forestGreen">make check</span></div>
Line 94: Line 89:
:Well done! Have a sip
:Well done! Have a sip


 
<!--
==Install subversion==
==Install subversion==
This is software needed to download ROMS source code. I used a GUI for subversion called Tortoise (wonderful and free), but you can use most any subversion client. Tortoise is an ADD-ON for Windows Explorer.
This is software needed to download ROMS source code. I used a GUI for subversion called Tortoise (wonderful and free), but you can use most any subversion client. Tortoise is an ADD-ON for Windows Explorer.
Line 101: Line 96:
:*Open the installer and follow instructions.
:*Open the installer and follow instructions.
:*Restart your computer (The Installer asks you to do so).
:*Restart your computer (The Installer asks you to do so).
 
-->
 
==Download ROMS==
==Download ROMS==
This section assumes that you registered and obtained your ROMS username/password as indicated in the [[#Register|Register]] section.
This section assumes that you registered and obtained your ROMS username/password as indicated in the [[#Register|Register]] section.


:*Create a <span class="red">roms</span> folder and change into it.
::<div class="box"><span class="forestGreen">cd ~<br />mkdir roms<br />cd roms</span></div>
:*Check out the ROMS source code replacing 'joeroms' with the ROMS user name you registered with.
::<div class="box"><span class="forestGreen">svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></span></div>
:*You will see many lines stream by. When it finishes, type <span class="forestGreen">ls</span>. You have a folder named <span class="red">trunk</span> that contains the ROMS source code.
<!--
:*In Windows Explorer, create a folder for ROMS in a place easy to find under cygwin. ''I.e.'' under <span class="red">C:\cygwin\</span> (I named my folder simply ROMS)
:*In Windows Explorer, create a folder for ROMS in a place easy to find under cygwin. ''I.e.'' under <span class="red">C:\cygwin\</span> (I named my folder simply ROMS)
:*Then, using Windows Explorer, get into the folder you just created and right-click and choose 'SVN Checkout...'
:*Then, using Windows Explorer, get into the folder you just created and right-click and choose 'SVN Checkout...'
Line 121: Line 122:


{{note}}<span class="red">Note:</span> In Windows VISTA there was a problem at the end of the download. Tortoise couldn't access the .svn folder. I think this will cause problems when getting ROMS updates. However, all source code got downloaded, compiling was successful and test case ran ok. This problem DIDN'T occur in Windows XP.
{{note}}<span class="red">Note:</span> In Windows VISTA there was a problem at the end of the download. Tortoise couldn't access the .svn folder. I think this will cause problems when getting ROMS updates. However, all source code got downloaded, compiling was successful and test case ran ok. This problem DIDN'T occur in Windows XP.
 
-->


==Customizing the [[build Script|Build Script]]==
==Customizing the [[build Script|Build Script]]==
The ROMS source code comes with a [[build Script|build script]] in the <span class="red">ROMS/Bin</span> directory. Examples written with <span class="forestGreen">bash</span> (<span class="red">build.bash</span>) and <span class="forestGreen">csh</span> (<span class="red">build.sh</span>) are provided. Cygwin uses <span class="forestGreen">bash</span> by default so we will work with <span class="red">build.bash</span>. A full description of the build script can be found [[build Script|here]].
The ROMS source code comes with a [[build Script|build script]] in the <span class="red">ROMS/Bin</span> directory. Examples written with <span class="forestGreen">bash</span> (<span class="red">build.bash</span>) and <span class="forestGreen">csh</span> (<span class="red">build.sh</span>) are provided. Cygwin uses <span class="forestGreen">bash</span> by default so we will work with <span class="red">build.bash</span>. A full description of the build script can be found [[build Script|here]].


:*With Windows Explorer create a folder named <span class="red">'''Projects'''</span> in the same directory as your new <span class="red">trunk</span> directory.
:*At the same level as your new <span class="red">trunk</span> directory create a new folder named <span class="red">Projects</span> and change into it.
:*Go into the <span class="red">Projects</span> folder and create a folder named <span class="red">Upwelling</span>. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box"><span class="forestGreen">mkdir Projects<br />cd Projects</span></div>
:*Open a new Windows Explorer window and go to <span class="red">C:\cygwin\ROMS\trunk\ROMS\External</span>
:*Create a folder named <span class="red">Upwelling</span> and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
:*Copy <span class="red">ocean_upwelling.in</span> and <span class="red">ocean_upwelling.in</span> file and paste it in the <span class="red">Upwelling</span> directory you just created
::<div class="box"><span class="forestGreen">mkdir Upwelling<br />cd Upwelling</span></div>
:*Using Windows Explorer, go to <span class="red">C:\cygwin\ROMS\trunk\ROMS\Bin</span>
 
:*Copy the <span class="red">build.bash</span> file and paste it in the <span class="red">Upwelling</span> directory
:*Copy the <span class="red">roms_upwelling\.in</span> file into the <span class="red">Upwelling</span> directory you just created.
:*Open the <span class="red">build.bash</span> script you just pasted into <span class="red">Upwelling</span> directory using Wordpad or your preferred text editor (except Notepad).
::<div class="box"><span class="forestGreen">cp ../../trunk/ROMS/External/roms_upwelling\.in .</span></div>
 
 
{{note}}'''NOTE:''' In Cygwin and Linux/UNIX ' <span class="red">../</span> ' translates to "up one directory" so what we are doing here is going "up" two directories ( <span class="red">../../</span> ), which puts us in the directory containing <span class="red">trunk</span> and <span class="red">Projects</span> (<span class="red">~/roms</span>), then going into the <span class="red">trunk/ROMS/External</span> directory and getting the <span class="red">roms_upwelling\.in</span> file. Likewise, ' <span class="red">.</span> ' translates to "current directory". Which, in this case, is <span class="red">~/roms/Projects/Upwelling</span>. So, we are copying the <span class="red">roms_upwelling\.in</span> file '''TO''' <span class="red">~/roms/Projects/Upwelling/</span>.
 
:*Copy the <span class="red">upwelling.h</span> file into the <span class="red">Upwelling</span> directory in the same way.
::<div class="box"><span class="forestGreen">cp ../../trunk/ROMS/Include/upwelling.h .</span></div>
 
:*Copy the <span class="red">build.bash</span> file into the <span class="red">Upwelling</span> directory.
::<div class="box"><span class="forestGreen">cp ../../trunk/ROMS/Bin/build.bash .</span></div>
 
:*Open the <span class="red">build.bash</span> script you just copied into your <span class="red">Upwelling</span> directory using Wordpad or your preferred text editor (except Notepad).




{{warning}}<span class="red">IMPORTANT:</span> The paths you set in this file are relative to the '''cygwin''' root directory. So, for example, span class="red">C:\cygwin\ROMS</span> in Windows Explorer would be <span class="red">/ROMS</span> in cygwin.
{{warning}}<span class="red">IMPORTANT:</span> The paths you set in this file are relative to the '''cygwin''' root directory. So, for example, <span class="red">C:\cygwin\ROMS</span> in Windows Explorer would be <span class="red">/ROMS</span> in cygwin.




:*Scroll down until you find <span class="orange">MY_ROOT_DIR</span> and <span class="orange">MY_ROOT_DIR</span>. Set them as follows.
:*Scroll down until you find <span class="orange">MY_ROOT_DIR</span> and <span class="orange">MY_ROOT_DIR</span>. Set them as follows (replacing 'joeroms' with your ROMS user name).
::<div class="box"><span class="blue">export</span>        <span class="red">MY_ROOT_DIR</span>=/ROMS<br /><span class="blue">export</span>    <span class="red">MY_PROJECT_DIR</span>=${<span class="red">MY_ROOT_DIR</span>}/Projects/Upwelling</div>
::<div class="box"><span class="blue">&nbsp;export</span>        <span class="red">MY_ROOT_DIR</span>=/home/joeroms/roms<br /><span class="blue">&nbsp;export</span>    <span class="red">MY_PROJECT_DIR</span>=${<span class="red">MY_ROOT_DIR</span>}/Projects/Upwelling</div>


:*Now set <span class="orange">MY_ROMS_SRC</span> to:
:*Now set <span class="orange">MY_ROMS_SRC</span> to:
::<div class="box"><span class="blue">export</span>        <span class="red">MY_ROMS_SRC</span>=${<span class="red">MY_ROOT_DIR</span>}/trunk</div>
::<div class="box"><span class="blue">&nbsp;export</span>        <span class="red">MY_ROMS_SRC</span>=${<span class="red">MY_ROOT_DIR</span>}/trunk</div>


:*Make sure that <span class="orange">MY_CPP_FLAGS</span> is '''not''' set. I had to comment out one line with the # symbol like so:
:*Make sure that <span class="orange">MY_CPP_FLAGS</span> is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#<span class="blue">export</span>     <span class="red">MY_CPP_FLAGS</span>="-DNPZD_POWELL"</div>
::<div class="box">#<span class="blue">export</span>       <span class="red">MY_CPP_FLAGS</span>="-DNPZD_POWELL"</div>
 
:*We are compiling in serial using the <span class="red">gfortran</span> compiler so make your <span class="red">build.bash</span> match the following:
::<div class="box"><span class="blue">&nbsp;export</span>            <span class="red">USE_MPI</span>=<br /><span class="blue">&nbsp;export</span>        <span class="red">USE_MPIF90</span>=<br /><span class="blue">&nbsp;export</span>              <span class="red">FORT</span>=gfortran</div>
 
:*Uncomment the line:
::<div class="box"><span class="blue">#export</span>          <span class="red">USE_MY_LIBS</span>=on</div>to look like:<div class="box"><span class="blue">&nbsp;export</span>          <span class="red">USE_MY_LIBS</span>=on</div>


:*We are compiling in serial using the <span class="red">g95</span> compiler so make your <span class="red">build.bash</span> match the following:
:*Find the <span class="forestGreen">gfortran</span> ''')''' section inside the '''<span class="blue">if</span> [ -n "${<span class="red">USE_MY_LIBS</span>:+1}" ]''' block.
::<div class="box"><span class="blue">export</span>           <span class="red">USE_MPI</span>=<br /><span class="blue">export</span>        <span class="red">USE_MPIF90</span>=<br /><span class="blue">export</span>              <span class="red">FORT</span>=g95</div>


:*You will need to add the following two lines anywhere '''above''' the line that reads <span class="blue">cd</span> ${<span class="red">MY_ROMS_SRC</span>}
:*Near the bottom of the <span class="forestGreen">gfortran</span> ''')''' section you will find the following lines:
::<div class="box"><span class="blue">export</span>      <span class="red">NETCDF_INCDIR</span>=/usr/local/include<br /><span class="blue">export</span>      <span class="red">NETCDF_LIBDIR</span>=/usr/local/lib</div>
::<div class="box">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'''else'''<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="blue">export</span>      <span class="red">NETCDF_INCDIR</span>=/opt/gfortransoft/serial/netcdf3/include<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="blue">export</span>     <span class="red">NETCDF_LIBDIR</span>=/opt/gfortransoft/serial/netcdf3/lib<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'''fi'''</div>change them to:<div class="box">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'''else'''<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="blue">export</span>      <span class="red">NETCDF_INCDIR</span>=/usr/local/include<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="blue">export</span>      <span class="red">NETCDF_LIBDIR</span>=/usr/local/lib<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'''fi'''</div>


:*Save and close the <span class="red">build.bash</span> file.
:*Save and close the <span class="red">build.bash</span> file.


==Customizing the <span class="red">CYGWIN-gfortran.mk</span> file==
<span class="forestGreen">Gfortran</span> is part of the 4.x line of the GNU Compiler Collection. Cygwin allows both the 3.x and 4.x versions to be installed at the same time. As a result, the <span class="forestGreen">gfortran</span> compiler has the non-standard name of <span class="forestGreen">gfortran-4</span>. This means that we have to edit the <span class="red">CYGWIN-gfortran.mk</span> file in the ROMS source.
:*Open <span class="red">~roms/trunk/Compilers/CYGWIN-gfortran.mk</span> with your preferred text editor (except Notepad).
:*Find the line following line:
::<div class="box"><span class="red">FC</span> := gfortran</div>and change it to:<div class="box"><span class="red">FC</span> := gfortran-4</div>
:*Save and close the <span class="red">CYGWIN-gfortran.mk</span> file.


==Compile ROMS==
==Compile ROMS==
Before you run ROMS, you need to compile it to create an executable <span class="red">oceanS</span> file. ROMS Source-Code files are readable by humans while executable files are readable by computers. The compilation process translates the source files into executables. Here are the instructions:
Before you run ROMS, you need to compile it to create an executable <span class="red">oceanS</span> file. ROMS Source-Code files are readable by humans while executable files are readable by computers. The compilation process translates the source files into executables. Here are the instructions:


:*In cygwin, go to the Upwelling directory:
:*In cygwin, if you're not there already, go to the Upwelling directory:
::<div class="box"><span class="forestGreen">cd /ROMS/Projects/Upwelling</span></div>
::<div class="box"><span class="forestGreen">cd ~/roms/Projects/Upwelling</span></div>


:*Then type:
:*Then type:
Line 170: Line 197:


==Run ROMS==
==Run ROMS==
:*We need to make one change to our <span class="red">ocean_upwelling.in</span> file so open it with your favorite editor and find the following line:<div class="box">    <span class="blue">VARNAME</span> = ROMS/External/varinfo.dat</div>and change it to:<div class="box">    <span class="blue">VARNAME</span> = /ROMS/trunk/ROMS/External/varinfo.dat</div>
:*We need to make one change to our <span class="red">roms_upwelling\.in</span> file so open it with your favorite editor and find the following line:<div class="box">    <span class="blue">VARNAME</span> = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your ROMS user name):<div class="box">    <span class="blue">VARNAME</span> = /home/joeroms/roms/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the <span class="red">ocean_upwelling.in</span> file
:*Save and close the <span class="red">roms_upwelling\.in</span> file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
:*In cygwin, within the <span class="red">Upwelling</span> directory where your <span class="forestGreen">oceanS</span> and <span class="red">roms_upwelling\.in</span> files live, type:
::<div class="box"><span class="forestGreen">./oceanS &lt; ocean_upwelling.in</span></div>
::<div class="box"><span class="forestGreen">./oceanS &lt; roms_upwelling\.in</span></div>


If lots of numbers are displayed on the screen ROMS is running! Poor a one last cup of coffee and enjoy the show (~15 min). Out of the box, ROMS comes programmed to run the Upwelling test case, which is what you are running now. When it finishes, the following output files are created:  
If lots of numbers are displayed on the screen ROMS is running! Poor one last cup of coffee and enjoy the show (~15 min). Out of the box, ROMS comes programmed to run the Upwelling test case, which is what you are running now. When it finishes, the following output files are created:  


:<span class="red">ocean_avg.nc</span><br><span class="red">ocean_dia.nc</span><br><span class="red">ocean_his.nc</span><br><span class="red">ocean_rst.nc</span>
:<span class="red">ocean_avg.nc</span><br><span class="red">ocean_dia.nc</span><br><span class="red">ocean_his.nc</span><br><span class="red">ocean_rst.nc</span>

Revision as of 19:03, 21 July 2020

Tutorial: Installing ROMS in Windows XP / Vista / 7 (via Cygwin)

NoteDisclaimer: This post was written for the very beginners. Some parts may be a bit tedious for more advanced users or people with solid Linux knowledge.


NoteNOTE: This tutorial no longer uses g95 because gfortran is now available from Cygwin's setup. If you are looking for the g95 instructions, those deprecated sections have been moved to the Contributions section of this page.


The following recipe will guide you through the steps required to download, compile and run ROMS on Windows XP or Vista.



Register

The very first thing to do is to Register. After some checking, ROMS crew will give you a username and a password within a day or two. While you wait, you can prepare your PC with lots of ancillary software that you will need. See below...

Install Cygwin

ROMS runs on a Unix or Linux command-line environment. So, to run ROMS on Windows, first we need to install a Linux emulator for Windows. We need to download and install Cygwin.

  • Download: Go to the Cygwin website and download the setup.exe file, by clicking on any of the cygwin-install icons. Or simply click here to start the download.
  • Open the recently downloaded setup.exe file
  • Select to 'Install from Internet'
  • Keep the selected defaults (i.e. 'All Users' and 'Unix / Binary')
  • Choose a path where to save Cygwin installation packages, I chose: C:\cygwinfiles
  • Select Internet Connection... likely 'Direct Connection' if you have high speed internet.
  • Select a download mirror-site. Choose one close to you... University sites are usually reliable.


WarningIMPORTANT: You will need to tell cygwin to install some modules that are not installed by default.


  • Install Perl: As shown in the figure below, find the Perl Category and click on 'Default' until it turns into 'Install'.


cygwin perl.png


  • Install X11: Do the same in the category of X11. (I needed X11 to run applications on a remote computer. Technically you don't need this to run ROMS on Windows. However, I haven't installed Cygwin without X11 so I'm not sure that some modules installed under X11 may be required later, but feel free to experiment and leave out X11).
  • Expand the window and click on the 'View' button on the upper right corner (shown below), until it toggles into 'Full' view.


cygwin view.png


  • Install diffutils: Scroll down and find 'diffutils' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
  • Install gcc4: Scroll down and find 'gcc4' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
  • Install gcc4-core: Scroll down and find 'gcc4-core' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
  • Install gcc4-fortran: Scroll down and find 'gcc4-fortran' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See image below.
  • Install GNUmake: Similarly, scroll down and find 'make' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X). See below.


cygwin make.png


  • Install Subversion: Scroll down and find 'subversion' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X).
  • Install wget: Scroll down and find 'wget' (on the package column). Click on 'Skip' (1st column) until it shows a version number (and a box selected with an X).
  • Click next. A list of dependencies will show. Install them all by making sure the tick-mark (bottom left) is on and click 'next'
  • Make a cup of coffee. Sit back. The download/installation may tage about 30 min.

Helpful Cygwin notes

WarningIMPORTANT to keep in mind:

  • Cygwin's home directory, which is where cygwin opens by default is, in this example, /cygwin/cygdrive/c/Users/Administrator/ but when in cygwin, this directory abbreviated it as ~
  • Cygwin's HOME directory (i.e. ~) = C:\Users\Administrator\ in Windows Explorer
  • Cygwin's ROOT directory (i.e. /) = C:\cygwin\ in Windows Explorer

NoteUseful Notes:

Install NetCDF

ROMS needs NetCDF to read input files and to write output files. NetCDF is free to download from Unidata. However, the executable file available is not good for ROMS. We need get the source code and recompile an executable file that is ROMS-friendly. Here are the step-by-step instructions:

  • In cygwin change into your software directory and download the NetCDF source code.
cd ~/software
wget http://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf.tar.Z
  • Unpack it and change into the resulting directory (at the time of this writing this is netcdf-3.6.2).
tar -xvzf netcdf.tar.Z
cd netcdf-3.6.2
  • Start the compilation by typing the line below. It will take about 10 minutes. Enough to start a fresh batch of coffee.
CC=gcc FC=gfortran-4 F77=gfortran-4 CPPFLAGS=-DpgiFortran ./configure
  • Then, type the text below. This will take just about enough the time for the coffee to brew.
make check
  • Finally, type the text below. This is fast; just enough to mix coffee, sugar and milk.
make install
Well done! Have a sip

Download ROMS

This section assumes that you registered and obtained your ROMS username/password as indicated in the Register section.

  • Create a roms folder and change into it.
cd ~
mkdir roms
cd roms
  • Check out the ROMS source code replacing 'joeroms' with the ROMS user name you registered with.
svn checkout --username joeroms https://www.myroms.org/svn/src/trunk
  • You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.


Customizing the Build Script

The ROMS source code comes with a build script in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. Cygwin uses bash by default so we will work with build.bash. A full description of the build script can be found here.

  • At the same level as your new trunk directory create a new folder named Projects and change into it.
mkdir Projects
cd Projects
  • Create a folder named Upwelling and change into it. 'Upwelling' is the name of the ROMS test case we are going to compile and run.
mkdir Upwelling
cd Upwelling
  • Copy the roms_upwelling\.in file into the Upwelling directory you just created.
cp ../../trunk/ROMS/External/roms_upwelling\.in .


NoteNOTE: In Cygwin and Linux/UNIX ' ../ ' translates to "up one directory" so what we are doing here is going "up" two directories ( ../../ ), which puts us in the directory containing trunk and Projects (~/roms), then going into the trunk/ROMS/External directory and getting the roms_upwelling\.in file. Likewise, ' . ' translates to "current directory". Which, in this case, is ~/roms/Projects/Upwelling. So, we are copying the roms_upwelling\.in file TO ~/roms/Projects/Upwelling/.

  • Copy the upwelling.h file into the Upwelling directory in the same way.
cp ../../trunk/ROMS/Include/upwelling.h .
  • Copy the build.bash file into the Upwelling directory.
cp ../../trunk/ROMS/Bin/build.bash .
  • Open the build.bash script you just copied into your Upwelling directory using Wordpad or your preferred text editor (except Notepad).


WarningIMPORTANT: The paths you set in this file are relative to the cygwin root directory. So, for example, C:\cygwin\ROMS in Windows Explorer would be /ROMS in cygwin.


  • Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your ROMS user name).
 export MY_ROOT_DIR=/home/joeroms/roms
 export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling
  • Now set MY_ROMS_SRC to:
 export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk
  • Make sure that MY_CPP_FLAGS is not set. I had to comment out one line with the # symbol like so:
#export MY_CPP_FLAGS="-DNPZD_POWELL"
  • We are compiling in serial using the gfortran compiler so make your build.bash match the following:
 export USE_MPI=
 export USE_MPIF90=
 export FORT=gfortran
  • Uncomment the line:
#export USE_MY_LIBS=on
to look like:
 export USE_MY_LIBS=on
  • Find the gfortran ) section inside the if [ -n "${USE_MY_LIBS:+1}" ] block.
  • Near the bottom of the gfortran ) section you will find the following lines:
      else
          export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include
          export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib
      fi
change them to:
      else
          export NETCDF_INCDIR=/usr/local/include
          export NETCDF_LIBDIR=/usr/local/lib
      fi
  • Save and close the build.bash file.

Customizing the CYGWIN-gfortran.mk file

Gfortran is part of the 4.x line of the GNU Compiler Collection. Cygwin allows both the 3.x and 4.x versions to be installed at the same time. As a result, the gfortran compiler has the non-standard name of gfortran-4. This means that we have to edit the CYGWIN-gfortran.mk file in the ROMS source.

  • Open ~roms/trunk/Compilers/CYGWIN-gfortran.mk with your preferred text editor (except Notepad).
  • Find the line following line:
FC := gfortran
and change it to:
FC := gfortran-4
  • Save and close the CYGWIN-gfortran.mk file.

Compile ROMS

Before you run ROMS, you need to compile it to create an executable oceanS file. ROMS Source-Code files are readable by humans while executable files are readable by computers. The compilation process translates the source files into executables. Here are the instructions:

  • In cygwin, if you're not there already, go to the Upwelling directory:
cd ~/roms/Projects/Upwelling
  • Then type:
./build.bash
  • If lots of stuff comes on the screen then you are good. Poor one more cup of coffee, sit back, and enjoy the compiling show. This will take ~15 min.
  • When it finishes type ls; if you can see oceanS (your executable file), then the compilation was successful.


Run ROMS

  • We need to make one change to our roms_upwelling\.in file so open it with your favorite editor and find the following line:
    VARNAME = ROMS/External/varinfo.dat
    and change it to (again replacing 'joeroms' with your ROMS user name):
    VARNAME = /home/joeroms/roms/trunk/ROMS/External/varinfo.dat
  • Save and close the roms_upwelling\.in file
  • In cygwin, within the Upwelling directory where your oceanS and roms_upwelling\.in files live, type:
./oceanS < roms_upwelling\.in

If lots of numbers are displayed on the screen ROMS is running! Poor one last cup of coffee and enjoy the show (~15 min). Out of the box, ROMS comes programmed to run the Upwelling test case, which is what you are running now. When it finishes, the following output files are created:

ocean_avg.nc
ocean_dia.nc
ocean_his.nc
ocean_rst.nc


To learn one way to visualize them, click here.


Thats it! You got ROMS running!

Now comes the hard part: Learn how to use ROMS. But by now you are probably all coffeed-up and ready learn more. Click here for a good place to start.

Good luck!

Related Pages

  • makefile - Detailed information about the ROMS makefile
  • Build Script - Detailed information about the ROMS build scripts
  • Visualization - Guides for plotting ROMS output
  • Test Cases - Description of the test cases that come with ROMS