Add sesame-extract clt; update README; update setup.py

sesame-extract is a command line tool that extracts individual
materials from SESAME tables based on material ID. opac-error
and opac-convert have unexpected behavior when opening
SESAME files with very many materials, and so sesame-extract
addresses this issue by creating files with only a single
material. Information regarding this issue and some sesame-extract
usage examples were added to the README. A link to the script for
the command line tools was added to setup.py.

README.md

@@ -78,6 +78,14 @@ Example output from `opac-convert` may be found in the [wiki](https://github.com
 
 ---
 
+### Warning About the SESAME Database
+
+Many SESAME EoS files have multiple materials. To ensure conversion accuracy,
+it is important that the SESAME file must have only one material. In order to aid in the process
+of extracting one material's table from an entire SESAME document, included in the command line tools
+of `opacplot2` is `sesame-extract`, which will extract a single material table from a SESAME
+document based on the material ID.
+
 <a name="opac-convert"></a>
 # opac-convert
 
@@ -244,4 +252,23 @@ See the [wiki](https://github.com/flash-center/opacplot2/wiki).
 
 First, `opac-convert` takes a conservative intersection of the two dens/temp grids from each file.
 Then it linearly interpolates the data from both files onto the intersection dens/temp grids.
- Using the interpolated data, it is able to create an error report.
+ Using the interpolated data, it is able to create an error report.
+
+
+<a name="sesame-extract"></a>
+# sesame-extract
+
+### Usage
+
+Check syntax possibilities:
+
+```bash
+python sesame_extract.py -h
+```
+
+Extract water (SESAME element 7150 - see the publicly available PDF) information
+from the 160 MB SESAME ASCII file, and save it into "water.ses":
+
+```bash
+python sesame_extract.py -o "./water.ses" "$HOME/SESAME/sesame-ec/sesame_ascii" 7150
+```

opacplot2/scripts/sesame_extract.py

@@ -0,0 +1,76 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+"""
+sesame_extract.py Extract single table from the SESAME ASCII file and write into a separate file 
+
+Created by JT Laune on Jan 26, 2017 for the Flash Center for Computational Science
+  for use in managing the Flash Center's SESAME tables, and for development of opacplot2.
+
+Simple enough to be hopefully functional in both Python 2.x and Python 3.x.
+
+Example usage:
+  # Check syntax possibilities
+  python sesame_extract.py -h
+  
+  # Extract water (SESAME element 7150 - see the publicly available PDF) information
+  #   from the 160 MB SESAME ASCII file, and save it into "water.ses"
+  python sesame_extract.py -o "./water.ses" "$HOME/SESAME/sesame-ec/sesame_ascii" 7150
+
+CHANGELOG:
+  2017-01-27 Tested by Scott Feister in Python 2.7.12; successfully extracted H2O from sesame_ascii
+             Added lots of comment lines -SKF
+
+TODO:
+  * Complementary function would call "Opacplot2" to print a summary of file contents
+"""
+
+import argparse
+
+def get_input_data():
+    """ Parse command syntax for arguments, and provide help ('-h') option. """
+    parser = argparse.ArgumentParser(
+                description='This script is used to extract single '
+                            'SESAME tables from the SESAME database.')
+    parser.add_argument('database', action='store', type=str,
+                        help='Database file name.')
+    parser.add_argument('tabnum', action='store', type=str,
+                        help='SESAME table number.')
+    parser.add_argument('-o', '--output', action='store', type=str,
+                        help='Output file name.')
+
+    args = parser.parse_args()
+
+    if args.output is None:
+        args.output = '{}_{}.ses'.format(args.database[:-4], args.tabnum)
+    return args
+
+def find_table(f_out, fhand, tabnum):
+    """ Seek file cursor position to the material of interest """
+    while True:
+        line = fhand.readline()
+        if not line: raise Warning('Table not found') # Reached EOF.
+        if line[:3] == " 2 ": raise Warning('Table not found') 
+        if line.split()[0] == '0':
+            if str(line.split()[1]) == tabnum:
+                f_out.write(line)
+                break # Advanced fhand far enough
+
+def write_entries(f_out, fhand):
+    """ Copy lines into output file until another material is reached """
+    while True:
+        line = fhand.readline()
+        if not line: break # Reached EOF.
+        if line.split()[0] == '0': break # Reached another material.
+        f_out.write(line)
+
+def extract_tables():
+    """ Extract single table from the SESAME ASCII file and write into a separate file """ 
+    args = get_input_data()
+    with open(args.output, 'w') as f_out:
+        with open(args.database, 'r') as fhand:
+            find_table(f_out, fhand, args.tabnum)
+            write_entries(f_out, fhand)
+
+
+if __name__=='__main__':
+    extract_tables()

setup.py

@@ -25,6 +25,8 @@
 
           entry_points = {
                     'console_scripts': ['opac-convert = opacplot2.scripts.opac_convert:convert_tables',
-                                        'opac-error = opacplot2.scripts.opac_error:check_error'],
+                                        'opac-error = opacplot2.scripts.opac_error:check_error',
+                                        'sesame-extract = opacplot2.scripts.sesame_extract:extract_tables'
+                                        ],
                         }
           )