sigma_tanh

 Generate a tanh sigma coordinate distribution.

 Mobj = sigma_tanh(nlev, dl, du, Mobj)

 DESCRIPTION:
   Generate a tanh vertical sigma coordinate distribution.

 INPUT:
   nlev:       Number of sigma levels (layers + 1)
   dl:         The lower depth boundary from the bottom, down to which the
               coordinates are parallel with uniform thickness.
   du:         The upper depth boundary from the surface, up to which the
               coordinates are parallel with uniform thickness.
   Mobj:       [optional] Mesh object file
   sigma_file: [optional] File to which to save the sigma distribution.

 OUTPUT:
   Mobj.sigma:     Hyperbolic tangent vertical sigma coordinate distribution.
   Mobj.sig...     All the sigma layers variables such as siglev, siglevz,
                   siglayz, etc.

 EXAMPLE USAGE:
   Mobj = read_sigma(nlev, dl, du, Mobj)

 Author(s):
   Geoff Cowles (University of Massachusetts Dartmouth)
   Pierre Cazenave (Plymouth Marine Laboratory)
   Ricardo Torres (Plymouth Marine Laboratory)

 Revision history
   2013-04-23 Added help on the function and reformatted the code.
   2018-09-14 Added option to add the sigma data to a mesh object.

0001 function Mobj = sigma_tanh(nlev,dl,du,Mobj,sigma_file)
0002 % Generate a tanh sigma coordinate distribution.
0003 %
0004 % Mobj = sigma_tanh(nlev, dl, du, Mobj)
0005 %
0006 % DESCRIPTION:
0007 %   Generate a tanh vertical sigma coordinate distribution.
0008 %
0009 % INPUT:
0010 %   nlev:       Number of sigma levels (layers + 1)
0011 %   dl:         The lower depth boundary from the bottom, down to which the
0012 %               coordinates are parallel with uniform thickness.
0013 %   du:         The upper depth boundary from the surface, up to which the
0014 %               coordinates are parallel with uniform thickness.
0015 %   Mobj:       [optional] Mesh object file
0016 %   sigma_file: [optional] File to which to save the sigma distribution.
0017 %
0018 % OUTPUT:
0019 %   Mobj.sigma:     Hyperbolic tangent vertical sigma coordinate distribution.
0020 %   Mobj.sig...     All the sigma layers variables such as siglev, siglevz,
0021 %                   siglayz, etc.
0022 %
0023 % EXAMPLE USAGE:
0024 %   Mobj = read_sigma(nlev, dl, du, Mobj)
0025 %
0026 % Author(s):
0027 %   Geoff Cowles (University of Massachusetts Dartmouth)
0028 %   Pierre Cazenave (Plymouth Marine Laboratory)
0029 %   Ricardo Torres (Plymouth Marine Laboratory)
0030 %
0031 % Revision history
0032 %   2013-04-23 Added help on the function and reformatted the code.
0033 %   2018-09-14 Added option to add the sigma data to a mesh object.
0034 
0035 dist = zeros(1, nlev);
0036 
0037 for k = 1:nlev-1
0038     x1 = dl+du;
0039     x1 = x1*(nlev-1-k)/(nlev-1);
0040     x1 = x1-dl;
0041     x1 = tanh(x1);
0042     x2 = tanh(dl);
0043     x3 = x2+tanh(du);
0044     dist(k+1) = (x1+x2)/x3-1.0;
0045 end
0046 if nargin >= 4
0047     conf.nlev = nlev;
0048     Mobj.sigma = dist;
0049     Mobj.siglev = zeros(Mobj.nVerts,conf.nlev);
0050     Mobj.siglevc = zeros(Mobj.nElems,conf.nlev);
0051     Mobj.siglayc = zeros(Mobj.nElems,conf.nlev-1);
0052     Mobj.siglev = repmat(Mobj.sigma,Mobj.nVerts,1);
0053     Mobj.siglay = Mobj.siglev(:,1:end-1) + (diff(Mobj.siglev,1,2)/2);
0054     for zz = 1:conf.nlev-1
0055         Mobj.siglevc(:, zz) = nodes2elems(Mobj.siglev(:, zz), Mobj);
0056         Mobj.siglayc(:, zz) = nodes2elems(Mobj.siglay(:, zz), Mobj);
0057     end
0058     % An extra level compared with layers.
0059     Mobj.siglevc(:, zz + 1) = nodes2elems(Mobj.siglev(:, zz + 1), Mobj);
0060 
0061     % Finally, make some [depth, sigma] arrays.
0062     Mobj.siglevz = repmat(Mobj.h, 1, conf.nlev) .* Mobj.siglev;
0063     Mobj.siglayz = repmat(Mobj.h, 1, conf.nlev-1) .* Mobj.siglay;
0064     if isfield(Mobj, 'hc')
0065         Mobj.siglevzc = repmat(Mobj.hc, 1, conf.nlev) .* Mobj.siglevc;
0066         Mobj.siglayzc= repmat(Mobj.hc, 1, conf.nlev-1) .* Mobj.siglayc;
0067     end
0068 else
0069     Mobj = dist;
0070 end
0071 % generate sigma file
0072 % Save to the given file name.
0073 if nargin==5
0074     fout = fopen(sigma_file, 'wt');
0075     assert(fout >= 0, 'Error opening sigma file: %s', sigma_file)
0076     fprintf(fout, 'NUMBER OF SIGMA LEVELS = %d\n', nlev);
0077     fprintf(fout, 'SIGMA COORDINATE TYPE = TANH\n');
0078     fprintf(fout, 'DU = %4.1f\n', du);
0079     fprintf(fout, 'DL = %4.1f\n', dl);
0080     fprintf(fout,'\n');
0081     fclose(fout);
0082 end
0083