Add advanced xml input examples, function tests (#990)

* Adding a complex hydraulic fracturing example

* Adding integrated test that uses heterogeneous in-situ properties

* Adding setters to functions for testing

* Adding a simple 1D table function unit test

* Adding 2D and 4D table unit tests

* Adding a symbolic function unit test

* Updating the new heterogeneous hf example

* Fixing a bug in the event restart dt calculation

* Adding a target to build pygeos using the same python executable as cmake

* Updating the pygeos build target

* Starting to write a hf tutorial

* Modifying the heterogeneous hydrofracture example

* Updating the pygeos cmake target

* Changing the xml formatting cmake target depend on pygeos build

* Updating pygeos git targets to prevent re-building of virtualenv

* Formatting new xml files

* Changing the name of pygeos to geosx_xml_tools to generalize, avoid future conflicts

* Updating numerical methods block in new function example xml files

* Adding a script-based entry into the xml formatter, applying it after xml processing

* Installing the hdf5_wrapper package into the default virtual environment

Author: cssherman

geosx_xml_tools_package/.gitignore

@@ -0,0 +1,2 @@
+build
+*.egg-info

pygeos_package/pygeos/__init__.py …ools_package/geosx_xml_tools/__init__.pypygeos_package/pygeos/__init__.py renamed to geosx_xml_tools_package/geosx_xml_tools/__init__.py pygeos_package/pygeos/__init__.py renamed to geosx_xml_tools_package/geosx_xml_tools/__init__.py

@@ -1,3 +1,3 @@
-"""@package pygeos
+"""@package geosx_xml_tools
 A python module that enables advanced xml features for GEOSX.
 """

pygeos_package/pygeos/__main__.py …ools_package/geosx_xml_tools/__main__.pypygeos_package/pygeos/__main__.py renamed to geosx_xml_tools_package/geosx_xml_tools/__main__.py pygeos_package/pygeos/__main__.py renamed to geosx_xml_tools_package/geosx_xml_tools/__main__.py

@@ -1,11 +1,11 @@
-"""Command line tools for pygeos"""
+"""Command line tools for geosx_xml_tools"""
 
 import argparse
-from pygeos import xml_processor
+from geosx_xml_tools import xml_processor
 
 
 def main():
-  """Entry point for the pygeos console script
+  """Entry point for the geosx_xml_tools console script
 
   @arg input Input file name
   @arg -o/--output Output filename (default = randomly generated string)

geosx_xml_tools_package/geosx_xml_tools/geosx_xml_tools_documentation.rst

@@ -0,0 +1,228 @@
+
+.. _advanced_xml_features:
+
+###############################################################################
+Advanced XML Features (geosx_xml_tools)
+###############################################################################
+
+geosx_xml_tools is a python module that enables advanced xml features in GEOSX (parameters, units, symbolic math, etc.), and is used to format xml files.
+
+
+Setup
+=================================
+
+The `geosx_xml_tools` package can be installed using the following command within the GEOSX build directory:
+
+`make geosx_xml_tools`
+
+During the installation step, two console scripts will be created: `preprocess_xml` and `format_xml`.
+These will be located within the GEOSX build/bin directory.
+Additional things to consider: 
+
+- The above make command will create a new virtual python environment to install the package.  By default, the source python environment will be the the version used to run the `config-build.py` command.  The version of python can be changed by specifying the `PYTHON_POST_EXECUTABLE` variable.  To build the environment, the `virtualenv` package must be installed in the source distribution.
+- The `geosx_xml_tools` package depends on the `lxml` package. If `lxml` is missing from the parent environment, the install script will attempt to fetch an appropriate version from the internet.
+- The package may also be manually installed within an existing python distribution (this required administrative priviliges) via pip: `pip install src/coreComponents/python/modules/geosx_xml_tools_package`.  In this case, the console scripts will be located in the python/bin directory
+
+
+Usage
+=================================
+
+geosx_xml_tools can be used via the command-line or can be imported into a python script.
+
+
+Command-line xml formatting
+------------------------------
+
+The following command will update the formatting of an existing xml file in-place:
+
+`format_xml input_file.xml`
+
+To update the formatting for all xml files located within the GEOSX repository, you can run the following command within the GEOSX build directory:
+
+`make geosx_format_all_xml_files`
+
+
+Command-line xml preprocessing
+------------------------------
+
+The following command will read an xml file, process any advanced xml features located within it, and write a new file that can be read by GEOSX:
+
+`preprocess_xml input_file.xml`
+
+The script returns the (randomly generated) name of the new xml file.
+Optional arguments for this script include:
+
+- `-o/--output`: The desired name for the output file (otherwise, it is randomly generated)
+- `-s/--schema`: The location of a schema to validate the final .xml file
+- `-v/--verbose`: Increase module verbosity
+
+For convenience, this script can be embedded within a call to GEOSX:
+
+`srun -n 16 geosx -i \`preprocess_xml input_file.xml\` -x 4 -z 4`
+
+
+Script-based Example
+------------------------------
+
+The geosx_xml_tools module can also be called from within a python script.  For example:
+
+.. code-block:: python
+
+  from geosx_xml_tools import xml_processor
+
+  initial_filename = 'input.xml'
+  new_filename = output_name = xml_processor.process(initial_filename)
+
+
+
+Advanced XML Features
+=================================
+
+The xml preprocessor in geosx_xml_tools is designed to take a raw input file, and generate a new file that can be directly read by GEOSX.
+The syntax for the advanced XML format is given below.
+During the processing the order of operations are:
+
+1) Merging any included XML files into the root structure
+2) Substituting in any parameters
+3) Evaluating unit strings
+4) Evaluating symbolic math
+5) Error checking and validation
+
+
+Including Child XML Files
+------------------------------
+XML inputs can point to included children (these children can then include grandchildren and so on).
+During processing, these are recursively inserted into the root XML structure by the following scheme:
+
+- Merge two objects if:
+
+    - At the root level an object with the matching tag exists.
+    - If the "name" attribute is present and an object with the matching tag and name exists.
+    - Any preexisting attributes are overwritten by the donor.
+- Otherwise append the XML structure with the target.
+
+
+.. code-block:: xml
+
+  <Included>
+    <File name='/path/to/included_a.xml'/>
+    <File name='/path/to/included_b.xml'/>
+  </Included>
+
+
+
+Parameters
+------------------------------
+Parameters are a convenient way to build a configurable and human-readable input XML.
+They are defined via a block in the XML structure.
+Parameter names may only include upper/lower case letters and underscores (to avoid conflicts with symbolic math).
+Parameters may have any value:
+
+- Path to a file
+- Numbers
+- A symbolic expression
+- Other parameters
+- Etc.
+
+
+They can be used in any field within in the XML file (except in Includes) as follows:
+
+- $x_par$  (preferred)
+- $x_par
+- $:x_par
+- $:x_par$
+
+
+For Example:
+
+.. code-block:: xml
+
+  <Parameters>
+    <Parameter
+      name="mu"
+      value="0.005"/>
+    <Parameter
+      name="table_root"
+      value="/path/to/table/root"/>
+  </Parameters>
+  
+  <Constitutive>
+    <CompressibleSinglePhaseFluid
+      name="water"
+      defaultDensity="1000"
+      defaultViscosity="$mu$"
+      referencePressure="0.0"
+      referenceDensity="1000"
+      compressibility="5e-10"
+      referenceViscosity="$mu$"
+      viscosibility="0.0"/>
+  </Constitutive>
+
+  <Functions>
+    <TableFunction
+      name="flow_rate"
+      inputVarNames="{time}"
+      coordinateFiles="{$table_root$/time_flow.geos}"
+      voxelFile="$table_root$/flow.geos"
+      interpolation="linear"/>
+  </Functions>
+
+
+
+Units
+------------------------------
+By default, input values are specified using SI units.
+In some cases, it is useful to override this behavior by explicitly specifying the units of the input.
+These are specified by appending a valid number with a unit definition in square braces.
+The unit manager supports most common units and SI prefixes, using both long- and abbreviated names (e.g.: c, centi, k, kilo, etc.).
+Units may include predefined composite units (dyne, N, etc.) or may be built up from sub-units using a python syntax (e.g.: [N], [kg*m/s**2]).
+Any (or no) amount of whitespace is allowed between the number and the unit bracket.
+
+
+Examples:
+
+.. code-block:: xml
+
+  <Parameters>
+    <Parameter name='a' value='2[m]'/>
+    <Parameter name='b' value='1.2 [cm]'/>
+    <Parameter name='c' value='1.23e4 [bbl/day]'/>
+    <Parameter name='d' value='1.23E-4 [km**2]'/>
+  </Parameters>
+
+
+
+Symbolic Math
+------------------------------
+Input XML files can also include symbolic mathematical expressions.
+These are placed within pairs of backticks (\`), and use a python syntax.
+Parameters and units are evaluated before symbolic expressions.
+Note: symbolic expressions are sanitized before by removing any residual alpha characters, but this can be relaxed if more complicated function are needed.
+Also, while symbolic expressions are allowed within parameters, errors may occur if these are used in a way that leads to nested symbolic expressions.
+
+
+Examples:
+
+.. code-block:: xml
+
+  <Parameters>
+    <Parameter name='a' value='2[m]'/>
+    <Parameter name='b' value='1.2 [cm]'/>
+    <Parameter name='c' value='1.23e4 [bbl/day]'/>
+    <Parameter name='d' value='1.23E-4 [km**2]'/>
+  </Parameters>
+  <Geometry>
+    <Box
+      name='perf'
+      xMin='`$a$ - 0.2*$b$`, -1e6, -1e6'
+      xMax='`$c$**2 / $d$`, 1e6, 1e6' />
+  </Geometry>
+
+
+Validation
+------------------------------
+Unmatched special characters ($, [, \`, etc.) mean that parameters, units, or symbolic math were not specified correctly.  
+If the code detects these, it will throw an error.
+The XML is validated against the input schema to check if all of the requireds field are present, and that input parameters match their expected types.
+
+

pygeos_package/pygeos/regex_tools.py …s_package/geosx_xml_tools/regex_tools.pypygeos_package/pygeos/regex_tools.py renamed to geosx_xml_tools_package/geosx_xml_tools/regex_tools.py pygeos_package/pygeos/regex_tools.py renamed to geosx_xml_tools_package/geosx_xml_tools/regex_tools.py

@@ -1,4 +1,4 @@
-"""Tools for managing regular expressions in pygeos"""
+"""Tools for managing regular expressions in geosx_xml_tools"""
 
 import re
 

pygeos_package/pygeos/table_generator.py …ckage/geosx_xml_tools/table_generator.pypygeos_package/pygeos/table_generator.py renamed to geosx_xml_tools_package/geosx_xml_tools/table_generator.py pygeos_package/pygeos/table_generator.py renamed to geosx_xml_tools_package/geosx_xml_tools/table_generator.py

@@ -2,8 +2,8 @@
 import re
 import os
 import filecmp
-from pygeos import regex_tools, unit_manager, xml_processor
-from pygeos.tests import generate_test_xml
+from geosx_xml_tools import regex_tools, unit_manager, xml_processor
+from geosx_xml_tools.tests import generate_test_xml
 
 
 # Create an instance of the unit manager
@@ -235,8 +235,9 @@ def setUpClass(cls):
     # Create a directory to hold tests
     cls.pwd = os.getcwd()
     rand_name = xml_processor.generate_random_name(suffix='')[:10]
-    os.makedirs('./pygeos_tests_%s/included' % (rand_name), exist_ok=True)
-    os.chdir('./pygeos_tests_%s' % (rand_name))
+    # os.makedirs('./geosx_xml_tools_tests_%s/included' % (rand_name), exist_ok=True)
+    os.makedirs('./geosx_xml_tools_tests_%s/included' % (rand_name))
+    os.chdir('./geosx_xml_tools_tests_%s' % (rand_name))
 
     # Generate test xml files to process
     generate_test_xml.generate_test_xml_files('.')

pygeos_package/pygeos/tests/__init__.py …ackage/geosx_xml_tools/tests/__init__.pypygeos_package/pygeos/tests/__init__.py renamed to geosx_xml_tools_package/geosx_xml_tools/tests/__init__.py pygeos_package/pygeos/tests/__init__.py renamed to geosx_xml_tools_package/geosx_xml_tools/tests/__init__.py

@@ -1,7 +1,7 @@
 """Tools for managing units in GEOSX"""
 
 import re
-from pygeos import regex_tools
+from geosx_xml_tools import regex_tools
 
 
 class UnitManager():