wiki:rappture_python_api

Version 7 (modified by dkearney, 14 years ago) (diff)

added rappture utils progress function declaration

Rappture/Python? API

Currently in development are the Python bindings to the Rappture Development Toolkit.

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 )
lib.put( path, value, id, append )

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 )

Module Methods

Rappture.result( lib )


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 )

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.

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 )

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 0, then value will overwrite data that may have existed at path. The input id is depricated 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 - depricated. Set to None.
  4. append - overwrite flag. if set to 0, data at path will be overwritten. if set to 1, data will be appended.

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

Rapppture.result( library )

Purpose:

Write the data from Rappture Library object library to file and signal the end of processing to the graphical user interface.

Input Arguments:

  1. library - Rappture library object.

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)

Rappture.result(driver)

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