Container for data in a PSCF field file. More...

Public Member Functions
def	__init__ (self, filename)
	Constructor. More...

def	read (self, openFile)
	Read and parse the passed-in file. More...

def	__str__ (self)
	Return string representation of this Field. More...

def	write (self, filename)
	Write out field to a file. More...

def	addColumn (self, index, element)
	Add a new column to the data list. More...

def	deleteColumn (self, index)
	Delete an existing column from the data list. More...

def	reorder (self, order)
	Reorder the data list. More...

Detailed Description

Container for data in a PSCF field file.

A Field object can parse a PSCF "field file" and store its contents. A field file contains both a header section and a data section. This class can read and parse all of the field file formats used by PSCF programs including the basis, rgrid, and kgrid formats used by the pscf_pc and pscf_pg programs to represent periodic fields, and the simpler file format used by pscf_fd for one-dimensional fields. For detail on these file formats see the section of the web manual on field files. Users can access and modify stored values of the parameters in the header and values in the data section after parsing by using specific statements (commands), and can write the entire object to a file in proper format.

Every PSCF field file format contains a header section and a data section. The header contains globale information about the system and spatial discretization. The data section is a table of field components in which each row contains components associated with a single spatial degree of freedom, and each column contains components associated with a single monomer type. The format of header is different for different types of field file, which makes it possible for the Field class to infer information about the type of a field file while parsing the header,

A Field object has three attributes named 'header', 'data', and 'type'. The 'header' attribute is a dictionary that contains the contents of the header section, using the variable names or labels as dictionary keys. The 'data' attribute is a list of lists in which each element of the outer list corresponds to one row of the data section in the field file. When accessing elements of the data attribute using two subscripts, the first subscript (the row index) is thus index for a spatial degree of freedom (i.e., a grid point or basis function) and the second (the column index) is an index for a monomer type.

The 'type' attribute is a string with possible values 'fd1d', 'basis', 'rgrid' or 'kgrid'.

Construction:

The Field constructor can parse any PSCF field file, and infer its type. To read and parse a field file with name 'field', one could enter:

from pscfpp.field import *

f = Field('field')

pscfpp.field

Module for parsing field files.

Definition: field.py:1

Printing and writing to file:

The str function can be used to convert a Field object to a multi-line string with a consistent with that of the file from which it was created. The write function can be used to write that string to a specified file. To write a field stored in a Field object named f to a file named 'out', one would enter:

f.write('out')

Accessing elements:

The header attribute is a Python dictionary containing the contents of the header section of the field file. One can access elements using names of header variables as dictionary keys, as in the expressions

f.header['format']

f.header['N_monomer']

The available keys are different for different file formats. Values for some quantities that are generally represented by more than one value are stored as lists, such as the list 'cell_param' of cell parameter values to describe the unit cell in a periodic system.

The data attribute is a list of lists, in which elements can be accessed using square brackets with integer indices. The expressions

f.data[10]

f.data[10][1]

access an entire row of the data section or a single component, respectively.

Elements of the header and data attributes can also be modified, simply by putting corresponding expressions on the left side of an equality (assignment) operator. For example, the expressions

f.header['dim'] = 3  
f.header['cell_param'] = [2.45]   
f.header['group_name'] = 'P_1'

modify variables defined in the header of a field file for a periodic system.

Modifying data table structure:

The methods addColumn, deleteColumn, and reorder can change the structure of the data section by adding, deleting or reordering columns associated with different monomer types.

Definition at line 105 of file field.py.

Constructor & Destructor Documentation

◆ init()

def pscfpp.field.Field.__init__	(	self,
		filename
	)

Constructor.

Parameters

filename a filename string

Definition at line 112 of file field.py.

Member Function Documentation

◆ read()

def pscfpp.field.Field.read	(	self,
		openFile
	)

Read and parse the passed-in file.

This function reads the passed-in open-file object line by line and update the read items into instance variables. The reading stops when all lines in file are read.

Parameters

openFile a file object, open for reading

Definition at line 129 of file field.py.

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__().

◆ str()

def pscfpp.field.Field.__str__ ( self )

Return string representation of this Field.

This function return the string representation of the Field object in the appropriate field file format.

Definition at line 186 of file field.py.

Referenced by pscfpp.field.Field.write(), pscfpp.output.Thermo.write(), and pscfpp.output.State.write().

◆ write()

def pscfpp.field.Field.write	(	self,
		filename
	)

Write out field to a file.

This function writes out the field file string to the specified file with the name of the passed-in parameter, filename.

Parameters

filename a filename string.

Definition at line 265 of file field.py.

References pscfpp.command.Script.__str__(), pscfpp.field.Field.__str__(), pscfpp.file.File.__str__(), pscfpp.file.Directory.__str__(), pscfpp.make.MakeMaker.__str__(), pscfpp.output.Thermo.__str__(), pscfpp.output.State.__str__(), pscfpp.param.Composite.__str__(), pscfpp.param.Parameter.__str__(), pscfpp.param.Array.__str__(), pscfpp.param.Matrix.__str__(), pscfpp.text.Wrapper.__str__(), and pscfpp.text.Record.__str__().

◆ addColumn()

def pscfpp.field.Field.addColumn	(	self,
		index,
		element
	)

Add a new column to the data list.

This function adds a new column to the data list of this Field object. The parameter 'index' is the desired position of the new column. The parameter 'element' can be either a single value that is applied to every element of the entire column, or a list of of values that represents the entire column of new values. If a list of values is supplied, the length of the list must be equal to the number of rows in the data list.

Example:

f.addColumn(2, 1.2)

f.addColumn(2, [list of values for the whole column])

Parameters

index	integer column index
element	value (float) or values (list) for elements of column

Definition at line 289 of file field.py.

References pscfpp.field.Field.data, Util::GridArray< Data >.data(), Util::IntDistribution.data(), and Util::Node< Data >.data().

◆ deleteColumn()

def pscfpp.field.Field.deleteColumn	(	self,
		index
	)

Delete an existing column from the data list.

This function deletes an existing column from the data list of this Field object. Input parameter "index" is the index of the column that should removed.

Parameters

index column index, numbered from 0

Definition at line 308 of file field.py.

References pscfpp.field.Field.data, Util::GridArray< Data >.data(), Util::IntDistribution.data(), and Util::Node< Data >.data().

◆ reorder()

def pscfpp.field.Field.reorder	(	self,
		order
	)

Reorder the data list.

This function reorders the data list of the Field object. By passing in one parameter, order, an integer list that represents the new order of the columns in the data list, the data list of the Field object can be updated with the desired order. The length of the list 'order' must be equal to the total number of columns in the data section, including any that do not contain field component values.

Note: This function treats all columns in the file format equivalently, whether they contain field component values or other information. Specifically, when treating a field file in basis file format for a system with C monomer types in a system of spatial dimension D, the field file format contains C + D + 1 columns, in which only the first C contain field components and the remaining D+1 contain Miller indices for a characteristic wave of each star and the number of waves in the star. To re-order columns that contain field components one must enter a permutation of the integers [0,...,C+D] in which only the first C columns (columsn 0,...,C-1) are re-ordered and the remaining D+1 integers must appear in their original order.

Example: To re-order the field component columns for a 3D periodic system containing three monomer, one might use something like

f.reorder([2, 0, 1, 3, 4, 5, 6])

Here, columns 0-2 represent field components, which have been re-ordered, while columns 3-6 represent information about basis functions (Miller indices and the number of waves per star) which are left in their original order.

Parameters

order a list of position integers.

Definition at line 349 of file field.py.

References pscfpp.field.Field.data, Util::GridArray< Data >.data(), Util::IntDistribution.data(), and Util::Node< Data >.data().

The documentation for this class was generated from the following file:

field.py

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ read()

◆ __str__()

◆ write()

◆ addColumn()

◆ deleteColumn()

◆ reorder()

◆ init()

◆ str()