merged with develop

Author: Francois Hamon

pygeos_package/pygeos/__init__.py

@@ -1,11 +1,3 @@
-
-__version__ = '0.3.1'
-
-
-from .regex_config import regexConfig, symbolicMathRegexHandler, parameterHandler, DictRegexHandler
-from .unit_manager import unitManager 
-from .xml_processor import preprocessGEOSXML, validateXML
-from .table_generator import writeGEOSTable, readGEOSTable
-from .test_manager import runUnitTests
-from .format_xml import format_xml_file
-
+"""@package pygeos
+A python module that enables advanced xml features for GEOSX.
+"""

pygeos_package/pygeos/__main__.py

@@ -1,9 +1,18 @@
+"""Command line tools for pygeos"""
 
 import argparse
-from pygeos import preprocessGEOSXML
+from pygeos import xml_processor
 
 
 def main():
+  """Entry point for the pygeos console script
+
+  @arg input Input file name
+  @arg -o/--output Output filename (default = randomly generated string)
+  @arg -s/--schema GEOSX schema to use for validating the generated xml
+  @arg -v/--verbose Verbosity level
+  """
+
   # Parse the user arguments
   parser = argparse.ArgumentParser()
   parser.add_argument('input', type=str, help='Input file name')
@@ -13,10 +22,10 @@ def main():
   args = parser.parse_args()
 
   # Process the xml file
-  output_name = preprocessGEOSXML(args.input,
-                                  outputFile=args.output,
-                                  schema=args.schema,
-                                  verbose=args.verbose)
+  output_name = xml_processor.process(args.input,
+                                      outputFile=args.output,
+                                      schema=args.schema,
+                                      verbose=args.verbose)
 
   print(output_name)
 

pygeos_package/pygeos/format_xml.py

@@ -8,7 +8,7 @@ It allows users to include child files, parameters, units, and symbolic math.
 
 Setup
 =================================
-The pygeos module is located in the GEOSX repository: `src/coreComponents/python/modules/pygeos_package` .
+The pygeos module is located in the GEOSX repository: `src/coreComponents/python/modules/pygeos_package`.
 The module is compabitable with python 2/3, and depends on the `lxml`, `numpy`, and `re` packages.
 It can be installed into an existing python distribution via pip:
 
@@ -19,18 +19,18 @@ Virtual Python Environment
 ---------------------------------
 
 On systems with a shared python installation, we recommend that users install the package within a virtual python environment.
-A script designed to automatically setup a virtual environment, install the dependencies, and install pygeos is included in `scripts/setupVirtualPythonEnvironment.bash` .
+A script designed to automatically setup a virtual environment, install the dependencies, and install pygeos is included in `scripts/setupVirtualPythonEnvironment.bash`.
 The options for the script include:
 
-- -p/--python_root : This specifies the root path for the parent python environment
-- -o/--output_path : This specifies location where the virtual environment will be installed
+- ``-p/--python_root``: This specifies the root path for the parent python environment
+- ``-o/--output_path``: This specifies location where the virtual environment will be installed
 
-The default settings for the script will build a virtual environment for the python-3.6.4 installation on LC systems, and will place the environment in `~/Python/virtual/geosx` .  The script will also install pygeos and its pre-requisites.
+The default settings for the script will build a virtual environment for the python-3.6.4 installation on LC systems, and will place the environment in `~/Python/virtual/geosx`.  The script will also install pygeos and its pre-requisites.
 
 To use the virtual environment, do one of the following:
 
-1) Load the startup script: `source ~/Python/virtual/geosx/bin/activate` .  This will add the (geosx) decorator to your shell, and will set the proper aliases for python, pip, etc.  To exit the environment, run `deactivate`.
-2) Access the bin directory of the virtual python environment directly (e.g. `~/Python/virtual/geosx/bin/python some_script.py` ).
+1) Load the startup script: `source ~/Python/virtual/geosx/bin/activate`.  This will add the (geosx) decorator to your shell, and will set the proper aliases for python, pip, etc.  To exit the environment, run `deactivate`.
+2) Access the bin directory of the virtual python environment directly (e.g. `~/Python/virtual/geosx/bin/python some_script.py`).
 
 
 
@@ -51,9 +51,9 @@ The following will read a raw .xml file, generate a processed version, and retur
 
 Optional arguments 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
+- ``-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 GEOSX arguments:
 
@@ -78,11 +78,11 @@ The pygeos module can also be called from within a python script.  For example:
 Advanced XML Features
 =================================
 
-The xml preprocessor in pygeos is designed to take an raw input file, and generate an new file that can be directly read by GEOSX.
-The syntax for the advanced xml format is given below.
+The xml preprocessor in pygeos 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
+1) Merging any included XML files into the root structure
 2) Substituting in any parameters
 3) Evaluating unit strings
 4) Evaluating symbolic math
@@ -95,10 +95,11 @@ XML inputs can point to included children (these children can then include grand
 During processing, these are recursively inserted into the root XML structure by the following scheme:
 
 - Merge two objects if:
-    - At the root level and an object with the matching tag exists.
-    - If the “name” attribute is present and a object with the matching tag and name exist.
+
+    - 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.
+- Otherwise append the XML structure with the target.
 
 
 .. code-block:: xml
@@ -112,8 +113,8 @@ During processing, these are recursively inserted into the root XML structure by
 
 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.
+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:
 
@@ -124,7 +125,7 @@ Parameters may have any value:
 - Etc.
 
 
-They can be used in any field within in the xml file (except in Includes) as follows:
+They can be used in any field within in the XML file (except in Includes) as follows:
 
 - $x_par
 - $:x_par
@@ -150,8 +151,8 @@ 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].
+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.
 
 
@@ -170,7 +171,7 @@ Examples:
 
 Symbolic Math
 ------------------------------
-Input xml files can also include symbolic mathematical expressions.
+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 by removing any residual alpha characters, but this can be relaxed if more complicated function are needed.
@@ -195,6 +196,6 @@ 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 required field are present, and that input parameters match their expected types.
+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/pygeos_documentation.rst

@@ -0,0 +1,75 @@
+"""Tools for managing regular expressions in pygeos"""
+
+import re
+
+
+# Define regex patterns used throughout the module:
+#
+# Pattern         |  Example targets             | Notes
+# ------------------------------------------------------------------------------------
+# parameters      | $Parameter, $Parameter$      | Matches entire parameter string
+# units           | 9.81[m**2/s],  1.0 [bbl/day] | Matches entire unit string
+# units_b         | m, bbl, day                  | Matches unit names
+# symbolic        | `1 + 2.34e5*2`               | Matches the entire symbolic string
+# sanitize        |                              | Removes any residual characters before
+#                 |                              |       evaluating symbolic expressions
+# strip_trailing  | 3.0000, 5.150050             | Removes unnecessary float strings
+# strip_trailing_b| 3.0000e0, 1.23e0             | Removes unnecessary float strings
+#
+patterns = {'parameters': r"\$:?([a-zA-Z_]*)\$?",
+            'units': r"([0-9]*?\.?[0-9]+(?:[eE][-+]?[0-9]*?)?)\ *?\[([-+.*/()a-zA-Z0-9]*)\]",
+            'units_b': r"([a-zA-Z]*)",
+            'symbolic': r"\`([-+.*/() 0-9eE]*)\`",
+            'sanitize': r"[a-z-[e]A-Z-[E]]",
+            'strip_trailing': r"\.?0+(?=e)",
+            'strip_trailing_b': r"e\+00|\+0?|(?<=-)0"}
+
+# String formatting for symbolic expressions
+symbolic_format = '%1.6e'
+
+
+def SymbolicMathRegexHandler(match):
+  """Evaluate symbolic expressions that are identified using the regex_tools.patterns['symbolic'].
+
+     @param match A matching string identified by the regex.
+  """
+  k = match.group(1)
+  if k:
+    # Sanitize the input
+    sanitized = re.sub(patterns['sanitize'], '', k).strip()
+    value = eval(sanitized, {'__builtins__': None})
+
+    # Format the string, removing any trailing zeros, decimals, etc.
+    str_value = re.sub(patterns['strip_trailing'], '', symbolic_format % (value))
+    str_value = re.sub(patterns['strip_trailing_b'], '', str_value)
+    return str_value
+  else:
+    return
+
+
+class DictRegexHandler():
+  """This class is used to substitute matched values with those stored in a dict."""
+
+  def __init__(self):
+    """Initialize the handler with an empty target list.
+       The key/value pairs of self.target indicate which values
+       to look for and the values they will replace with.
+    """
+    self.target = {}
+
+  def __call__(self, match):
+    """Replace the matching strings with their target.
+
+       @param match A matching string identified by the regex.
+    """
+
+    k = match.group(1)
+    if k:
+      if (k not in self.target.keys()):
+          raise Exception('Error: Target (%s) is not defined in the regex handler' % k)
+      value = self.target[k]
+      return str(value)
+    else:
+      return
+
+