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.checkAndNormaliseBucketEntry(t)¶

Check that the foramt of the type entry t is any of the valid “A” - single particle. (N,”A”) - numbered single particle. [“A”, (N1,”B”)] - a list with a combination of the other two.

Parameters:	t – The type entry to check.
Returns:	The normalized [(N,”A”)] formatted type.

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.bucketListToStdVectorStdVectorString(bucket_list)¶

Converts a list of the format [[(n,”A”), ...], ...] to a std::vector< std::vector<std::string> > representation.

Parameters:	bucket_list – The list to convert.
Returns:	A corresponding std::vector<std::vector<std::string> > object.

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.stdVectorStringToStringList(cpp_list)¶

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

Parameters:	cpp_list – The std::vector to convert.
Returns:	A corresponding list of strings.

KMCLib.Utilities.ConversionUtilities.stdVectorTypeBucketToPython(cpp_vector, cpp_type_map)¶

Translate a std::vector<TypeBucket> object to the python format [[(n, “A”), ... ], ... ] by using a map of the type std::vector<std::string>.

Parameters:	cpp_vector – The C++ vector to translate. cpp_type_map – The type map to use.

KMCLib.Utilities.ConversionUtilities.stringListToStdVectorStdVectorString(string_list)¶

Converts a list of strings to a std::vector<std::vector<std::string> > object with one elemnt in each of the inner vectors.

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

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.

KMCLib.Utilities.ConversionUtilities.toShortBucketsFormat(types_list)¶

Convert any valid types information to the short buckets format, i.e. on the form [[(n,”A”), ...], ...]

Parameters:	types_list – The list to convert.
Returns:	The types list in the short buckets format.

KMCLib.Utilities.ConversionUtilities.typeBucketToList(type_bucket)¶

Convert a TypeBucket to a numpy list.

Parameters:	type_bucket – The type bucket to convert.
Returns:	A corresponding python list.

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)¶

Write the header to the file.

Parameters:	configuration – The configuration of the system.

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

Constructor for the XYZTrajectory.

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 coordinate, 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.