<p><b>mhoffman@lanl.gov</b> 2012-03-12 16:17:30 -0600 (Mon, 12 Mar 2012)</p><p>TRUNK COMMIT - land_ice documents only<br>
Updated the getting_started guide to reflect all of the recent modifications the branch. This document should now successfully guide a new user starting from scratch to run the dome test case and visualize output. This is still an 'empty' run without calls to the LifeV dycore.<br>
</p><hr noshade><pre><font color="gray">Modified: trunk/documents/land_ice/reference_manual/getting_started.txt
===================================================================
--- trunk/documents/land_ice/reference_manual/getting_started.txt 2012-03-12 22:13:16 UTC (rev 1623)
+++ trunk/documents/land_ice/reference_manual/getting_started.txt 2012-03-12 22:17:30 UTC (rev 1624)
@@ -1,9 +1,21 @@
MPAS Land Ice Core Quick Start:
-=======================
-Checking out the branch
-$ svn checkout -username xylar@lanl.gov https://svn-mpas-model.cgd.ucar.edu/branches/land_ice_projects
+============
+Organization:
+In this document, the following directory convention is used:
+~/mpas = a root directory to hold all mpas related work
+~/mpas/land_ice_projects = https://svn-mpas-model.cgd.ucar.edu/branches/land_ice_projects ; where the land ice development happens
+~/mpas/grid_gen = https://svn-mpas-model.cgd.ucar.edu/trunk/grid_gen ; the trunk version of grid generation tools - this is the only piece of the trunk that is currently used
+~/mpas/grids = an unversioned directory in which to generate grids
+~/mpas/runs = an unversioned directory in which to actually perform runs
+(Note: the land_ice_projects and grid_gen directories can either be separate checkouts or symlinks to a single checkout of the entire repository, e.g. ~/mpas/mpasall/. The latter option allows a single 'snv up' to update all the pieces.)
+The quick start assumes you want to run the dome test case.
+================================
+Checking out the land ice branch
+================================
+$ svn checkout --username somebody@lanl.gov https://svn-mpas-model.cgd.ucar.edu/branches/land_ice_projects ~/mpas/land_ice_projects
+
All land ice development occurs within the land_ice_projects branch in separate projects.
The land ice core is located in the 'implement_core' project which is equivalent to the 'mpas' directory in the trunk.
@@ -11,29 +23,47 @@
$ svn update
+========================
+Setting up a workspace
+========================
+We will create unversioned directories called 'grids' and 'runs' where simulations are performed. All work can be done in the directories under version control, but this is somewhat cleaner for illustrative purposes.
+mkdir ~/mpas/grids
+mkdir ~/mpas/grids/dome
+mkdir ~/mpas/runs
+cp -R ~/mpas/land_ice_projects/test_cases/dome ~/mpas/runs/dome
+(this could also be a symlink)
+
=======================
Building MPAS: Land Ice
+========================
$ setenv CORE land_ice (or export CORE=land_ice)
$ setenv NETCDF /usr/local/netcdf-gfortran (or export NETCDF=/usr/local/netcdf-gfortran)
-$ cd implement_core
+$ cd ~/mpas/land_ice_projects/implement_core
$ make clean
$ make gfortran SERIAL=true ( or make gfortran if MPI is installed, and compiled with gfortran; replace gfortran with the compiler of your choice)
look for the link to land_ice_model.exe to make sure the build succeeded
+Notes on building:
+* Starting with netcdf4, linking to the netcdf fortran libraries requires both netcdf.a and netcdff.a. The Makefile needs to be modified to include -lnetcdff on the LIBS line. (Same for periodic_hex's Makefile.) If you are using netcdf version 3.x, this doesn not apply.
+* On bluefire 'make' will not work - gmake needs to be used instead. One way to avoid having to replace all instances of 'make' with 'gmake' in all Makefiles is to set up a link named 'make' to /usr/local/bin/gmake in your home directory. For example:
+cd ~
+mkdir bin
+ln -s /usr/local/bin/gmake ./bin/make
+Now put /glade/home/USERNAME/bin at the beginning of your path in your .bashrc by adding this line:
+export PATH=/glade/home/USERNAME/bin:$PATH
+Just remember that from now on you will always be using gmake when you invoke 'make'!
=============
-Making a grid:
+Making a grid
+=============
Checking out the trunk version of grid gen
-$ svn checkout -username xylar@lanl.gov https://svn-mpas-model.cgd.ucar.edu/trunk/grid_gen
+$ svn checkout --username somebody@lanl.gov https://svn-mpas-model.cgd.ucar.edu/trunk/grid_gen ~/mpas/grid_gen
-Assuming initial conditions are stored in subdirectories in ~/mpas_initial:
-$ mkdir ~/mpas_initial/periodic_hex_500_500
-From the trunk
-$ cd grid_gen/periodic_hex
+$ cd ~/mpas/grid_gen/periodic_hex
$ vim Makefile
Modify the Makefile to use your compiler (this one is not smart like the Makefile in mpas/).
For example:
@@ -45,21 +75,25 @@
$ make
-Now work from the initial condition location:
-$ cd ~/mpas_initial/periodic_hex_500_500
-$ cp ~/mpas_ice/grid_gen/periodic_hex/namelist.input .
-$ ln -s ~/mpas_ice/grid_gen/periodic_hex/periodic_grid
+Now we will work from our 'grids' directory to actually create the grid:
+$ cd ~/mpas/grids/dome/
+Get the namelist file that will create the appropriately sized grid for the dome test case
+$ cp ~/mpas/land_ice_projects/test_cases/dome/namelist.input.periodic_hex ./namelist.input
+$ ln -s ~/mpas/grid_gen/periodic_hex/periodic_grid
+
+If you'd like, modify the namelist file:
$ vim namelist.input (or emacs namelist.input)
-modify as desired:
&periodic_grid
- nx = 500, # the number of columns
- ny = 500, # ...rows
- dc = 10000., # the characteristic size of a cell
- nVertLevels = 1, # the number of vertical levels in the grid
- nTracers = 1, # the number of tracers (temperature, etc)
+ nx = 30, # the number of columns
+ ny = 35, # ...rows
+ dc = 2000., # the characteristic size of a cell
+ nVertLevels = 9, # the number of vertical levels in the grid
+ nTracers = 1, # the number of tracers - this is not used by the land ice core (gets removed in a subsequent step), but periodic_hex requires a value
nproc = 2, 4, 8, # one entry each for the number of processors that should be supported for parallel runs, generates data partitioning in files graph.info.part.*
/
+
+Create the grid:
$ ./periodic_grid
Look for:
grid.nc
@@ -70,66 +104,81 @@
Next the default MPAS grid needs to be modified to include land ice variables. This is currently done with a python script.
The script is located here: land_ice_projects/grid_tools/add_land_ice_variables_to_mpas_grid.py
-Move the script to the directory that contains your newly generated grid file (grid.nc). Run the script with:
-./add_land_ice_variables_to_mpas_grid.py -f grid.nc
-It will create a new file called land_ice_grid.nc that contains the land ice variables.
-You can confirm this with ncdump -h land_ice_grid.nc. At the end of the variable list should be:
+Run the script with:
+python ~/mpas/land_ice_projects/grid_tools/add_land_ice_variables_to_mpas_grid.py
+(you can also copy it to the current directory and then run it)
+It will create a new file called land_ice_grid.nc that contains the land ice variables. (Note that the script will use grid.nc as the input file by default, but a different file name can be passed in as an argument.)
+You can confirm this worked with ncdump -h land_ice_grid.nc. At the end of the variable list should be:
double layerThicknessFractions(nVertLevels) ;
double thickness(Time, nCells) ;
double bedTopography(Time, nCells) ;
double beta(Time, nCells) ;
double normalVelocity(Time, nEdges, nVertLevels) ;
- double tracers(Time, nCells, nVertLevelsPlus2, nTracers) ;
+ double temperature(Time, nCells, nVertLevelsPlus2) ;
================
Setting up a Run:
+================
The following assumes the following locations:
-land_ice branch is in ~/mpas_ice (this should be the 'implement_core' project)
-initial conditions are stored in subdirectories in ~/mpas_initial
-runs are made from subdirectories in ~/mpas_runs
+land_ice branch is in ~/mpas/land_ice_projects (this should include MPAS as the 'implement_core' project)
+grids are stored in subdirectories in ~/mpas/grids
+runs are made from subdirectories in ~/mpas/runs
-make a directory for running the code
-$ mkdir ~/mpas_runs/periodic_hex_01
-$ cd ~/mpas_runs/periodic_hex_01
-$ ln -s ~/mpas_ice/mpas/land_ice_model.exe land_ice_model.exe
-$ cp ~/mpas_ice/mpas/namelist.input.land_ice namelist.input
-$ ln -s ~/mpas_initial/periodic_hex_500_500/land_ice_grid.nc grid.nc
+Move to the directory for running the code and gather needed files
+$ cd ~/mpas/runs/dome
+$ ln -s ~/mpas/land_ice_projects/implement_core/land_ice_model.exe
+$ cp namelist.input.land_ice_core namelist.input
+There should be no need to modify namelist.input as it is setup to run the dome test case.
+$ cp ~/mpas/grids/dome/land_ice_grid.nc .
+(The grid could also be symlinked if it is large, but in this case it is small.)
-There should be no need to modify namelist.input
+Now the dome initial conditions need to be added to the grid file. This is currently done with a python script:
+python setup_dome_initial_conditions.py
+(By default this script modifies land_ice_grid.nc, but a different file name can be specified as a command line argument.)
+You can check that the script worked with:
+ncdump -v thickness land_ice_grid.nc
+You should see a bunch of nonzero values for the thickness.
+if running on 1 processor:
+$ ./land_ice_model.exe
+
if running on 2 processors:
-$ ln -s ~/mpas_initial/periodic_hex_500_500/graph.info.part.2 graph.info.part.2
+$ ln -s ~/mpas/grids/dome/graph.info.part.2 graph.info.part.2
$ mpirun -np 2 land_ice_model.exe
-if running on 1 processor:
-$ ./land_ice_model.exe
+
Output:
Reading namelist.input
- Setting up land ice test case 1
- -- Evolution of an isothermal dome
Initial timestep 0000-01-01_00:00:00
Doing timestep 0000-01-01_00:01:00
timer_name total calls min max avg percent efficiency
- 0 total time 0.62200 1 0.62200 0.62200 0.62200
- 1 initialize 0.11700 1 0.11700 0.11700 0.11700 0.19 0.00
+ 0 total time 0.43400 1 0.43400 0.43400 0.43400
+ 1 initialize 0.03700 1 0.03700 0.03700 0.03700 0.09 0.00
1 time integration 0.00000 1 0.00000 0.00000 0.00000 0.00 0.00
-look for output.nc
+Now look for output.nc
+Currently, there is no call to a dycore (LifeV) enabled, so land_ice_model.exe simply spits out the initial conditions that it was fed. To check if it worked use one of the viz options below (or ncdump -v).
-
================
Examining Output
-Use paraview to visualize output.nc (this will have to be a separate tutorial).
+================
+There are a number of options for visualizing output:
+
+1. Some simple plots of the dome test case are generated with a python script:
+python visualize_dome.py
+It can take commandline arguments to visualize a different time step (default=the first) or file (default=output.nc) and to save the plots to files. Get details with: python visualize_dome.py -h
+
+2. Use paraview to visualize output.nc (this will have to be a separate tutorial).
However, paraview is limited to variables with dimensions that include nCells (or nVertices), nVertLevels. Few land ice variables meet that criterion. Hopefully this will be remedied in a future version of the paraview MPAS plugin.
-An alternative is to convert the output file to a regular grid that can be viewed (somwhat sloppily) in ncview (or similar tool). A script that does that conversion is here:
+3. An alternative is to convert the output file to a regular grid that can be viewed (somwhat sloppily) in ncview (or similar tool). A script that does that conversion is here:
land_ice_projects/grid_tools/convert_mpas_grid_to_regular_grid_netcdf.py
-For more rigorous examination of the output, python can be used. Python viz scripts are likely to be added to the test cases eventually.
+4. For more rigorous examination of the output, python or Matlab can be used.
</font>
</pre>