forked from CVMix/CVMix-src
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
229 lines (179 loc) · 10.9 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
Last update: July 23, 2014
--------------------------
CVMix is a transparent, robust, flexible, and well-documented open source
Fortran library for parameterizing ocean vertical mixing processes. It contains
the following first-order closures:
1. Background [time-independent] mixing, including the Bryan and Lewis (1979)
parameterization
2. Convective mixing (both density-based and the Brunt-Vaisala scheme)
3. Double diffusion mixing, as described in Large, et al. (1994) and modified
according to Danabasoglu, et al. (2006)
4. The KPP boundary layer mixing scheme from Large, et al. 1994
5. Shear [Richardson number-based] mixing, including both Pacanowski and
Philander (1981) and the shear mixing used in Large, et al. (1994)
6. Tidal mixing, which currently only offers the method described in Simmons,
et al. (2004)
The library can be built on its own and linked in to a general ocean
circulation model. Additionally, CVMix is packaged with a very light-weight
stand-alone driver that offers the ability to run quick (typically single
column) tests to ensure everything is working properly.
Community input is both welcomed and encouraged. Documentation online at
https://github.com/CVMix/CVMix-src/wiki
goes into details about how to contribute, but basically we ask three things:
1. Follow the CVMix coding policies to ensure all modules use the same
formatting and all documentation is consistent.
2. Run the provided suite of regression tests to ensure you did not
accidentally change something in another module.
3. Provide a stand-alone driver for your method so that others can ensure they
do not accidentally change something in your module.
INSTALLATION NOTES
------------------
The src directory contains a Makefile and a simple 'make' should be sufficient
to build the standalone driver. The first time you build, the 'cvmix_setup'
utility will run and prompt you for compiler and netcdf information - it will
only run once, and the info is saved in bld/.CVMix_env.
To build with netcdf, run 'make netcdf'.
The default executable is $CVMix/bin/cvmix, but it can be overwritten with
'make EXE=[executable]'.
To build just the library, run the following (from src/shared):
$ make FC=[compiler] \
FCFLAGS=[compiler flags] \
INC_DIR=[place to save .mod files] \
LIB_DIR=[place to create libcvmix.a] \
OBJ_DIR=[place to save .o files]
And then use -I$(INC_DIR) -L$(LIB_DIR) -lcvmix when you build software using
the CVMix library.
DIRECTORY STRUCTURE
-------------------
bin/ -- Default location for the cvmix executable.
bld/ -- Contains auxiliary files needed by the build system. CompileFlags.mak
has default compile flags for 5 different compilers -- gfortran,
pgf90, ifort, xlf90, and nagfor, as well as ftn (the Cray wrapper for
pgf90). At this time, no other compilers are supported on Cray systems.
cvmix_setup is a python script that saves information about what
compiler to use and where netCDF is installed in .CVMix_env.
bld/obj -- Where .o and .mod files for the stand-alone drivers are stored.
doc/ -- Contains documentation. At this point, it only has a PDF of the latest
protex in-code notes and a script to generate said PDF.
git_config/ -- Contains files for recommended git setup of repository. At this
time, only file is git_commit_template.txt, and running
$ git config commit.template git_config/git_commit_template.txt
Will add comments to default commit log to help organize the
commit log.
include/ -- Default location for the .o and .mod files that need to be included
with libcvmix.a.
inputdata/ -- The stand-alone tidal driver requires some large netCDF files to
provide initial conditions and grid information. These files are
downloaded the first time you run Simmons-test.sh (due to the
file size, they are not kept in the same repository as the source
code).
lib/ -- Default location for libcvmix.a, the library that can be linked in
to an ocean model.
reg_tests/ -- Contains functional tests for all mixing methods except
convective. Each test directory contains a shell script that
calls functions defined in common/ to determine what settings to
use for the test. All scripts have a "-h" (or "--help") flag to
print usage options and a "-nc" (or "--netcdf") flag to turn on
netCDF output. Note that the "-nc" is required for the tidal
mixing test because it reads in netcdf data.
All directories contain one (or many) NCL script(s) to produce a
plot from the output; by default these plots are in the PDF
format.
reg_tests/Bryan-Lewis/ -- location of the Bryan-Lewis background mixing test
$ ./BL_test.sh
* plot_diff_coeffs.ncl -- makes a plot with depth on the y-axis
and diffusivity (for both columns) on the x-axis.
reg_tests/double_diff/ -- location of the double diffusion test
$ ./double_diff-test.sh
* plot_diff_coeffs.ncl -- makes two plots
1. ddiff-diffuse: shows the interior diffusivity for potential
temperature (normalized by the molecular diffusivity)
in the diffusive convection regime plotted against the
inverse stratification parameter.
2. ddiff-salt: shows the interior diffusivity for salinity
(normalized by its maximum) in the salt fingering regime
plotted against the stratification parameter.
Note: these plots are comparable to the two plots in Figure 4
of Large et al.
reg_tests/kpp/ -- location of the KPP mixing test
$ ./kpp-test.sh
* compare_interpolation_methods.ncl -- makes three plots
1. bldepth: compares different interpolation techniques
(linear, quadratic, and cubic) when it comes to estimating
the boundary layer depth based on the depth of the mix
layer (analytically, HBL = HMIX+2)
2. bldepth_error: the error of the three different
interpolation techniques compared to the analytic solution
3. single_col22.05.pdf: the estimated boundary layer depth
using each interpolation method when HMIX=22.05 (shows
bulk Richardson number on x-axis, HBL is point where bulk
Richardson = 0.3)
* plot_bulk_Rich.ncl -- makes the KPP-bulk_Rich plot, which
shows buoyancy, zonal wind, and bulk Richardson values at
each layer center. Compare to Figure C1 of Large et al.
* plot_flux_profiles.ncl -- makes the KPP-flux_profile plot,
which shows the non-dimensional flux profiles for momentum
and scalars as a function of the stability parameter. Compare
to Figure B1 of Large et al.
reg_tests/shear-KPP/ -- location of the shear mixing test
$ ./Large_test.sh
* plot_diff_coeffs.ncl -- makes a plot with the local gradient
Richardson number on the x-axis and the temperature
diffusivity coefficient (normalized by its maximum) on the
y-axis. Compare to Figure 3 of Large et al.
reg_tests/tidal-Simmons/ -- location of the tidal mixing test
$ ./Simmons_test.sh -nc
* plot_diff_coeffs.ncl -- shows how the tidal diffusivity
changes over depth for a specified column (column is set in
the Simmons_nml namelist)
* plot_tidal_energy_map.ncl -- produces a global contour map
for the tidal energy flux (taken from the inputdata/
directory)
reg_tests/common/ -- a set of bash shell scripts that are used by the
individual scripts mentioned above to reduce the amount
of duplicate code from test to test.
src/ -- Contains the source code, organized as follows. The top directory
contains modules needed by the stand-alone driver (output, for example)
as well as the driver routine itself. Also contains the Makefile used
to build the cvmix executable.
src/drivers/ -- Subroutines called by the driver (one per test).
src/shared/ -- Where all the modules that are needed to use CVMix with an
outside model are stored. Also contains the Makefile used to
build the libcvmix.a library.
templates/ -- Contains a template F90 file for adding a new mixing module to
the src/shared/ directory. See the CVMix webpage for directions
for requesting to have your module included in the main CVMix
repository.
ABOUT THE STAND-ALONE CVMIX DRIVER
----------------------------------
There are five options for the stand-alone driver which can be used to test two
different mixing methods. The first test is to output Bryan-Lewis mixing on two
columns (a high latitude column and a tropical column), and output the tracer
diffusivity coefficients at each level. This tests both the Bryan-Lewis portion
of the background mixing module and the ability for the CVMix data type (used
for the "wrapped" interface of all of the coefficient computation routines) to
use pointers or memory copies to store column data.
The second driver tests double diffusion mixing by setting up two columns, one
in the salt fingering regime and one in the diffusive convective instability
regime. In each case, the stratification parameter is set and then the
temperature and salinity diffusivity coefficients are computed.
The third driver runs a set of 6 tests for KPP boundary layer mixing:
1. Compute the boundary layer depth for a column with a given HMIX (HBLT
should = |HMIX|+2)
2. Compute shape function coefficients with G(0) = G(1) = G'(1) = 0 and G'(0)
= 1; should be sigma*(sigma-1)^2
3. Compute nondimensional flux profile over range of stability parameter
values
4. Compute diffusivity in the boundary layer when boundary layer is (a) below
cell center and (b) above cell center
5. Compute bulk Richardson number from buoyancy and zonal wind data
6. Compute velocity scales (a) when surface buoyancy flux is 0 and friction
is positive; and (b) when surface buoyancy flux is negative and friction
velocity is 0.
The fourth driver sets up a single column using the shear mixing formula found in
the Large, et al. KPP paper. For this test, each level is a different local
gradient Richardson number rather than a different depth to show how tracer
diffusivity varies with different Richardson numbers.
The fifth driver reads in tidal energy flux and buoyancy frequency data from an
input data set and computes diffusivities in a column based on these physical
values.