Description of write_FVCOM

0001 function write_FVCOM_spectide(ObcNodes,Components,Period,Phase,Amp,BetaLove,EquilibriumAmp,SpectralFile,MyTitle)
0002 
0003 % Write an FVCOM spectral tidal elevation forcing file
0004 %
0005 % function write_FVCOM_spectide(ObcNodes,Components,Period,Phase,Amp,BetaLove,EquilibriumAmp,SpectralFile,MyTitle)
0006 %
0007 % DESCRIPTION:
0008 %    Write an FVCOM NetCDF spectral tidal elevation forcing file
0009 %
0010 % INPUT:
0011 %   ObcNodes     = list of open boundary nodes of size [nObcs]
0012 %   Components   = list of component names (e.g. 'M2', 'N2' etc.) [nComponents]
0013 %   Period       = list of periods in seconds of size [nComponents]
0014 %   Phase        = list of phases in degrees of size [nObcs,nComponents]
0015 %   Amp          = list of amplitudes (m) of size [nObcs,nComponents]
0016 %   BetaLove     = list of beta Love numbers [nComponents]
0017 %   EquilibriumAmp = list of equilibrium tidal amplitudes [nComponents]
0018 %   SpectralFile = name of NetCDF file
0019 %   MyTitle      = case title, written as global attribute of NetCDF file
0020 %
0021 % OUTPUT:
0022 %    SpectralFile, A NetCDF FVCOM spectral tide forcing file
0023 %
0024 % EXAMPLE USAGE
0025 %    write_FVCOM_spectide(ObcNodes,Period,Phase,Amp,SpectralFile,MyTitle)
0026 %
0027 % Author(s):
0028 %    Geoff Cowles (University of Massachusetts Dartmouth)
0029 %    Pierre Cazenave (Plymouth Marine Laboratory)
0030 %
0031 % Revision history
0032 %    2012-06-14 Ported NetCDF write to use MATLAB's native NetCDF support.
0033 %    Requires MATLAB v2010a or greater.
0034 %    2012-08-02 Added beta (Love) number and equilibrium amplitude support
0035 %    when writing output.
0036 %
0037 %==============================================================================
0038 
0039 global ftbverbose
0040 report = false;
0041 if(ftbverbose); report = true; end;
0042 subname = 'write_FVCOM_spectide';
0043 if(report);  fprintf('\n'); end;
0044 if(report); fprintf(['begin : ' subname '\n']); end;
0045 %------------------------------------------------------------------------------
0046 % Sanity check on input and dimensions
0047 %------------------------------------------------------------------------------
0048 nComponents = numel(Period);
0049 if(report); fprintf('Number of Tide Components %d\n',nComponents); end;
0050 
0051 nObcs = numel(ObcNodes);
0052 if(report); fprintf('Number of Open Boundary Nodes %d\n',nObcs); end;
0053 
0054 [chk1,chk2] = size(Amp);
0055 if( (nObcs-chk1)*(nComponents-chk2) ~= 0)
0056     fprintf('Amp dimensions do not match!!!')
0057     fprintf('nObcs %d nComponents %d\n',chk1,chk2)
0058     error('bad');
0059 end;
0060 
0061 [chk1,chk2] = size(Phase);
0062 if( (nObcs-chk1)*(nComponents-chk2) ~= 0)
0063     fprintf('Phase dimensions do not match!!!')
0064     fprintf('nObcs %d nComponents %d\n',chk1,chk2)
0065     error('bad');
0066 end;
0067 
0068 %%
0069 %------------------------------------------------------------------------------
0070 % Dump the file
0071 %------------------------------------------------------------------------------
0072 
0073 nc=netcdf.create(SpectralFile,'clobber');
0074 
0075 % define global attributes
0076 netcdf.putAtt(nc,netcdf.getConstant('NC_GLOBAL'),'type','FVCOM SPECTRAL ELEVATION FORCING FILE')
0077 netcdf.putAtt(nc,netcdf.getConstant('NC_GLOBAL'),'title',MyTitle)
0078 ComponentsOut = char();
0079 for i=1:nComponents
0080     if i == 1
0081         ComponentsOut = Components{i};
0082     else
0083         ComponentsOut = [ComponentsOut, ' ', Components{i}];
0084     end
0085 end
0086 netcdf.putAtt(nc,netcdf.getConstant('NC_GLOBAL'),'components',ComponentsOut)
0087 netcdf.putAtt(nc,netcdf.getConstant('NC_GLOBAL'),'history', sprintf('File created using %s from the MATLAB fvcom-toolbox', subname))
0088 
0089 % define dimensions
0090 one_dimid=netcdf.defDim(nc,'one',1);
0091 nobc_dimid=netcdf.defDim(nc,'nobc',nObcs);
0092 tidal_components_dimid=netcdf.defDim(nc,'tidal_components',nComponents);
0093 date_str_len_dimid=netcdf.defDim(nc,'DateStrLen',26);
0094 
0095 % define variables and attributes
0096 nobc_varid=netcdf.defVar(nc,'obc_nodes','NC_INT',nobc_dimid);
0097 netcdf.putAtt(nc,nobc_varid,'long_name','Open Boundary Node Number');
0098 netcdf.putAtt(nc,nobc_varid,'grid','obc_grid');
0099 
0100 tide_period_varid=netcdf.defVar(nc,'tide_period','NC_FLOAT',tidal_components_dimid);
0101 netcdf.putAtt(nc,tide_period_varid,'long_name','tide angular period');
0102 netcdf.putAtt(nc,tide_period_varid,'units','seconds');
0103 
0104 tide_Eref_varid=netcdf.defVar(nc,'tide_Eref','NC_FLOAT',nobc_dimid);
0105 netcdf.putAtt(nc,tide_Eref_varid,'long_name','tidal elevation reference level');
0106 netcdf.putAtt(nc,tide_Eref_varid,'units','meters');
0107 
0108 tide_Ephase_varid=netcdf.defVar(nc,'tide_Ephase','NC_FLOAT',[nobc_dimid,tidal_components_dimid]);
0109 netcdf.putAtt(nc,tide_Ephase_varid,'long_name','tidal elevation phase angle');
0110 netcdf.putAtt(nc,tide_Ephase_varid,'units','degrees, time of maximum elevation with respect to chosen time origin');
0111 
0112 tide_Eamp_varid=netcdf.defVar(nc,'tide_Eamp','NC_FLOAT',[nobc_dimid,tidal_components_dimid]);
0113 netcdf.putAtt(nc,tide_Eamp_varid,'long_name','tidal elevation amplitude');
0114 netcdf.putAtt(nc,tide_Eamp_varid,'units','meters');
0115 
0116 equilibrium_tide_Eamp_varid=netcdf.defVar(nc,'equilibrium_tide_Eamp','NC_FLOAT',tidal_components_dimid);
0117 netcdf.putAtt(nc,equilibrium_tide_Eamp_varid,'long_name','equilibrium tidal elevation amplitude');
0118 netcdf.putAtt(nc,equilibrium_tide_Eamp_varid,'units','meters');
0119 
0120 equilibrium_beta_love_varid=netcdf.defVar(nc,'equilibrium_beta_love','NC_FLOAT',tidal_components_dimid);
0121 netcdf.putAtt(nc,equilibrium_beta_love_varid,'formula','beta=1+klove-hlove');
0122 
0123 date_str_len_varid=netcdf.defVar(nc,'equilibrium_tide_type','NC_CHAR',[date_str_len_dimid,tidal_components_dimid]);
0124 netcdf.putAtt(nc,date_str_len_varid,'long_name','formula');
0125 netcdf.putAtt(nc,date_str_len_varid,'units','beta=1+klove-hlove');
0126 
0127 time_origin_varid=netcdf.defVar(nc,'time_origin','NC_FLOAT',one_dimid);
0128 netcdf.putAtt(nc,time_origin_varid,'long_name','time');
0129 netcdf.putAtt(nc,time_origin_varid,'units','days since 1858-11-17 00:00:00');
0130 netcdf.putAtt(nc,time_origin_varid,'format','modified julian day (MJD)');
0131 netcdf.putAtt(nc,time_origin_varid,'time_zone','none');
0132 netcdf.putAtt(nc,time_origin_varid,'comments','tidal harmonic origin_date:1899-12-31 12:00:00');
0133 
0134 % end definitions
0135 netcdf.endDef(nc);
0136 
0137 % write data
0138 netcdf.putVar(nc,nobc_varid,ObcNodes);
0139 netcdf.putVar(nc,tide_period_varid,Period);
0140 netcdf.putVar(nc,tide_Eref_varid,zeros(1,nObcs));
0141 netcdf.putVar(nc,tide_Ephase_varid,Phase);
0142 netcdf.putVar(nc,tide_Eamp_varid,Amp);
0143 netcdf.putVar(nc,equilibrium_tide_Eamp_varid,EquilibriumAmp);
0144 netcdf.putVar(nc,equilibrium_beta_love_varid,BetaLove);
0145 
0146 nStringOut=char();
0147 for i=1:nComponents
0148     if Period(i) <= 13*3600 % Be a bit fuzzy to get the M2 in
0149         % Semi-diurnal
0150         nStringOut = [nStringOut, 'SEMIDIURNAL               '];
0151     elseif (Period(i) > 13*3600 && Period(i) < 28*3600)
0152         % Diurnal
0153         nStringOut = [nStringOut, 'DIURNAL                   '];
0154     else
0155         % Just call them all 'long period'
0156         warning('FVCOM does not (apparently) support long period harmonics. This output may cause the model to crash during initialisation.')
0157         nStringOut = [nStringOut, 'LONG PERIOD               '];
0158     end
0159 end
0160 netcdf.putVar(nc,date_str_len_varid,nStringOut);
0161 netcdf.putVar(nc,time_origin_varid,15019.5);
0162 
0163 % close file
0164 netcdf.close(nc);
0165 
0166 if(report); fprintf(['end   : ' subname '\n']); end;
0167
write_FVCOM_spectide

PURPOSE

SYNOPSIS

DESCRIPTION

CROSS-REFERENCE INFORMATION

SOURCE CODE
