|
PSCF v1.1
|
Container for data of a Composite in a param file. More...
Public Member Functions | |
| def | __init__ (self, file=None, label=None) |
| Constructor. More... | |
| def | read (self, file) |
| Read and parse a parameter block from a file. More... | |
| def | addChild (self, child) |
| Add a single child to this Composite. More... | |
| def | getChildren (self) |
| Get the dictionary of child items. More... | |
| def | __str__ (self) |
| Return an indented string representation of this Composite. More... | |
| def | __getattr__ (self, attr) |
| Return the value of one child of this Composite. More... | |
| def | __setattr__ (self, label, val) |
| Set a new value for a specified child or attribute. More... | |
| def | getString (self, depth='') |
| Get an indented string representation of this Composite. More... | |
| def | write (self, filename) |
| Write the indented param file string for this to a file. More... | |
| def | returnData (self) |
| Return the Composite object itself. More... | |
Container for data of a Composite in a param file.
The Composite class provides tools to parse and store the contents of a a parameter file block that appears in a parameter file delimited by curly brackets ('{' and '}'). The class provides special functions that allow users to access and modify stored values of parameters and subblocks within that block using the dot syntax that is normally used for python object attributes, and to obtain a multi-line string representation of the associated block in parameter file format.
Construction:
A PSCF parameter file always consists of a main block with a label 'System' that contains nested sub-elements or children. The constructor function for the Composite class accepts the name of such a parameter file as a function parameter, opens and parses the specified file and returns a Composite object that contains the contents of that file.
Example: To read and parse a parameter file with the file named 'param', one could enter
The variable p is then a Composite object that contains the contents of file 'param'.
String representation:
The getString and str methods of a Composite return the string representation of a Composite object in the multi-line, indented format of a PSCF parameter file. The write method allows a user to write the resulting string to a specified file.
Example: To write the contents to a file named 'paramOut', enter
Accessing elements:
After creating a Composite object, users can retrieve the values of any child sub-element by name, using a dot notation for children of a Composite. Each child of a Composite may be an instance of the class Composite (to represent a subblock), an instance of class Parameter (to represent a single parameter), an Array (for an array-valued parameter), or a Matrix (a matrix-valued parameter). Syntax for accessing different types of child elements, and the nature of the return values, are discussed below:
Composite: A nested sub-block that is delimited by curly brackets is represented by a child Composite object. The label of such a subblock is given by the identifier string that precedes the opening curly bracket on the first line. If this label is unique within its parent object, then child Composite may be accessed by the python dot notation for object attributes, using the unique sub-block label as an attribute name. If there are two or more subblocks of the same parent block with the same label, then using this shared name as an attribute name after a dot returns a list in which each element is a Composite representing one of the blocks with this label, indexed from 0 in the order in which they appear in the parameter file block.
Example: If p is an instance of Composite that contains the contents of a PSCF parameter file for a mixture containing two or more polymer species, then the expressions
return Composite objects that contain the contents of the entire Mixture block and of the second Polymer subblock within the Mixture block, respectively.
Parameter: A single parameter that appears in the parameter file on a single line containing a label and one or more values is represented internally by a child Parameter object. Using dot notation to access a parameter, using the label as an attribute name, returns the value of the parameter, which can be an int, a float, a string, or a Python list. The value of a parameter is stored and returned as a list if and only if the corresponding line in the parameter file contains two or more values separated by spaces after the label.
Example: If p is an initialized Composite that contains the contents of a parameter file, then the expressions
return the integer value of the number of monomer types (nMonomer) and a list of integer mesh dimensions (mesh).
Array: An array-valued parameter within a parameter file block is delimited by an opening line containing an array label immediately followed by an opening square bracket ('['), and by a closing line containing a closing square bracket (']'), separated by lines that contain element values, with one element value per line. Accessing an Array using dot notation, using the name of the array as an attribute of the parent Composite, returns a Python list in which each element of the list is equal to the value of one element of the Array. Specific elements can then be accessed by square bracket indexing.
Example: If p is the root Composite for a parameter file, the expressions
return the list of monomer statistical segment lengths, and the value for the first monomer type, respectively.
Matrix: A Matrix appears in a parameter file delimited by parentheses '(' and ')'. Accessing a Matrix returns a list of lists that represents a square, symmetric matrix; specific values within the Matrix can be accessed by two separate square bracket indices.
Example: If p is the root Composite for a parameter file, then the expressions
return the entire chi matrix (a list of lists) and the value of the element in row 0 and column 1, respectively.
Modifying elements:
The parser also allows users to modify parameter entries that are accessed by dot notation, as discussed below:
Parameter: A Parameter with a single value can be modified by Python assignment and arithmetic assignment operators. A parameter that contains multiple values on a single line, which is stored as a Python list, can can only be modified by assigning a new Python list to the attribute.
Example:
Array: The value of an array-valued parameter is stored as a python list, and may only be modified by assigning a new list to the variable.
Example: If p is a Composite representing the parameter file for system with two monomer types, we may assign new values for the statistical segment lengths of both monomers by an assignment such as
Matrix: There are two ways to modify elements of a Matrix
Design notes:
The following two attributes are created by the constructor:
The getattr function is overloaded to treat the attribute name as a key in "_children" dictionary and return either a corresponding value. If the value in the dictionary is a Composite, this function returns the Composite object. If the value is an instance of Parameter, Array or Matrix, it returns the value of object.
| def pscfpp.param.Composite.__init__ | ( | self, | |
file = None, |
|||
label = None |
|||
| ) |
Constructor.
The constructor normally parses a parameter file and returns an object containing the contents of that file. The parameter "file", if present, can be either the name of a parameter file (a string) or a python file object that is open for reading. The parameter "label", if present, is a string that is the label of the Composite object, which is equal to None by default. Both parameters have default values of None.
If the "file" parameter is absent, the constructor returns an object with no children. When an object is constructed in this way, the read() method may be called later in order to parse a parameter file.
| file | a filename string or an file object |
| label | label string for the Composite |
Definition at line 218 of file param.py.
References pscfpp.param.Composite._children, pscfpp.command.Command.label, pscfpp.param.Composite.label, pscfpp.param.Parameter.label, pscfpp.param.Array.label, pscfpp.param.Matrix.label, Util::XmlAttribute.label(), Util::XmlEndTag.label(), Util::XmlStartTag.label(), Util::ArrayParam< Type >.label(), Util::MatrixParam< Type >.label(), Util::Parameter.label(), Pscf::Pspc::BasisFieldState< D >.read(), Pscf::Pspg::BasisFieldState< D >.read(), pscfpp.output.Thermo.read(), pscfpp.param.Composite.read(), pscfpp.param.Array.read(), pscfpp.param.Matrix.read(), pscfpp.command.Script.read(), pscfpp.field.Field.read(), Util::Label.read(), Pscf::Fd1d::Mixture.read(), Pscf::AmIteratorTmpl< Iterator< D >, FieldCUDA >.read(), Pscf::AmIteratorTmpl< Iterator, DArray< double > >.read(), Pscf::AmIteratorTmpl< Iterator, T >.read(), Pscf::AmIteratorTmpl< Iterator< D >, DArray< double > >.read(), Pscf::Pspc::Domain< D >.read(), Pscf::Pspc::FilmIteratorBase< 3, IteratorType >.read(), Pscf::Pspc::FilmIteratorBase< D, IteratorType >.read(), Pscf::Pspc::FilmIteratorBase< 1, IteratorType >.read(), Pscf::Pspc::FilmIteratorBase< 2, IteratorType >.read(), Pscf::Pspc::Mixture< D >.read(), Pscf::Pspg::Mixture< D >.read(), and Util::ParamComposite.read().
| def pscfpp.param.Composite.read | ( | self, | |
| file | |||
| ) |
Read and parse a parameter block from a file.
This function reads a parameter block and stores its contents in this Composite object. The parameter "file" must be a python file object that is open for reading. Processing of the file stops when the closing bracket "}" that matches the opening bracket is encountered.
| file | a python file object that is open for reading |
Definition at line 246 of file param.py.
References pscfpp.param.Composite.addChild(), CompositeTestRunner.addChild(), and pscfpp.param.getValue().
Referenced by pscfpp.param.Composite.__init__(), pscfpp.field.Field.__init__(), pscfpp.command.Script.__init__(), pscfpp.output.Thermo.__init__(), pscfpp.param.Matrix.__init__(), and pscfpp.param.Array.__init__().
| def pscfpp.param.Composite.addChild | ( | self, | |
| child | |||
| ) |
Add a single child to this Composite.
This function adds the child object that is passed as a parameter to the _children dictionary of this Composite object. The child object should be an instance of Composite, Parameter, Array, or Matrix. The dictionary key is set equal to the label of the child which must thus have been assigned before entry to this function.
| child | object that should needs to be added |
Definition at line 320 of file param.py.
References pscfpp.param.Composite._children.
Referenced by pscfpp.param.Composite.read().
| def pscfpp.param.Composite.getChildren | ( | self | ) |
Get the dictionary of child items.
This function return the python dictionary that holds the children of this Composite object. Note: A separate function is required to return this attribute because the getattr function has been redefined so as to cause the dot operator to do something other than simply return an attribute by name.
Definition at line 341 of file param.py.
References pscfpp.param.Composite._children.
| def pscfpp.param.Composite.__str__ | ( | self | ) |
Return an indented string representation of this Composite.
This function returns a string representation of this Composite in an indented form of the param file format, with no indentation of the first line (i.e., no prefix string of spaces).
Definition at line 351 of file param.py.
References pscfpp.param.Composite.getString(), pscfpp.param.Parameter.getString(), pscfpp.param.Array.getString(), and pscfpp.param.Matrix.getString().
Referenced by pscfpp.field.Field.write(), pscfpp.output.Thermo.write(), and pscfpp.output.State.write().
| def pscfpp.param.Composite.__getattr__ | ( | self, | |
| attr | |||
| ) |
Return the value of one child of this Composite.
This function is only called when a Composite object attribute is accessed with an attribute name that is not one of the actual object attributes. If the function is called with an attr parameter that is instead the name (or dictionary key) of a child of this this Composite, then this function returns the value of the corresponding child. For a child Composite, the returned value is the Composite object itself. For a Parameter or Array, the return value is either a primitive variable (int, float or string), or a list of values. For a Matrix, the return value is always a list of lists of values.
| attr | the string to specify the value returned. |
Definition at line 370 of file param.py.
References pscfpp.param.Composite._children, and pscfpp.param.Composite.returnData().
| def pscfpp.param.Composite.__setattr__ | ( | self, | |
| label, | |||
| val | |||
| ) |
Set a new value for a specified child or attribute.
This function sets new value, given by parameter val, to the specified a child of this Composite with name given by the parameter "label".
| label | name of a child (key string) |
| val | the new value to be assigned |
Definition at line 393 of file param.py.
References pscfpp.param.Composite.__setattr__(), and pscfpp.param.Composite._children.
Referenced by pscfpp.param.Composite.__setattr__().
| def pscfpp.param.Composite.getString | ( | self, | |
depth = '' |
|||
| ) |
Get an indented string representation of this Composite.
This function return an indented multi-line string representation of this Composite object in the PSCF parameter file format, with neighboring levels of indentation offset by 2 spaces. The optional parameter "depth" is a string of spaces that, which is empty by default, that prepended to each line, and thus is the total indentation of the first line.
| depth | string of spaces used as a prefix to all lines |
Definition at line 411 of file param.py.
References pscfpp.param.Composite._children, pscfpp.param.Composite.getString(), pscfpp.command.Command.label, pscfpp.param.Composite.label, pscfpp.param.Parameter.label, pscfpp.param.Array.label, pscfpp.param.Matrix.label, Util::XmlAttribute.label(), Util::XmlEndTag.label(), Util::XmlStartTag.label(), Util::ArrayParam< Type >.label(), Util::MatrixParam< Type >.label(), and Util::Parameter.label().
Referenced by pscfpp.param.Composite.__str__(), pscfpp.param.Parameter.__str__(), pscfpp.param.Array.__str__(), pscfpp.param.Matrix.__str__(), pscfpp.param.Composite.getString(), and pscfpp.param.Composite.write().
| def pscfpp.param.Composite.write | ( | self, | |
| filename | |||
| ) |
Write the indented param file string for this to a file.
This function writes out the indented multi-line string representation of this Composite to a specified file, with no indentation of the first line (i.e., depth == ''). The paramete "filename" is a the name of the file to which this should be written,
| filename | name filename string. |
Definition at line 433 of file param.py.
References pscfpp.param.Composite.getString(), pscfpp.param.Parameter.getString(), pscfpp.param.Array.getString(), and pscfpp.param.Matrix.getString().
| def pscfpp.param.Composite.returnData | ( | self | ) |
Return the Composite object itself.
This function returns the Composite object itself.
Definition at line 442 of file param.py.
Referenced by pscfpp.param.Composite.__getattr__().
1.9.5