HyVR inputs and outputs¶
The .ini
configuration file¶
The key piece of information requried by HyVR is the parameter file. This is an
.ini
configuration file that contains all the parameters required to run a
HyVR simulation.
The parameter file is separated into sections denoted by headers surrounded by
brackets (e.g. [section_name]
). Parameters (or keys) and their associated
values are then stipulated using the equals sign (e.g. key = value
). Each
key is associated with the section in which it is located. Section and variable
names should be in lower case. String values do nore require quotation marks in
.ini
files.
In HyVR the following sections are necessary:
[run]
- This contains parameters related to the model run.[model]
- This contains details about the model dimensions[strata]
- In this section the strata parameters are set.[*architectural_elements*]
- Each architectural element to be simulated inHyVR is included in its own section. Please see the subsection below for more information.
[hydraulics]
- This section includes information for setting the hydraulicproperties of simulated features.
An additional section [flowtrans]
is included in some parameter files - this
section included parameters used in groundwater flow and solute transport
simulation packages not implemented in HyVR. .ini
files are readable by a
range of programming languages so the user can also store and read flow and
transport parameters from the configuration file.
Model setup sections¶
[run]
section¶
This section contains general sections how the program should be run. It controls where outputs are stored and which kind of output files are generated, and how many realisations are generated.
HyVR simulations are structured in the following way:
Model -> Run -> Realisation
Typically we assume that the .ini
file is stored in a model directory:
mymodel/
|-- myconfig.ini
When HyVR is run with this parameter file, it will create a run directory.
The name of the run directory can be set with the runname
option, e.g. to
myrun
. HyVR then stores a copy of the .ini
file inside the run directory
under the name myrun_autogenerated_backup.ini
. If runname
is not given,
the filename of the ini-file without .ini
will be used. If you are only
running one realization, the output of this realization is also stored directly
in this directory:
mymodel/
|-- myconfig.ini
|-- myrun/
| |-- myrun_autogenerated_backup.ini
| |-- myrun_hyvr.dat
| |-- myrun_hyvr.vtk
| |...
If you are running multiple realizations, HyVR creates a subdirectory for each realization output:
mymodel/
|-- myconfig.ini
|-- myrun/
| |-- myrun_autogenerated_backup.ini
| |-- real_001/
| | |-- myrun_real_001_hyvr.dat
| | |-- myrun_real_001_hyvr.vtk
| |-- real_002/
| | |-- myrun_real_002_hyvr.dat
| | |-- myrun_real_002_hyvr.vtk
| |...
ATTENTION: If the name of the ini-file ends with
_autogenerated_backup.ini
we assume the file was created automatically and
is already in the run directory. In this case the model directory will default
to the directory above the directory of the ini-file and the run directory will
be the directory of the ini-file. Also, if the runname
is not given in the
ini-file, the part before _autogenerated_backup.ini
will be chosen as
runname.
Example: If you run the file myrun_autogenerated_backup.ini
in the example
above, the run directory will be myrun
and the runname will default to
myrun
if it is not given.
For every run, HyVR needs to have a empty run directory. This can either be
accomplished by changing the runname in the config file, or you can either run
HyVR with the --overwrite
option or add overwrite_old_output=1
in the
config file to automatically remove the old run directory.
ATTENTION: Setting overwrite_old_output=1
or using --overwrite
will
delete everything from the run directory before running HyVR. This is done in
order to assure that no output files of previous runs with potentially even
different settings remain alongside the new output.
The following settings are possible in the run section:
runname
: (optional) Name of the model simulation run. Defaults to the name of the ini-file without the last for characters (.ini
)numsim
: (optional, default: 1) Number of realisations to be generated.outputs
: (optional) List of simulation output data formats (see Model outputs), e.g.[vtr, mat, py, h5, npz, mf, mf6, hgs]
overwrite_old_output
: (optional, default: false) Whether to overwrite previous model results. Iftrue
and the run directory already exists, all previous content is of the run directory is deleted and new files are created in this directory. Otherwise if the run directory already exists and contains files, the program stops. The deletion of old content should prevent having output of different models in the same directory after a run. Iffalse
, HyVR will check if the directory already exists and will ask you to change the runname in case it exists.
[model]
section¶
This section contains the size of the model, the grid it should be realized on, and which parameters should be generated.
x0
,y0
,z0
: (optional, default: 0.0) Grid origin.dx
,dy
,dz
: (required/optional) Model grid cell dimensions. Ifdy
ordz
are not given,dx
will be used instead.lx
,ly
,lz
: (required) Model domain dimensions.periodic
: (optional, default: false) Periodic model domain? (works for sheets/truncated ellipsoids only, not with channels)anisotropy
: (optional, default: true) Generate anisotropy parameters?hydraulics
: (optional, default: true) Generate hydraulic parameters?heterogeneity
: (optional, default: true) Ifhydraulics
istrue
, generate heterogeneous hydraulic parameters.heterogeneity_level
: (optional, default: internal) Hierarchical level at which heterogeneity should be simulated. Can befacies
orinternal
. Will only be used ifhydraulics
andheterogeneity
is set totrue
.
[strata]
section¶
The [strata]
section contains the settings for the major strata, the
top-level object of a HyVR model.
strata
: (required) List of sequence names. This should be a list of strings.strata_contact_models
: (required) List of contact models for strata contact surfaces, length should be thelength(strata)-1
. This should be understood as top contact for all but the last stratum instrata
(since the top surface of the last stratum is the domain top). A contact model is a list, of which the first item is a string describing what kind of surface it should be, and the following items are numbers that describe the contact surface. Currently there are two different types implemented:flat
andrandom
. A flat contact surface is just a plane at the depth given as first parameter. The corresponding contact model looks like this:[flat, <depth>]
. A random contact surface is created according to a random gaussian process with gaussian covariance. The parameters are the mean depth, the variance, and the correlation lengths in x and y direction. The contact model therefore looks like this:[random, <depth>, <variance>, <corl_x>, <corl_y>]
.ae
: (required) List of architectural elements in the model. This is a list of strings, which are the names of the[*architectural_elements*]
sections below.ae_in_strata
: (required) Which architectural elements are in each stratum. This should be a list of lists of strings. The outer list must have the same length asstrata
, the inner list can be of variable length. The elements of the inner lists must be strings fromae
.ae_prob
: (required) Probability of an architectural element occuring inside the respective stratum. This must be a list of lists of floats with the same shape asae_in_strata
.ae_z_mean
: (required) Mean thickness of architectural element unit. This must be a list of lists of floats with the same shape asssm_ae
.avul_prob
: (required) Probability of avulsion. List of floats with the same length asstrata
.avul
: (required) Avulsion depth range. List of lists of floats. The outer list must have the same length asstrata
, the inner lists must be of length 2 and are the start and end point of the depth range.bg_facies
: (required) Facies to assign to cells that are not in a geometrical object of an architectural element. This should be a list with the same size asstrata
. The items in the list should be names of hydrofacies as listed in the[hydraulics]
section.bg_azim
: (required) Azimuth to assign to cells that are not in a geometrical object of an architectural element. This should be a list with the same size asstrata
. The values should be angles in degree.bg_dip
: (required) Dip to assign to cells that are not in a geometrical object of an architectural element. This should be a list with the same size asstrata
. The values should be angles in degree.
[*element*]
sections for architectural elements¶
Sections that describe architectural elements are entitled with an identifying
name (e.g. [sparse_scour]
). Note that section names should not include
spaces. The first parameter to be set is the geometry
. The current
implementation of HyVR includes three geometries: troughs
(trough
), channels (channel
), and sheets (sheet
).
General [*element*]
parameters¶
geometry
: (required) Geometry of hydrofacies assemblages within architectural element, eithertrough
,channel
, orsheet
structure
: (required) Internal structure of hydrofacies assemblages. This can bemassive
ordip
. For truncated ellipsoidsbulb
,bulb_sets
, orrandom
are also possible.random
will randomly choose one of the 4 other options.dipset_dist
: (required if ``structure`` is ``dip``) Thickness of dipping internal structures.contact_model
(required) Contact model for the top contact surfaces of the architectural element. Similar to thestrata_contact_models
this should be a list starting with the type of the contact surface. However, no depth should be given. This means a flat contact model looks like this:[flat]
. A random contact model should look like this:[random, <variance>, <corl_x>, <corl_y>]
.dip
: (optional, default: [0,0]) Range of the uniform distribution from which the dip will be randomly drawn. This will be used if the internal structure ismassive
ordip
.azimuth
: (optional, default: [0,0]) Range of the uniform distribution from which the azimuth will be randomly drawn. This will be used if the internal structure ismassive
ordip
.facies
: (required) This should be a list of possible hydrofacies included in hydrofacies assemblage (the geometrical objects, e.g. the troughs). These should be names of facies that are listed in[hydraulics].hydrofacies
.altfacies
: (optional) Alternating facies specification. This is a list of lists where the outer list has the same length asfacies
. This assigns an alternating facies to each facies above. These will be used if the internal structure of an AE consists of alternating dipping layers. If we start with on facies for the alternating layers, then the next facies must be one of the respectivealtfacies
of this facies. If this is not given, the facies from above are chosen at random.size_ztrend
: (optional) Linear trend in geometry sizes with elevation. Given as a percentage change mulitplier in mean value from bottom to top of domain, i.e. \([\lambda_{bottom}, \lambda_{top}]\)k_ztrend
: (optional) Linear trend in isotropic hydraulic conductivity from bottom to top of domain \([\xi_{bottom},\xi_{top}]\)k_xtrend
: (optional) Linear trend in isotropic hydraulic conductivity from model inlet to outlet \([\xi_{inlet},\xi_{outlet}]\)n_ztrend
: (optional) Linear trend in porosity from bottom to top of domain \([\xi_{bottom},\xi_{top}]\)n_xtrend
: (optional) Linear trend in porosity from model inlet to outlet \([\xi_{inlet},\xi_{outlet}]\)
Erosive element-specific parameters (truncated_ellipsoid, extruded parabola)¶
agg
: (required) Aggradation thickness added between each generation elevation. This can be understood as the thickness of layers of geometrical objects, i.e. the thickness of a layer of troughs, or the distance between one channel and the next channel above.buffer
: (optional, default: 0.0) Buffer to reduce erosion of underlying units (see methods). This will start generating geometrical objects (i.e. troughs or channels) onlybuffer * depth
above the bottom surface.lag_height
: (optional, default: 0.0) It’s possible to include a lag surface at the bottom of the trough, which means that the trough/channel is filled up to this height with another hydrofacies (without dip).lag_facies
: (required if ``lag_height`` is not 0) Facies string with which to fill up the lag part.bg_facies
: (optional) Facies to assign to cells inside the element but not inside a geometrical object. If this is not given, the background value for the current stratum is used instead.bg_azim
: (optional) Azimuth to assign to cells inside the element but not inside a geometrical object. If this is not given, the background value for the current stratum is used instead.bg_dip
: (optional) Dip to assign to cells inside the element but not inside a geometrical object. If this is not given, the background value for the current stratum is used instead.
Trough parameters¶
trough_density
: (required) Number of elements to be simulated per simulation elevation and layer arealength
,width
,depth
: (required) Mean geometry of truncated ellipsoidspaleoflow
: (required) Range of the uniform distribution from which the paleoflow orientation will be randomly drawn. This is the direction into which the trough is elongated (i.e. thelength
axis). Formassive
anddip
troughs, theazimuth
angle will be added to the paleoflow angle.bulbset_dist
: (required only if ``structure`` is ``bulb_sets``) Thickness of nested-bulb structures at the maximum depth of the truncated ellipsoid.te_xyz
: (optional) List of 3D coordinated for manually setting the centrepoint of truncated ellipsoids. This should be a list of lists. The inner lists must have length 3. Example:te_xyz = [[0, 0, 0]]
. This option is mostly for debugging purposes.migrate
: (optional) Lateral migration of ellipsoid centrepoints drawn from a random normal distribution, given as mean and variance in \(x\) and \(y\) directions \([\overline{\Delta x}, \sigma^2_{\Delta x}, \overline{\Delta y}, \sigma^2_{\Delta y}]\).
Extruded parabola parameters¶
width
,depth
: (required) Mean geometry of channelh
: (required) Extruded parabola centreline curve shape parameterk
: (required) Extruded parabola centreline curve shape wave numberds
: (required) Distance between centreline points along trajectoryeps_factor
: (required) Variance of random fluctuations of channel centreline.channel_no
: (required) Number of Extruded parabolas to generate at each elevationmig
: (optional) Length scale on which the channel start should migrate between different levels.flow_angle
: (optional) Angle of mean flow with respect to the x-axis in degree. Will be 0 by default.
Sheet parameters¶
lens_thickness
- Thickness of individual sheets. If set to-1
then no individual sheets are generated within each sheet architectural element unit.
[hydraulics]
section¶
The input parameters in this section are associated with the simulation of hydraulic parameters. It is also possible to only simulate the geometries of architectural elements and hydrofacies if required.
hydrofacies
: (required) List of hydrofacies codesk_h
: Mean horizontal hydraulic conductivity. This must be either a float if it is the same for all hydrofacies, or a list of the same length ashydro
.sig_y
- Variance of log hydraulic conductivity. This must be either a float if it is the same for all hydrofacies, or a list of the same length ashydro
.ycorlengths
: (required) Default correlation lengths for \(\log(K_{iso})\) in each hydrofacies in \(x,y,z\)-directions. This can be either a single float, if it’s the same in all directions for all hydrofacies, a list of floats of length 3 if it’s the same for all hydrofacies, or a list of lists of floats, where the outer list has the same length ashydro
and the inner lists have length 3k_ratio
: (required) List of perpendicular anisotropy ratios (i.e \(\frac{K_h}{K_v}\)) or single value if it’s the same for all hydrofacies.n
: (required) List of mean porosity values or single value if it’s the same for all hydrofacies.sig_n
: (required) Variance of porosity values. List of floats or single float if it’s the same for all hydrofacies.ncorlengths
: (required) Default correlation lengths for porosity in each hydrofacies in \(x,y,z\)-directions This can be either a single float, if it’s the same in all directions for all hydrofacies, a list of floats of length 3 if it’s the same for all hydrofacies, or a list of lists of floats, where the outer list has the same length ashydro
and the inner lists have length 3
[flowtrans]
section¶
This section contains parameters to be used for groundwater flow and solute
transport simulations. This allows all input parameters for field generation and
subsequent modelling to be stored in the same .ini
file.
This section is only required if you want to have model output, e.g. ‘mf’, ‘mf6’
or ‘hgs’.
hin
: (required) boundary condition (head in). List of 3 floatshout
: (required) boundary condition (head out). List of 3 floats
HyVR outputs¶
Parameter field outputs¶
Model outputs include three-dimensional fields with values at each model grid cell for the following parameters:
Strata,
strata
- strata identifierArchitectural element
ae
- architectural element identifierHydrofacies assemblage
ha
- Unique identifiers for each hydrofacies assemblage/geometrical object generatedHydrofacies assemblage type
hat
- Type of hydrofacies assemblage generated, this corresponds to the elements sections in the ini-file.Hydrofacies
fac
- Type of hydrofaciesIsotropic hydraulic conductivity
k_iso
Dip
dip
- bedding parameterAzimuth
azim
- bedding parameterAnisotropy ratio
ani_rat
Porosity
poros
Full hydraulic conductivity tensor
ktensors
- based on isotropic hydraulic conductivity, dip, azimuth and anisotropy ratio (methods)
Output formats¶
HyVR has a number model outputs that can be set in the input parameter file. A
copy of the .ini
model parameter file is saved in the model directory
automatically. The following data output files include model outputs as
three-dimensional arrays:
dat
: Python ‘pickle’ file - this is a native Python format that can be loaded into Python usinghyvr.utils.load_pickle()
.mat
: MATLAB filevtr
: VTK rectilinear grid file - this can be opened in ParaView for improved three-dimensional visualisation.h5
: HDF5 formatnpz
: Numpy compressed format
HyVR can also create files that can be used as model inputs for some flow and transport modelling packages These currently include:
mf
: MODFLOW-2005 -bas
,dis
,lpf
,nam
,oc
, andpcg
model input files. Provided suitable flow and transport parameters are set in the[flowtrans]
section of the input parameter file, this simulation can be executed.mf6
: MODFLOW 6 -dis
,nam
, andnpf
model input files. A complete set of MODFLOW 6 input files cannot be generated in HyVR at this stage.hgs
: HydroGeoSphere - K tensors and porosity at each grid node.
Note that these model inputs can only have regular model grids. They have not been tested for use in the above-named packages.