WikiROMS - User contributions [en]

ROMS Mac Snow Leopard

2012-03-06T20:03:51Z

Marcellosekoot: /* MPICH2 */ changed frotransoft to fortransoft

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfortransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:

:*If you're not there already, go to the Upwelling directory:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /Users/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*Within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-03-06T19:57:21Z

Marcellosekoot: /* Compile ROMS */ removed reference to Cygwin

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:

:*If you're not there already, go to the Upwelling directory:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /Users/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*Within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-03-06T19:35:47Z

Marcellosekoot: /* Run ROMS */ modified path from /home to /Users, deleted reference to Cygwin

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /Users/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*Within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-03-06T04:40:34Z

Marcellosekoot: /* NetCDF Version 4 Format (optional) */ formatting corrections

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-03-06T04:39:53Z

Marcellosekoot: /* NetCDF Version 4 Format (optional) */ formatting corrections

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-03-06T04:38:50Z

Marcellosekoot: /* NetCDF Version 4 Format (optional) */ formatting corrections

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-02-27T02:28:37Z

Marcellosekoot: /* MPICH2 */ formatting

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-02-25T07:58:04Z

Marcellosekoot: /* HDF5 (optional) */ added filename to ftp path for automatic download

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds> tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/hdf5-1.8.4-patch1.tar.gz] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-02-25T07:53:00Z

Marcellosekoot: /* NetCDF Version 3 Format (recommended) */ formatting corrections

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds> tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/ ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' > ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-02-25T07:50:47Z

Marcellosekoot: /* NetCDF Version 3 Format (recommended) */ moved the tag to start a newline beofre ./configure

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds> tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/ ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-02-25T07:42:18Z

Marcellosekoot: /* GNU Fortran Compiler */ changed the response to 'which' from /usr to /opt

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /opt/local/bin/gcc43 which g++43 /opt/local/bin/g++43 which gfortran /opt/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds> tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/ ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!

ROMS Mac Snow Leopard

2012-02-25T07:39:07Z

Marcellosekoot: /* Open MPI */ added br tag

<div class="title">Tutorial: Installing ROMS on Mac OS X Snow Leopard</div>

<center>{{warning}}THIS PAGE IS UNDER CONSTRUCTION{{warning}}</center>

Special thanks to Parker MacCready at the University of Washington. Most of the original tutorial was taken verbatim from his website. The tutorial for a MacBook Pro running Mac OS X 10.5.4, Darwin 9.4.0 can be found [[ROMS_Mac|here]].

This tutorial was tested on an iMac and a MacBook Pro running Mac OS X 10.6.4, Darwin 10.4.0. The iMac is running in full 64-bit mode; for details on what that means and how to do it, [http://macperformanceguide.com/SnowLeopard-64bit.html click here]. The iMac is a quad-core Intel Core i7 processor while the MacBook Pro is a dual-core Intel Core i7 processor.

{{note}}'''Code Box Legend:''' In the code boxes, The text in green is what you need to type at the terminal prompt and the '''black''' text is what is displayed as a result of your command. Ellipsis ('''. . .''') mean that large amounts of output are omitted for brevity.

__TOC__

{{warning}}You must be logged in as a user with administrator privileges to complete most this tutorial.

==Install Supporting Software==

{{note}}Note: most of this software needs to be installed in the order given (e.g. you need Xcode to install MacPorts, MacPorts to install gfortran, and gfortran to make HDF5, NetCDF, etc.).

===Xcode===

Download the Apple Developers Tools Xcode, from [http://developer.apple.com/technologies/tools/ developer.apple.com/technologies/tools/], click the Xcode 3: "Free Download" button then the "Mac Dev Center" button. Follow the standard installation (this means that it will install itself when you click on it, and you just need to click to accept a few defaults). To download this you need to sign up (free) as an ADC member, but if you already have an Apple account (e.g. for iTunes) you can use that. It is free.

{{warning}}Caution: the download is almost 3 GB so it might take a while to download.

===MacPorts===

Get MacPorts-1.9.1-10.6-SnowLeopard.dmg from the Snow Leopard link at [http://www.macports.org/install.php www.macports.org/install.php] and follow the standard installation. By default the the installation should add a block similar to that shown below to .profile in your home directory.

:<div class="box"># MacPorts Installer addition on 2010-09-17_at_13:36:22: adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:/opt/local/sbin:$PATH # Finished adapting your PATH environment variable for use with MacPorts.</div>

{{note}}'''Note:''' If you don't use bash as your shell you might have to adapt these lines and/or put them in different file. If you copy and paste the above lines from this tutorial page, remove the line return after the word '''appropriate'''.

To test if MacPorts was installed and setup correctly, open a terminal window (Applications -> Utilities -> Terminal) and type which port. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which port /opt/local/bin/port</div>

If no path is returned, you need to update your '''PATH''' environment variable to include /opt/local/bin.

===GNU Fortran Compiler===

{{note}}'''Note:''' I tried gcc45 but ran in to problems compiling HDF5. If you don't plan to install NetCDF4/HDF5 capabilities you should be able to use this newer gcc/gfortran.

In the terminal window, use MacPorts to install gcc43:

:<div class="box">sudo port install gcc43</div>

{{warning}} This can take a while since it has to download, configure, build, and install the GNU compiler suite (including gfortran) and its dependencies.

The default GNU compiler suite that comes with the system is the 4.2.X series and does not include gfortran. In order for the compiler suite you just installed (the 4.3 series) to avoid conflicts with the pre-installed compilers the executables are given different names. I suggest making symbolic links in the /opt/local/bin directory to make the compiler names easier to type and remember.

:<div class="box">cd /opt/local/bin sudo ln -s gcc-mp-4.3 gcc43 sudo ln -s g++-mp-4.3 g++43 sudo ln -s gfortran-mp-4.3 gfortran</div>

{{note}}Notice that I did not use gfortran43 for the gfortran link. There are two reasons for this: one, there isn't another gfortran on the system that the name would conflict with and two, it makes ROMS slightly easier to build (more on the second reason later).

You can use the which command in the terminal to check symbolic links you just made. If you are using tcsh instead of bash as your shell you will have to type rehash first.

:<div class="box">which gcc43 /usr/local/bin/gcc43 which g++43 /usr/local/bin/g++43 which gfortran /usr/local/bin/gfortran</div>

===GNU Make===

Make sure that GNU make 3.81 is already installed on your system by typing make -v in the terminal window.

:<div class="box">make -v GNU Make 3.81 Copyright (C) 2006 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This program built for i386-apple-darwin10.0</div>

If make is not found, check your '''PATH''' environment variable; my make is at /usr/bin/make.

===Perl===

Perl is most likely already installed. However, if executing which perl from the terminal tells you perl isn't found, you will need to install it; my perl is at /usr/bin/perl.

===Set Up Your Build Environment===

There are several environment variables that will need to be set in order to build the NetCDF, MPI (optional), and HDF5 (optional) libraries. Again, if you don't use bash as your shell you will have to adapt the lines below.

:<div class="box">export CC=gcc43 export CXX=g++43 export FC=gfortran export F90=gfortran export F77=gfortran</div>

I would suggest making a source_builds directory in your home directory so you have a place to build the libraries.

:<div class="box">mkdir ~/source_builds</div>

===MPI (optional)===

{{note}} If you don't plan to run ROMS in distributed memory (MPI), you can skip this section.

At this time the MPICH libraries don't build successfully. Open MPI and MPICH2 will build successfully. I prefer Open MPI so we'll start there and follow with MPICH2. Choose one or the other unless you have a good reason for needing both.

====Open MPI====
Download the Open MPI source code (openmpi-1.4.2.tar.bz2) from [http://www.open-mpi.org/software/ompi/v1.4/ www.open-mpi.org/software/ompi/v1.4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">cd ~/source_builds tar xjf openmpi-1.4.2.tar.bz2 cd openmpi-1.4.2 ./configure --prefix=/opt/gfortransoft/openmpi/openmpi-1.4.2 . . . make -j 4 . . . make -j 4 check . . . sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your Open MPI libraries and executables.

:<div class="box">> cd /opt/gfortransoft/openmpi > sudo ln -s openmpi-1.4.2/bin > sudo ln -s openmpi-1.4.2/etc > sudo ln -s openmpi-1.4.2/include > sudo ln -s openmpi-1.4.2/lib > sudo ln -s openmpi-1.4.2/share</div>

Configuring Open MPI to build static only libraries ('''--disable-shared''') caused run-time segmentation faults. A side effect of this fact is that you will have to set the '''DYLD_LIBRARY_PATH''' environment variable in addition to updating the PATH variable. Below are the lines you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export DYLD_LIBRARY_PATH=/opt/gfortransoft/openmpi/lib > export PATH=/opt/gfrotransoft/openmpi/bin:${PATH}</div>

====MPICH2====

If you have already installed Open MPI skip this step unless you have a reason for building both MPI implementations.

Download the MPICH2 source code (mpich2-1.2.1p1.tar.gz) from [http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds> tar xzf mpich2-1.2.1p1.tar.gz > cd mpich2-1.2.1p1 > ./configure --prefix=/opt/gfortransoft/mpich2/mpich2-1.2.1p1 . . . > make -j 4 . . . > sudo make install</div>

{{warning}}'''IMPORTANT:''' Do not set '''--prefix''' to /usr because you will replace the system's default MPI. We are not using the default MPI because the Fortran bindings are missing.

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be the number of processing cores on your machine.

You may also want to set some symbolic links to simplify the paths to your MPICH2 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/mpich2 > sudo ln -s mpich2-1.2.1p1/bin > sudo ln -s mpich2-1.2.1p1/etc > sudo ln -s mpich2-1.2.1p1/include > sudo ln -s mpich2-1.2.1p1/lib > sudo ln -s mpich2-1.2.1p1/sbin > sudo ln -s mpich2-1.2.1p1/share</div>

Below is the line you should add to your login script (.profile or .bashrc or .cshrc, etc. adjusting accordingly for different shells)

:<div class="box">> export PATH=/opt/gfrotransoft/mpich2/bin:${PATH}</div>

MPICH2 works a little differently than Open MPI. It uses a multi-purpose daemon (mpd) to schedule and control the MPI calls and communications. In order to run MPI jobs using MPICH2 there are a couple extra steps. First we need to create a special secret word file in our home directory and correctly set its permissions:

:<div class="box">> echo "secretword=shh_secret" > ~/.mpd.conf > chmod 600 ~/.mpd.conf</div>

Replace "shh_secret" with a word of your choice. Now we can start mpd and test that MPICH2 was built correctly.

:<div class="box">> mpd & . . . > make -j 4 check</div>

If no errors are reported, we are ready to move on.

===HDF5 (optional)===

{{note}}If you do not need to output or read NetCDF4 files please skip this section.

Download the HDF5 source code (hdf5-1.8.4-patch1.tar.gz) from [ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/ ftp.unidata.ucar.edu/pub/netcdf/netcdf-4/] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf hdf5-1.8.4-patch1.tar.gz > cd hdf5-1.8.4-patch1</div>

In order for HDF5 to compile on the Mac, you have to add the following line to the config/apple file:

:<div class="box">hdf5_cv_mpi_complex_derived_datatype_works='no'</div>

Once you have made this change you can configure, build, and install HDF5:

:<div class="box">> ./configure --prefix=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 --enable-fortran \ --enable-static-exec --disable-shared . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your HDF5 libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s hdf5-1.8.4-patch1 hdf5</div>

{{note}}'''Note:''' It is possible to build HDF5 (and NetCDF4) to perform parallel I/O. However, this is not recommend because at this point parallel I/O in ROMS is slower than serial I/O.

===NetCDF===

There are two major NetCDF formats: NetCDF-3 and NetCDF-4/HDF5. I have included instructions for compiling both so remember to follow the appropriate section for your needs. The latest NetCDF sources can can be used to compile both versions.

Download the NetCDF source code (netcdf-4.1.1.tar.gz) from [http://www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp www.unidata.ucar.edu/downloads/netcdf/netcdf-4_1_1/index.jsp] into your ~/source_builds directory. Once the download completes, execute the following from your terminal window:

:<div class="box">> cd ~/source_builds > tar xzf netcdf-4.1.1.tar.gz > cd netcdf-4.1.1</div>

====NetCDF Version 3 Format (recommended)====

Unless you have a specific need for NetCDF version 4 format, I would recommend compiling NetCDF without version 4 support.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf3</div>

====NetCDF Version 4 Format (optional)====

As hinted above, you will need to have successfully compiled HDF5 in order to compile a NetCDF that can read and write NetCDF-4/HDF5 files. Not all of the configure options and arguments shown below are necessary. In particular, '''--enable-dap''' requires libcurl (version 7.18.0 or later) to be installed. I will show the full featured configuration first.

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 --enable-dap --with-udunits \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{warning}} '''Notice:''' If you get lots of undefined symbol references you are probably missing some of the libraries required for the [http://www.opendap.org/ OPeNDAP] ('''--enable-dap''' and '''--with-udunits''') capabilities. You can either install the necessary libraries or us the minimal configuration line shown below:

:<div class="box">> CPPFLAGS='-DNDEBUG -DpgiFortran' ./configure \ --with-hdf5=/opt/gfortransoft/serial/hdf5-1.8.4-patch1 \ --prefix=/opt/gfortransoft/serial/netcdf-4.1.1 \ --enable-netcdf-4 --disable-shared --disable-cxx . . . > make -j 4 . . . > make -j 4 check . . . > sudo make install</div>

{{note}}'''Caution:''' I have found that if you don't give the '''-j''' option a number (4 in this case) builds will fail. Typically this number should be less than or equal to the number of processing cores on your machine.

You may also want to set a symbolic link to simplify the paths to your NetCDF libraries and executables.

:<div class="box">> cd /opt/gfortransoft/serial > sudo ln -s netcdf-4.1.1 netcdf4</div>

==Download ROMS==
This section assumes that you have registered and obtained your ROMS username/password.

Create the directory ~/ROMS and checkout the ROMS source code replacing 'joeroms' with your ROMS user name:

:<div class="box">> cd ~ > mkdir ROMS > cd ROMS > svn checkout --username joeroms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki></div>

You will see many lines stream by. When it finishes, type ls. You have a folder named trunk that contains the ROMS source code.

{{note}}Note: The first time you run the '''svn''' command you will be asked for your ROMS password and store it for future use.

==Customizing the [[build Script|Build Script]]==

The ROMS source code comes with a [[build Script|build script]] in the ROMS/Bin directory. Examples written with bash (build.bash) and csh (build.sh) are provided. For convenience, we will work with build.bash since bash is the default shell on a Mac. A full description of the build script can be found [[build Script|here]].

:*At the same level as your new trunk directory create a new folder named Projects and change into it.
::<div class="box">mkdir Projects cd Projects</div>

:*Create a folder named Upwelling and change into it. 'Upwelling' is the name of the [[Test Cases|ROMS test case]] we are going to compile and run.
::<div class="box">mkdir Upwelling cd Upwelling</div>

:*Copy the ocean_upwelling.in file into the Upwelling directory you just created.
::<div class="box">cp ../../trunk/ROMS/External/ocean_upwelling.in .</div>

:*Copy the upwelling.h file into the Upwelling directory in the same way.
::<div class="box">cp ../../trunk/ROMS/Include/upwelling.h .</div>

:*Copy the build.bash file into the Upwelling directory.
::<div class="box">cp ../../trunk/ROMS/Bin/build.bash .</div>

:*Open the build.bash script you just copied into your Upwelling directory using your favorite text editor.

:*Scroll down until you find MY_ROOT_DIR and MY_ROOT_DIR. Set them as follows (replacing 'joeroms' with your Mac user name).
::<div class="box"> export MY_ROOT_DIR=/Users/joeroms/ROMS  export MY_PROJECT_DIR=${MY_ROOT_DIR}/Projects/Upwelling</div>

:*Now set MY_ROMS_SRC to:
::<div class="box"> export MY_ROMS_SRC=${MY_ROOT_DIR}/trunk</div>

:*Make sure that MY_CPP_FLAGS is '''not''' set. I had to comment out one line with the # symbol like so:
::<div class="box">#export MY_CPP_FLAGS="-DNPZD_POWELL"</div>

:*We are compiling in serial using the gfortran compiler so make your build.bash match the following:
::<div class="box"> export USE_MPI=  export USE_MPIF90=  export FORT=gfortran</div>

:*Uncomment the line:
::<div class="box">#export USE_MY_LIBS=on</div>to look like:<div class="box"> export USE_MY_LIBS=on</div>

:*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:
::<div class="box">      '''else'''           export NETCDF_INCDIR=/opt/gfortransoft/serial/netcdf3/include           export NETCDF_LIBDIR=/opt/gfortransoft/serial/netcdf3/lib       '''fi'''</div>change them to:<div class="box">      '''else'''           export NETCDF_INCDIR=/usr/local/include           export NETCDF_LIBDIR=/usr/local/lib       '''fi'''</div>

:*Save and close the build.bash file.

==Create the Darwin-gfortran.mk file==

ROMS does not have a Mac-gfortran make module so you will need to create one. Luckily, the Linux-gfortran.mk can be used without modification:

:<div class="box">cd ~/ROMS/trunk/Compilers cp Linux-gfortran.mk Darwin-gfortran.mk cd ~/ROMS/Projects/Upwelling</div>

==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:
::<div class="box">cd ~/roms/Projects/Upwelling</div>

:*Then type:
::<div class="box">./build.bash</div>

:*If lots of stuff comes on the screen then you are good. 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 ocean_upwelling.in file so open it with your favorite editor and find the following line:<div class="box"> VARNAME = ROMS/External/varinfo.dat</div>and change it to (again replacing 'joeroms' with your Mac user name):<div class="box"> VARNAME = /home/joeroms/ROMS/trunk/ROMS/External/varinfo.dat</div>
:*Save and close the ocean_upwelling.in file
:*In cygwin, within the Upwelling directory where your oceanS and ocean_upwelling.in files live, type:
::<div class="box">./oceanS < ocean_upwelling.in</div>

If lots of numbers are displayed on the screen ROMS is running! 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, [[Plotting Package Installation|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. [http://www.myroms.org/index.php?page=RomsPackages Click here] for a good place to start.

Good luck!