Rappture R API
Summary:
require(Rappture)
Library Class
These functions provide an interface to the Rappture I/O library.
Constructor
lib = rp_lib( fileName )
Functions
value = rp_lib_get_boolean( lib, path )
value = rp_lib_get_double( lib, path )
value = rp_lib_get_integer( lib, path )
value = rp_lib_get_string( lib, path )
value = rp_lib_get_file( lib, path, fileName )
err = rp_lib_put_double( lib, path, value, append )
err = rp_lib_put_file( lib, path, fname, compress, append )
err = rp_lib_put_string( lib, path, value, append )
err = rp_lib_result( lib )
Units Class
These functions provide an interface to the Rappture Units library.
Functions
value = rp_units_convert_double( fromVal, toUnitsName )
value = rp_units_convert_string( fromVal, toUnitsName, showUnits )
Utils Module
These functions provide an interface to the Rappture Utils library.
Functions
err = rp_utils_progress( percent, message )
Detail:
rp_lib (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>
require(Rappture)
lib = rp_lib("driver.xml")
if (lib <= 0) {
cat("Successfully opened a Rappture Library Object\n")
} else {
cat("Creating a Rappture Library Object from driver.xml failed\n")
}
quit(save="no")
# Result:
# Successfully opened a Rappture Library Object
rp_lib_get_string( lib, path )
Purpose:
Retrieve the data held at the xml location path from this object.
Input Arguments:
1) lib - handle to the Rappture library.
2) 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, an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
Ef = rp_lib_get_string(lib,"input.number(Ef).current")
cat("Ef = ", Ef, "\n")
quit(save="no")
# Result:
# Ef = 3.5eV
rp_lib_get_double( lib, path )
Purpose:
Retrieve the data held at the xml location path from this object.
Input Arguments:
1) lib - handle to the Rappture library.
2) path - xml path (location) of the element to be retrieved.
Return Value:
On success, a double with the value stored at xml location path of this object. On failure, an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
Ef = rp_lib_get_double(lib,"input.number(Ef).current")
cat("Ef = ", Ef, "\n")
quit(save="no")
# Result:
# Ef = 3.5
rp_lib_get_integer( lib, path )
Purpose:
Retrieve the data held at the xml location path from this object.
Input Arguments:
1) lib - handle to the Rappture library.
2) path - xml path (location) of the element to be retrieved.
Return Value:
On success, an integer with the value stored at xml location path of this object. On failure, an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# <integer id="points">
# <min>10</min>
# <max>1000</max>
# <default>100</default>
# <current>150</current>
# </integer>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
Ef = rp_lib_get_double(lib,"input.number(Ef).current")
points = rp_lib_get_integer(lib,"input.integer(points).current")
cat("Ef = ", Ef, "\n")
cat("points = ", points, "\n")
quit(save="no")
# Result:
# Ef = 3
# points = 150
rp_lib_get_boolean( lib, path )
Purpose:
Retrieve the data held at the xml location path from this object.
Input Arguments:
1) lib - handle to the Rappture library.
2) path - xml path (location) of the element to be retrieved.
Return Value:
On success, a boolean with the value stored at xml location path of this object. On failure, an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <boolean id="integrate">
# <default>false</default>
# <current>true</current>
# </boolean>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
integrate = rp_lib_get_boolean(lib,"input.boolean(integrate).current")
cat("integrate = ", integrate, "\n")
quit(save="no")
# Result:
# integrate = TRUE
rp_lib_get_file( lib, path, fileName )
Purpose:
Retrieve the data held at the xml location path from this object and write it to a file named fileName
Input Arguments:
1) lib - handle to the Rappture library.
2) path - xml path (location) of the element to be saved.
3) fileName - name of the file to save the data to.
Return Value:
On success, the number of bytes written to the file is returned. On failure, an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <string id="values">
# <default>14 32 54 71 12 43 18</default>
# <current>9 22 48 74 15 50 22</current>
# </string>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
nbytes = rp_lib_get_file(lib,"input.string(values).current", "values.dat")
cat("nbytes = ", nbytes, "\n")
quit(save="no")
# Result:
# nbytes = 20
# contents of the file named "values.dat":
# 9 22 48 74 15 50 22
rp_lib_put_string( lib, path, value, append )
Purpose:
Place data value into the object lib at the xml location path. If the append flag is set to TRUE, 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.
Input Arguments:
1) lib - handle to the Rappture library.
2) path - xml path (location) of the element to be retrieved.
3) value - data to be stored in the library.
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 to.
Return Value:
On success, an integer error code of 0 is returned. On failure, a non-zero integer error code is returned or an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
x <- seq(0,10,by=1)
y <- sapply(x,function(x1) x1*x1)
s <- paste(sprintf("%g %g\n",x,y),collapse="")
err = rp_lib_put_string(lib,"output.curve(squares).component.xy",s,FALSE)
if (err == 0) {
cat("rp_lib_put_string successful\n")
} else {
cat("rp_lib_put_string failed\n")
}
quit(save="no")
# Result:
# rp_lib_put_string successful
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# <output>
# <curve id="squares">
# <component>
# <xy>
# 0 0
# 1 1
# 2 4
# 3 9
# 4 16
# 5 25
# 6 36
# 7 49
# 8 64
# 9 81
# 10 100
# </xy>
# </component>
# </curve>
# </output>
# </run>
rp_lib_put_double( lib, path, value, append )
Purpose:
Place data value into the object lib at the xml location path. If the append flag is set to TRUE, 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.
Input Arguments:
1) lib - handle to the Rappture library.
2) path - xml path (location) of the element to be retrieved.
3) value - data to be stored in the library.
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 to.
Return Value:
On success, an integer error code of 0 is returned. On failure, a non-zero integer error code is returned or an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
x <- 12
y <- x*x
err = rp_lib_put_double(lib,"output.number(result).current",y,FALSE)
if (err == 0) {
cat("rp_lib_put_double successful\n")
} else {
cat("rp_lib_put_double failed\n")
}
quit(save="no")
# Result:
# rp_lib_put_double successful
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# <output>
# <number id="result">
# <current>144</current>
# </number>
# </output>
# </run>
rp_lib_put_file( lib, path, fileName, compress, append )
Purpose:
Place data from the file fileName into the object lib at the xml location path. If the compress flag is set to TRUE or Rappture thinks there are non-ascii characters within the data, the data from fileName is gzip compressed and base64 encoded before being placed into lib. If the append flag is set to TRUE, then the data from fileName will be appended to data that already exists at path. If the append flag is set to FALSE, then the data from fileName will overwrite data that may have existed at path.
Input Arguments:
1) lib - handle to the Rappture library.
2) path - xml path (location) of the element to be retrieved.
3) fileName - data to be stored in the library.
4) compress - compress flag (TRUE or FALSE). if set to TRUE, data from the file will be gzip compressed and base64 encoded.
5) append - overwrite flag (TRUE or FALSE). if set to FALSE, data at path will be overwritten. if set to TRUE, data will be appended to.
Return Value:
On success, an integer error code of 0 is returned. On failure, a non-zero integer error code is returned or an error is raised.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
#
# Contents of values.dat:
# 9 22 48 74 15 50 22
require(Rappture)
lib = rp_lib("driver.xml")
err = rp_lib_put_file(lib,"output.string(values).current","values.dat",FALSE,FALSE)
if (err == 0) {
cat("rp_lib_put_file successful\n")
} else {
cat("rp_lib_put_file failed\n")
}
quit(save="no")
# Result:
# rp_lib_put_double successful
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# <output>
# <string id="values">
# <current>9 22 48 74 15 50 22</current>
# </string>
# </output>
# </run>
rp_lib_result( lib )
Purpose:
This function writes the xml of the Rappture library lib to a unique run.xml file on disk, and a signal is sent to the rappture graphical user interface.
Input Arguments:
1) lib - handle to the Rappture library.
Return Value:
1) 0 on success, all other values represent failure.
2) A unique run.xml file is generated on disk.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
x <- seq(0,10,by=1)
y <- sapply(x,function(x1) x1*x1)
s <- paste(sprintf("%g %g\n",x,y),collapse="")
rp_lib_put_string(lib,"output.curve(squares).component.xy",s,FALSE)
err = rp_lib_result(lib)
if (err == 0) {
cat("rp_lib_result successful\n")
} else {
cat("rp_lib_result failed\n")
}
quit(save="no")
# Result:
# rp_lib_result successful
# a unique run.xml file is created on disk.
# signal sent to gui stating processing has completed.
rp_units_convert_double( fromVal, toUnitsName )
Purpose:
Convert the numeric value and units found in the string fromVal to the units named in toUnitsName. A double precision value is returned.
Input Arguments:
1) fromVal - String representing the numeric value and units you want to convert from.
2) toUnitsName - String representing the name of the units you want to convert to.
Return Value:
The converted value is provided as the return value of the function.
An error is raised on failure.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
Ef = rp_lib_get_string(lib,"input.number(Ef).current")
Ef = rp_units_convert_double(Ef,"J")
cat("Ef = ", Ef, "\n")
quit(save="no")
# Result:
# Ef = 5.60762e-19
rp_units_convert_string( fromVal, toUnitsName, showUnits )
Purpose:
Convert the numeric value and units found in the string fromVal to the units named in toUnitsName. If showUnits is set to TRUE, a string value containing the numeric value and units is returned.
Input Arguments:
1) fromVal - String representing the numeric value and units you want to convert from.
2) toUnitsName - String representing the name of the units you want to convert to.
3) showUnits - Flag (TRUE or FALSE) that specifies whether units should be appended to the returned string.
Return Value:
The converted value is provided as the return value of the function.
An error is raised on failure.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0.0eV</default>
# <current>3.5eV</current>
# </number>
# </input>
# </run>
require(Rappture)
lib = rp_lib("driver.xml")
Ef = rp_lib_get_string(lib,"input.number(Ef).current")
Ef = rp_units_convert_string(Ef,"J",FALSE)
cat("Ef without units: ", Ef, "\n")
Ef = rp_units_convert_string(Ef,"J",FALSE)
cat("Ef with units: ", Ef, "\n")
quit(save="no")
# Result:
# Ef without units: 5.60762e-19
# Ef with units: 5.60762e-19J
