Setting and Running up dfnWorks ================================ Docker ------------------------------ The easiest way to get started with dfnWorks is using our docker container (https://hub.docker.com/r/ees16/dfnworks). If you do not already have Docker installed on your machine, visit `Getting Started with Docker `_. The dfnWorks Docker image can be pulled from DockerHub using: .. code-block:: bash $ docker pull ees16/dfnworks:latest Running the dfnWorks container ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The base command for running the dfnWorks container is: .. code-block:: bash docker run -ti ees16/dfnworks:latest However, to exchange files between the host and container, we will need to mount a volume. The option ``-v LOCAL_FOLDER:/dfnWorks/work`` will allow all files present in the container folder ``dfnWorks/work`` to be exposed to ``LOCAL_FOLDER``, where ``LOCAL_FOLDER`` is the absolute path to a folder on your machine. With this is place, the final command for running the Docker container is: **On macOS:** .. code-block:: bash docker run -ti -v :/dfnWorks/work dfnworks:latest Native build from github repository ------------------------------------------ This document contains instructions for setting up dfnWorks natively on your machine. To setup dfnWorks using Docker instead, see the next section. Clone the dnfWorks repository ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash $ git clone https://github.com/lanl/dfnWorks.git Fix paths in test directory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Fix the pathnames in files throughout pydfnworks. This can be done automatically by running the script ``fix_paths.py``: .. code-block:: bash $ cd dfnWorks/pydfnworks/bin/ $ python fix_paths.py Set the LagriT, PETSC, PFLOTRAN, Python, and FEHM paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Before executing dfnWorks,** the following paths must be set: - dfnWorks_PATH: the dfnWorks repository folder - PETSC_DIR and PETSC_ARCH: PETSC environmental variables - PFLOTRAN_EXE: Path to PFLOTRAN executable - PYTHON_EXE: Path to python executable - LAGRIT_EXE: Path to LaGriT executable .. code-block:: bash $ vi dfnWorks/pydfnworks/pydfnworks/paths.py For example: .. code-block:: python os.environ['dfnWorks_PATH'] = '/home/username/dfnWorks/' Alternatively, you can create a ``.dfnworksrc`` file in your home directory with the following format .. code-block:: bash { "dfnworks_PATH": "/src/dfnworks-main/", "PETSC_DIR": "/src/petsc", "PETSC_ARCH": "arch-darwin-c-debug", "PFLOTRAN_EXE": "/src/pflotran/src/pflotran/pflotran", "PYTHON_EXE": "/anaconda3/bin/python", "LAGRIT_EXE": "/bin/lagrit", "FEHM_EXE": "//src/xfehm_v3.3.1" } Setup the python package pydfnworks ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Go up into the pydfnworks sub-directory: .. code-block:: bash $ cd dfnWorks/pydfnworks/ **If the user has admin privelges**: .. code-block:: bash $ python setup.py install **If the user DOES NOT have admin priveleges**: .. code-block:: bash $ python setup.py install --user Installation Requirements for Native Build ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Tools that you will need to run the dfnWorks work flow are described in this section. VisIt and ParaView, which enable visualization of desired quantities on the DFNs, are optional, but at least one of them is highly recommended for visualization. CMake is also optional but allows faster IO processing using C++. Operating Systems ***************************** dfnWorks currently runs on Macs and Unix machine running Ubuntu. Python ***************************** pydfnworks uses Python 3. We recommend using the Anaconda 3 distribution of Python, available at https://www.continuum.io/. pydfnworks requires the following python modules: ``numpy``, ``h5py``, ``scipy``, ``matplotlib``, ``multiprocessing``, ``argparse``, ``shutil``, ``os``, ``sys``, ``networkx``, ``subprocess``, ``glob``, ``networkx``, ``fpdf``, and ``re``. LaGriT ****** The LaGriT_ meshing toolbox is used to create a high resolution computational mesh representation of the DFN in parallel. An algorithm for conforming Delaunay triangulation is implemented so that fracture intersections are coincident with triangle edges in the mesh and Voronoi control volumes are suitable for finite volume flow solvers such as FEHM and PFLOTRAN. .. _LaGriT: https://lagrit.lanl.gov PFLOTRAN ******** PFLOTRAN_ is a massively parallel subsurface flow and reactive transport code. PFLOTRAN solves a system of partial differential equations for multiphase, multicomponent and multi-scale reactive flow and transport in porous media. The code is designed to run on leadership-class supercomputers as well as workstations and laptops. .. _PFLOTRAN: http://pflotran.org FEHM **** FEHM_ is a subsurface multiphase flow code developed at Los Alamos National Laboratory. .. _FEHM: https://fehm.lanl.gov CMake ***************************** CMake_ is an open-source, cross-platform family of tools designed to build, test and package software. It is needed to use C++ for processing files at a bottleneck IO step of dfnWorks. Using C++ for this file processing optional but can greatly increase the speed of dfnWorks for large fracture networks. Details on how to use C++ for file processing are in the scripts section of this documentation. .. _CMake: https://cmake.org Paraview ***************************** Paraview_ is a parallel, open-source visualisation software. PFLOTRAN can output in ``.xmf`` and ``.vtk`` format. These can be imported in Paraview for visualization. While not required for running dfnWorks, Paraview is very helpful for visualizing dfnWorks simulations. Instructions for downloading and installing Paraview_ can be found at http://www.paraview.org/download/ .. _Paraview: http://www.paraview.org