User Guide 023

12 Appendix B: Description of Output Files

XMDF Solution Files (Binary Format)

By default, CMS global solution output files are written in a binary format called XMDF which is based on the HDF5 format which was developed to allow for portability between Windows and non-windows platforms. At present, the SMS reads and writes XMDF files. Additional binary formats are under review to be implemented in CMS for compatibility with other numerical models.

To make post-processing a little easier, CMS developers have written a Matlab code, shown below, that reads in the CMS XMDF solution file.

---

function varargout = read_cmsh5sol(filename,varargin) % sol = read_cmsh5out(filename,...'dataset1','dataset2',...) % %DESCRIPTION: % Reads a CMS solution file and creates % a structure variable containing the solution % datasets values and times % %INPUT: % filename - input file name including full path % varargin - dataset names % %OUTPUT: % sol - structure variable containing dataset values and times % varargout - variable length datasets corresponding to varargin % %USAGE: % filename = 'test_sol.h5'; % sol = read_cmsh5sol(filename); % wse = read_cmsh5sol(filename,'Water_Elevation'); % [wse,uv] = read_cmsh5sol(filename,'Water_Elevation',... % Current_Velocity'); % % written by Alex Sanchez, USACE-ERDC-CHL info = hdf5info(filename); s = info.GroupHierarchy.Groups.Groups; sol = struct(); for i=1:length(s);

   field = s(i).Name;
   ind = findstr(field,'/');
   field = field(ind(end)+1:end);
   if nargin>1 %select only few datasets
       for k=1:nargin-1
           if strcmpi(field,varargin{k})
               varargout{k}.Times = ...
                   double(hdf5read(s(i).Datasets(3)));
               varargout{k}.Values = ...
                   double(hdf5read(s(i).Datasets(4)));
               continue
           end
       end
   else %write all datasets
       field = regexprep(field,'(', '_');
       field = regexprep(field,')', );
       field = regexprep(field,' ', );
       try
           sol = setfield(sol,field,'Times',...
               double(hdf5read(s(i).Datasets(3))));
           sol = setfield(sol,field,'Values',...
               double(hdf5read(s(i).Datasets(4))));
       catch
           try
               for j=1:length(s(i).Groups)
                   field = s(i).Groups(j).Name;
                   ind = findstr(field,'/');
                   field = field(ind(end)+1:end);
                   field = regexprep(field,'(', '_');
                   field = regexprep(field,')', );
                   field = regexprep(field,' ', );
                   val = double(hdf5read( ...
                       s(i).Groups(j).Datasets(3)));
                   sol = setfield(sol,field,'Times',val);
                   val = double(hdf5read( ...
                       s(i).Groups(j).Datasets(4)));
                   sol = setfield(sol,field,'Values',val);
               end
           catch
               warning(['Unable to read ',field])
           end
       end
   end    

end if nargin>1 && nargout==1

   for k=1:nargin-1
       sol.(varargin{k}) = varargout{k};
   end

elseif nargin==1

   simlabel = info.GroupHierarchy.Groups.Name(2:end);
   sol.Simulation_Label = simlabel;
   varargout{1} = sol;

end return

---

SMS Super Files (ASCII Format)

Another option in CMS is to write out solutions in an ASCII format. CMS developers decided to use a format previously implemented in the SMS for writing large ASCII datasets. This format requires three files to be present for each solution dataset: a super file, a scatter point file, and the scatter data file.

The super file simply contains a link to the scatter point file which stores the XY coordinates of each solution point. This file has a “.sup” file extension.

The scatter point file contains the name associated with this output file, the total number of solution points and a list of the XY coordinates of each solution point. This file has a “.xy” file extension.

The scatter data file typically contains information such as the name associated with this output file (same as the name given in 2. Above), reference time, time units, and then scalar or vector records for each output interval as specified in the parameter file. This file has a “.dat” file extension.

To activate ASCII output for solutions, the user must define the “GLOBAL_SUPER_FILES ON” card in the CMS parameter file.

Time Series (Observation Point) Files

As an alternative to frequent output intervals in the global solutions, which are often quite large after completion, CMS has the option to output information for individual locations inside the domain into ASCII files. These are referred to as observation points. Because information is stored for a very small selection of points, users can define this output to be at much smaller time intervals without resulting in very large files.

Individual scalar files are written for each type of information that is to be written. Presently, these types are: current velocity U and V components, water surface elevation, flow rates in X and Y direction, sediment transport rates in X and Y direction, suspended load sediment concentration, salinity concentration, and bed composition. Each file may contain output for one or more cells as defined in the SMS observation cell selection procedure. A flagged value of ‘-999.0000’ is given for any computational cell that is considered dry at each output time. A partial example of the file format is shown below:

---

% time(hrs) 22883 60601 62753

    0.0000    0.0000 -999.0000    0.0000
    0.5000    0.0078 -999.0000    0.0077
    1.0000    0.0500 -999.0000    0.0495

…

 2062.5000    1.1605    1.1216    1.1614
 2063.0000    1.3580    1.3414    1.3580
 2063.5000    1.4783    1.4835    1.4788
 2064.0000    1.5100    1.5406    1.5174

---

In each file, there is a header row which gives a description of the contents of the following rows. In the example above, the first column contains “time in hours”, followed by three columns giving the cell numbers as saved by the SMS interface. There will be one row per output time.