GEOS-5

GEOS GCM Quick Start: Difference between revisions

← Older editNewer edit →
No edit summary
No edit summary
Line 3: Line 3:
'''Back to [[Documentation for GEOS GCM v10]]'''
'''Back to [[Documentation for GEOS GCM v10]]'''


== How to Obtain GEOS GCM and Compile Source Code ==
= How to build GEOS GCM =


There are two options for obtaining the model source code: from the CVS repository on the NCCS progress server, and from the SVN "public" repository on the trac server.  Since the code on progress is more current, elgible users are strongly encouraged to obtain accounts from NCCS and use the progress repository.
== Preliminary Steps ==


=== Using the NCCS CVS code repository ===
=== Load Build Modules ===


The following assumes that you know your way around Unix, have successfully logged into your cluster account and have an account on the source code repository with the proper <code>ssh</code> configuration -- see the NCCS repository quick start pages at: https://www.nccs.nasa.gov/trac/admin/wiki/QuickStart. The link requires your NCCS username and password. The recommend SSH config setup for CVS on discover is:
In your <code>.bashrc</code> or <code>.tcshrc</code> or other rc file add a line:


Host cvsacldirect
==== NCCS (SLES11) ====
    HostName cvsacl.nccs.nasa.gov
    Port 22223


That's it. Progress is not needed unless you specifically know you need it. It won't hurt to add it, but at present it isn't needed. Also, you'll need to generate RSA or ED25519 keys and upload them (this is mentioned in the quick start page above) to https://www.nccs.nasa.gov/keyupload/. (NOTE: DSA keys are not recommended as some sites, e.g., NAS, have started disallowing them.) The usual way of doing this is to go to your <tt>.ssh</tt> directory and run <tt>ssh-keygen</tt>, making a key with no password:
module use -a /discover/swdev/gmao_SIteam/modulefiles-SLES11


$ cd $HOME/.ssh
==== NCCS (SLES12) ====
$ ssh-keygen -o -a 100 -b 3072 -t rsa


The commands below assume that your shell is <code>csh</code>. Since the scripts to build and run GEOS tend to be written in the same, you shouldn't bother trying to import too much into an alternative shell.  If you prefer a different shell, it is easiest just to open a <code>csh</code> process to build the model and your experiment.
  module use -a /discover/swdev/gmao_SIteam/modulefiles-SLES12


Furthermore, model builds should be created in your space under <code>/discover/nobackup</code>, as creating them under your home directory will quickly wipe out your disk quota.
==== NAS ====


Set the following three environment variables:
module use -a /nobackup/gmao_SIteam/modulefiles


setenv CVS_RSH ssh
==== GMAO Desktops ====
setenv CVSROOT :ext:''USERID''@cvsacldirect:/cvsroot/esma


where ''USERID'' is, of course, your repository username, which should be the same as your NASA and NCCS username.  Then, issue the command:
On the GMAO desktops, the SI Team modulefiles should automatically be part of running <code>module avail</code> but if not, they are in:


  cvs co -r Jason-3_0 GEOSagcm
  module use -a /ford1/share/gmao_SIteam/modulefiles


This should check out the latest stable version of the model from the repository and create a directory called <code>GEOSagcm</code>.
Also do this in any interactive window you have. This allows you to get module files needed to correctly checkout and build the model.


==== CVS Errors ====
Now load the <code>GEOSenv</code> module:


If the CVS checkout doesn't work for you, there are many possibilities.
module load GEOSenv


===== Keyupload =====
which obtains the latest <code>git</code>, <code>CMake</code>, and <code>manage_externals</code> modules.


If the error says something about "keyupload", then the key upload either hasn't taken hold yet (can take 5-10 minutes to work after uploading the key), or, perhaps, the wrong key was uploaded.
== Clone the Model ==


===== Access denied for this host =====
GEOS is now hosted on GitHub.


If you see something like "access denied for this host", then your best bet is to contact NCCS. Per a response from NCCS to a user that had something similar happen, they need to add the CVS hosts to an LDAP entry.
git clone -b v10.12.4 git@github.com:GEOS-ESM/GEOSgcm.git


===== Failed to create lock/permission denied =====
== Building GEOS ==


If you see something like:
=== Single Step Building of the Model ===


cvs checkout: failed to create lock directory for `/cvsroot/esma/CVSROOT' (/cvsroot/esma/CVSROOT/#cvs.history.lock): Permission denied
If all you wish is to build the model, you can run <code>parallel_build.csh</code> from a head node. Doing so will checkout all the external repositories of the model and build it. When done, the resulting model build will be found in <code>build/</code> and the installation will be found in <code>install/</code> with setup scripts like <code>gcm_setup</code> and <code>fvsetup</code> in <code>install/bin</code>.
cvs checkout: failed to obtain history lock in repository `/cvsroot/esma'
cvs checkout: Updating src
cvs checkout: failed to create lock directory for `/cvsroot/esma/esma/src/Applications/GEOSdas' (/cvsroot/esma/esma/src/Applications/GEOSdas/#cvs.lock): Permission denied
cvs checkout: failed to obtain dir lock in repository `/cvsroot/esma/esma/src/Applications/GEOSdas'
cvs [checkout aborted]: read lock failed - giving up


this means you don't have a home directory on progress. Try doing:
==== Develop Version of GEOS GCM ====


$ ssh progress.nccs.nasa.gov
The user will notice two files in the main directory: <code>Externals.cfg</code> and <code>Develop.cfg</code>. The difference between these two is that <code>Externals.cfg</code> always refers to stable tested released subrepositories. The <code>Develop.cfg</code> points to the <code>develop</code> branch of <code>@GEOSgcm_GridComp</code> and <code>@GEOSgcm_App</code>. This is equivalent in the CVS days of the difference between a stable <code>Jason-X_Y</code> tag and the development <code>Jason-UNSTABLE</code> tag. In order to build the <code>Develop.cfg</code> version of the model with <code>parallel_build.csh</code> do:


You'll enter your PASSCODE and password and then it'll seem like the terminal is "stuck". Just hit Ctrl-C. Now try the CVS command again.
parallel_build.csh -develop


=== Compiling the Model ===
==== Debug Version of GEOS GCM ====


First, you need to set <code>ESMADIR</code>. For example, if your <code>src/</code> directory is:
To obtain a debug version, you can run <code>parallel_build.csh -debug</code> which will build with debugging flags. This will build in <code>build-Debug/</code> and install into <code>install-Debug/</code>.


/discover/nobackup/mathomp4/Models/GEOSgcm-10.12/GEOSgcm
==== Mepo Version of GEOS GCM ====


then you should set:
GEOS GCM will soon be transitioning from using <code>checkout_externals</code> to using [https://github.com/GEOS-ESM/mepo <code>mepo</code>], a GMAO-developed multi-repository management tool. If you wish to use it via <code>parallel_build.csh</code> you can run:


  setenv ESMADIR /discover/nobackup/mathomp4/Models/Jason-3_0/GEOSagcm
  parallel_build.csh -mepo


Next, we need to source <code>g5_modules</code> with:
along with any other flags you usually use.


source $ESMADIR/src/g5_modules
=== Multiple Steps for Building the Model ===


This will set up the build environment. If you then type
The steps detailed below are essentially those that <code>parallel_build.csh</code> performs for you. Either method should yield identical builds.


module list
==== Checkout externals ====


you should see:
Using the <code>checkout_externals</code> command to compose the model is done by:


  Currently Loaded Modulefiles:
  cd GEOSgcm
  1) other/comp/gcc-6.3
checkout_externals
  2) comp/intel-18.0.1.163
  3) mpi/sgi-mpt-2.17
  4) lib/mkl-18.0.1.163
  5) other/SIVO-PyD/spd_1.25.0_gcc-6.3_mkl-17.0.4.196


If this all worked, then type:
====== Checking out develop ======


cd $ESMADIR/src
To use the <code>Develop.cfg</code> file, run:
gmake install


This will build the model.  It will take about 30 minutes.  If this works, it should create a directory under <code>GEOSagcm</code> called <code>Linux/bin</code>. In here you should find the executable: <code>GEOSgcm.x</code> .
  checkout_externals -e Develop.cfg


== Setting up a Run ==
==== Mepo ====


=== Passwordless Logins ===
To checkout the full model with the [https://github.com/GEOS-ESM/mepo <code>mepo</code>] tool, you run:
 
mepo init
mepo clone
 
The first command initializes the multi-repository and the second one clones and assembles all the sub-repositories according to <code>components.yaml</code>
 
===== Checking out develop =====
 
To get development branches of GEOS GCM with <code>mepo</code> is different. <code>mepo</code> itself knows (via <code>components.yaml</code>) what the development branch of each subrepository is. The equivalent of <code>Develop.cfg</code> for <code>mepo</code> is to checkout the development branches of GEOSgcm_GridComp and GEOSgcm_App:
 
mepo develop GEOSgcm_GridComp GEOSgcm_App
 
This must be done after <code>mepo clone</code> as it is running a git command in each sub-repository.
 
==== Build the Model ====
 
===== Load Compiler, MPI Stack, and Baselibs =====
 
On tcsh:
 
<pre>source @env/g5_modules
</pre>
or on bash:
 
<pre>source @env/g5_modules.sh
</pre>
===== Create Build Directory =====
 
We currently do not allow in-source builds of GEOSgcm. So we must make a directory:
 
<pre>mkdir build
</pre>
The advantages of this is that you can build both a Debug and Release version with the same clone if desired.
 
===== Run CMake =====
 
CMake generates the Makefiles needed to build the model.
 
<pre>cd build
cmake .. -DBASEDIR=$BASEDIR/Linux -DCMAKE_Fortran_COMPILER=ifort -DCMAKE_INSTALL_PREFIX=../install
</pre>
This will install to a directory parallel to your <code>build</code> directory. If you prefer to install elsewhere change the path in:
 
-DCMAKE_INSTALL_PREFIX=&lt;path&gt;
</pre>
and CMake will install there.
 
===== Build and Install with Make =====
 
<pre>make -j6 install
</pre>
 
= Running GEOS GCM =
 
== Passwordless Logins ==


First of all, to run jobs on the cluster you will need to set up passwordless <code>ssh</code> (which operates within the cluster, between the nodes running the job).  To do so, run the following from your '''discover''' home directory:
First of all, to run jobs on the cluster you will need to set up passwordless <code>ssh</code> (which operates within the cluster, between the nodes running the job).  To do so, run the following from your '''discover''' home directory:
Line 112: Line 153:
Then, log into  '''dirac''' and cut and paste the contents of the <code>id_rsa.pub</code> file on '''discover''' into the  <code>~/.ssh/authorized_keys</code> file on  '''dirac'''.  Problems with <code>ssh</code> should be referred to NCCS support.
Then, log into  '''dirac''' and cut and paste the contents of the <code>id_rsa.pub</code> file on '''discover''' into the  <code>~/.ssh/authorized_keys</code> file on  '''dirac'''.  Problems with <code>ssh</code> should be referred to NCCS support.


==== DSA Keys ====
=== DSA Keys ===


Note: Due to evolution of security, it is recommended to not use DSA keys. NAS currently doesn't not allow them, and RSA and ED25519 keys are considered "better" anyway.
Note: Due to evolution of security, it is recommended to not use DSA keys. NAS currently doesn't not allow them, and RSA and ED25519 keys are considered "better" anyway.


=== Setting up a model run ===
== Setting up a model run ==


To set the model up to run, cd to <code>GEOSgcm/install/bin</code> and run:
Once the model has built successfully, you will have an <code>install/</code> directory in your checkout. To run <code>gcm_setup</code> go to the <code>install/bin/</code> directory and run it there:


cd install/bin
  ./gcm_setup
  ./gcm_setup


Retrieved from "https://geos5.org/wiki/index.php?title=GEOS_GCM_Quick_Start"