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 in

    HyVR is included in its own section. Please see the subsection below for more information.

  • [hydraulics] - This section includes information for setting the hydraulic

    properties 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. If true 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. If false, 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. If dy or dz 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) If hydraulics is true, generate heterogeneous hydraulic parameters.

  • heterogeneity_level: (optional, default: internal) Hierarchical level at which heterogeneity should be simulated. Can be facies or internal. Will only be used if hydraulics and heterogeneity is set to true.

[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 the length(strata)-1. This should be understood as top contact for all but the last stratum in strata (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 and random. 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 as strata, the inner list can be of variable length. The elements of the inner lists must be strings from ae.

  • 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 as ae_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 as ssm_ae.

  • avul_prob: (required) Probability of avulsion. List of floats with the same length as strata.

  • avul: (required) Avulsion depth range. List of lists of floats. The outer list must have the same length as strata, 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 as strata. 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 as strata. 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 as strata. 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, either trough, channel, or sheet

  • structure: (required) Internal structure of hydrofacies assemblages. This can be massive or dip. For truncated ellipsoids bulb, bulb_sets, or random 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 the strata_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 is massive or dip.

  • 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 is massive or dip.

  • 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 as facies. 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 respective altfacies 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) only buffer * 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 area

  • length, width, depth: (required) Mean geometry of truncated ellipsoids

  • paleoflow: (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. the length axis). For massive and dip troughs, the azimuth 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 channel

  • h: (required) Extruded parabola centreline curve shape parameter

  • k: (required) Extruded parabola centreline curve shape wave number

  • ds: (required) Distance between centreline points along trajectory

  • eps_factor: (required) Variance of random fluctuations of channel centreline.

  • channel_no: (required) Number of Extruded parabolas to generate at each elevation

  • mig: (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 codes

  • k_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 as hydro.

  • 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 as hydro.

  • 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 as hydro and the inner lists have length 3

  • k_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 as hydro 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 floats

  • hout: (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 identifier

  • Architectural element ae - architectural element identifier

  • Hydrofacies assemblage ha - Unique identifiers for each hydrofacies assemblage/geometrical object generated

  • Hydrofacies assemblage type hat - Type of hydrofacies assemblage generated, this corresponds to the elements sections in the ini-file.

  • Hydrofacies fac - Type of hydrofacies

  • Isotropic hydraulic conductivity k_iso

  • Dip dip - bedding parameter

  • Azimuth azim - bedding parameter

  • Anisotropy 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 using hyvr.utils.load_pickle().

  • mat : MATLAB file

  • vtr : VTK rectilinear grid file - this can be opened in ParaView for improved three-dimensional visualisation.

  • h5 : HDF5 format

  • npz : 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, and pcg 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, and npf 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.