hyvr 0.2

A python package for simulating hydrogeological virtual realities

====================================================================
Introduction
====================================================================

**HyVR: Turning your geofantasy into reality!**

The Hydrogeological Virtual Reality simulation package (HyVR) is a Python module
that helps researchers and practitioners generate subsurface models with
multiple scales of heterogeneity that are based on geological concepts. The
simulation outputs can then be used to explore groundwater flow and solute
transport behaviour. This is facilitated by HyVR outputs in common flow
simulation packages input formats. As each site is unique, HyVR has been
designed that users can take the code and extend it to suit their particular
simulation needs.

The original motivation for HyVR was the lack of tools for modelling sedimentary
deposits that include bedding structure model outputs (i.e., dip and azimuth).
Such bedding parameters were required to approximate full hydraulic-conductivity
tensors for groundwater flow modelling. HyVR is able to simulate these bedding
parameters and generate spatially distributed parameter fields, including full
hydraulic-conductivity tensors. More information about HyVR is available in the online `technical
documentation <https://driftingtides.github.io/hyvr/index.html>`_.

I hope you enjoy using HyVR much more than I enjoyed putting it together! I look
forward to seeing what kind of funky fields you created in the course of your
work.

Installing the HYVR package
--------------------------------------

Installing Python
^^^^^^^^^^^^^^^^^


Windows
"""""""

If you are using Windows, we recommend installing the `Anaconda distribution
<https://www.anaconda.com/download/>`_ of Python 3. This distribution has the
majority of dependencies that HyVR requires.

It is also a good idea to install the HyVR package into a `virtual environment
<https://conda.io/docs/user-guide/tasks/manage-environments.html>`_. Do this by
opening a command prompt window and typing the following::

python -m virtualenv hyvr_env

You need to then activate this environment::

call hyvr_env/scripts/activate


Linux
"""""

You probably already have Python 3 installed. If not, install it using your
package manager (e.g. ``apt`` on Ubuntu/Debian).

As with Windows we recommend using a virtual environment for HyVR in order
to reduce problems with different versions of the dependencies. A great tool for
managing virtual environments is `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/>`_.

Installing HyVR
^^^^^^^^^^^^^^^

Once you have activated your virtual environment, you can install HyVR from PyPI using ``pip``::

pip install hyvr

The version on PyPI should always be up to date. If it's not, you can also install HyVR from git::

git clone https://github.com/driftingtides/hyvr.git
pip install hyvr


Usage
-----

To use HyVR you have to create a configuration file with your settings.
You can then run HyVR the following way::

(hyvr_env) $ python -m hyvr my_configfile.ini

HyVR will then run and store all results in a subdirectory.

If you want to use HyVR in a script, you can import it and use the ``run`` function::

import hyvr
hyvr.run('my_configfile.ini')

Examples can be found in the ``testcases`` directory of the `github repository
<https://github.com/driftingtides/hyvr/>`_, the general setup and possible
options of the config-file is described in :ref:`HyVR inputs and outputs <inout>`.

Source
------
The most current version of HyVR will be available at this `github repository
<https://github.com/driftingtides/hyvr/>`_; a version will also be available on
the `PyPI index <https://pypi.python.org/pypi/hyvr/>`_ which can be installed
using ``pip``.


Requirements
------------

Python
^^^^^^
HyVR was developed for use with Python 3.4 or greater. It may be possible to use
with earlier versions of Python 3, however this has not been tested.

Dependencies
^^^^^^^^^^^^^^

* `scipy <https://www.scipy.org/scipylib/index.html>`_ = 1.0.0
* `pandas <https://pandas.pydata.org/>`_ = 0.21.0
* `numpy <http://www.numpy.org/>`_ <= 1.13.3
* `matplotlib <https://matplotlib.org/>`_ <= 2.1.0
* `flopy <https://github.com/modflowpy/flopy>`_ <= 3.2.8 (optional for modflow output)
* `pyevtk <https://pypi.python.org/pypi/PyEVTK>`_ = 1.1.0
* `cython <https://www.cython.org>`_


Development
-----------
You can contact the developer(s) of HyVR by `email
<mailto:[e-mail]>`_. HyVR is currently being developed by Jeremy
Bennett (`website <https://jeremypaulbennett.weebly.com>`_) as part of his
doctoral research at the University of Tübingen.


Problems, Bugs, Unclear Documentation
-------------------------------------

If you have problems with HyVR have a look at the `troubleshooting
<https://driftingtides.github.io/hyvr/troubleshooting.html>`_ section. If this
doesn't help, don't hesitate to contact us.

If you find that the documentation is unclear, lacking, or wrong, please contact
us.