Annotation of /MITgcm_contrib/jmc_script/README

Some basic scripts are gather here.

a) the restart test: "2+2=4"

script: tst_2+2
- to use in a run dir. after a successful "testreport"
- input argument: '0','1','2','3','4' or 'All':
  proceed step by step or all steps at once
- tst_2+2 (no argument) -> print "usage"
- know problems: specific restart procedure (with fizhi pkg or offline pkg)
  not yet implemented

script: do_test_2+2
- call restart test "tst_2+2" multiple times, in every test experiment.
- needs to be in MITgcm/verification (with a copy of tst_2+2i script)
  and can only be used after a successful "testreport"
- do_test_2+2 -help -> print "usage"

NOTE: scripts "tst_2+2" & "do_test_2+2" have been moved (Dec 25, 2007)
 to: MITgcm/tools/

script: tst_2+2_cpl
 = version of tst_2+2 adapted for coupled set-up (e.g., verification/cpl_aim+ocn)

b) PBS-batch script that re-submit itself (loop).
script: runScript

- used (and tested) on myrinet-3 cluster.
- suffer from a lack of meaningful comments.
- not specially design to be general and obviously
  need to be modified/customized for each set-up.

c) A short script to split the ASCII Diagnostics-Stats output file
   into separated files (one per field) that are easy to read/load
   (e.g., in matlab, just use "load" command)
script: extract_StD
 no known dependency
+  A matlab script to load in 1 array all the separated files:
matlab-script: read_StD.m
 no known dependency
+  2 example scripts to make simple plots from Stat-Diags output:
matlab-script: grph_StD.m (uses read_StD.m)
matlab-script: plot_StD.m (uses read_StD.m, c_levs.m)

d) script: rn_pickup
- Rename 'pickup*.ckpt[A,B].*' files to 'pickup*.[10-digits-iter].*'
  with several selection options.
- rn_pickup (no argument) -> print "usage"

e) script: mk_mkfile
- run genmake2 with the same options as when "Makefile" was generated
 (needs an existing previous "Makefile") ; this replaces "make makefile".
 in addition, link *_mpi files from the MODS directory when -mpi was
 used to generate the previous Makefile.

f) script: derive_other_types
  from 1 src file, derive other type (R4,RS,RL,RS) version. For now, can
  only be applied to the 4 src files: "mdsio_pass_r{4,8}tor{l,s}.F"

g) script: mk_options_list
  generate list of CPP Options used in Fortran source files

h) script: comp_res
  to compare MONITOR output from 2 STDOUT files (outside of testreport).
  Note: use executable "cmpnum" compiled from tiny fortran code: cmpnum.f

i) script: mod
  to perform automatic substitution (useful to maintain src code) using
  command "sed" and set of rules from file (default rule file: "mod.sed")

----------------------------------------------------------------------
shell & matlab scripts to process MONITOR output from STDOUT files
 and make simple time-serie plots:
--------------------
a) shell script: select_MON
 get all MONITOR output from a single file and split into many
 single-variable output files (easier to load and plot)

b) shell scripts: do_extract_MON & extract_MON
 collect into a single file all MONITOR output from consecutive
 STDOUT output files (from a single experiment with one of more restart)

c) matlab script: grph_MON.m
 plot MONITOR time-serie of one or more experiment (with lines of different
 color). Note: experiment with larger number of records needs to come first.
Uses: read_MON.m
 to load-in single-variable output files (--> many files per experiment)
and/or: readnc_MON.m
 to load-in netcdf (MNC) MONITOR output files
1	jmc	1.6	Some basic scripts are gather here.
2
3	jmc	1.14	a) the restart test: "2+2=4"
4	jmc	1.6
5			script: tst_2+2
6			- to use in a run dir. after a successful "testreport"
7			- input argument: '0','1','2','3','4' or 'All':
8			proceed step by step or all steps at once
9			- tst_2+2 (no argument) -> print "usage"
10			- know problems: specific restart procedure (with fizhi pkg or offline pkg)
11			not yet implemented
12
13			script: do_test_2+2
14			- call restart test "tst_2+2" multiple times, in every test experiment.
15			- needs to be in MITgcm/verification (with a copy of tst_2+2i script)
16			and can only be used after a successful "testreport"
17			- do_test_2+2 -help -> print "usage"
18	jmc	1.1
19	jmc	1.11	NOTE: scripts "tst_2+2" & "do_test_2+2" have been moved (Dec 25, 2007)
20	jmc	1.17	to: MITgcm/tools/
21	jmc	1.7
22	jmc	1.5	script: tst_2+2_cpl
23	jmc	1.20	= version of tst_2+2 adapted for coupled set-up (e.g., verification/cpl_aim+ocn)
24	jmc	1.5
25	jmc	1.1	b) PBS-batch script that re-submit itself (loop).
26			script: runScript
27
28	jmc	1.6	- used (and tested) on myrinet-3 cluster.
29			- suffer from a lack of meaningful comments.
30			- not specially design to be general and obviously
31			need to be modified/customized for each set-up.
32
33	jmc	1.3	c) A short script to split the ASCII Diagnostics-Stats output file
34	jmc	1.6	into separated files (one per field) that are easy to read/load
35	jmc	1.3	(e.g., in matlab, just use "load" command)
36			script: extract_StD
37			no known dependency
38	jmc	1.7	+ A matlab script to load in 1 array all the separated files:
39			matlab-script: read_StD.m
40	jmc	1.4	no known dependency
41	jmc	1.7	+ 2 example scripts to make simple plots from Stat-Diags output:
42			matlab-script: grph_StD.m (uses read_StD.m)
43	jmc	1.8	matlab-script: plot_StD.m (uses read_StD.m, c_levs.m)
44	jmc	1.3
45	jmc	1.6	d) script: rn_pickup
46			- Rename 'pickup.ckpt[A,B].' files to 'pickup.[10-digits-iter].'
47	jmc	1.13	with several selection options.
48	jmc	1.6	- rn_pickup (no argument) -> print "usage"
49	jmc	1.9
50			e) script: mk_mkfile
51			- run genmake2 with the same options as when "Makefile" was generated
52			(needs an existing previous "Makefile") ; this replaces "make makefile".
53	jmc	1.12	in addition, link *_mpi files from the MODS directory when -mpi was
54	jmc	1.9	used to generate the previous Makefile.
55	jmc	1.10
56			f) script: derive_other_types
57	jmc	1.12	from 1 src file, derive other type (R4,RS,RL,RS) version. For now, can
58	jmc	1.10	only be applied to the 4 src files: "mdsio_pass_r{4,8}tor{l,s}.F"
59	jmc	1.15
60			g) script: mk_options_list
61	jmc	1.16	generate list of CPP Options used in Fortran source files
62	jmc	1.18
63	jmc	1.20	h) script: comp_res
64			to compare MONITOR output from 2 STDOUT files (outside of testreport).
65			Note: use executable "cmpnum" compiled from tiny fortran code: cmpnum.f
66
67	jmc	1.21	i) script: mod
68			to perform automatic substitution (useful to maintain src code) using
69			command "sed" and set of rules from file (default rule file: "mod.sed")
70
71	jmc	1.19	----------------------------------------------------------------------
72			shell & matlab scripts to process MONITOR output from STDOUT files
73			and make simple time-serie plots:
74			--------------------
75			a) shell script: select_MON
76			get all MONITOR output from a single file and split into many
77			single-variable output files (easier to load and plot)
78
79			b) shell scripts: do_extract_MON & extract_MON
80			collect into a single file all MONITOR output from consecutive
81			STDOUT output files (from a single experiment with one of more restart)
82
83			c) matlab script: grph_MON.m
84			plot MONITOR time-serie of one or more experiment (with lines of different
85			color). Note: experiment with larger number of records needs to come first.
86			Uses: read_MON.m
87			to load-in single-variable output files (--> many files per experiment)
88			and/or: readnc_MON.m
89			to load-in netcdf (MNC) MONITOR output files