1. Initial Setup

Sections

Customize your Odyssey Login Environment

The GEOS-Chem Support Team has created a Git repository of Unix environment scripts that are customized for use with the MITgcm.  These are hosted on Bitbucket.org, and are also stored in the /n/sunderland_lab/Lab/environment folder.

To obtain the startup scripts, type the following commands:

cd /n/sunderland_lab/Lab/environment
./install

This will copy a number of startup files to your home folder (~/) and your ~/bin folder.  You will get output such as this:

Installing environemnt files for MITgcm
... Copied .bashrc_mitgcm to ~/.bashrc_mitgcm
... ~/.my_personal_settings_mitgcm is already installed
... ~/bin directory already exists
... ~/bin/interactive is already installed
... ~/bin/awake.sh is already installed
... ~/bin/jobinfo is already installed
... ~/bin/jobstats is already installed

NOTE: You may already have your own copies of .my_personal_settings_mitgcm, ~/bin/interactive, ~/bin/jobinfo, and ~/bin/jobstats installed.  The install script will not overwrite these files if they are already present.

For a complete list of the files that are copied, see the README file.  Of these, the most important scripts are:

.bashrc_mitgcm
interactive
awake.sh 

These scripts will be explained in further detail in Chapter 2: Start an interactive session on Odyssey .

Download the MITgcm_code from Bitbucket 

The GEOS-Chem Support Team has created a Git repository with the MITgcm source code.  We recommend that you clone a copy of the MITgcm code onto your /n/regal/sunderland_lab/YOUR-USER-NAME folder, which is where you will compile and run MITgcm.  

Type the following commands:

cd /n/regal/sunderland_lab/YOUR-USER-NAME
git clone https://bitbucket.org/harvard-bgc/mitgcm_code MITgcm_code
cd MITgcm_code

This will create a copy of the MITgcm_code source code to your personal folder at  /n/regal/sunderland_lab/YOUR-USER-NAME.

You will need to set up a free Bitbucket.org account in order to be able to access the MITgcm_code Git repostiory. We have set this repository up as a private Git repo for exclusive use of Harvard BGC group members.  You should receive an invitation to join this repository   If you aren’t yet on Bitbucket, then Bob Yantosca has a copy of the MITgcm in his directory on regal: /n/regal/sunderland_lab/ryantosca/MITgcm_code that you can copy.

IMPORTANT NOTE: Files on the /n/regal/ disk are purged every 90 days to save disk space.  Therefore, we recommend that you keep a backup copy of your MITgcm_code folder on your Sunderland group lab space folder; /n/sunderland_lab/Lab/Users/YOUR-USER-NAME.  Also, you should copy any MITgcm output files that you want to store for longer than 90 days to your lab space folder.  More on this in a couple of sections.

Open a new branch in Git where you can make modifications

The MITgcm_code directory that you just downloaded uses the Git source code management system for version control.  This allows you to "check in" your modifications so that they can be shared with other people.  You can also "roll back" your changes to a prior state if you need to start over.

Git provides two utilities to make the version control process easier:

• Git GUI - A graphic user interface that lets you execute most common Git commands
• GitK browser - a utility to let you examine the version history of the MITgcm_code directory.  You can see all of the commits that were made by other users.

To start the Git Gui, type at the Unix prompt:

git gui &

This will open a window that looks like this:

To open the GitK browser, click on Repository / Visualize All Branch History: 

This will open GitK as a separate window:

In the GitK window, the top left window shows the version history. Each blue dot is a commit, or a time when someone saved their work to the repository (which stored in your in the MITgcm_code/.git folder).  The name of the committer and his/her email is also provided in the center and right top columns.

If you click on an individual commit, you will get more information, including the commit message (bottom left window) and a list of modified files (bottom right window).

The green box that says master denotes the name of the current branch. We recommend that you open your own branch where you can make your own modifications to MITgcm.   To open a new branch you can go to Git GUI and then click on Branch / Create:

This will bring up a dialog box where you can type the name of the branch.  Let's call it my_branch for now:

When you create a branch in Git Gui, it automatically checks it out for you.  In other words, it switches you from the previous branch (in this case, master) to the branch you just created (in this case, my_branch).  If you look at the GitK browser, you will see a green box that says master and a green box that says my branch (in bold).  The boldface denotes the currently-checked out branch.

If you wanted to switch back to the master branch, you can do it in 2 ways:

1. In the GitK browser, right-click on the the green box that says "master" and pick Check out this branch:

2. Or in the Git Gui, you could click on Branch / Checkout

and then click on master in the dialog box that pops up:

This is just a brief introduction to the features of Git.  For more in-depth information we recommend the resources below.  Or feel free to ask the GEOS-Chem Support Team for more information!

• Git: About Version Control (book)
• Git tutorial video
  • Excellent lecture given by Bart Trojanowski for the Ottawa Group of Ruby Enthusiasts. HIGHLY RECOMMENDED!
• Git for the Lazy
  
  • This is an excellent Git guide for beginners. Short, sweet, and to the point.
    
• Version control with Git
  • Written for GEOS-Chem users but contains much useful information that will carry over to MITgcm
• Using Git with GEOS-Chem
  
  • Written for GEOS-Chem users, but contains much useful information that will carry over to MITgcm
    

Up | Next