source: branches/uq/lang/python/Rappture/pyxml.py @ 5410

# ----------------------------------------------------------------------
#  COMPONENT: PyXml - Python access to the Rappture XML library
#
# ======================================================================
#  AUTHOR:  Martin Hunt, Purdue University
#  Copyright (c) 2015  HUBzero Foundation, LLC
#
#  See the file "license.terms" for information on usage and
#  redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
# ======================================================================
from library import library
from result import result
import numpy as np
import itertools

"""
This library provides a simpler way to read and write Rappture
XML for Python tools.  It is backwards-compatible with the old
library API.

Motivation: The previous API was not pythonic.  Everything in an XML
file is text, but there is no reason the API cannot convert common
python type like tuples, lists, and arrays to text instead of requiring the
developer to do this.  Also, there were only two Python examples in
Rappture and they both converted numbers to strings and appended them
in a loop.  This is ugly and horribly inefficient.


Getting Started
===============

You must always open the xml file first. To use PyXML instead
of the old library API, you do this
>>> rx = Rappture.PyXML(sys.argv[1])
instead of
>>> lib = Rappture.library(sys.argv[1])


Reading Inputs
--------------
You can use the old syntax
>>> temp_str = rx.get('input.(temperature).current')
or the new
>>> temp_str = rx['input.(temperature).current'].value

Writing Outputs
---------------

All XML data must be converted to strings. However PyXML
will do this for you, allowing you to pass it lists and
arrays. Here is an example from the old app-fermi.py

(Important Note: Appending is extremely inefficient and
should never be done in a loop like this!)
>>> while E < Emax:
>>>     f = 1.0/(1.0 + exp((E - Ef)/kT))
>>>     line = "%g %g\n" % (f, E)
>>>     rx.put('output.curve(f12).component.xy', line, append=1)
>>>     E = E + dE

A more efficient example.
Here we pass PyXML a list containing two lists and
it serializes it for us.

>>> fermi = []
>>> energy = []
>>> while E < Emax:
>>>     energy.append(E)
>>>     fermi.append(1.0/(1.0 + exp((E - Ef)/kT)))
>>>     E = E + dE
>>> rx['output.curve(f12).component.xy'] = [fermi, energy]

PyXML takes tuples, lists, or numpy arrays and
serializes them into a string. In the above example
it would create a string like this:
"fermi[0] energy[0] fermi[1] energy[1] ..."
A numpy array with fermi in column 0 and energy in column 1
would have the same result.

If you are writing lots of outputs you probably have code like
>>> seq = 'output.sequence(stress-strain).element(%s)' % j
>>> rx.put(seq+'.curve(stress-strain).about.group', 'Stress-Strain Curve')

PyXML allows you to to simplify this by getting a node
and providing a path relative to that node.
>>> seq = rx['output.sequence(stress-strain).element(%s)' % j]
>>> seq['curve(stress-strain).about.group'] = 'Stress-Strain Curve'

or consider rewriting this from the old app-fermi example
>>> driver.put('output.curve(f12).about.label','Fermi-Dirac Factor',append=0)
>>> driver.put('output.curve(f12).xaxis.label','Fermi-Dirac Factor',append=0)
>>> driver.put('output.curve(f12).yaxis.label','Energy',append=0)
>>> driver.put('output.curve(f12).yaxis.units','eV',append=0)

becomes
>>> f12 = rx['output.curve(f12)']
>>> f12['about.label'] = 'Fermi-Dirac Factor'
>>> f12['xaxis.label'] = 'Fermi-Dirac Factor'
>>> f12['yaxis.label'] = 'Energy'
>>> f12['yaxis.units'] = 'eV'

Setting Non-String Values
-------------------------
Consider this code which sets the xml path "output/secret"
to the string "hello world"
>>> out = rx['output']
>>> out['secret'] = 'hello world'

What if you wanted to instead include the contents of a file?
You can still use the old API and it works with new nodes.

OLD (still works)
>>> rx.put('output.secret', 'results.txt', type='file')

NEW
>>> out.put('secret', 'results.txt', type='file')

What if you wanted the contents compressed to save space?
>>> out.put('secret', 'results.txt', type='file', compress=True)
"""


def PyXml(path):
    '''
    Open the Rappture xml file located at 'path' and return a node
    reference to the root.
    '''
    lib = library(path)
    return Node(lib, '')


class Node:
    def __init__(self, library, path):
        self.lib = library
        self.path = path

    def __setitem__(self, path, val):
        self.put(path, val)

    def __getitem__(self, path):
        if self.path != '':
            path = self.path + '.' + path
        return Node(self.lib, path)

    def get(self, path):
        return self.__getitem__(path).value

    def put(self, path, val, **kwargs):
        if self.path != '':
            path = self.path + '.' + path
        if type(val) == np.ndarray:
            val = ' '.join(map(str, val.ravel().tolist()))
        elif type(val) == list or type(val) == tuple:
            val = ' '.join(map(str, (itertools.chain(*zip(*val)))))
        self.lib.put(path, val, **kwargs)

    @property
    def value(self):
        return self.lib.get(self.path)

    def __str__(self):
        if self.path != '':
            return("['%s']" % self.path)
        return "root node"

    def __repr__(self):
        if self.path != '':
            return("%s['%s']" % (self.lib, self.path))
        return "root node on %s" % self.lib

    def copy(self, dest, src):
        return self.lib.copy(dest, src)

    def xml(self):
        return self.lib.xml()

    def close(self):
        result(self.lib)