PDielec.Utilities

Utility Functions

A set of utility functions that may be used anywhere in the package.

Module Contents

Classes

Debug

A class aimed at providing a structured way to include debug messages in code.

Functions

find_program_from_name(filename)	Determine the simulation program from a given filename.
get_reader(name, program, qmprogram)	Get the appropriate output reader based on the simulation program and, if specified, the quantum mechanical program.
pdgui_get_reader(program, names, qmprogram)	Get the appropriate reader based on the provided program and file names.
printsp(name, matrix)	Utility routine for printing 4x4 matrices or 4 vectors.

class PDielec.Utilities.Debug(debug, text, level=0)

A class aimed at providing a structured way to include debug messages in code.

Methods

print(args, level=0)

Prints debug messages based on the debug level provided as argument compared to the object’s debug level.

state()

Returns the current state (enabled or disabled) of debugging.

Notes

The print method provides a flexible way to include additional information along with the base debug message, allowing for a detailed and adjustable debugging output.

print(*args, level=0)

Prints message if debugging level allows.

Parameters

args

Variable length argument list for the message to be printed.

levelint, optional

The level of the message that determines if it gets printed or not, based on the instance’s level. Default value is 0.

Notes

This method will only print the message if the instance’s debug flag is True and the provided level is less than or equal to the instance’s level.

state()

Get the debug state.

Parameters

None

Returns

The current debug state.

PDielec.Utilities.find_program_from_name(filename)

Determine the simulation program from a given filename.

Parameters

filenamestr

The complete path (absolute or relative) to a file.

Returns

str

A string representing the simulation program the file is associated with. Possible returns are ‘phonopy’, ‘vasp’, ‘gulp’, ‘castep’, ‘abinit’, ‘qe’, ‘crystal’, ‘experiment’, ‘pdgui’, or an empty string if the program cannot be determined.

Notes

This function examines the file extension and, in some cases, the presence of specific files in the same directory, to determine the associated simulation program. It recognizes files from several popular materials simulation programs, such as ‘phonopy’, ‘gulp’, ‘vasp’, and others.

Examples

program = find_program_from_name('./data/structure.castep')
print(program)
# Output: 'castep'

program = find_program_from_name('path/to/simulation/OUTCAR')
print(program)
# Depends on the presence of 'phonopy.yaml', could be 'phonopy' or 'vasp'

PDielec.Utilities.get_reader(name, program, qmprogram)

Get the appropriate output reader based on the simulation program and, if specified, the quantum mechanical program.

This function is designed to create an output reader object for various simulation programs (like CASTEP, VASP, etc.) and, for phonopy simulations, it can additionally create a quantum mechanical output reader based on the specified quantum mechanical program.

Parameters

namestr

The primary filepath or name associated with the output file(s).

programstr

The name of the simulation program. Supported values are ‘castep’, ‘vasp’, ‘gulp’, ‘crystal’, ‘abinit’, ‘qe’, and ‘phonopy’.

qmprogramstr

The name of the quantum mechanical program used in conjunction with phonopy. Supported values are the same as for program, but its relevance is exclusive to when program is set to ‘phonopy’.

Returns

object

An instance of the appropriate output reader class based on the input program and, if applicable, qmprogram.

Notes

For phonopy simulations, both phonon and quantum mechanical output files are considered. If the qmprogram is not compatible or not specified, the function will exit.

Examples

>>> reader = get_reader("output.log", "castep", "")
>>> reader = get_reader("output", "phonopy", "vasp")

PDielec.Utilities.pdgui_get_reader(program, names, qmprogram)

Get the appropriate reader based on the provided program and file names.

This function determines the correct output reader to use based on the program specified and the presence of certain files in the provided directory or file names list. It supports various quantum mechanics and molecular dynamics programs as well as experiment data.

Parameters

programstr

The name of the program or an empty string to attempt automatic detection. Supported programs include ‘vasp’, ‘castep’, ‘gulp’, ‘crystal’, ‘abinit’, ‘qe’, ‘phonopy’, and ‘experiment’.

nameslist of str

A list containing either directory names or file names to be read or analysed.

qmprogramstr

Specifies the quantum mechanics program used in conjunction with ‘phonopy’. It is only relevant if ‘program’ is set to ‘phonopy’. Supported programs include ‘castep’, ‘vasp’, ‘gulp’, ‘crystal’, ‘abinit’, and ‘qe’.

Returns

object

Returns an instance of the correct output reader based on the specified program and available files. If the necessary files are not found or if the program is not recognized, it returns None.

Notes

• The readers returned are capable of parsing output files from their respective programs and extracting relevant data.

• For ‘phonopy’, additional handling is included to combine phonopy output with quantum mechanics results from another specified program.

• This function also handles directory or file existence checks and will print errors if required files are missing.

Examples

To get a VASP output reader for a directory containing VASP output files:

>>> reader = pdgui_get_reader('', ['path/to/vasp/output'], '')
>>> print(reader)

For phonopy with VASP as the quantum mechanics program:

>>> qm_reader = pdgui_get_reader('phonopy', ['path/to/phonopy/files'], 'vasp')
>>> print(qm_reader)

PDielec.Utilities.printsp(name, matrix)

Utility routine for printing 4x4 matrices or 4 vectors.

Parameters

None

Returns

None

Notes

None