Updated README to contain more information on how to run the

script. Minor cleanup in build.sh. Added two octave files to
visualize results.

README.md

@@ -2,33 +2,80 @@
 
 This example uses the MITgcm numerical model.
 
+## Prerequisites
+
+In this example we rely on various code sources and tools. Please
+note not all of these items are necessary to try out all the different
+options.
+
+Resources:
+ * docker with docker-compose
+ * octave (you may be able to use mathlab, but we tested this with
+   octave)
+ * MITgcm `https://github.com/MITgcm/MITgcm/tree/master`
+ * When building locally, you will need to install several gnu tools
+   and compilers
+ * mencoder to generate animations
+
 ## Getting started
 
-### With Docker
-Folder: /docker
+## Using Docker wiht Docker-Compose
+
+Folder: `/docker`
 
 Make sure you have Docker installed. 
 
-Before deploying the docker container make sure to have valid data in the data folder. Use your own code/data or use code from the verification folder in the MITgcm git repository for testing purposes (e.g. https://github.com/MITgcm/MITgcm/tree/master/verification/tutorial_barotropic_gyre). 
+Before deploying the docker container make sure to have valid data
+in the data folder. Use your own code/data or use code from the
+verification folder in the MITgcm git repository for testing purposes.
 
-*  Deploy the container by using docker-compose 
+You find all examples in 
+`https://github.com/MITgcm/MITgcm/tree/master/verification`
 
+As a first example you may try `tutorial_barotropic_gyre`
+
+You have to copy the content of the example directory into the directory
+your docker-compose or docker setup uses as data folder. 
+
+To avoid issues with running the container, for example when you changed
+configuration files, you must run
 ```
-docker-compose up -d
+docker-compose build
 ```
 
+Deploy the container by using docker-compose
+```
+docker-compose up
+```
+
+After running the model free everything with
+```
+docker-compose down
+```
+
+## Using Docker
 
-*  or using plain docker by runnning
+Using plain docker you can follow the above docker-compose instructions.
+However, instead of running `docker-compose`, you can build the image
+with
 
 ```
 docker image build -t case-study-mitgcm .
+```
+
+And subsequently run the image with
+```
 docker run -v $(pwd)/../data/:/data --name case-study-mitgcm case-study-mitgcm
 ```
 
+When the model finished execution, you must remove the container.
+Please consult the docker documentation for details.
+
 ### Without Docker
 Folder: /bare
 
-You can use build.sh to run code on your machine, use the -x flag to use example code
+You can use build.sh to run code on your machine, use the -x flag to use
+example code
 
 e.g. ./build.sh -x -i
 
@@ -38,6 +85,51 @@ OPTIONS:
  -i		install required packages
  -k		keep binary files
  -a		architecture [amd64(default), ia32]
- -x		use example data (WARNING: deletes the content of the data folder and replaces it with example code)
+ -x		use example data (WARNING: deletes the content of the
+   		data folder and replaces it with example code)
  -h		help 
-```
\ No newline at end of file
+```
+
+### Running a complete example
+
+Assuming you were successful in running a setup successful, you might
+want to extend on that and try a more elaborate run.
+
+1. Change in `/data/input` the `data` file. Here three options are
+   relevant
+   - `dumpFreq` (15552000.0) specifies with which frequence data is
+      written out. This does not directly correlate with the steps
+      value. 
+   - `nTimeSteps` specifies how many steps the simulation should run.
+      The example uses 10 steps in the beginning. 77760 ist for longer
+      runs.
+   - `monitorFreq` speficies in which intervals logging information is
+      written.
+1. Run the experiment. This may produce, depending on your settings, a
+   lot of output in `/data/run/`
+1. After the run copy the files `/plot-result.m` and 
+   `/prepare-animation.m` to the `/data/run` directory. 
+1. Switch to that directory `/data/run`
+1. Run `octave --gui` 
+1. Load the `plot-result.m` file, adjust the `addPath` to the location
+   of the MITgcm checkout, as it contains necessary tools and scripts.
+1. Finally execute the script with F5. This should produce a suitable
+   graphic. Depending on your nTimeSteps setting, you have to select
+   different values for the `Eta` variable. 0 and the `nTimeSteps`
+   value are usual good candidates. For further values, you can consult
+   the `/data/run` directory. Look for files starting with `T.` followed
+   by a number. Each of these numbers can be used as value in `Eta`.
+   
+In case you want to produce an animation, you can use the 
+`prepare-animation.m` script. It will produce multiple files called
+`out????.png`. Depending on your setup, you have to adjust the number
+of frames to produce and the filename/number step value.
+
+Video encoding can be done with `mencoder`
+
+```
+mencoder mf://out????.png -mf fps=2:type=png -ovc lavc \
+    -lavcopts vcodec=mpeg4:mbd=2:trell -oac copy -o output.avi
+```
+
+

docker/build/build.sh

@@ -9,4 +9,7 @@ make
 cd /data/run
 ln -s ../input/* .
 ln -s ../build/mitgcmuv .
+
 ./mitgcmuv > output.txt
+
+# end

plot-result.m

+# Adjust the following path
+addpath /home/reiner/Projects/OceanDSL/case-studies/MITgcm/utils/matlab/
+
+XC=rdmds('XC'); YC=rdmds('YC');
+# Select a proper value. The start value is 0
+Eta=rdmds('Eta',0);
+
+contourf(XC/1000,YC/1000,Eta,[-.04:.01:.04]);
+colorbar;
+colormap((flipud(hot)));
+set(gca,'XLim',[0 1200]);
+set(gca,'YLim',[0 1200])

prepare-animation.m

+# Adjust the following path
+addpath /home/reiner/Projects/OceanDSL/case-studies/MITgcm/utils/matlab/
+XC=rdmds('XC'); YC=rdmds('YC');
+
+# The number of frames depend on your setup
+for m = 0:60
+  out=["out" num2str(m, "%04d") ".png"];
+  # The multiplier depends on your setup
+  Eta=rdmds('Eta',1296*m);
+
+  hf = figure ("visible", "off");
+  contourf(XC/1000,YC/1000,Eta,[-.04:.01:.04]);
+  colorbar;
+  colormap((flipud(hot)));
+  set(gca,'XLim',[0 1200]);
+  set(gca,'YLim',[0 1200]);
+  print(hf, out, "-dpng "); 
+endfor