Updating the pygeos documentation

Author: cssherman

pygeos_package/pygeos/pygeos_documentation.rst

@@ -2,42 +2,42 @@
 Python Input Processing: pygeos
 ###############################################################################
 
-Pygeos is a python-based module designed to construct input files for GEOSX.
-It allows users to create xml files that include child files, parameters, units, and symbolic math.
-It also includes helper-functions for validating input files and constructing tables. 
+Pygeos is a python module that enables advanced .xml features in GEOSX.
+It allows users to include child files, parameters, units, and symbolic math. 
 
 
 Setup
 =================================
-The pygeos module is located here: `src/coreComponents/python/modules/pygeos_package` .
-The module is compabitable with python 2/3, and its dependencies include the `numpy` and `lxml` packages.
-It can easily be installed using tools such as pip:
+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:
 
 `pip install src/coreComponents/python/modules/pygeos_package`
 
 
 Virtual Python Environment
 ---------------------------------
 
-On systems with a shared python installation, we reccomend that users install the package within a 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` .
 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
 
-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 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 load the python environment, run the following: `source ~/Python/virtual/geosx/bin/activate` .
-Within the environment, the commands `python` and `pip` will point to the correct versions.
-To exit the virtual environment, run the command: `deactivate` .
+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` ).
 
 
-XML Preprocessing
+
+Advanced XML Features
 =================================
 
-The xml preprocessor is designed to take an raw input file, and generate an new file that can be directly read by GEOSX.
+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.
 During the processing the order of operations are:
 
@@ -49,14 +49,29 @@ During the processing the order of operations are:
 
 
 
-Use Example
+Command-line Example
 ------------------------------
 
-`pygeos.preprocessGEOSXML(input, schema='')` is used to process the input xml.
-The name of the newly generated, preprocessed xml file will be returned by this function call.
-By default it will have the name 'prep_' + a randomly generated string.
+Pygeos can be called from the command line to process .xml files via the script.
+(Note: this be on your path if you are in a virtual environment.  Otherwise, it can be called directly from the bin directory of your python distribution.)
+The following will read a raw .xml file, generate a processed version, and return the new file name.
+
+pygeos input_file.xml
+
+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
+
+This can be embedded within a call to GEOSX:
+
+srun -n 16 geosx -i \`pygeos input_file.xml\`
+
+
+Script-based Example
+------------------------------
 
-The following is a example python script that will read process an xml file specified via the command line.
+The pygeos module can also be called from within a python script.  For example:
 
 .. code-block:: python
 
@@ -150,7 +165,7 @@ Examples:
 Symbolic Math
 ------------------------------
 Input xml files can also include symbolic mathematical expressions.
-These are indicated with curly braces, and use a python syntax.
+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.
 
@@ -166,64 +181,14 @@ Examples:
     <Parameter name='d' value='1.23E-4 [km**2]'/>
   </Parameters>
   <Nodesets>
-    <Nodeset name='perf' xmin='{$a$ - 0.2*$b$} -1e6 -1e6' xmax='{$c$**2 / $d$} 1e6 1e6' />
+    <Nodeset name='perf' xmin='`$a$ - 0.2*$b$` -1e6 -1e6' xmax='`$c$**2 / $d$` 1e6 1e6' />
   </Nodesets>
 
 
 Validation
 ------------------------------
-Unmatched special characters ($, [, }, etc.) mean that parameters, units, or symbolic math were not specified correctly.  
+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.
 
 
-
-Input Table Generation
-=================================
-
-The pygeos package also includes some tools to convert numpy arrays into GEOSX input tables, and vice-versa.
-
-The following example shows how to write a series of structrued tables using a list of spatial axes and a dictionary of table values:
-
-.. code-block:: python
-
-  import numpy as np
-  import pygeos
-
-  # Config
-  N = (10, 20, 30)
-
-  # Generate coordinate axes
-  # These correspond to each axis of the numpy tables
-  # The example function accepts up to four axes, and
-  # will assign them the names x, y, z, and t in order
-  spatial = [np.linspace(0, 1, N[0]),
-             np.linspace(0, 1, N[1]),
-             np.linspace(0, 1, N[2])]
-
-  # Generate the property dictionary
-  properties = {'random_variable_A': np.randn(N),
-                'random_variable_B': np.randn(N),
-                'random_variable_C': np.randn(N)}
-
-  # Write the tables
-  # The files will be written to the current directory,
-  # and will have the .txt extension
-  pygeos.writeGEOSTable(spatial, properties)
-
-
-The following shows how to read the geos tables written in the previous example:
-
-. code-block:: python
-
-  import numpy as np
-  import pygeos
-
-  spatial_names = ['x', 'y', 'z']
-  property_names = ['random_variable_A', 'random_variable_B', 'random_variable_C']
-
-  spatial, properties = pygeos.readGEOSTable(spatial_names, property_names)
-
-
-
-