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

[Diego]

Please use the version of this tutorial that is in the wiki. The wiki page contains corrections and extra information and can be found at:

https://www.myroms.org/wiki/index.php/Tutorials

This post will remain for historical reasons only.



Hi All,

I am new to ROMS... new to Linux... and trained as a biologist. For me, the path of learning ROMS has been a bit like off-roading... thrilling and exciting, but it gives me back pain (due to hours on Google). However, I decided that my first post on this forum should not be about asking questions. I prefer to start by posting a bit of what I have done so far. Hopefully this would help new(er) ROMS users!

===============================================

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.

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


(1)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...

(2) 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, I chose: C:\Program Files\cygwin
  * 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.
  
  IMPORTANT: 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".
  
  
  
  
  
  * 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 install Cygwin without X11 so I'm not sure that some modules installed under X11 may be required later... 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.
  
  
  
  
  
  * 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 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.
  
  
  
  
  
  
  * 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.

(3) 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 is compiling... read point 8 below.

• * Go to the g95-project website and download the G95 Source Code. Or simply click here to start the download.
  * Save it inside the cygwin folder C:\cygwin
  * Now you have to open cygwin and go to the place where you save the g95-x86-cygwin.tgz.tar file. Here you need to know that cygwing uses the folder C:\cygwin\cygdrive 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 (say... C:\Users\Administrator\ ), but they will appear to be in a different location (i.e. /cygwin/cygdrive/c/Users/Administrator/ ). This is just cygwin's way to emulate a Linux-type hard-drive inside Windows.
  
  IMPORTANT to keep in mind:
  • * Cygwin's home directory, which is where cygwin opens by default is /cygwin/cygdrive/c/Users/Administrator/ but when in it, cygwin abbreviates 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
  USEFUL NOTES:
  * PASTE: To paste text in the cygwin window, right-click on the cygwin symbol on the left-upper corner of the window. Chose Edit > Paste.
  * Here are some websites where you can learn more Linux commands
  http://www.howtoforge.com/useful_linux_commands
  http://www.tuxfiles.org/linuxhelp/cli.html
  
  
  Ok back to g95... open cygwin and go to the root directory. To do this type cd / (cd = command for: 'change directory"). Now that you are in the root directory, type ls (command for: "show contents of this directory"), you should see our recently downloaded g95-x86-cygwin.tgz.tar file.
  
  *Extract (or unzip) g95-x86-cygwin.tgz.tar by typing:

  Code: Select all

  tar -xvzf g95-x86-cygwin.tgz.tar

  *This should install g95 in /usr/local/bin and its documentation in /usr/local/doc/g95

(4) 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 Unidata website and download the NetCDF C/C++/Fortran Source Code and Documentation. Or simply click here to start the download.
  * Same as before, save the file in the cygwin folder C:\cygwin
  * Unpack it by typing:

  Code: Select all

  tar -xvzf netcdf.tar.Z

  * Go to the location where it unpacked by typing cd netcdf-3.6.2 and start the compilation by typing the line below... It will take about 10 minutes. Enough to start a fresh batch of coffee.

  Code: Select all

  CC=gcc FC=g95 CPPFLAGS=-DpgiFortran FFLAGS=-fno-second-underscore FCFLAGS=-fno-second-underscore ./configure

  * Then, type the text below... this will take just about enough the time for the coffee to brew.

  Code: Select all

  make check

  * Finally, type the text below... this is fast... just enough to mix coffee, sugar and milk.

  Code: Select all

  make install

  Well done! Have a sip!

(5) Install subversion
This is software needed to download ROMS source code... I used a GUI for subversion called Tortoise (wonderful and free)... This program is an ADD-ON for Windows Explorer.

• * First download the installer at the TortoiseSVN website. Or simply click here to start the download.
  * Open the installer and follow instructions.
  * Restart your computer (The Installer asks you to do so).

(6) Download ROMS
This section assumes that you registered and obtained your ROMS username / password as indicated in section (1).

• * In Windows Explorer, create a folder for ROMS in a place easy to find under cygwin... let say under C:\cygwin\ (I named my folder simply ROMS)
  * Then, using Windows Explorer, get into the folder you just created and right-click... choose "Checkout".
  * Type the URL where ROMS lives: https://www.myroms.org/svn/src ...and click Ok
  * Enter your username and password... poor another cup of coffee and let the download begin! (Takes ~8 min)
  
  NOTE: 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.

(7) Modify makefile and compiler file
Now you need to modify 2 files so ROMS can works properly.

• * In windows explorer, go to the folder where you put ROMS (for me... C:\cygwin\ROMS)
  * Go into the trunk directory and open the file named makefile using wordpad or your preferred text editor (except Notepad).
  * Scroll down until you find FORT ?= ...modify it so it reads FORT ?= g95 ...as shown below.
  
  
  
  
  
  * Save and close the makefile
  * Then go into the Compilers folder and open CYGWIN-g95.mk using wordpad
  * Now you have to tell ROMS where to find the NetDCF include and library directories. In the lines below I wrote the path where I installed NetCDF (step 4 above). If you follow my steps, your path is likely the same. Nevertheless, you should check.

  Code: Select all

      NETCDF_INCDIR ?= /usr/local/include
      NETCDF_LIBDIR ?= /usr/local/lib
  

  
  Also, you have to be careful because the text NETCDF_INCDIR and NETCDF_LIBDIR appears a few times in the file. Use the pic below to guide you.
  
  
  
  
  
  
  
  *Save and close the CYGWIN-g95.mk file

(8 ) 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 cywin, go to the trunk directory where the makefile lives. For me... cd /ROMS/trunk
  * Then type...

  Code: Select all

  make clean

  * and then type...

  Code: Select all

  make

  * 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.

(9) Run ROMS

• * In cygwin and within the trunk directory, where your oceanS file lives.... type:

  Code: Select all

  ./oceanS < ROMS/External/ocean_upwelling.in

  If lost 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 programed to run the Upwelling test case, which is what you are running now. When if 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!


Diego



PS. Just as I was reviewing the last changes to this post, the power when off (wicked storm in Halifax). Oh well, the second time was definitely faster to write.

[arango]

Good job with this beginner recipe ROMS is a very complex model so it takes some time to learn all the parts, but after the first overwhelming shock It will grow on you. I always tell the new users that the amount of time spent at the beginning will pay big time in the future.

I don't know if this forum is a good venue for this recipe. Perhaps this nice information can be put into WikiROMS. If you notice, WikiROMS has a discussion menu for each page. If a page has a discussion, the menu box blinks. For example, check the following page with a discussion. These discussion pages are user wiki pages. They were designed for the information that you included in this post.

If you prefer to enter that information in WikiROMS, let us know and we will give you access. Currently, we are giving editing access to a few users that would like to contribute to WikiROMS development. I will ask David to enter this information there.

By the way, the above link shows how to use the build.sh script. This is a more powerful way to compile ROMS. There is no need to change the makefile or any of the internal ROMS files. You just need to create a project directory and copy the build script and other files that you would like to modify. There is plenty of information in the above link for how to do this. There is also complete information about compiling.

[Diego]

I will be glad to put this information wherever it will be most useful!

I personally find that information in the 'discussion' part of WikiROMS (and ALL other WikiMedia-powered Wikis, for that matter) is a bit hard to discover. It took me many visits to the 'Built Script' wikipage before I noticed the yellow-blinking 'discussion' tab. Also, queries via the WikiROMS search box don't return hits in the discussion pages (unless you specifically tick the 'Talk' box on the bottom, and repeat the search). I guess I find things easier through links in Tables of Contents or throughout text. In any case, you just let me knnow where you want this tutorial, and I'll send it that way

By the way... build.sh is awesome! I currently do all my compilations using build.sh and I find it much easier to keep things organized.

Cheers!

[jprinehimer]

From my experiences editing Wikipedia, the discussion or talk pages are for meta-information, i.e. talking about the main wiki page. For example, you might talk about what sort of content would be on a page or if you should create a new page from some subset of a current page's content. They act as a forum for that page. As noticed above, anything that you want a user to be able to find easily should not be in the discussion pages. Maybe there should be a new main entry on the wiki for tutorials?

While this is generally how MediaWikis work, the ROMS community can decide to do things differently. At this point, with few editors, policies for adding information to the wiki are easy to control. For users trying to discover information about ROMS from the wiki however, non-standard policies should be made clear (at WikiROMS) and information should be easy to find (e.g. make the talk tick-box in the search dialog on by default)

Also, is editing the wiki going to be open to all ROMS users? I understand that WikiROMS is still young and (will always be) a work in progress, but the more contributors, the more powerful the wiki. This is what makes a wiki more than your average webpage.

[kate]

I think all registered ROMS users should be allowed to edit the wiki, but I'm not the one in control of the keys.

[rouf]

Many thanks to Deigo for the Tutorial. Without that I (as a new user) will never be able to install ROMS.
However, i found following error at the end of point 6.
Error: Can't open file 'C:\cygwin\ROMS\tags\roms-2.3\Lib\MCT_WRF\.svn\text-base\con.F.svn-base': Access is denied.


Eventhough, I followed ur next steps (pont 7, 8, 9) and found the same output u mentioned on ur tutorial.

Is there be any problem in future if i ignore the above error? If yes, pls let me know, how can i overcome the above error.

ROUF

[Diego]

Hi Rouf,

I think the file that is causing the error...

'C:\cygwin\ROMS\tags\roms-2.3\Lib\MCT_WRF\.svn\text-base\con.F.svn-base': Access is denied.

...is a file from an old version of ROMS (v2.3), which are located under the "tags" directory... I would suspect that you won't have problems in the future.

You may also want to check the UPDATED version of this tutorial... which is in WikiROMS ( https://www.myroms.org/wiki/index.php/ROMS_Cygwin ) ...in this updated version we mention to only download (via SVN Tortoise) the "trunk" directory... since the other directories contain non-required files like old ROMS versions (under the tags directory).

Cheers!

Diego

[rouf]

Hi Diego,
Thanks for reply. I went to wikiroms and followed instruction as it is. But i found following error after typing
./build.bash during compilation of ROMS.


./build.bash: line 40: $'\r': command not found
./build.bash: line 43: $'\r': command not found
./build.bash: line 46: syntax error near unexpected token `$'in\r''
'/build.bash: line 46: ` case "$1" in

pls suggest me how to overcome the problem.

Rouf

[kate]

Line 40 is the first non-comment line and is blank except for line terminations. Try running dos2unix on build.bash.

[robertson]

I have updated the tutorial in the wiki to suggest using the cygwin command line svn client. If you have already installed cygwin you can run the setup.exe again and grab any packages you may have missed. There are three more packages listed than before.

[rouf]

Yes! I am successful in compiling and running ROMS. Many thanks to Diego, Kate and Robertson.

Rouf

[tek2002]

Many thanks for your manual.

I also succeeded to simulate the ROMS according to your manual. But, when I follow "customizing the build script", I met those notice below

./build.bash: line 40: $'\r': command not found
./build.bash: line 43: $'\r': command not found
./build.bash: line 46: systax error near unexpected token '$' in\r''
./build.bash: line 46: ' case "$1" in [/img]

[tek2002]

Many thanks.

I also figured out my problem below.

dos2unix build.bash
./build.bash

[bibi951]

thank you very much for the tutorial!
i'm new in both ROMS and Unix,so i have to follow step by step the istall instruction.
but why this tutorial is different with the one on the wikiROMS at https://www.myroms.org/wiki/index.php/R ... all_Cygwin ?
because on that one there are

Install diffutils:
Install Subversion:
Install wget:

when install cygwin,but yours do not^
i feel puzzled about which to follow
by the way ,i'm using windowXP and it takes more than 3hours for me to install the cygwin once····
hoping for reply!

[Diego]

Hi bibi951,

Follow the tutorial in WikiROMS ( https://www.myroms.org/wiki/index.php/R ... all_Cygwin )

I originally posted the tutorial here in the forums, but then the tutorial was moved to WikiROMS where the tutorial was further refined.

The tutorial in this post was kept for historical reasons... but only the WikiROMS version is subject to updates and modifications... so I recommend you follow that tutorial.

About downloading Cygwin... before you start downloading there is an option to choose download location. You may want to experiment with a few servers close to where you live. I found download time varies wildly depending on what server you choose (from 10 min ... to more than 3 hr).

I hope this helps!

Diego

[mariafattorini]

Hi everyone,
I'm trying to install ROMS on my Windows Vista PC using Cygwin, but I got some errors.

May you help me?

I followed the installation procedure provided on Wikiroms (https://www.myroms.org/wiki/index.php/ROMS_Cygwin).
After installing Cygwin the root folder has the following folders:
bin, cygdrive, dev, ect, lib, sbin, svr, tmp, usr, var.
When I open the cygwin home directory (~), I cannot see the files and folders in the administrator directory.
Changing directory and moving to the root directory (cd/), there are the following files and folders:
bin, cygdrive, dev, ect, home, lib, proc, sbin, srv, tmp, usr, var.
After the first opening of the Cygwin program there is a new folder “home”, which contains the folder “administrator”. This folder (c:/cygwin/home/administrator) contains the following files:
.bash_profile, .bashrc, .inputrc.
From the Cygwin program the files in the folder c:/cygwin/home/administrator are not visible, while they are visible using Explorer.

Going ahead, I install g95 according to the procedure reported in Wikiroms:
I save the “g95-x86-cygwin.tgz” compressed file in the root directory (c:/cygwin),
after completing some steps of the procedure, I have the following situation:
- the “g95-x86-cygwin.tgz” compressed file is located in c:/cygwin/usr/local/bin;
- the files xxxx are located in xxxx.

Then I continue with the installation of NetCDF, but when I type ‘make check’ some errors appear; I list below the last lines:

util.o:util.F:(.data+0x7204): undefined reference to `nf_inq_var_fletcher32_'
util.o:util.F:(.data+0x7208): undefined reference to `nf_inq_var_endian_'
util.o:util.F:(.data+0x720c): undefined reference to `nf_inq_user_type_'
util.o:util.F:(.data+0x7218): undefined reference to `nf_inq_vlen_'
util.o:util.F:(.data+0x721c): undefined reference to `nf_insert_array_compound_

util.o:util.F:(.data+0x7220): undefined reference to `nf_insert_compound_'
util.o:util.F:(.data+0x7228): undefined reference to `nf_insert_enum_'
util.o:util.F:(.data+0x7234): undefined reference to `nf_open_par_'
util.o:util.F:(.data+0x724c): undefined reference to `nf_put_att_'
util.o:util.F:(.data+0x725c): undefined reference to `nf_put_var_'
util.o:util.F:(.data+0x72e4): undefined reference to `nf_put_vlen_element_'
util.o:util.F:(.data+0x7304): undefined reference to `nf_var_par_access_'
make[2]: *** [nf_test.exe] Error 1
make[2]: Leaving directory `/home/maria/software/netcdf-4.0/nf_test'
make[1]: *** [check-am] Error 2
make[1]: Leaving directory `/home/maria/software/netcdf-4.0/nf_test'
make: *** [check-recursive] Error 1

If I move to the folder '/ home / maria (my administator) / software/netcdf-4.0/nf_test' there is not the file called 'nf_test.exe', but only the files 'nf_test.F' and nf_test.o '.

What does it mean? And how can I complete the installation properly?

Any help or advice is welcome.
Thanks,
Maria

[robertson]

First, in cygwin (and any UNIX like envronment) ls, by default, hides "dot" files. That means any file that starts with a "." will not show up with a standard 'ls' command. To see dot files you must type 'ls -a'; type 'ls --help' for further info and options.

Second, NetCDF has changed the way their configure script works. It now requires that you chose both a Fortran90 (FC) and a Fortran77 (F77) compiler. Therefore you should change your configure line to:

Code: Select all

$ CC=gcc FC=g95 F77=g95 CPPFLAGS='-DNDEBUG -DpgiFortran' FFLAGS=-fno-second-underscore FCFLAGS=-fno-second-underscore ./configure

I have updated the tutorial to reflect this fact. I have also changed the tutorial to use gfortran instead of g95 since gfortran is now available from Cygwin setup. The g95 specific notes were moved to the contributions section.

Lastly, you are not finding nf_test.exe because the build failed while trying to create it.

[mariafattorini]

Dear Robertson, thank you very much for your quick answer.

I followed the updated tutorial but again the nf_test.exe file is not created.
However I went forward in the installation process.

I opened the file ‘build.bash’ and changed some lines according to the instructions in the tutorial.
In the ‘build.bash’ file I added the lines described in the tutorial and, as I downloaded NetCDF version 4.0, I changed all written 'NetCDF3' in 'NetCDF4'.
Anyway after typing ‘./build.bash’, the compiler works only for a few minutes and then the compilation stops and the following lines appear:

cd /home/maria/roms/Projects/Upwelling/Build; /usr/bin/gfortran-4 -c -frepack-ar
rays -O3 -ffast-math -ffree-form -ffree-line-length-none mod_netcdf.f90
mod_netcdf.f90:19.16:

USE netcdf
1
Fatal Error: File 'netcdf.mod' opened at (1) is not a GFORTRAN module file
make: *** [/home/maria/roms/Projects/Upwelling/Build/mod_netcdf.o] Error 1


What should I do to end up compilating the ROMS correctly?

Thank you,
Maria

[robertson]

I don't know why you still don't have nf_test.exe. Are you sure make check completed successfully?

Earlier in the ROMS compilation, netcdf.mod is copied from the NETCDF_INCDIR directory. One of three things is likely happening:

1. When building NetCDF make install failed or was not executed
2. Your NETCDF_INCDIR directory is set incorrectly in your build.bash
3. NetCDF was not built with gfortran

In case one ROMS is copying the netcdf.mod file from a previous build of netcdf that would have been replaced had make install completed successfully. For case 2 check further up in the ROMS build process to find where netcdf.mod is being copied from. It should be the directory you set NETCDF_INCDIR to. If not, check your build.bash again to make sure you have set the correct instance of NETCDF_INCDIR.

In case three (probably my fault), perhaps you copied the configure line from my post instead of the new one in the tutorial. I mentioned in my post that I changed the tutorial but it probably wasn't clear that you should use the line from there and not the line from my post and for that I apologize.

Good luck!

[hafezahmad100]

thank you very much. this is very simple procedure for windows users. is there is any step by step installation ROMS in linux user? I am actually new user .

[kate]

I have tried to provide all you need to know (and more!) for Unix in the manual.