Tutorial
This is a brief tutorial to illustrate how to run a simple application
that makes use of the cmmpy
. For more details and more options,
one can have a look at many examples available in the bitbucket/github
repositories in the folder test. The files provided in the test
folder cover almost all the examples explored in the companion paper
published in Computers and Geosciences by A.Comunian and M.Giudici,
DOI: 10.1016/j.cageo.2021.104705 (hereinafter, the
companion paper).
Example - Tomographic approach
This example is based on the implementation of the CMM with a tomographic approach. It should allow to obtain part e) of Fig.9 of the companion paper.
Hereinafter we will briefly describe the main components required to run the CMM.
Setting up the forward problem
As many other inversion tools, the CMM requires to set up a tool to
solve the forward problem (FP). Here the set up is implemented with
flopy
and the Modflow6
version. Nevertheless, you can
customize the code to use different tools for the solution of the FP,
as it was for example done in the preliminary part of this study by
using Modflow2005
, or by Comunian and Giudici (DOI:
10.1007/s11004-018-9727-0) who applied the CMM
with Parflow as flow simulation engine.
In the provided Python code, this is done in the function run_fp
of the module tool
. You can customize this function to suit your
particular needs. However, if your have modeling assumption akin to
the one stated in the companion paper, then you will not need to
customize this function too much, maybe even not. In fact, the code is
written in order to delegate as much as possible all the
parameterization and a big part of the model settings to an editable
json
file, to avoid as much as possible edits on the
function run_fp
function. The content of this json
file is
described in the next section.
Parameter file
As mentioned in the previous section, the main modifications that a
user should do to apply the CMM to his case study should be made on
the data files and to the input parameter file (JSON file). An example
of this file is provided for many test cases in the bitbucket/github
repositories in the aforementioned test folder. For example,
hereinafter it is provided a list of the entries of the file test.json
contained in the
folder test/test07_md_paper/04_S-SW-W-NW
, explained one by one.
In general, the parameters are grouped into four categories:
general
some “general” parameters.
fwd
parameters related to the forward problem run.
t_gen
parameters related to the generation of the synthetic \(T\) distribution which is used as reference.
cmm
parameters related to the Comparison Model Method (CMM).
noise
parameters related to the addition of noise to the input head fields.
Let us start to describe in details the sub-categories of the aforementioned “main” categories:
general["wdir"]
The working directory where all the output files will be saved.
general["data"]
Directory containing some needed data sets. For example, the files containing the boundary conditions and the shape of the domain will be stored here. For examples of possible input files, you can have a look at the folder
test/data
general["out"]
An output directory to save all the output needed by the flopy implementation.
fwd["ws"]
The workspace related to the Modflow problem
fwd["name"]
Name of the modflow problem
fwd["exe_name"]
The name of the modflow executable. In the example, the name
mf6dbl
is provided. However, in general, a more common name would bemf6
(if you are working on Linux of macOS) ormf6.exe
. Clearly, if the binary file of your modflow is not in the system PATH, you could also set here the explicit path.fwd["bcs"]
A file that contains codes that indicate the type of the cells used for the boundary conditions. The next section Input data files contains a more detailed description of this input format.
fwd["nx"]
,fwd["ny"]
Numer of cells along the \(x\) and \(y\) coordinates
fwd["dx"]
,fwd["dy"]
Size of the cells side (in meters)
fwd["data_sets"]
This keyword contains the detailed description of all the multiple data sets that can be used within
cmmpy
to apply the CMM with a tomographic approach. The main components of this keyword is a list, containing one dictionary for each data set. The dictionary contain the following keywords:name
defines a name for the corresponding data set, which at the moment is not explicitly used inside the code, but that is useful as reference to the data set;h_BCs
is the name of the VTK file (contained in the folder defined by the previously mentioned keyworddata
) that contains the values of the fixed head boundary conditions.fwd["rch"]
This contains the numerical value of a diffuse recharge term.
fwd["wells_loc"]
This should be a list containing three integers, that correspond to the cell location of the well (see for example the JSON files in the folder
test/test06_wells1a1
)fwd["well_ID"]
A reference name for the well.
fwd["well_q"]
The abstraction rate of the well, with the same conventions used in flopy.
t_gen["seed"]
The seed for the pseudo-random generator
t_gen["dim"]
The dimension of the problem, 2D or 3D.
t_gen["var"]
Variance of the heterogeneous field.
t_gen["len_scale"]
The scale length of the simulated heterogeneity.
cmm["nb_iter"]
The maximum number of iterations required to run the CMM. For the case study analyzed in the companion paper, 10 iteration were OK.
cmm["cprop"]
The proportions of data to be rejected and where the low gradient values should be corrected.
cmm["eps_gradh"]
A threshold value for the hydraulic gradient \(\grad (h)\).
cmm["mode"]
When using multiple data sets, this is the mode that is used to merge the \(T\) computed with the different input data. Allowed values are arithmetic, geometric, harmonic, median, and mincorr (there is also an “alternative” mincorrX). Default value is geometric. See the code and the companion paper for more details.
The same algorithm used for the generation of the synthetic field
example is here used to generate a correlated noise field to be added
to the input \(h\) data. If you do not need to add noise to your data, simply set the value of std
to 0.0.
noise["seed"]
The seed for the pseudo-random generator
noise["dim"]
The dimension of the problem, 2D or 3D.
noise["var"]
Variance of the heterogeneous field.
noise["len_scale"]
The scale length of the simulated heterogeneity.
Input data files
This is a brief description of some of the input data files contained
in the folder test/data
.
- shape of the domain and cells type
A matrix with the same shape of the domain should be provided, with the letter
I
for internal cells,D
for Dirichlet fixed head BCs,E
for external cells. See for example the filebcs.txt
in the foldertest/data
.- files containing the head BCs values
These are VTK structured points files.
Run the test
Once you set up all the parameters in the JSON file and provided the
required data files, you can run the inversion. If you take as
reference the folder structures provided on Github or Bitbucket, you
should first move to the folder test
. Once there, from the shell,
you can call the script run_cmm.py
by providing the name of the
JSON input file. For example, you could write:
./run_cmm.py test07_md_paper/04_S-SW-W-NW/test.json
At the end of the run, you can find the intermediate and the output
files into the folder defined in the JSON file, for example in the
folder out/test07_md_paper/04_S-SW-W-NW/
.