Rappture Python API
This page describes how to use Rappture with the python language.
Summary:
import Rappture;
library Class
This module provides an interface to Rappture I/O (RpLibrary) library.
Constructor
lib = Rappture.library( path )
Methods
lib.get( path, decode )
lib.put( path, value, id, append, type, compress )
lib.result( status )
Units Class
This module provides an interface to Rappture Units (RpUnits) library.
Static Methods
Rappture.Units.convert( fromVal, to, units )
encoding Module
This module provides an interface to Rappture Encode (zlib and base64 encoding) library.
Static Methods
Rappture.encoding.isbinary( string )
Rappture.encoding.encode( string, flags )
Rappture.encoding.decode( string, flags )
Utils Module
This module provides an interface to Rappture Utils Library
Static Methods
Rappture.Utils.progress( percent, message )
Detail:
Rappture.library (path)
Purpose:
Create a Rappture I/O object using the xml file located at path as the object reference.
Input Arguments:
- path - path of xml file to be opened with Rappture.
Return Value:
Rappture I/O object referencing path as its library.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
import sys
import Rappture
driver = Rappture.library("driver.xml")
if (driver != None):
print "Successfully opened a Rappture Library Object\n"
else:
print "Creating a Rappture Library Object from driver.xml failed\n"
sys.exit()
# Result:
# Successfully opened a Rappture Library Object
instance.get( path, decode )
Purpose:
Retrieve the data held at the xml location path from this object.
Input Arguments:
- path - xml path (location) of the element to be retrieved.
- decode - True/False? flag. uncompress data before returning it to the user. flag defaults to True
Return Value:
On success, a string with the value stored at xml location path of this object. On failure, None is returned.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
import sys
import Rappture
driver = Rappture.library("driver.xml")
Ef = driver.get("input.number(Ef).current")
if (Ef != None):
print "Ef = %s\n" % (Ef)
else:
print "Failed to retrieve \'input.number(Ef).current\' from driver.xml\n"
sys.exit()
# Result:
# Ef = 3eV
instance.put( path, value, id, append, type, compress )
Purpose:
Place data value into this object at the xml location path. If the append flag is set to 1, then value will be appended to data that already exists at path. If the append flag is set to False, then value will overwrite data that may have existed at path. The input id is deprecated and will be ignored. If it is used, it should be set to None.
Input Arguments:
- path - xml path (location) to store value.
- value - data to store in this object.
- id - deprecated. Set to None.
- append - overwrite flag (True or False). if set to False, data at path will be overwritten. if set to True, data will be appended.
- type - may be set to "string" or "file". flag defaults to "string". when set to "file", data within the file is stored at path.
- compress - may be set to True or False. flag defaults to False. when set to True, data is gzip compressed and mime (base64) encoded.
Return Value:
No value is returned.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
import sys
import Rappture
driver = Rappture.library("driver.xml")
print "Overwrite:\n"
driver.put("input.number(Ef).current", "6", append=0)
Ef = driver.get("input.number(Ef).current")
print "Ef = %s" % (Ef)
print "\n"
print "Append:\n"
driver.put("input.number(Ef).current", "eV", append=1)
Ef = driver.get("input.number(Ef).current")
print "Ef = %s" % (Ef)
sys.exit()
# Result:
#
# Overwrite:
# Ef = 6
#
# Append:
# Ef = 6eV
instance.result( status )
Purpose:
Write the data from Rappture Library object instance to file and signal the end of processing to the graphical user interface.
Input Arguments:
- status - integer representing the success or failure of the application. 0 for success, any other number is failure.
Return Value:
No value is returned.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
import sys
import Rappture
driver = Rappture.library("driver.xml")
driver.put("input.number(Ef).current", "6", append=0)
driver.result(status=0)
sys.exit()
# Result:
# A run.xml file is created and the Rappture Graphical User Interface is signaled that processing has ended.
Rappture.Units.convert( fromVal, to, units )
Purpose:
Convert the string fromVal, containing a numeric value and optional units, to the units specified in the to argument. If the units flag is set to "off", a double precision value is returned, else a string with units appended to the end is returned.
Input Arguments:
- fromVal - String with numeric portion and optional units (ie. "3m" or "3").
- to - String name of the units you want to convert to.
- units - "on" or "off" to tell if you want units to show up in the result.
Return Value:
Return converted value as a string or double depending on units flag. Return None on failure. units are set to "on" by default.
Notes:
- .
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
import sys
import Rappture
driver = Rappture.library("driver.xml")
Efstr = driver.get("input.number(Ef).current")
Ef = Rappture.Units.convert(Efstr,to="J",units="off")
if (Ef != None):
print "Ef in Joules = %d" % (Ef)
result = Rappture.Units.convert("3cm", "m")
print "result = %s" % (result)
result = Rappture.Units.convert("300K", "F", "off")
print "result = %d" % (result)
result = Rappture.Units.convert("3cm", "A")
print "result = %s" % (result)
result = Rappture.Units.convert("3", "m")
print "result = %s" % (result)
result = Rappture.Units.convert("3", "m", units="off")
print "result = %s" % (result)
sys.exit()
# Result:
# Ef in Joules = 4.80653e-19
# result = 0.03m
# result = 80.329999999999998
# result = 3e+08A
# result = 3m
# result = 3.0
