Skip to content

Initialization Data

Jump to bottom
Giorgos Kourakos edited this page Jun 20, 2023 · 17 revisions

Mantis reads the initialization data from a configuration file as follows:

MantisServer.exe -c config.ini

While the file can have any extension we use the *.ini extension because the format of the file is similar to *.ini files and most editor know how to properly highlight the .ini data.

The configuration options are divided into sections:
The section names are enclosed in square brackets

Main configuration file

The main configuration file contains 2 sections:

[ModelAreas]

In the second version of Mantis we introduced the concept of Model Areas. Each model area has its own data sets.
The ModelAreas section has only one option at the moment, the File option.

The file option is the name of the file that lists the Model Areas configuration files. The format of the file is

RegionName Filename

Where RegionName is a code for the model area and the filename is the name of the file that lists of the input data specific to the model area.

The following is an example of a ModelAreas file

# Region Name Path/to/file
#The Region name has to be without spaces
# The file path must be absolute or can be found under relative path
    
# Main input file for Modesto
#Modesto Modesto.ini

# This is the main input file for the entire CV
CentralValley CV_inputs.ini

# Main input file for Tulare
#TuleRiver TuleRiver.ini

Empty lines and lines that start with # are ignored. In this file the model area name is the CentralValley and the data associated with that are in the CV_inputs.ini.

[ServerOptions]

These are options specific to server

  • PORT is the port number
  • IP is the ip address. If it is empty the ip gets the value 127.0.0.1
  • NTHREADS is the number of threads.
  • RFmem controls for how long the RFURF data will remain into the memory.
  • logFile If it is not empty all the console output will be printed in this file. The Data.Path does not affect this file. It is better to specify the full path along with the name for better control.
  • logClearFreq If logFile is present this specifies how often the lofFile will be cleared.
  • DebugPrefix This is used as a prefix if DebugID is provided in the input scenario. It will use this prefix for the various files that are printed.

Model area configuration file

For each Model area a separate configuration file must be prepared with the following sections:

[CV_Raster]

The simulated domain is discretized into a raster where all the information is aggregated to. The following is a list of options that describe the rasterization of the domain:

  • Ncells : is the total number of active pixels of the domain.
  • Nrows : is the number of rows of the raster
  • Ncols : is the number of the columns of the raster
  • Xorig : is the x coordinate of the left edge of the first cell
  • Yorig : is the y coordinate of the bottom edge of the bottom cell
  • CellSize : is the size of the raster cell
  • File : is the name of the file that contains the active area. The raster is a 2D array that contains -1 to the pixels that correspond to the area outside the domain. Every pixel in the active area contains a unique id from 0 to Ncells-1.

The format of the file in ASCII format is:

ROW COL

while; for HDF format, a dataset with name Raster must contain a 2D array with -1 for the inactive areas and the linear indices for the active areas.

Example code

Here is an example code how to prepare the raster for Central Valley. Since we are using the same raster as in other application, first we are going to load a few data from the GNLM repository

gnlm_years = 1945:15:2050;
for ii = 1:5
    LU{ii,1} = double(imread(fullfile('GNLM',['model_input_LU' num2str(gnlm_years(ii)) '.tif'])));
end
for ii = 1:8
    NGW{ii,1} = double(imread(fullfile('GNLM',['Ngw_' num2str(gnlm_years(ii)) '.tif'])));
end

We Identify as active cells the ones that have information to at least one of the above maps

CVpixels  = false(size(LU{1,1}));
for ii = 1:length(LU)
    CVpixels(LU{ii} > 0) = true;
end
for ii = 1:length(NGW)
    CVpixels(NGW{ii} > 0) = true;
end

Create a linear index for the pixels

[CVpixels_II, CVpixels_JJ] = find(CVpixels);
CVpixels_lin_ind = sub2ind(size(CVpixels),CVpixels_II, CVpixels_JJ);

Write a raster with the active indices positions

CVpixel_pos = zeros(size(CVpixels));
CVpixel_pos(CVpixels_lin_ind) = [1:length(CVpixels_lin_ind)]';

Write the active raster indices to HDF5 format. Here we print the entire 2D raster map

h5create('CVraster.h5','/Raster',[size(CVpixel_pos,1) size(CVpixel_pos,2)], 'Datatype','int32');
h5write('CVraster.h5','/Raster', (CVpixel_pos-1));

Write the active raster indices as ASCII file. Here we write only the active indices

fid = fopen('CVraster.mnts','w');
fprintf(fid,'%d %d\n',[CVpixels_II-1 CVpixels_JJ-1]');
fclose(fid);

[Data]

The Data section provides the input files of the main data

Path

All the files must be relative to this path including the raster file of the previous section.

BMAPS

This is a file which contains all the background maps. This file contains only the names of the background maps and subregions not the actual geometry. The format of the file is as follows:

Nbmaps
bMapName Nregions
RegionName1
:
:
RegionNameNregions
(repeat Nbmaps)

NO3

This is a filename that contains a list of the loading scenarios.

Each line in the file describes an N loading scenario as follows

TYPE NAME UNIT filename ExtrapMethod

where

  • TYPE: is one of the GTL or RASTER keywords. GTL refers to grid time loading which is a time series loading function while RASTER is a constant value for each pixel.
  • NAME: is a descriptive name of the loading scenario that should not have any spaces or symbols. This name it is used in the incoming message in the loadScen variable.
  • UNIT: is either CONC or MASS depending of the type of loading. If the type is MASS then it is converted to concentration during the simulation. The units are mg/l for CONC and kg/ha/year for MASS.
  • filename: is the name of the file and has to be relative to the Path
  • ExtrapMethod : is either NEAREST or REPEAT. THis is used only in GTL. The NEAREST method extrapolates the first or the last value while the REPEAT method repeats the loading forwards of backwards.

For example

GTL GNLM MASS CV_GNLM.h5 NEAREST
GTL SWAT1 CONC CV_SWAT1 REPEAT
#GTL SWAT2 CONC CV_SWAT2.h5 REPEAT
RASTER TESTLOAD CONC ../../path/to/test01Load.h5

If the line starts with # or is empty then it is ignored.

GTL

An example of GTL is the GNLM loading which estimates the nitrate loading from 1945 to 2050 with 15 years increment (see the map). Besides loading the land use changes at the same intervals until 2005. After that the land use remains constant. There are two option for preparing the input files: ASCII and HDF5

  • ASCII
    For the ASCII option two files are required

    • #######.idxlu
      The format of the idxlu file is the following
    Npixels StartYear Interval Nlu
id LU1 LU2 LU3 ...
:

    Npixels : is the number of rows in the file which should be identical to the Ncells of the Raster
    StartYear is the starting year of the land use time series
    Interval is the interval of the land use time series
    Nlu is the number land use values per pixel
    id is the row of the .nload. LU1, LU2... etc are the land use codes for the Nlu time snapshots
    The first two lines for the idxlu file of GNLM can be

    1064833 1945 15 5
3341 2 2 2 3 3
    • #######.nload
      The format of the nload file is
    Nrows StartYear Interval Nval
N1 N2 N3 ...

    Nrows is the number of rows of the file
    StartYear is the starting year of the N loading
    Interval is the interval of the Nloading time series
    Nval is the number of columns.
    N1 N2... are the loading values.
    The first two lines for the idxlu file of GNLM can be

    239129 1945 15 8
0.0011 0.0019 0.0025 0.0039 0.0050 0.0060 0.0075 0.0089

    To calculate the loading of a streamline we start from the I,J cell that the streamline gets its loading. The I,J cell is converted to linear index lidx with the help of the RASTER which points to the lidxth row of the idxlu table. Using the id of the lidxth row we read the loading time series from the idth row of the nload file. The reduction of loading is based on the year and the crop type of the idxlu table.
    The filename for the ASCII option should be given without the suffixes .idxlu and .nload.

  • HDF5
    The HDF5 format includes the data of the two files into one as different data sets. In particular three data sets are expected

    • LU which contains the LU1 LU12 ... values without the id
    • Nidx which containts the id only
    • NLoad contains the N1 N2 N3 ... data

RASTER

The RASTER type allows to setup unique loading values at each cell of the CV Raster which remain constant over the entire simulation.

The following snippet shows how to prepare a RASTER N loading type.

testLoad = [100*rand(length(CVpixels_JJ),1) 50*rand(length(CVpixels_JJ),1)];
h5create('test01Load.h5','/Data',[size(testLoad,1) size(testLoad,2)], 'Datatype','single');
h5write('test01Load.h5', '/Data', [testLoad]);
h5create('test01Load.h5','/Names',2, 'Datatype','string');
h5write('test01Load.h5', '/Names', {'test100', 'test50'});

WELLS

A file that lists the files (one in each row) that contain the wells for each flow scenario.
Each well file has the following format:

Nwells ScenarioName recharge CalcSourceArea PrintSourceArea
Eid X Y D S Q R A name1 name2 ...nameNbmaps

where:
Nwells is the number of the wells in this set
ScenarioName is the well scenario name. This name has the format flowScen_wellType
recharge is the recharge map to use during the source area computation
CalcSourceArea Can be set equal to 0 1 or 2. If is set to 1 or 2 Mantis approximates the source area for each streamline. In that case the R and A should be valid entries.
Eid is the well id, X,Y,D,S,Q are the coordinates, depth, screen length and pumping rate of the well. R and A are the ratio and angle of the source area and the names are the background map region names that the well belongs to.

URFS

A file that lists the files (one in each row) that contain the URFS for each flow scenario.
Each urf file has the following format

nurfs ScenarioName LGNRM
Eid Sid ROW COL InRiver m s w Npxl

where Eid and Sid are the well and streamline ids, ROW COL are the cell indices where this streamline exits the domain, m s are the mean and standard deviation parameter and w is the weight. Npxl is an approximation of the source area in cells for the streamline.

UNSAT

A file that contains the values of Depth/Recharge. The format is identical to RCH file that follows.

RCH

A file the contains the recharge values. The units of recharge have to be mm/year
Both UNSAT and RCH have the same format.

N
ScenarioName1
:
ScenarioNameN
Col1 Col2 ... ColN

where N is the number of scenarios, followed by a list of scenario names and a table of size Ncells x N.

Here is an example how to write the recharge data as HDF5 format. First we read the geotiff with the recharge values.

RCH = imread(fullfile('path','to','C2VSimII_Mod_3310.tif'));
RCH(RCH == RCH(1,1)) = nan;
RCH = double(RCH);
RCH_linear = RCH(CVpixels_lin_ind);
RCH_linear(isnan(RCH_linear)) = 0;
RCH_linear = RCH_linear*365000;

h5create(fullfile('MantisData', 'RCH_mapsII.h5'),'/Data',[length(RCH_linear) 1], 'Datatype','single');
h5write(fullfile('MantisData', 'RCH_mapsII.h5'), '/Data', [RCH_linear]);
h5create(fullfile('MantisData', 'RCH_mapsII.h5'),'/Names',1, 'Datatype','string');
h5write(fullfile('MantisData', 'RCH_mapsII.h5'), '/Names', {'C2VSIM_II_01'});

Note that the recharge has to be multiplied by 365000. This is used to convert the m/day values of the tif file to mm/year.

RFURF

RFURF stands for Region and Flow specific unit response functions. The URFs of the previous sets can be sliced into different sets at run time. The region/flow specific URFs correspond to a particular region and cannot be grouped in a different way. These are used only for the Virtual monitoring wells and they are grouped into Townships. The format of the files is the following

Nameset1 N
file1
:
fileN
Nameset2 N1
file1
:
fileN1
:

where Nameset is the representative name of the set and N is the number of files that contain the data for that set followed by a list of files with the data

The data have to be in HDF5 format and contain 4 datasets

  • EID A table with the entity (virtual well) ids.
  • EXY A table with the x,y coordinates of the virtual wells
  • SEIJR A table with 4 columns Eid, urfI, urfJ, Riv, where Eid is the entity id with values from the EID dataset, urfI urfJ are the row and column of the starting point of the streamline and Riv is 1 if the starting point is from a stream.
  • SMSWD A table with 4 columns Mean, Std, Weight, Depth.

Path

If the path is not empty then all the input files will be relative to this path.
The path should always contain the / or \ character

  • Path = /my/path ❌
  • Path = /my/path/ or Path = f:\bla\bla\ 👍
Clone this wiki locally