wiki:rappture_python_api
Last modified 16 months ago Last modified on 04/29/14 09:36:01

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:

  1. 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:

  1. path - xml path (location) of the element to be retrieved.
  2. 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:

  1. path - xml path (location) to store value.
  2. value - data to store in this object.
  3. id - deprecated. Set to None.
  4. append - overwrite flag (True or False). if set to False, data at path will be overwritten. if set to True, data will be appended.
  5. type - may be set to "string" or "file". flag defaults to "string". when set to "file", data within the file is stored at path.
  6. 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:

  1. 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:

  1. fromVal - String with numeric portion and optional units (ie. "3m" or "3").
  2. to - String name of the units you want to convert to.
  3. 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:

  1. .
# 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