Non-API code¶

This code is documented here for development purpouses. These modules, classes and functions are not part of the API and may change more frequently.

CoordinateUtilities¶

Module for holding common coordinate manipulating utility functions.

KMCLib.Utilities.CoordinateUtilities.centerCoordinates(coordinates, index)¶

Center the coordinates around the given index.

Parameters:	coordinates – The coordinates of the system. index (int) – The index of the center to use as origin.
Returns:	The coordinates centered at the specified index.

KMCLib.Utilities.CoordinateUtilities.sortCoordinates(coordinates, types1, types2=None, co_sort=None)¶

Sort the coordinates with respect to their x,y and z coordinates

Parameters:	coordinates – The coordinates to sort. types1 (a list of strings) – The first list of site types to co-sort with the coordinates. types2 (a list of strings) – The second, optional, list of site types to co-sort with the coordinates. co_sort – The list of some thing to co-sort.
Returns:	The sorted coordinates and sorted types. A sorted co_sort list is also returned if a co_sort argument was given.

KMCLib.Utilities.CoordinateUtilities.sortCoordinatesDistance(coordinates, center, types1, types2=None, co_sort=None)¶

Sort the coordinates with respect to distance form the provided center index and type.

Parameters:	coordinates – The coordinates to sort. center (int) – The index of the center to calculate distances from. types1 (a list of strings) – The first list of site types to co-sort with the coordinates. types2 (a list of strings) – The second, optional, list of site types to co-sort with the coordinates.
Returns:	The sorted coordinates, distances and sorted types.

CheckUtilities¶

Module for holding common checking utility functions.

KMCLib.Utilities.CheckUtilities.checkCellVectors(cell_vectors)¶

Check that the cell vectors are of the correct dimensions and not fully linearly dependent.

Parameters:	cell_vectors – The cell vectors to test.
Returns:	The valid cell vectors as a 3x3 numpy array.

KMCLib.Utilities.CheckUtilities.checkCoordinateList(coordinates, varname='coordinates')¶

Check that the given coordinates is a valid Nx3 sequence of numbers.

Parameters:	coordinates – The object to test. To pass the test this must be an Nx3 array of floating point numbers. varname (string) – The name of the variable. Defaults to “coordinates”
Returns:	A valid Nx3 numpy array of numbers.

KMCLib.Utilities.CheckUtilities.checkIndexWithinBounds(index, list, msg=None)¶

Check that the given index is within the bounds of the list.

Parameters:	index (int) – The index to check. list – The list to check against. msg (string) – The error message to print. If none is given the string default to “Index out of range.”
Returns:	The valid index.

KMCLib.Utilities.CheckUtilities.checkPositiveFloat(parameter, default_parameter, parameter_name)¶

Utility function for checking that a parameter is a positive float.

Parameters:	parameter – The parameter to check. default_parameter – The value to use if the parameter value is None parameter_name (str) – The name of the parameter to use in error messages.
Returns:	The checked parameter.

KMCLib.Utilities.CheckUtilities.checkPositiveInteger(parameter, default_parameter, parameter_name)¶

Utility function for checking that a parameter is a positive integer.

Parameters:	parameter – The parameter to check. default_parameter – The value to use if the parameter value is None parameter_name (str) – The name of the parameter to use in error messages.
Returns:	The checked parameter.

KMCLib.Utilities.CheckUtilities.checkSequence(sequence, msg='The tested object is not a sequence.')¶

Check that the given object is sequence.

Parameters:	sequence – The object to test. msg (string) – Non-default error message to print.
Returns:	The valid sequence object.

KMCLib.Utilities.CheckUtilities.checkSequenceOf(sequence, class_type, msg='The tested object is not a sequence of the correct type.')¶

Utility function to check if a parameter is a sequence of instances of a given type.

Parameters:	sequence – The sequence to check. class_type – The class of which the elements in the sequence should be instances. msg (string) – Non-default error message to print.
Returns:	The valid sequence.

KMCLib.Utilities.CheckUtilities.checkSequenceOfFloats(sequence, msg='The tested object is not a sequence of floats.')¶

Utility function to check if a parameter is a sequence of floating point numbers.

Parameters:	sequence – The sequence to check. msg (string) – Non-default error message to print.
Returns:	The valid sequence.

KMCLib.Utilities.CheckUtilities.checkSequenceOfPositiveIntegers(sequence, msg='The tested object is not a sequence of positive integers.')¶

Utility function to check if a parameter is a sequence of positive integers.

Parameters:	sequence – The sequence to check. msg (string) – Non-default error message to print.
Returns:	The valid sequence.

KMCLib.Utilities.CheckUtilities.checkTypes(types, length)¶

Check that the types list is given as a list of strings with the correct length.

Parameters:	types – The object to check. length (int) – The size the list should have.
Returns:	The checked list.

ConversionUtilities¶

Module for holding common type conversion utility functions.

KMCLib.Utilities.ConversionUtilities.numpy2DArrayToStdVectorCoordinate(array)¶

Convert a Nx3 2D numpy array to a std::vector<Coordinate> representation.

Parameters:	array – The array to convert.
Returns:	A corresponding std::vector<Coordinate> object.

KMCLib.Utilities.ConversionUtilities.numpy2DArrayToStdVectorStdVectorDouble(array)¶

Convert a 2D numpy array to a std::vector<std::vector<double> > representation.

Parameters:	array – The array to convert.
Returns:	A corresponding std::vector<std::vector<double> > object.

KMCLib.Utilities.ConversionUtilities.stdVectorCoordinateToNumpy2DArray(cpp_vector)¶: Convert a std::vector<Coordinate> to a nx3 numpy array.

KMCLib.Utilities.ConversionUtilities.stdVectorPairCoordinateToNumpy2DArray(cpp_vector)¶: Convert a std::vector< std::pair<Coordinate, Coordinate> > to a nx6 numpy array.

KMCLib.Utilities.ConversionUtilities.stringListToStdVectorString(string_list)¶

Converts a list of strings to a std::vector<std::string> object.

Parameters:	string_list – The list of strings.
Returns:	A corresponding std::vector<std::string> object.

SaveAndReadUtilities¶

Module for holding common save and read utility functions.

KMCLib.Utilities.SaveAndReadUtilities.KMCConfigurationFromScript(script_file_path)¶

Utility function to read a KMCConfiguration from a script file.

Parameters:	script_file_path (str) – The script file path to read.
Returns:	The KMCConfiguration saved in the file.

KMCLib.Utilities.SaveAndReadUtilities.KMCInteractionsFromScript(script_file_path)¶

Utility function to read a KMCInteractions from a script file.

Parameters:	script_file_path (str) – The script file path to read.
Returns:	The KMCInteractions saved in the file.

KMCLib.Utilities.SaveAndReadUtilities.KMCLatticeModelFromScript(script_file_path)¶

Utility function to read a KMCLatticeModel from a script file.

Parameters:	script_file_path (str) – The script file path to read.
Returns:	The KMCLatticeModel saved in the file.

KMCLib.Utilities.SaveAndReadUtilities.getScriptComponent(script_file_path, component_type)¶

Utility function to get a component of a certain type from a script file.

Parameters:	script_file_path (str) – The script file path to read. component_type (class) – The class type of the component to extract.
Returns:	The first component found that matches the type.

PrintUtilities¶

Module for holding common printing utility functions.

KMCLib.Utilities.PrintUtilities.prettyPrint(msg, output=None)¶

Utility function for printing an output string to screen.

Parameters:	msg (str) – The message to print. out – The stream to write to. Defaults to sys.stdout.

KMCLib.Utilities.PrintUtilities.printHeader(output=None)¶

Utility function for printing the run header information.

Parameters:	out – The stream to write to. Defaults to sys.stdout.

Error¶

class KMCLib.Exceptions.Error.Error(msg='')¶

Class for describing an error.

__init__(msg='')¶

Constructor for the error class.

Parameters:	msg (string) – A message to the user describing what went wrong. If none is given the message is set to an empty string.

__str__()¶

Get a string representation of the error.

Returns:	The error message string.

Trajectory¶

class KMCLib.Utilities.Trajectory.Trajectory.Trajectory(trajectory_filename, max_buffer_size=None, max_buffer_time=None)¶

Trajectory base class for defining common trajectory functionality.

__init__(trajectory_filename, max_buffer_size=None, max_buffer_time=None)¶

Constructor for the Trajectory.

Parameters:	trajectory_filename (str) – The file name to write trajectory information to. max_buffer_size (int) – The max size of the the buffer in memory before writing to file. max_buffer_time (float) – The max time limit between dumps to file.

append(simulation_time, step, configuration)¶

Append to the trajectory. The trajectory if flushed to file if the flush time limit or buffer memory size limit has passed.

Parameters:	simulation_time (float) – The current time of the simulation. step (int) – The step number in the simulation. configuration – The configuration of the simulation.

LatticeTrajectory¶

class KMCLib.Utilities.Trajectory.LatticeTrajectory.LatticeTrajectory(trajectory_filename, configuration, max_buffer_size=None, max_buffer_time=None)¶

Class for handling lattice IO to a trajectory file.

_LatticeTrajectory__writeHeader(sites)¶

Write the header to the file.

Parameters:	sites – The sites in the system.

_LatticeTrajectory__writeToFile(simulation_time_buffer, step_buffer, types_buffer)¶

Append the types and time information to the trajectory. The trajectory if flushed to file if the flush time limit has passed.

Parameters:	simulation_time_buffer – A list of simulation times to be written to disk. step_buffer – A list of step numbers to be written. types_buffer – The types buffer given as a list of lists of strings.

__init__(trajectory_filename, configuration, max_buffer_size=None, max_buffer_time=None)¶

Constructor for the Trajectory.

Parameters:	trajectory_filename (str) – The file name to write trajectory information to. sites – The lattice sites of the configuration as an Nx3 list. max_buffer_size (int) – The max size of the the buffer in memory before writing to file. max_buffer_time (float) – The max time limit between dumps to file.

_bufferSize()¶: Calculate and return the buffer size.

_storeData(simulation_time, step, configuration)¶

Append the types and time information to the internal buffers.

Parameters:	simulation_time (float) – The current time of the simulation. step (int) – The step number in the simulation. configuration – The configuration of the simulation.

flush()¶: Write all buffers to file.

XYZTrajectory¶

class KMCLib.Utilities.Trajectory.XYZTrajectory.XYZTrajectory(trajectory_filename, configuration, max_buffer_size=None, max_buffer_time=None)¶

Class for handling xyz IO to a trajectory file.

_XYZTrajectory__writeHeader(configuration)¶