Feature ugrid (#204)

* CF: out2d validates for ics=1 and iof_ugrid=2

* 3D outputs working for iof_ugrid=0

* Tested for all iof_ugrid = (/1,2,3/) and ics=1

* New iof_ugrid tested with ics=2 and optional metadata.nc input

* Documented iof_ugrid=2 and metadata.nc

* MAke sure that CRS is transferred from metadata.nc even for ics=1 (when it does not exist in original output)

* Simplified to have only iof_ugrid = 0, 1

* Added full reference, make empty institution and license by default

* Cleaned up CF output on iof_ugrid=0

* Remove redundant createion_date from variable attributes

* Keep iof_ugrid=0 with minimal metadata, keep iof_ugrid=1 with complete data+metadata, new iof_ugrid=2 with complete metadata and referenced data in 3D

* Reverted renameing of add_mesh_attributes

Author: platipodium

docs/input-output/optional-inputs.md

@@ -259,3 +259,7 @@ NHAGE, NHAGV = flags that indicate whether or not harmonic analysis is performed
     - FMV: fraction of the harmonic analysis period (extending back from the end of the harmonic analysis period) to use for comparing the water elevation and velocity means and variances from the raw model time series with corresponding means and variances of a time series resynthesized from the harmonic constituents. This comparison is helpful for identifying numerical instabilities and for determining how complete the harmonic analysis was. Examples: FMV = 0. - do not compute any means and vars. FMV = 0.1 - compute means and vars. over final 10% of period used in harmonic analysis FMV = 1.0 - compute means and vars. over entire period used in harmonic analysis.
     - NHAGE: NHAGE= 0 no harmonic analysis is performed for global elevations; NHAGE =1 harmonic analysis is performed for global elevations (output on harme.53);
     - NHAGV: NHAGV is for velocity which is not active right now.
+
+### metadata.nc
+
+This optional file can contain global and variable metadata in the form of NetCDF attributes that will be copied over to the SCHISM output NetCDF files.  This file is useful for adding project- or institution-specific metadata.   In particular, you should use it to fill the contact and institution information required by CF, and to add a coordinate reference system to SCHISM output on projected coordinates (`ics = 1`) if you add a grid mapping variable called `crs` with appropriate attributes.  See the CF conventions for details on required and recommended metadata: https://cfconventions.org/.

docs/input-output/param.md

@@ -400,9 +400,12 @@ If `iout_sta=1`, each line of outputs `staout_[1-]` represents time series of th
  location for 3D variables). If `iout_sta=2`, 2 lines of outputs are produced at each time step: the odd lines are same as `iout_sta=1`,
  and the even lines are 3D profiles - see `Utility/Post-Processing-Fortran/read_staout.f90` for the profile format.
 
-### iof_ugrid (int)
-UGRID option for outputs under scribed IO. If iof_ugrid/=0, outputs will also have UGRID metadata (at
-the expense of file size).
+### iof_ugrid = 0 (int)
+UGRID option for 3D outputs under scribed IO (`out2d_*.nc` always has metadata
+info). If `iof_ugrid > 0`, 3D outputs will contain UGRID and CF metadata.  
+if `iof_ugrid == 1`,  3D output contains UGRID mesh data at the expense
+of file size; if `iof_ugrid == 2`, 3D output references mesh data in the
+2D output.
 
 ### nc_out =1(int)
 Main switch to turn on/off netcdf outputs, useful for other programs (e.g., ESMF) to control outputs.

sample_inputs/param.nml

@@ -835,8 +835,10 @@
 
 !-----------------------------------------------------------------------
 ! UGRID option for _3D_ outputs under scribed IO (out2d*.nc always has meta
-! data info). If iof_ugrid/=0, 3D outputs will also have UGRID metadata (at
-! the expense of file size). 
+! data info). If iof_ugrid > 0, 3D outputs will also have UGRID metadata.  
+! if iof_ugrid == 1 3D output will contain UGRID mesh data (at the expense
+! of file size); if iof_ugrid == 2, 3D output references mesh data in the 
+! 2D output.
 !-----------------------------------------------------------------------
   iof_ugrid = 0