PyTrilinos Logo PyTrilinos.Teuchos

PyTrilinos.Teuchos

The C++ version of the Teuchos package provides a large variety of tools and utilities. Many of these tools and utilities are already supported in python by standard library modules. As a result, much of Teuchos, such as the command-line interpreter, has not been given a python interface.

What has been wrapped centers around the ParameterList class, an important utility class that is used by several Trilinos packages for communicating arbitrary-type parameters between users and packages. The classes XMLObject, XMLParameterListWriter and XMLParameterListReader are used to convert between XML and ParameterList objects. The classes XMLInputSource, FileInputSource, and StringInputSource can be used to convert text to XML objects.

Often, the Teuchos module is invisible to the user. The ParameterList class is analagous to the python dictionary (with the restriction that the dictionary keys must be strings), and python programmers can provide a python dictionary wherever a ParameterList is expected. Teuchos is imported by the package that uses the ParameterLists and converts between dictionaries and ParameterLists automatically.

The user can create a Teuchos.ParameterList directly, using the constructor, set and sublist methods, if he so chooses, and methods that accept ParameterLists will work as expected. It is really just a question of verbosity and elegance that argues in favor of using a python dictionary.

The python implementation of the ParameterList class has been expanded extensively. Its constructor can accept a python dictionary, and several methods and operators have been added to the class so that it behaves somewhat like a dictionary.

C++ ParameterLists are designed to support parameters of arbitrary type. The python implementation supports a subset of types a priori :

Python type Dir C/C++ type
bool <-> bool
int <-> int
float <-> double
str <-- char *
str <-> std::string
dict --> ParameterList
ParameterList <-> ParameterList

The C++ ParameterList class supports begin() and end() methods for iterating over the parameters. These methods are disabled in the python implementation, in favor of the dictionary iterator methods: __iter__(), iteritems(), iterkeys() and itervalues().

ParameterList

The ParameterList class is augmented to behave somewhat like a python dictionary. Here are the following differences between the C++ and python implementations:

  • Ignored methods: begin(), end(), entry(), getEntryPtr(), getPtr(), isType(), name(ConstIterator) and setEntry().

  • Dictionary constructors. A ParameterList can be constructed using a dictionary:

    plist = Teuchos.ParameterList(dict[,string])
    

    where dict is a dictionary whose keys are all strings and whose values are of types supported in the above table. The string name argument is optional and defaults to "ANONYMOUS".

  • Set methods. The templated C++ set() method is replaced in python with a method that takes a string name and a python object of supported type. For example:

    plist = Teuchos.ParameterList()
    plist.set("b",True)
    plist.set("i",10)
    plist.set("f",2.718)
    plist.set("s","Trilinos")
    plist.set("d",{"a":1, "b":2})
    
  • Get methods. The templated C++ get() method is replaced in python with a method that returns a python object. From the previous example:

    print plist.get("f")
    print plist.get("d")
    

    will output:

    2.718
    {'a': 1, 'b': 2}
    
  • The setParameters() method can take either a ParameterList or a python dictionary as its argument. The ParameterList is updated to contain all of the entries of the argument.

  • Printing. Since print is a python keyword, the print() C++ method has been renamed _print in python. It takes an optional file argument that defaults to standard output. Its output is the same as the C++ implementation.

    The __str__() method returns a string representation of the ParameterList as though it were a python dictionary. The python eval function applied to the output of __str__() will produce an equivalent dictionary.

    The __repr__() method returns the __str__() output encapsulated by ParameterList(...). The python eval function applied to the output of __repr__() will produce an equivalent ParameterList.

  • The unused() method in python takes an optional python file object as its argument, defaulting to standard output.

  • Parameter type determination. With the templated isType() methods disabled, type determination of python ParameterList entries is accomplished with the type() method, which returns python type objects. From our previous example:

    print plist.type("b")
    print plist.type("s")
    

    results in:

    <type 'bool'>
    <type 'str'>
    

    A non-existent key given as the argument will raise a KeyError exception.

  • An asDict() method has been added that returns the contents of the ParameterList converted to a python dictionary.

The following python dictionary methods and operators are added to the python implementation of the ParameterList class:

  • Comparison. The == and != comparison operators work for ParameterList objects. Comparison against other ParameterList objects, as well as python dictionaries, is supported. Less-than and greater-than operators also work, mimicking the default dictionary behavior, but are less useful.

  • The in operator also works, searching the parameter names:

    print "a" in plist
    print "b" in plist
    

    produces:

    False
    True
    
  • Length method. The python len() function works on ParameterLists:

    print len(plist)
    

    gives:

    5
    
  • Iteration. To iterate over the parameters in a ParameterList, treat it like a dictionary:

    for key in plist:
      print key, ":", plist[key]
    

    will result in the output:

    b : True
    d : {'a': 1, 'b': 2}
    f : 2.718
    i : 10
    s : Trilinos
    

    Note that the order of the parameters is somewhat indeterminant, as with dictionaries, because the iteration object is obtained from an equivalent dictionary, and dictionaries are ordered by hash function.

  • Index notation. Like dictionaries, parameters can be set and gotten using square brackets:

    plist["zero"] = 0
    e = plist["f"]
    
  • Update methods. An update() method has been added that can accept either a ParameterList or a python dictionary. Otherwise, it behaves just as the dictionary method, which is functionally equivalent to the setParameters() method.

  • Other new methods for the python implementation that behave just as with dictionaries: has_key(), items(), iteritems(), iterkeys(), itervalues(), keys() and values().

Note that the C++ implementation of the ParameterList class does not support parameter deletion. Therefore, python dictionary methods that delete items, such as pop() or __delitem__(), have not been added to the ParameterList class.

XML Support

PyTrilinos.Teuchos supports several classes related to XML. They are:

  • XMLObject - The python implementation of this class is largely unchanged from the C++ interface, with the following exceptions:
    • The constructor that takes an XMLObjectImplem* argument has been removed. The XMLObjectImplem class is hidden from the python user.
    • A __str__() method has been added, so that it is possible to print an XMLObject object. It returns the same string as the toString() method, but if toString() raises an exception (such as when the XMLObject is empty), the __str__() method returns the empty string.
  • XMLParameterListWriter - This simple class has been implemented unchanged from its C++ interface. Its purpose is to convert ParameterList objects into XMLObject objects.
  • XMLParameterListReader - This simple class has been implemented unchanged from its C++ interface. Its purpose is to convert XMLObject objects into ParameterList objects.
  • XMLInputSource - This is a base class from which FileInputSource and StringInputSource derive. The source() method is ignored.
  • FileInputSource - This is a class for reading an XML object from a file. The source() method is ignored.
  • StringInputSource - This is a class for reading an XML object from a string. The source() method is ignored.