PyTrilinos Logo PyTrilinos.Teuchos

PyTrilinos.Teuchos

The Teuchos package provides a large variety of tools and utilities, many of which are already supported in python by independent, standard library modules. Currently, the only class supported in the python module is Teuchos::ParameterList, which is used by several Trilinos packages for communicating arbitrary-type parameters between users and packages.

Typically, 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 where 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. Starting with Trillinos version 7.0.4, the ParameterList class can accept a python dictionary as a constructor.

In versions 7.0.3 and earlier, methods that return a ParameterList in C++ will return a special class in python: a PyDictParameterList. This class inherits from ParameterList, but adds several methods and operators so that it behaves like a python dictionary. A PyDictParameterList can also be constructed and provided to methods that accept a ParameterList if the user so chooses.

In versions 7.0.4 and later, the PyDictParameterList class has been eliminated in favor of expanded functionality for the python version of ParameterList. In addition to the constructor that accepts a python dictionary, several methods and operators have been added to the ParameterList 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
PyDictParameterList --> ParameterList

The C++ ParameterList class supports begin() and end() methods for iterating over the parameters. These methods are disabled in the python implementation. The python version of ParameterList (version 7.0.4 and later), however, does provide all of the python dictionary iterator methods: __iter__(), iteritems(), iterkeys() and itervalues(). (In earlier versions, this functionality is assigned to the PyDictParameterList class.)

ParameterList

The ParameterList class is augmented to "play nice" and 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 ignored, 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
    
  • Index notation. Like dictionaries, parameters can be set and gotten using square brackets:

    plist["zero"] = 0
    e = plist["f"]
    
  • 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
    zero : 0
    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.

  • 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.