.. _inout: ========================================================== 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 :ref:`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, ]``. 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, , , , ]``. - ``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, , , ]``. - ``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. :math:`[\lambda_{bottom}, \lambda_{top}]` - ``k_ztrend``: *(optional)* Linear trend in isotropic hydraulic conductivity from bottom to top of domain :math:`[\xi_{bottom},\xi_{top}]` - ``k_xtrend``: *(optional)* Linear trend in isotropic hydraulic conductivity from model inlet to outlet :math:`[\xi_{inlet},\xi_{outlet}]` - ``n_ztrend``: *(optional)* Linear trend in porosity from bottom to top of domain :math:`[\xi_{bottom},\xi_{top}]` - ``n_xtrend``: *(optional)* Linear trend in porosity from model inlet to outlet :math:`[\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 :ref:`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. .. _teparams: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 :math:`x` and :math:`y` directions :math:`[\overline{\Delta x}, \sigma^2_{\Delta x}, \overline{\Delta y}, \sigma^2_{\Delta y}]`. .. _chparams: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. .. _shparams: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 :math:`\log(K_{iso})` in each hydrofacies in :math:`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 :math:`\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 :math:`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 .. _modelout: ----------------------------------- 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 (:ref:`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.