wiki:rappture_perl_api
Last modified 4 years ago Last modified on 10/04/10 15:19:21

Rappture Perl API

Perl bindings to the Rappture Development Toolkit.

Summary:

    use Rappture;

RpLibrary Class

This module provides an interface to Rappture I/O (RpLibrary) library.

Constructor

$library = Rappture::RpLibrary?->new( $path )

Methods

$library->get( $path )
$library->put( $path, $value, $append )
$library->putFile( $path, $fileName, $compress, $append )
$library->result( )

Rappture::RpUnits Class

This module provides an interface to Rappture Units (RpUnits) library.

Static Methods

Rappture::RpUnits::convert( $fromVal, $to, $showUnits )

Rappture::Utils Module

This module provides an interface to Rappture Utils Module.

Static Methods

Rappture::Utils::progress( $value, $message )


Detail:

Rappture::RpLibrary?->new ($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>

use Rappture;

my $lib = Rappture::RpLibrary->new("driver.xml");

if (not defined $lib) {
    print "creation of library successful\n";
} else {
    print "creation of library failed\n";
}

print "lib = $lib";
# $lib->delete;

# Result:
# creation of library successful
# lib = Rappture::RpLibrary=SCALAR(0x1bd9060)

instance->get( $path )

Purpose:

Retrieves the data held at location $path from the rappture object.

Input Arguments:

  1. $path - xml path (location) of the element to be retrieved.

Return Value:

String representation of the data at path within the rappture object.

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

use Rappture;

my $lib = Rappture::RpLibrary->new("driver.xml");

my $Ef = $lib->get("input.number(Ef).current");

print "Ef = $Ef";

# Result:
# Ef = 3eV

instance->put( $path, $value, $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.

Input Arguments:

  1. $path - xml path (location) to store value.
  2. $value - data to store in this object.
  3. $append' - overwrite flag (1 or 0). 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>


use Rappture;

my $lib = Rappture::RpLibrary->new("driver.xml");

print "Overwrite:\n";
$lib->put("input.number(Ef).current", "6", 0);
my $Ef = $lib->get("input.number(Ef).current");
print "Ef = $Ef";

print "\n";
print "Append:\n";
$lib->put("input.number(Ef).current", "eV", 1);
$Ef = $lib->get("input.number(Ef).current");
print "Ef = $Ef";

# Result:
#
# Overwrite:
# Ef = 6
#
# Append:
# Ef = 6eV

instance->putFile( $path, $fileName, $compress, $append )

Purpose:

Place data from file $fileName into this object at the xml location $path. If the $compress flag is set to 1, the data will be gzip compressed and base64 encoded. 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.

Input Arguments:

  1. $path - xml path (location) to store value.
  2. $fileName - name of the file to store in this object.
  3. $compress - flag (1 or 0). if set to 1, file data will be gzip compressed and base64 encoded.
  4. $append - overwrite flag (1 or 0). 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>
#
# temp.jpg is a JPEG image file

use Rappture;

my $lib = Rappture::RpLibrary->new("driver.xml");

$lib->putFile("input.image.current", "temp.jpg", 1, 0);

instance->result( )

Purpose:

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

Input Arguments:

None

Return Value:

None

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

use Rappture;

my $lib = Rappture::RpLibrary->new("driver.xml");

$lib->result();

Rappture::RpUnits::convert( $fromVal, $to, $showUnits )

Purpose:

Convert a string, ($fromVal) containing a numeric value and option units, to the units specified in the second argument ($to).

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. $showUnits - String "1" or "0" to tell if you want units to show up in the result.

Return Value:

Return converted value as a string. Return undef on failure. $showUnits are set to on ("1") by default.

Notes:

None.

    use Rappture;
    
    $result = Rappture::RpUnits::convert( "3cm", "m" )
    # result is "0.03m"

    $result = Rappture::RpUnits::convert( "300K", "F", "0" )
    # result is "80.329999999999998"

    $result = Rappture::RpUnits::convert( "3cm", "A" )
    # result is "3e+08A"

    $result = Rappture::RpUnits::convert( "3", "m" )
    # result is "3m"

    $result = Rappture::RpUnits::convert( "3", "m", "0" )
    # result is "3.0"

Rappture::Utils::progress( $value, $message )

Purpose:

Print a progress percentage and message on the screen during simulation.

Input Arguments:

  1. $value - Percentage to display. Value between 0 and 100.
  2. $message - Comment associated with $value.

Return Value:

None.

Notes:

None.

    use Rappture;

    Rappture::Utils::progress(45,"Iterating...");