Input Instructions
To run RW3D, a single parameter file has to be provided.
Type of inputs
In the Parameter file, input parameters can be specified following these different formats:
logical:Tfor True;Ffor Falsestringintegerrealtime_function: A text file describing the temporal evolution of a non-array parameter.array: The parameter is potentially spatially and/or temporally variable and can be read from a file. The following information have to be provided in a single line:file namemultiplierivarflag(see specifications in the Table below). In some specific cases, one or two additional parameters (options) must also be provided.
Required inputs for an Array-type parameter Variable
Type
Description
file name
stringname of the file. Put some text even if no file is used
multiplier
realFixed parameter values (for
flag= 0), or multiplier of the variable
ivar
integervariable index of the variable in the gslib array
flag
integerway to read the values of the parameter:
0: spatially and temporally constant parameter, defined as the multiplier
1: read from the ascii file specified in
file name2: read from a MODFLOW type file (only for fluxes)
3: read from a DFS file
4: read from a NetCDF file
File format for a parameter of type array
A parameter of type array can be read from a file (with name file name) using a flag integer other than 0.
The file can be an text file, a DFS file, or a NetCDF file.
Text file
A text file (flag set to 1) must follow the following format:
Line |
Variable |
Type |
Description |
|---|---|---|---|
1 |
|
|
header line (not used by the code) |
2 |
|
|
number of variables |
repeat the following line |
|||
3 |
|
|
name of the variable (not used by the code) |
repeat the following line \(nx \times ny \times nz\) times: |
|||
4 |
|
|
variable values |
A single file can contain information about multiple (nvar) variables.
The values of each variable is defined in space separated columns. The file must contain \(nx \times ny \times nz\) rows, where \(ni\) is the number of cells in the i-th dimension.
All values are corrected by multiplying the read values by multiplier.
The values of the variable with index ivar are read as follow:
do k=1,nz
do j=1,ny
do i=1,nx
read(iunit,*) (aline(jcol),jcol=1,nvar) ! read all columns, i.e., all variables values, corresponding to the location (i,j,k)
values(i,j,k) = aline(ivar) * multiplier ! values of the selected variable (corresponding to the column ivar), corrected by a user-defined constant (multiplier)
end do
end do
end do
To read a parameter from a text file, use the usual inputs for an array parameter: file name multiplier ivar flag:
file name(string) is the name of the DFS file;
multiplier(real) is a number multiplying all values;
ivar(integer) is the column index to be used (set to 1 for a unique column of values in the text file);
flag(integer) is set to 1.
DFS file
RW3D supports reading input data from DFS files (flag set to 3).
The DFS (Data File System) is a binary data file format typically used in the MIKE Powered by DHI software.
For an extensive description of what DFS files are, follow the link https://docs.mikepoweredbydhi.com/core_libraries/dfs/dfs-file-system/
To read a parameter from a DFS file, use the usual inputs for an array parameter: file name multiplier ivar flag:
file name(string) is the name of the DFS file;
multiplier(real) is a number multiplying all values;
ivar(integer) is the item index to be used (set to 1 for a unique item in the DFS file);
flag(integer) is set to 3.
Note that for the moment, the geometry of the DFS files must match the grid specified in the parameter file (Geometry) (i.e., same domain and spatial discretization). The same applies to the time discretization, which must correspond to the discretization specified in the parameter file (Time). A more flexible approach will be developed soon.
NetCDF file
RW3D supports reading input data from NetCDF files (flag set to 4).
NetCDF (Network Common Data Form) is a widely used, self-describing binary file format designed for storing array-oriented scientific data.
For more information on the NetCDF format, see the official documentation: https://www.unidata.ucar.edu/software/netcdf/
The NetCDF file must follow a specific format. It must contain 4 dimensions (t, x, y, z) that fits the temporal and spatial discretizations of the model, even for time-invariant and 1D/2D parameters. Also, the NetCDF dataset must contain only one variable (i.e., the parameter to be specified). The name of the variable that the code read and use is recalled in the log file.
Note that the NetCDF format of the file will have to follow the specifications of your instalation of the NetCDF library.
To read a parameter from a NetCDF file, use the usual inputs for an array parameter: file name multiplier ivar flag:
file name(string) is the name of the NetCDF file;
multiplier(real) is a number multiplying all values;
ivar(integer) has to be specified but will not be used;
flag(integer) is set to 4.
File format for time function
This file is a plain text file used to define a time-dependent function. It provides a sequence of time-value pairs that describe how a quantity evolves over time. The file is read when flag == 1.
File Structure
The file must follow this structure:
Heading line (ignored by the subroutine).
Name line: a string that will be stored in func%name.
Number of time points: an integer value nt.
Time-function data: nt lines, each containing: - A real number representing the time value. - A real number representing the corresponding function value.
Ensure that the number of time-value pairs matches the integer specified in line 3.
Example
# Time function data for simulation
MyTimeFunction
4
0.0 1.0
1.0 2.0
2.0 1.5
3.0 0.5
Parameter file
The parameter file consists in a text file. The following blocks of information has to be sequentially provided.
Warning
Note that 3 header lines has to be written before each block.
General setup
Line
Variable
Type
Description
4
path_outputs
string
path_outputs: path to the output files5
base_outputs
string
base_outputs: base name for all output files
Note
The line number in each table is reset for each block to simplify the description of the inputs. Each block is to be filled up sequentially, so the absolute line number will be different.
Species and Phases
Line
Variable
Type
Description
4
nspe_aqnspe_min
integer
nspe_aq: number of aqueous (i.e., mobile) species
nspe_min: number of aqueous (i.e., immobile) species5
name_aq
string
name_aq: name(s) of aqueous (i.e., mobile) species6
name_min
string
name_min: name(s) of aqueous (i.e., immobile) species
Time
Line
Variable
Type
Description
4
t_sim
real
t_sim: simulation time5
transient_flag
logical
transient_flag: True if transient conditionsif
transient_flag==F, go to Geometry; iftransient_flag==T, fill up the following:6
read_dt_from_fileloop_dt
logical
read_dt_from_file: True if the time steps are read from a text fileif
read_dt_from_file==T:7
dt_file
string
dt_file: name of the text file listing the time stepsif
read_dt_from_file==T, go to Geometry; ifread_dt_from_file==F:8
n_dt
integer
n_dt: number of time stepsto be repeated \(n_{dt}\) times:
9 …
dt
real
dt: time step
Example: A problem involving 2 aqueous chemical species (named A and B) and 0 mineral species. The simulation will run for 150.0 time units with transient parameters. The temporal discretization of the transient parameters is specified in the file time_discretization.dat and the transient paramters are set to be looped in time until the end of the simulation. The first first blocs of the input file would look like that:
-----------------------------------------------------------------
General Setup
-----------------------------------------------------------------
C:\Path\To\Ouputs !... path_outputs
test_case !... basename_outputs
-----------------------------------------------------------------
Species and Phases
-----------------------------------------------------------------
2 0 !nspe_aq; nspe_min
A B !name_aq
- !name_min
-----------------------------------------------------------------
Time
-----------------------------------------------------------------
150.0 !t_sim
T !transient_flag
T T !read_dt_from_file; loop_dt
time_discretization.dat !dt_file
Geometry
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
|
5 |
|
|
|
6 |
|
|
|
7 |
|
|
option: Constant layer thickness
|
8 |
|
|
|
9 |
|
|
values: 0: active; 1: inactive option: Particle in inactive cells are killed
|
10 |
|
|
Defines the particle behaviour if a domain boundary is reached.
values:
|
8 |
|
|
|
Example: The domain is discretized in 1200 cells in the x-direction, 1400 cells in the y-direction and 11 cells in the z-direction. The cell size in x and y is fixed to 100 space units. The cell size in the z-direction is variable in space and specified in the first column of the text file dz.dat. The top elevation of the domain (topography) is also variable in space and specified in the text file topography.dat. The location of inactive cells is provided in the text file InactCell.dat and particles reaching an inactive cell will be killed. No multipliers are to be used (all set to 1.0). Finally, particles reaching the boundary of the domain will be killed, expect at the top of the domain, where particles will bounce. We would also like to produce a vtu file to visualize the grid, the active/innactive cells and the topography elevation in Paraview.
---------------------------------------------------------------
Geometry
---------------------------------------------------------------
1200 1400 11 !nx; ny; nz
not_used 100.0 1 0 !dx
not_used 100.0 1 0 !dy
dz.dat 1.0 1 1 F !dz
topography.dat 1.0 1 1 !topography
InactCell.dat 1.0 1 1 T !inactive_cell
0 0 0 0 0 1 !ib(1,1); ib(1,2); ib(2,1); ib(2,2); ib(3,1); ib(3,2)
T !write_vtu
Time step
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
Defines the way time steps are computed values: description provided in section Time discretization
|
5 |
|
|
Time step restrictors, as defined in section Time discretization |
6 |
|
|
Time step relaxation factor, as defined in section Time discretization |
Example: The time step is determined from the advective characteristic times only. The time step restrictors have to be provided, but only mult_adv will be used. It is fixed to 0.5.
The time step relaxation factor is set to 0.99, meaning that the 1% more restrictive characteristic times (1% fastest particles) will be disregarded in the time step determination.
-----------------------------------------------------------------
Time discretization
-----------------------------------------------------------------
constant_move !... dt_method
1.0 0.5 0.2 0.1 0.1 0.1 !... dt, mult_adv, mult_disp, mult_kf, mult_kd, mult_mt
0.99 !... time step relaxation
Advection
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
5 |
|
|
Method for advective motion of particles, as defined in Advective Motion values:
|
6 |
|
|
flow/flux in the x direction option 1: transient conditions
option 2: flow to flux
|
7 |
|
|
flow/flux in the y direction option 1: transient conditions
option 2: flow to flux
|
8 |
|
|
flow/flux in the z direction option 1: transient conditions
option 2: flow to flux
|
9 |
|
|
porosity (or water content) option 1: transient conditions
|
Example: Advective displacements are simulated. The Eulerian scheme is used to interpolate velocities. Darcy flows in x, and y directions are provided in a respective netcdf file. Flows will then have to be converted into fluxes within RW3D. The fluxes in z are directly provided, also in a netcdf file. All flows and fluxes are transient. The fluxes in z are to be multiplied by a factor of 2.0. The porosity field does not change in time and its spatial distribution is defined in a text file.
-----------------------------------------------------------------
Advection
-----------------------------------------------------------------
T !... advection_action
Eulerian !... advection_method
qx_DK1.nc 1.0 1 4 T T !... qx array
qy_DK1.nc 1.0 1 4 T T !... qy array
qz_DK1.nc 2.0 1 4 T T !... qz array
porosity_DK1.dat 1.0 1 1 F !... porosity array
Heads
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
5 |
|
|
cell-by-cell head elevation option: transient conditions
|
6 |
|
|
maximum head elevation for the cell to be considered dry |
Example: Hydrualic heads are accounted for to track particles reaching the water table. Heads are provided in a netcdf file. A cell will be considered dry if heads are below 0.05 (space unit).
--------------------------------------------------------------------------------------------
Heads
--------------------------------------------------------------------------------------------
T !... heads_action
heads_DK1.nc 1.0 1 4 F !... heads
0.05 !... heads_threshold
Sinks
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
5 |
|
|
number of sink |
to be repeated \(n_{sinks}\) times: |
|||
6… |
|
|
option 1: transient conditions
option 2: print_BTC
|
Example: 4 types of cell sinks are considered: river, drain, uz, well. All sinks are read from a respective a netcdf file. Breakthrough curves for all sinks will be saved, expect for the well sink. All sink fluxes are temporally variable.
--------------------------------------------------------------------------------------------
Sinks
--------------------------------------------------------------------------------------------
T !... sink_action
4 !... number of sink
river Qriver_DK1.nc 1.0 1 4 T T !... name, qsink array
drain Qdrain_DK1.nc 1.0 1 4 T T !... name, qsink array
uz Q_uz_DK1.nc 1.0 1 4 T T !... name, qsink array
well Qwell_DK1.nc 1.0 1 4 T F !... name, qsink array
Dispersion / Diffusion
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
5 |
|
|
dispersivity in the longitudinal direction option: transient conditions
|
6 |
|
|
dispersivity in the transverse horizontal direction option: transient conditions
|
7 |
|
|
dispersivity in the transverse vertical direction option: transient conditions
|
8 |
|
|
effective molecular diffusion in the longitudinal direction option: transient conditions
|
9 |
|
|
effective molecular diffusion in the transverse horizontal direction option: transient conditions
|
10 |
|
|
effective molecular diffusion in the transverse vertical direction option: transient conditions
|
11 |
|
|
Species dependent multiplier for the dispersivity coefficients for each aqueous species, the effective dispersivity coefficients is multiplied by the given factor |
12 |
|
|
Species dependent multiplier for the diffusion coefficients for each aqueous species, the effective diffusion coefficient is multiplied by the given factor |
Example: Dispersion and diffusion processes are simulated. All parameters are considered spatially homogeneous. Longitudinal, transverse horizonal, and transverse vertical dispersivities are set to 5.0, 5.0 and 0.1, respectively. Diffusion coefficients in all directions are set to 0.01. Two single aqueous species were considered. Diffusion coefficients for the second specie are two times larger than the set values (diffusion_factor set to 2.0). Set dispervities and diffusion coefficients are used otherwise (dispersivity_factor and diffusion_factor set to 1.0).
--------------------------------------------------------------------------------------------
Dispersion / diffusion
--------------------------------------------------------------------------------------------
T !... dispersion_action
not_used 5.0 1 0 !... alpha_L array
not_used 5.0 1 0 !... alpha_TH array
not_used 0.1 1 0 !... alpha_TV array
not_used 0.01 1 0 F !... Dm_L array
not_used 0.01 1 0 F !... Dm_TH array
not_used 0.01 1 0 F !... Dm_TV array
1.0 1.0 !... mult_alpha
1.0 2.0 !... mult_diff
Mass transfer
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
5 |
|
|
Defines the type of mass transfer process values: description provided in section Multirate Mass Transfer
|
if |
|||
6 |
|
|
number of immobile zones |
to be repeated |
|||
7 |
|
|
porosity in the ith immobile zone |
8 |
|
|
mass transfer coefficient in the ith immobile zone |
if |
|||
6 |
|
|
number of immobile zones |
to be repeated |
|||
7 |
|
|
total capacity |
8 |
|
|
minimum mass transfer coefficient |
9 |
|
|
maximum mass transfer coefficient |
10 |
|
|
power coefficient |
if |
|||
6 |
|
|
number of immobile zones |
to be repeated |
|||
7 |
|
|
total capacity |
8 |
|
|
mean of the lognormal mass transfer coefficients |
9 |
|
|
standart deviation in mass transfer coefficients |
if |
|||
6 |
|
|
|
for each mass transfer model, fill up sequentially the corresponding parameters as described above |
|||
Reactions
Retardation
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
to be repeated |
|||
5… |
|
|
retardation factor for a given aqueous species |
if |
|||
if |
|||
… to be repeated |
|||
…… to be repeated |
|||
6 … |
|
|
retardation factor for a given aqueous species and given imoobile zone |
if |
|||
… to be repeated |
|||
6 … |
|
|
retardation factor for a given aqueous species (for all imoobile zones) |
Note
Retardation is not available if type_mass_transfer = composite_media.
First-order decay
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
5 |
|
|
number of species involved in the decay network |
6 |
|
|
name(s) of the species involved in the decay network |
7 |
|
|
type of the decay network values:
|
|
|||
… to be repeated |
|||
8 … |
|
|
first-order decay rate |
…… do not fill for the first species for the serial network: |
|||
9 … |
|
|
yield coefficient |
if |
|||
… if |
|||
…… to be repeated |
|||
……… to be repeated |
|||
10… |
|
|
first-order decay rate for a given aqueous species and given imoobile zone |
… if |
|||
…… to be repeated |
|||
10… |
|
|
first-order decay rate a given aqueous species (for all imoobile zones) |
|
|||
… to be repeated |
|||
8 … |
|
|
first-order decay rate |
…… do not fill for the first species for the serial network: |
|||
9 … |
|
|
yield coefficient |
|
|||
… to be repeated |
|||
8 … |
|
|
first-order decay rate |
… to be repeated |
|||
9 … |
|
|
yield coefficient |
if |
|||
… if |
|||
…… to be repeated |
|||
……… to be repeated |
|||
10… |
|
|
first-order decay rate for a given aqueous species and given imoobile zone |
… if |
|||
…… to be repeated |
|||
10… |
|
|
first-order decay rate a given aqueous species (for all imoobile zones) |
Note
serial_moments option is not available if mass_transfer_action = T.
Note
Linear reaction solver is not available if type_mass_transfer = composite_media.
Bimolecular reactions
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
True if the package is activated |
5 |
|
|
number of reactions in the network |
to be repeated |
|||
6 |
|
|
string describing a reaction instructions:
available reaction so far:
|
to be repeated |
|||
7 |
|
|
reaction rate |
Observation
Note
Information about all observation surfaces (extraction wells, planes, registration lenses) have to be provided in a single block, without header lines between them,
Extraction well
Note
Extraction wells acting as a sink (strong or weak) can be specified in Sinks if the sink is considered uniformly in the cell where a well is located. In Observation, extraction wells are considered as a sink at the well location, with converging velocity leading to the actual well location. See Sink for more details about the implementation.
Line |
Variable |
Type |
Description |
|---|---|---|---|
4 |
|
|
number of wells |
to be repeated |
|||
6 |
|
|
|
7 |
|
|
Method with which extraction fluxes (Q_well) are read values:
|
|
|||
… to be repeated |
|||
8… |
|
|
total flux extracted by the given well |
|
|||
8 |
|
|
name of the file following the Modflow’s package |
Control plane
Line |
Variable |
Type |
Description |
|---|---|---|---|
5 |
|
|
number of control planes |
There are 2 options to define the control planes: |
|||
|
|||
6 |
|
|
values:
|
|
|||
6 |
|
|
|
Registration lense
Injection
Well recirculation
Note
In connection_string, the well names must correspond to the wellID specified in _Extraction well.
Outputs
Line |
Variable |
Type |
Description |
|---|---|---|---|
1 |
|
|
header line (not used by the code) |
2 |
|
|
number of snapshots |
repeat the following line |
|||
3 |
|
|
time of the snapshot |
Example:
--------------------------------------------------------------------------------------------
Outputs
--------------------------------------------------------------------------------------------
0 !... ixmom
1 1 !... iwcshot, output_format
150.0 50 1 !... tlen,ntstep,tmult
0 !... itmom
1 100 plugin -10. 0.0 250.0 0 !... iwbtc, ngrid, Kernel, bw, tmin, tmax, output_format
1 1 0 !... iwcbtc, inc, , output_format
1 0 0 !... iwhistory, print_out, output_format
0 1 35496 0 !... iwpath, pathfreq, pathpart, output_format