Getting Started with SOG

SOG is maintained in a set of Mercurial distributed version control repositories. The central, reference copies of those repositories are stored in /ocean/sallen/hg_repos/.

SOG Run & Code Development Environment

If you’re impatient, you can get a fresh SOG environment set up on one of the ocean machines with the commands:

$ hg clone /ocean/sallen/hg_repos/SOG
$ cd SOG
$ make env

This will create a SOG environment in a directory called SOG. The environment looks like this:

     SOG-code-ocean/ - reference copy of the SOG-code repository
     SOG-code-dev/ - clone of SOG-code-ocean for code development work
     SOG-initial/ - SOG initialization data repository
     SOG-forcing/ - SOG forcing data repository
     SOG-test/ - directory for reference test results
       SOG-dev-yyyy-mm-dd/ - ref test results from SOG-code-dev on yyyy-mm-dd
                               profiles/ - profile output files
                               timeseries/ - timeseries output file
       SOG-ocean-yyyy-mm-dd/ - ref test results from SOG-code-ocean on yyyy-mm-dd
                               profiles/ - profile output files
                               timeseries/ - timeseries output file
     SOG-project/ - directory for doing SOG runs in
                      profiles/ - profile output files
                      timeseries/ - timeseries output file

Feel free to to rename the default SOG-project directory to something more appropriate to you project.

For details of how to customize this process, and links to other documentation like the recommended workflow in this environment, read on...

Create a SOG Environment with a Different Name

To create a fresh SOG environment called something other than SOG use the commands:

$ hg clone /ocean/sallen/hg_repos/SOG newSOG
$ cd newSOG
$ make env

Create a SOG Project Directory with a Different Name

To create a fresh SOG project directory called something other than SOG-project (SOG-hindcast, for example) use the commands:

$ cd SOG
$ make project PROJECT_NAME=SOG-hindcast

Create a SOG Environment on a non-ocean Computer

If you want to run SOG or work on the code on your own computer there are a few pre-requisites. It’s pretty easy to get them set up on Linux or OS/X and probably a bit more of a challenge on Windows. Pre-requisites:

  • Mercurial >1.0; it’s probably already installed
  • an account on ocean with ssh key access set up
  • g95 FORTRAN compiler; not required to create the SOG environment, but needed to compile and run the code. You’ll probably need to use your OS’s package installer, or download and install the appropriate binary.

With the above in place, you can set up a fresh SOG environment with the commands:

$ hg clone ssh://<user>@<host>
$ cd SOG
$ make env HG_REPOS=ssh://<user>@<host>

where <user> is your ocean user id, and <host> is the name of one of the ocean computers; e.g. nerka, grinder, herring.

SOG Command Processor

The SOG command processor, SOG, is a command line tool for doing various operations associated with SOG.

At the very least you will want to use SOG run to run SOG.


The SOG command processor is a Python package called SOGcommand. To install it so that you can use it:

  1. Confirm that you are using Python 2.6 by default. The response to the commmand:

    $ python --version

    should be something like Python 2.6.5. If not, create an alias:

    $ alias python '/usr/local/python26/bin/python2.6'

    if you use csh, or

    $ alias python='/usr/local/python26/bin/python2.6'

    if you use bash. Add the same command to your ~/.cshrc or ~/.bashrc file so that the alias takes effect every time you log in or create a new shell.

  2. Create your personal Python 2.6 packages directory:

    $ mkdir -p ~/.local/lib/python2.6/site-packages
  3. Install SOGcommand in development mode so that updates will take effect automatically:

    $ cd SOG
    $ python develop --user
  4. Test it with ~/.local/bin/SOG help or ~/.local/bin/SOG --version.

  5. Add ~/.local/bin to your path, both at the command line, and in your ~/.cshrc or ~/.bashrc file so that the SOG command is available every time you log in or create a new shell.


Use SOG help to get a list of the commands available for doing things with and related to SOG. Use SOG help <command> to get a synopsis of what a command does, what its required arguments are, and what options are available to control the command.

See SOG Command Processor for more details.

SOG Documentation

More documentation about SOG can be found online at The source files for the documentation are in SOG/docs/. The documentation includes: