write_FVCOM_river

 Write FVCOM 3.x NetCDF river file

 function write_FVCOM_river(RiverFile,RiverName,time,flux,temp,salt,RiverInfo1,RiverInfo2)

 DESCRIPTION:
    Write river flux, temperature, and salinity to an FVCOM river file.
    Flux, temperature and salinity must be calculated prior to being given
    here as the raw values in the arrays are simply written out as is to
    the NetCDF file.

 INPUT
    RiverFile  : FVCOM 3.x netCDF river forcing file
    RiverName  : Names of the rivers
    time       : Time array in Modified Julian Days
    flux       : Total river flux in m^{3}/s ([time, nRivernodes])
    temp       : Temperature in Celsius ([time, nRivernodes])
    salt       : Salinity in PSU ([time, nRivernodes])
    RiverInfo1 : Global attribute title of file
    RiverInfo2 : Global attribute info of file

 OUTPUT:
    FVCOM NetCDF river file with flux, temperature and salinity.

 EXAMPLE USAGE
    write_FVCOM_river('tst_riv.nc', {'Penobscot'}, time, flux, temp, ...
         salt, 'Penobscot Flux', 'source: USGS')

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

 Revision history
   2013-03-21 Modified to take a list of river nodes rather than a single
   river spread over multiple nodes. This means you have to scale your
   inputs prior to using this function. This also means I have broken
   backwards compatibility with the old way of doing it (i.e. this
   function previously wrote only a single river's data but spread over a
   number of nodes). I removed the sediment stuff as the manual makes no
   mention of this in the river input file. Also added support for writing
   to NetCDF using MATLAB's native tools.
   2013-03-21 Transpose the river data arrays to the correct shape for the
   NetCDF file.
   2016-03-02 Minor changes to the help.

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

0001 function write_FVCOM_river(RiverFile,RiverName,time,flux,temp,salt,RiverInfo1,RiverInfo2)
0002 % Write FVCOM 3.x NetCDF river file
0003 %
0004 % function write_FVCOM_river(RiverFile,RiverName,time,flux,temp,salt,RiverInfo1,RiverInfo2)
0005 %
0006 % DESCRIPTION:
0007 %    Write river flux, temperature, and salinity to an FVCOM river file.
0008 %    Flux, temperature and salinity must be calculated prior to being given
0009 %    here as the raw values in the arrays are simply written out as is to
0010 %    the NetCDF file.
0011 %
0012 % INPUT
0013 %    RiverFile  : FVCOM 3.x netCDF river forcing file
0014 %    RiverName  : Names of the rivers
0015 %    time       : Time array in Modified Julian Days
0016 %    flux       : Total river flux in m^{3}/s ([time, nRivernodes])
0017 %    temp       : Temperature in Celsius ([time, nRivernodes])
0018 %    salt       : Salinity in PSU ([time, nRivernodes])
0019 %    RiverInfo1 : Global attribute title of file
0020 %    RiverInfo2 : Global attribute info of file
0021 %
0022 % OUTPUT:
0023 %    FVCOM NetCDF river file with flux, temperature and salinity.
0024 %
0025 % EXAMPLE USAGE
0026 %    write_FVCOM_river('tst_riv.nc', {'Penobscot'}, time, flux, temp, ...
0027 %         salt, 'Penobscot Flux', 'source: USGS')
0028 %
0029 % Author(s):
0030 %    Geoff Cowles (University of Massachusetts Dartmouth)
0031 %    Pierre Cazenave (Plymouth Marine Laboratory)
0032 %
0033 % Revision history
0034 %   2013-03-21 Modified to take a list of river nodes rather than a single
0035 %   river spread over multiple nodes. This means you have to scale your
0036 %   inputs prior to using this function. This also means I have broken
0037 %   backwards compatibility with the old way of doing it (i.e. this
0038 %   function previously wrote only a single river's data but spread over a
0039 %   number of nodes). I removed the sediment stuff as the manual makes no
0040 %   mention of this in the river input file. Also added support for writing
0041 %   to NetCDF using MATLAB's native tools.
0042 %   2013-03-21 Transpose the river data arrays to the correct shape for the
0043 %   NetCDF file.
0044 %   2016-03-02 Minor changes to the help.
0045 %
0046 %==========================================================================
0047 
0048 subname = 'write_FVCOM_river';
0049 
0050 global ftbverbose
0051 if ftbverbose
0052     fprintf('\nbegin : %s\n', subname)
0053 end
0054 
0055 [nTimes, nRivnodes] = size(flux);
0056 if ftbverbose
0057     fprintf('# of river nodes: %d\n', nRivnodes);
0058     fprintf('# of time frames: %d\n', nTimes);
0059 end
0060 
0061 [year1, month1, day1, ~, ~, ~] = mjulian2greg(time(1));
0062 [year2, month2, day2, ~, ~, ~] = mjulian2greg(time(end));
0063 if ftbverbose
0064     fprintf('time series begins at:\t%04d %02d %02d\n', year1, month1, day1);
0065     fprintf('time series ends at:\t%04d %02d %02d\n', year2, month2, day2);
0066 end
0067 clear year? month? day?
0068 
0069 %--------------------------------------------------------------------------
0070 % dump to netcdf file
0071 %--------------------------------------------------------------------------
0072 
0073 % river node forcing
0074 nc = netcdf.create(RiverFile, 'clobber');
0075 
0076 % global variables
0077 netcdf.putAtt(nc, netcdf.getConstant('NC_GLOBAL'), 'type', 'FVCOM RIVER FORCING FILE')
0078 netcdf.putAtt(nc, netcdf.getConstant('NC_GLOBAL'), 'title', RiverInfo1)
0079 netcdf.putAtt(nc, netcdf.getConstant('NC_GLOBAL'), 'info', RiverInfo2)
0080 netcdf.putAtt(nc, netcdf.getConstant('NC_GLOBAL'), 'history', sprintf('File created using %s from the MATLAB fvcom-toolbox', subname))
0081 
0082 % dimensions
0083 namelen_dimid = netcdf.defDim(nc, 'namelen', 80);
0084 rivers_dimid = netcdf.defDim(nc, 'rivers', nRivnodes);
0085 time_dimid = netcdf.defDim(nc, 'time', netcdf.getConstant('NC_UNLIMITED'));
0086 date_str_len_dimid = netcdf.defDim(nc, 'DateStrLen', 26);
0087 
0088 % variables
0089 river_names_varid = netcdf.defVar(nc, 'river_names', 'NC_CHAR', [namelen_dimid, rivers_dimid]);
0090 
0091 time_varid = netcdf.defVar(nc, 'time', 'NC_FLOAT', time_dimid);
0092 netcdf.putAtt(nc, time_varid, 'long_name', 'time');
0093 netcdf.putAtt(nc, time_varid, 'units', 'days since 1858-11-17 00:00:00');
0094 netcdf.putAtt(nc, time_varid, 'format', 'modified julian day (MJD)');
0095 netcdf.putAtt(nc, time_varid, 'time_zone', 'UTC');
0096 
0097 itime_varid = netcdf.defVar(nc, 'Itime', 'NC_INT', time_dimid);
0098 netcdf.putAtt(nc, itime_varid, 'units', 'days since 1858-11-17 00:00:00');
0099 netcdf.putAtt(nc, itime_varid, 'format', 'modified julian day (MJD)');
0100 netcdf.putAtt(nc, itime_varid, 'time_zone', 'UTC');
0101 
0102 itime2_varid = netcdf.defVar(nc, 'Itime2', 'NC_INT', time_dimid);
0103 netcdf.putAtt(nc, itime2_varid, 'units', 'msec since 00:00:00');
0104 netcdf.putAtt(nc, itime2_varid, 'time_zone', 'UTC');
0105 
0106 times_varid = netcdf.defVar(nc,'Times','NC_CHAR',[date_str_len_dimid, time_dimid]);
0107 netcdf.putAtt(nc, times_varid, 'time_zone','UTC');
0108 
0109 river_flux_varid = netcdf.defVar(nc, 'river_flux', 'NC_FLOAT', [rivers_dimid, time_dimid]);
0110 netcdf.putAtt(nc, river_flux_varid, 'long_name', 'river runoff volume flux');
0111 netcdf.putAtt(nc, river_flux_varid, 'units', 'm^3s^-1');
0112 
0113 river_temp_varid = netcdf.defVar(nc, 'river_temp', 'NC_FLOAT', [rivers_dimid, time_dimid]);
0114 netcdf.putAtt(nc, river_temp_varid, 'long_name', 'river runoff temperature');
0115 netcdf.putAtt(nc, river_temp_varid, 'units', 'Celsius');
0116 
0117 river_salt_varid = netcdf.defVar(nc, 'river_salt', 'NC_FLOAT', [rivers_dimid, time_dimid]);
0118 netcdf.putAtt(nc, river_salt_varid, 'long_name', 'river runoff salinity');
0119 netcdf.putAtt(nc, river_salt_varid, 'units', 'PSU');
0120 
0121 % end definitions
0122 netcdf.endDef(nc);
0123 
0124 % river names (must be 80 character strings)
0125 rString = char();
0126 for i = 1:nRivnodes
0127     % Left-aligned 80 character string.
0128     rString = [rString, sprintf('%-80s', RiverName{i})];
0129 end
0130 netcdf.putVar(nc, river_names_varid, rString);
0131 
0132 % dump dynamic data
0133 netcdf.putVar(nc, time_varid, 0, nTimes, time);
0134 netcdf.putVar(nc, itime_varid, 0, nTimes, floor(time));
0135 netcdf.putVar(nc, itime2_varid, 0, nTimes, mod(time, 1)*24*3600*1000);
0136 netcdf.putVar(nc, river_flux_varid, flux');
0137 netcdf.putVar(nc, river_temp_varid, temp');
0138 netcdf.putVar(nc, river_salt_varid, salt');
0139 
0140 % build the time string and output to NetCDF.
0141 nStringOut = char();
0142 [nYr, nMon, nDay, nHour, nMin, nSec] = mjulian2greg(time);
0143 for tt = 1:nTimes
0144     nDate = [nYr(tt), nMon(tt), nDay(tt), nHour(tt), nMin(tt), nSec(tt)];
0145     nStringOut = [nStringOut, sprintf('%04i/%02i/%02i %02i:%02i:%02i       ', nDate)];
0146 end
0147 netcdf.putVar(nc, times_varid, nStringOut);
0148 
0149 netcdf.close(nc);
0150 
0151 if ftbverbose
0152     fprintf('end   : %s\n', subname)
0153 end
0154