|
PyTrilinos
Development
|
Public Member Functions | |
| def | numParams |
| def | setName |
| def | setParameters |
| def | setParametersNotAlreadySet |
| def | disableRecursiveValidation |
| def | getEntry |
| def | getEntryRCP |
| def | remove |
| def | sublist |
| def | name |
| def | isParameter |
| def | isSublist |
| def | currentParametersString |
| def | validateParameters |
| def | validateParametersAndSetDefaults |
| def | __init__ |
| def | set |
| def | get |
| def | unused |
| def | type |
| def | __cmp__ |
| def | __contains__ |
| def | __eq__ |
| def | __getitem__ |
| def | __iter__ |
| def | __len__ |
| def | __ne__ |
| def | __setitem__ |
| def | __repr__ |
| def | __str__ |
| def | has_key |
| def | items |
| def | iteritems |
| def | iterkeys |
| def | itervalues |
| def | keys |
| def | update |
| def | values |
| def | asDict |
Public Attributes | |
| this | |
The ``ParameterList`` class is an important utility class that is used by several Trilinos packages for communicating arbitrary-type parameters between users and packages. Often, the ``ParameterList`` class is invisible to the user. It 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 other packages that use the ``ParameterList`` class and converts between dictionaries and ``ParameterList`` objects automatically. The user can create a ``Teuchos.ParameterList`` directly, using the constructor, ``set`` and ``sublist`` methods, if he so chooses, and methods that accept ``ParameterList`` objects 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++ ``ParameterList`` objects 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()``. 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.
| def PyTrilinos.Teuchos.ParameterList.__init__ | ( | self, | |
| args | |||
| ) |
__init__(Teuchos::ParameterList self) -> ParameterList
__init__(Teuchos::ParameterList self, std::string const & name) -> ParameterList
__init__(Teuchos::ParameterList self, ParameterList source) -> ParameterList
__init__(Teuchos::ParameterList self, PyObject * dict, string name=std::string("ANONYMOUS")) -> ParameterList
If ``dict`` is provided, it must be a dictionary whose keys are all
strings and whose values are all of supported types. The string name
argument is optional and defaults to ``ANONYMOUS``.
| def PyTrilinos.Teuchos.ParameterList.__cmp__ | ( | self, | |
| args | |||
| ) |
__cmp__(ParameterList self, PyObject * obj) -> int __cmp__(ParameterList self, ParameterList plist) -> int
| def PyTrilinos.Teuchos.ParameterList.__contains__ | ( | self, | |
| args | |||
| ) |
__contains__(ParameterList self, std::string const & name) -> int
The python ``in`` operator works for ``ParameterList`` objects,
searching the parameter names::
plist = Teuchos.ParameterList({'b':False})
print 'a' in plist
print 'b' in plist
produces::
False
True
| def PyTrilinos.Teuchos.ParameterList.__eq__ | ( | self, | |
| args | |||
| ) |
__eq__(ParameterList self, PyObject * obj) -> PyObject __eq__(ParameterList self, ParameterList plist) -> PyObject * The ``ParameterList`` equals operator (==)
| def PyTrilinos.Teuchos.ParameterList.__getitem__ | ( | self, | |
| args | |||
| ) |
__getitem__(ParameterList self, std::string const & name) -> PyObject * Like dictionaries, parameters can be gotten using square brackets:: plist = Teuchos.ParameterList() plist['f'] = 2.718 e = plist['f']
| def PyTrilinos.Teuchos.ParameterList.__iter__ | ( | self, | |
| args | |||
| ) |
__iter__(ParameterList self) -> PyObject *
To iterate over the parameters in a ``ParameterList``, treat it like a
dictionary::
plist = Teuchos.ParameterList({'b':True,
'i':10,
'f':2.718,
's':'Trilinos',
'd':{'a':1, 'b':2}})
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.
| def PyTrilinos.Teuchos.ParameterList.__len__ | ( | self, | |
| args | |||
| ) |
__len__(ParameterList self) -> int
The python ``len()`` function works on ``ParameterList`` objects just
as on python dictionaries::
plist = Teuchos.ParameterList({'b':True,
'i':10,
'f':2.718,
's':'Trilinos',
'd':{'a':1, 'b':2}})
print len(plist)
gives::
5
| def PyTrilinos.Teuchos.ParameterList.__ne__ | ( | self, | |
| args | |||
| ) |
__ne__(ParameterList self, PyObject * obj) -> PyObject __ne__(ParameterList self, ParameterList plist) -> PyObject * The ``ParameterList`` not equals operator (!=)
| def PyTrilinos.Teuchos.ParameterList.__repr__ | ( | self, | |
| args | |||
| ) |
__repr__(self) -> string 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``.
| def PyTrilinos.Teuchos.ParameterList.__setitem__ | ( | self, | |
| args | |||
| ) |
__setitem__(ParameterList self, std::string const & name, PyObject * value) Like dictionaries, parameters can be set using square brackets:: plist = Teuchos.ParameterList() plist['zero'] = 0
| def PyTrilinos.Teuchos.ParameterList.__str__ | ( | self, | |
| args | |||
| ) |
__str__(self) -> string 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.
| def PyTrilinos.Teuchos.ParameterList.asDict | ( | self, | |
| args | |||
| ) |
asDict(ParameterList self) -> PyObject * The ``asDict()`` method has been added to ``ParameterList``, which returns the contents of the ``ParameterList`` converted to a python dictionary.
| def PyTrilinos.Teuchos.ParameterList.currentParametersString | ( | self, | |
| args | |||
| ) |
currentParametersString(ParameterList self) -> std::string std::string Teuchos::ParameterList::currentParametersString() const Create a single formated std::string of all of the zero-level parameters in this list.
| def PyTrilinos.Teuchos.ParameterList.disableRecursiveValidation | ( | self, | |
| args | |||
| ) |
disableRecursiveValidation(ParameterList self) -> ParameterList ParameterList & Teuchos::ParameterList::disableRecursiveValidation() Disallow recusive validation when this sublist is used in a valid parameter list. This function should be called when setting a sublist in a valid parameter list which is broken off to be passed to another object. The other object should validate its own list.
| def PyTrilinos.Teuchos.ParameterList.get | ( | self, | |
| args | |||
| ) |
get(ParameterList self, string const & name, PyObject * default_value=None) -> PyObject *
The templated C++ ``get()`` method is replaced in python with a method
that returns a python object. For example::
plist = Teuchos.ParameterList({'f':2.718, 'd':{'a':1. 'b':2}})
print plist.get('f')
print plist.get('d')
will output::
2.718
{'a': 1, 'b': 2}
| def PyTrilinos.Teuchos.ParameterList.getEntry | ( | self, | |
| args | |||
| ) |
getEntry(ParameterList self, std::string const & name) -> ParameterEntry getEntry(ParameterList self, std::string const & name) -> ParameterEntry const ParameterEntry & Teuchos::ParameterList::getEntry(const std::string &name) const Retrieves a const entry with the name name. Throws Exceptions::InvalidParameterName if this parameter does not exist.
| def PyTrilinos.Teuchos.ParameterList.getEntryRCP | ( | self, | |
| args | |||
| ) |
getEntryRCP(ParameterList self, std::string const & name) -> Teuchos::RCP< Teuchos::ParameterEntry > getEntryRCP(ParameterList self, std::string const & name) -> Teuchos::RCP< Teuchos::ParameterEntry const > RCP< const ParameterEntry > Teuchos::ParameterList::getEntryRCP(const std::string &name) const Retrieves the RCP for a constant entry with the name name if it exists.
| def PyTrilinos.Teuchos.ParameterList.has_key | ( | self, | |
| args | |||
| ) |
has_key(ParameterList self, std::string const & name) -> int Equivalent to the python dictionary has_key() method
| def PyTrilinos.Teuchos.ParameterList.isParameter | ( | self, | |
| args | |||
| ) |
isParameter(ParameterList self, std::string const & name) -> bool bool Teuchos::ParameterList::isParameter(const std::string &name) const Query the existence of a parameter. "true" if a parameter with this name exists, else "false". Warning, this function should almost never be used! Instead, consider using getEntryPtr() instead.
| def PyTrilinos.Teuchos.ParameterList.isSublist | ( | self, | |
| args | |||
| ) |
isSublist(ParameterList self, std::string const & name) -> bool bool Teuchos::ParameterList::isSublist(const std::string &name) const Query the existence of a parameter and whether it is a parameter list. "true" if a parameter with this name exists and is itself a parameter list, else "false". Warning, this function should almost never be used! Instead, consider using getEntryPtr() instead.
| def PyTrilinos.Teuchos.ParameterList.items | ( | self, | |
| args | |||
| ) |
items(ParameterList self) -> PyObject * Equivalent to the python dictionary items() method
| def PyTrilinos.Teuchos.ParameterList.iteritems | ( | self, | |
| args | |||
| ) |
iteritems(ParameterList self) -> PyObject * Equivalent to the python dictionary iteritems() method
| def PyTrilinos.Teuchos.ParameterList.iterkeys | ( | self, | |
| args | |||
| ) |
iterkeys(ParameterList self) -> PyObject * Equivalent to the python dictionary iterkeys() method
| def PyTrilinos.Teuchos.ParameterList.itervalues | ( | self, | |
| args | |||
| ) |
itervalues(ParameterList self) -> PyObject * Equivalent to the python dictionary itervalues() method
| def PyTrilinos.Teuchos.ParameterList.keys | ( | self, | |
| args | |||
| ) |
keys(ParameterList self) -> PyObject * Equivalent to the python dictionary keys() method
| def PyTrilinos.Teuchos.ParameterList.name | ( | self, | |
| args | |||
| ) |
name(ParameterList self) -> std::string const & const std::string & Teuchos::ParameterList::name(ConstIterator i) const Access to name (i.e., returns i->first)
| def PyTrilinos.Teuchos.ParameterList.numParams | ( | self, | |
| args | |||
| ) |
numParams(ParameterList self) -> Teuchos::Ordinal Ordinal Teuchos::ParameterList::numParams() const Get the number of stored parameters.
| def PyTrilinos.Teuchos.ParameterList.remove | ( | self, | |
| args | |||
| ) |
remove(ParameterList self, std::string const & name, bool throwIfNotExists=True) -> bool bool Teuchos::ParameterList::remove(std::string const &name, bool throwIfNotExists=true) Remove a parameter (does not depend on the type of the parameter). Parameters: ----------- name: [in] The name of the parameter to remove throwIfNotExists: [in] If true then if the parameter with the name name does not exist then a std::exception will be thrown! Returns true if the parameter was removed, and false if the parameter was not removed ( false return value possible only if throwIfExists==false).
| def PyTrilinos.Teuchos.ParameterList.set | ( | self, | |
| args | |||
| ) |
set(ParameterList self, string const & name, PyObject * value) -> ParameterList
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})
| def PyTrilinos.Teuchos.ParameterList.setName | ( | self, | |
| args | |||
| ) |
setName(ParameterList self, std::string const & name) -> ParameterList ParameterList & Teuchos::ParameterList::setName(const std::string &name) Set the name of *this list.
| def PyTrilinos.Teuchos.ParameterList.setParameters | ( | self, | |
| args | |||
| ) |
setParameters(ParameterList self, ParameterList source) -> ParameterList 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.
| def PyTrilinos.Teuchos.ParameterList.setParametersNotAlreadySet | ( | self, | |
| args | |||
| ) |
setParametersNotAlreadySet(ParameterList self, ParameterList source) -> ParameterList ParameterList & Teuchos::ParameterList::setParametersNotAlreadySet(const ParameterList &source) Set the parameters in source that are not already set in *this. Note, this function will set the parameters and sublists from source into *this but will not result in parameters being removed from *this or in parameters already set in *this being overrided. Parameters in *this with the same names as those in source will not be overwritten.
| def PyTrilinos.Teuchos.ParameterList.sublist | ( | self, | |
| args | |||
| ) |
sublist(ParameterList self, std::string const & name, bool mustAlreadyExist=False, std::string const & docString="") -> ParameterList const ParameterList & Teuchos::ParameterList::sublist(const std::string &name) const Return a const reference to an existing sublist name. If the list does not already exist or the name exists but is not a sublist, an std::exception is thrown.
| def PyTrilinos.Teuchos.ParameterList.type | ( | self, | |
| args | |||
| ) |
type(ParameterList self, std::string const & name) -> PyObject *
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. For example::
plist = Teuchos.ParameterList({'b':True, 's':'Trilinos'})
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.
| def PyTrilinos.Teuchos.ParameterList.unused | ( | self, | |
| args | |||
| ) |
unused(self, pf=None) The ``unused()`` method in python takes an optional python file object as its argument, defaulting to standard output. This specifies where the output should go. unused(self, pf=None) The ``unused()`` method in python takes an optional python file object as its argument, defaulting to standard output. This specifies where the output should go. void Teuchos::ParameterList::unused(std::ostream &os) const Print out unused parameters in the ParameterList.
| def PyTrilinos.Teuchos.ParameterList.update | ( | self, | |
| args | |||
| ) |
update(ParameterList self, PyObject * dict, bool strict=True) update(ParameterList self, ParameterList plist) An ``update()`` method has been added to the ``ParameterList`` class 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.
| def PyTrilinos.Teuchos.ParameterList.validateParameters | ( | self, | |
| args | |||
| ) |
validateParameters(ParameterList self, ParameterList validParamList, int const depth=1000, Teuchos::EValidateUsed const validateUsed=VALIDATE_USED_ENABLED,
Teuchos::EValidateDefaults const validateDefaults=VALIDATE_DEFAULTS_ENABLED)
void Teuchos::ParameterList::validateParameters(ParameterList const
&validParamList, int const depth=1000, EValidateUsed const
validateUsed=VALIDATE_USED_ENABLED, EValidateDefaults const
validateDefaults=VALIDATE_DEFAULTS_ENABLED) const
Validate the parameters in this list given valid selections in the
input list.
Parameters:
-----------
validParamList: [in] This is the list that the parameters and sublist
in *this are compared against.
depth: [in] Determines the number of levels of depth that the
validation will recurse into. A value of dpeth=0 means that only the
top level parameters and sublists will be checked. Default: depth =
large number.
validateUsed: [in] Determines if parameters that have been used are
checked against those in validParamList. Default: validateDefaults =
VALIDATE_DEFAULTS_ENABLED.
validateDefaults: [in] Determines if parameters set at their default
values using get(name,defaultVal) are checked against those in
validParamList. Default: validateDefaults = VALIDATE_DEFAULTS_ENABLED.
If a parameter in *this is not found in validParamList then an
std::exception of type Exceptions::InvalidParameterName will be
thrown which will contain an excellent error message returned by
excpt.what(). If the parameter exists but has the wrong type, then an
std::exception type Exceptions::InvalidParameterType will be thrown.
If the parameter exists and has the right type, but the value is not
valid then an std::exception type Exceptions::InvalidParameterValue
will be thrown.
Recursive validation stops when: The maxinum depth is reached
A sublist note in validParamList has been marked with the
disableRecursiveValidation() function, or
There are not more parameters or sublists left in *this
A breath-first search is performed to validate all of the parameters
in one sublist before moving into nested subslist.
| def PyTrilinos.Teuchos.ParameterList.validateParametersAndSetDefaults | ( | self, | |
| args | |||
| ) |
validateParametersAndSetDefaults(ParameterList self, ParameterList validParamList, int const depth=1000) void Teuchos::ParameterList::validateParametersAndSetDefaults(ParameterList const &validParamList, int const depth=1000) Validate the parameters in this list given valid selections in the input list and set defaults for those not set. Parameters: ----------- validParamList: [in] This is the list that the parameters and sublist in *this are compared against. depth: [in] Determines the number of levels of depth that the validation will recurse into. A value of dpeth=0 means that only the top level parameters and sublists will be checked. Default: depth = large number. If a parameter in *this is not found in validParamList then an std::exception of type Exceptions::InvalidParameterName will be thrown which will contain an excellent error message returned by excpt.what(). If the parameter exists but has the wrong type, then an std::exception type Exceptions::InvalidParameterType will be thrown. If the parameter exists and has the right type, but the value is not valid then an std::exception type Exceptions::InvalidParameterValue will be thrown. If a parameter in validParamList does not exist in *this, then it will be set at its default value as determined by validParamList. Recursive validation stops when: The maxinum depth is reached A sublist note in validParamList has been marked with the disableRecursiveValidation() function, or There are not more parameters or sublists left in *this A breath-first search is performed to validate all of the parameters in one sublist before moving into nested subslist.
| def PyTrilinos.Teuchos.ParameterList.values | ( | self, | |
| args | |||
| ) |
values(ParameterList self) -> PyObject * Equivalent to the python dictionary values() method
1.7.6.1