write_FVCOM_z0

 Dump spatially-variable or uniform bottom roughness (z0) to FVCOM forcing
 file.

 function write_FVCOM_z0(z0, filename, mytitle)

 DESCRIPTION:
    Generate a NetCDF file containing spatially variable z0 for FVCOM

 INPUT
   z0        = user defined roughness field (m)
               roughness is defined on the elements
               expect values between 3 10^-3 (gravel) and .2 10^-3 (i.e. 0.0002) for mud
   filename  = filename to dump to
   mytitle   = title of the case (set as global attribute)
   cbcmin    = minimum value of CBC (optional, defaults to 0.0018 if
               omitted).

 OUTPUT:
    netCDF file called `filename'

 EXAMPLE USAGE
    write_FVCOM_z0(z0field, 'tst_z0.nc', 'z0 tst domain')

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

 Revision history
    2012-06-15 Added support for native MATLAB NetCDF routines. Requires
    MATLAB 2010a or higher.
    2016-08-09 Added new variable (cbcmin) to support FVCOM version 4.
    Also tidied up the code a bit.

==============================================================================

0001 function write_FVCOM_z0(z0,filename,mytitle,cbcmin)
0002 % Dump spatially-variable or uniform bottom roughness (z0) to FVCOM forcing
0003 % file.
0004 %
0005 % function write_FVCOM_z0(z0, filename, mytitle)
0006 %
0007 % DESCRIPTION:
0008 %    Generate a NetCDF file containing spatially variable z0 for FVCOM
0009 %
0010 % INPUT
0011 %   z0        = user defined roughness field (m)
0012 %               roughness is defined on the elements
0013 %               expect values between 3 10^-3 (gravel) and .2 10^-3 (i.e. 0.0002) for mud
0014 %   filename  = filename to dump to
0015 %   mytitle   = title of the case (set as global attribute)
0016 %   cbcmin    = minimum value of CBC (optional, defaults to 0.0018 if
0017 %               omitted).
0018 %
0019 % OUTPUT:
0020 %    netCDF file called `filename'
0021 %
0022 % EXAMPLE USAGE
0023 %    write_FVCOM_z0(z0field, 'tst_z0.nc', 'z0 tst domain')
0024 %
0025 % Author(s):
0026 %    Geoff Cowles (University of Massachusetts Dartmouth)
0027 %    Pierre Cazenave (Plymouth Marine Laboratory)
0028 %
0029 % Revision history
0030 %    2012-06-15 Added support for native MATLAB NetCDF routines. Requires
0031 %    MATLAB 2010a or higher.
0032 %    2016-08-09 Added new variable (cbcmin) to support FVCOM version 4.
0033 %    Also tidied up the code a bit.
0034 %
0035 %==============================================================================
0036 
0037 [~, subname] = fileparts(mfilename('fullpath'));
0038 global ftbverbose;
0039 if ftbverbose
0040     fprintf('\nbegin : %s\n', subname);
0041 end
0042 
0043 %------------------------------------------------------------------------------
0044 % Parse input arguments
0045 %------------------------------------------------------------------------------
0046 if ~exist('z0', 'var')
0047     error('incorrect usage of write_FVCOM_z0, must provide z0 field')
0048 end
0049 if ~exist('filename', 'var')
0050     error('incorrect usage of write_FVCOM_z0, must provide filename')
0051 end
0052 if ~exist('mytitle', 'var')
0053     error('incorrect usage of write_FVCOM_z0, must provide title field')
0054 end
0055 
0056 % check dimensions
0057 nElems = numel(z0);
0058 if nElems == 0
0059     error('Number of elements in z0 is 0.')
0060 end
0061 
0062 % If we haven't been given a value of cbc min, set it to the example from
0063 % Jianzhong Ge.
0064 if nargin == 3
0065     cbcmin = repmat(0.0018, nElems, 1);
0066 end
0067 
0068 %------------------------------------------------------------------------------
0069 % Dump to variables to the netCDF file
0070 %------------------------------------------------------------------------------
0071 if ftbverbose
0072   fprintf('Dumping to z0 NetCDF file: %s\n', filename);
0073   fprintf('Size of z0 array: %i\n', nElems);
0074 end
0075 nc = netcdf.create(filename, 'clobber');
0076 
0077 netcdf.putAtt(nc, netcdf.getConstant('NC_GLOBAL'), 'title', mytitle)
0078 netcdf.putAtt(nc, netcdf.getConstant('NC_GLOBAL'), 'history', ...
0079     sprintf('File created with %s from the MATLAB fvcom-toolbox', subname))
0080 
0081 % dimensions
0082 nele_dimid = netcdf.defDim(nc, 'nele', nElems);
0083 
0084 % variables and attributes
0085 z0b_varid = netcdf.defVar(nc, 'z0b', 'NC_FLOAT', nele_dimid);
0086 netcdf.putAtt(nc, z0b_varid, 'long_name', 'bottom roughness');
0087 netcdf.putAtt(nc, z0b_varid, 'units', 'm');
0088 netcdf.putAtt(nc, z0b_varid, 'type', 'data');
0089 
0090 cbcmin_varid=netcdf.defVar(nc, 'cbcmin', 'NC_FLOAT', nele_dimid);
0091 netcdf.putAtt(nc, cbcmin_varid, 'long_name', 'bottom roughness minimum');
0092 netcdf.putAtt(nc, cbcmin_varid, 'units', 'None');
0093 netcdf.putAtt(nc, cbcmin_varid, 'type', 'data');
0094 
0095 % end definitions
0096 netcdf.endDef(nc);
0097 
0098 % write data
0099 netcdf.putVar(nc, z0b_varid, z0);
0100 netcdf.putVar(nc, cbcmin_varid, cbcmin);
0101 
0102 % close file
0103 netcdf.close(nc);
0104 
0105 if ftbverbose
0106   fprintf('end   : %s\n', subname)
0107 end