MDMC.common package

Submodules

MDMC.common.constants module

Module which defines physical constants

MDMC.common.constants.h: float = 4.135667696e-15: Planck’s constant in eV s

MDMC.common.constants.h_bar: float = 6.582119568038699e-16: Reduced Planck’s constant in eV s

MDMC.common.decorators module

Module which defines decorators.

MDMC.common.decorators.mod_docstring(replacements: dict[str, str]) → Callable[source]

Decorator for modifying the docstring of a function, method, class or property.

This is done by replacing specified substrings. After replacement the docstring is text wrapped to ensure that line length and indentations are preserved.

While this can be used for replacements in equations, care must be taken to ensure that wrapping does not cause line breaks in invalid places in the LaTeX.

Parameters:: replacements (dict[str, str]) – {old: new} pairs where old is a str in the docstring which will be replaced, and new is the str it should be replaced with.
Returns:: A decorator which modifies the docstring of a function, method, class or property.
Return type:: function
Raises:: TypeError – If mod_docstring is applied to an object which is not a function, method, class, or property.

Examples

To dynamically modify the docstring of a function so “this” is replaced with “that”:

@mod_docstring({'this': 'that'})
def function():
    """
    The word this will be replaced
    """

To dynamically modify the docstring of a class so “this” is replaced with “that”:

@mod_docstring({'this': 'that'})
class DocClass():
    """
    This is the class level docstring. The word this will be
    replaced.
    """

To dynamically modify the docstring of a property so “this” is replaced with “that”:

@property
@mod_docstring({'this': 'that'})
def prop():
    """
    The word this will be replaced.
    """

MDMC.common.decorators.repr_decorator(attribute: str, *attributes: str | None)[source]

Implement __repr__ for a class using passed attributes (including properties).

The first element of all __repr__ returns is always the name of the class.

Warning

Testing for repr_decorator is restricted to testing the decorator outputs the correct format, not whether each occurence it is used is valid. It is strongly recommended that classes decorated with repr_decorator are tested to ensure that repr(class) is valid, for instance whether the class actually has all of the attributes passed as str to repr_decorator.

Parameters:

attribute (str) – The name of an attribute of the class being decorated. This attribute (or property) will be included in the __repr__ of the class.
*attributes (str) – Zero or more str with the name of an attribute (or property) of the class being decorated. These attributes will be included in the __repr__ of the class.

Returns:

A class with __repr__ implemented such that attribute and attributes are printed.

Return type:

class

Examples

Add a repr_decorator to the Atom class to include the name attribute and the position property:

>>> @repr_decorator('name', 'position')
... Class Atom(Structure):
...
...     def __init__(self, element, name, position):
...         self.element = element
...         self.name = name
...         self.position = position
...
...     @property
...     def position(self):
...         return self._position
...
... atom = Atom('H', 'Hydrogen', [1., 1., 1.])
... atom
< Atom
 {name: 'Hydrogen',
  position: [1., 1., 1.]}>

MDMC.common.decorators.set_docstring(docstring: str) → Callable[source]

Decorator for setting the docstring of a function, method, class or property.

The new docstring is text wrapped to ensure that the line length is valid. It is assumed that the specified docstring has the correct indentations.

Parameters:: docstring (str) – The new docstring for the function, method, class or property.
Returns:: A decorator which sets the docstring of a function, method, class or property.
Return type:: function
Raises:: TypeError – If set_docstring is applied to an object which is not a function, method, class, or property.

Examples

To dynamically set the docstring of a function:

@set_docstring("This is the new docstring")
def function():
    """
    This docstring will be replaced
    """

To dynamically set the docstring of a class:

@set_docstring("This is the new docstring")
class DocClass():
    """
    This is a class level docstring. This docstring will be
    replaced.
    """

To dynamically set the docstring of a property:

@property
@set_docstring("This is the new docstring")
def prop():
    """
    This docstring will be replaced
    """

MDMC.common.decorators.time_function_execution(func: Callable) → Callable[source]

Time a given function.

Create an instance of the TimeKeeper and stores the function execution time in TimeKeeper’s class attributes.

This decorator is meant to be used on functions that are likely to be using up too much CPU time, so the scale of the problem can be assessed.

Parameters:: func (Callable) – Function to time.
Returns:: Decorated function with attached timer.
Return type:: function

MDMC.common.decorators.unit_decorator(unit: str | None) → Callable[source]

Decorate property.setter methods to add units.

Adds units to the values passed to property.setter methods. These units are displayed when either repr or str is called for the corresponding property.getter method.

Suitable for use with setter methods that either take float (or objects that can be cast to float), or NumPy array (or objects that can be cast to NumPy array).

Parameters:: unit (str or None) – The unit applied to the property. If None then self.unit is used, which enables classes to have properties with units defined at runtime.
Returns:: A property.setter function with a value parameter which has a unit (e.g. UnitFloat or UnitNDArray).
Return type:: function

Examples

Add a unit_decorator to the position property:

>>> Class Atom(Structure):
...
...     @property
...     def position(self):
...         return self._position
...
...     @position.setter
...     @unit_decorator(unit=Unit('Ang'))
...     def position(self, value):
...         self._position = value

MDMC.common.decorators.unit_decorator_getter(unit: str | None) → Callable[source]

Decorate property.getter methods to add units.

Adds units to the return values of property.getter methods. These units are displayed when either repr or str is called.

Suitable for use with setter methods that either take float (or objects that can be cast to float), or NumPy array (or objects that can be cast to NumPy array). This method exists for properties which have no setter method.

Parameters:: unit (str or None) – The unit applied to the property. If None then self.unit is used, which enables classes to have properties with units defined at runtime.
Returns:: A property.getter function with a return type which has a unit (e.g. UnitFloat or UnitNDArray).
Return type:: function

Examples

Add a unit_decorator_getter to the volume property:

>>> Class Universe:
...
...     @property
...     @unit_decorator_getter(unit=Unit('Ang') ^ 3)
...     def volume(self):
...         return self.dimensions ** 3

MDMC.common.decorators.weakref_cache(maxsize: int = 128) → Callable[source]

Weakref LRU cache to avoid memory leaks.

Caches on instance methods store self, which can lead to excess memory use. This avoids it by only holding a weakref to the instance.

Parameters:: maxsize (int, optional, default=128) – Max size of LRU cache.
Returns:: Decorated function with LRU cache.
Return type:: function

MDMC.common.decorators.wrap_docstring(docstring: str, line_length: int) → str[source]

Wrap a docstring to a specific line length.

This maintains any indentation which exists at the start of a line. While equations should not be affected by this wrapping, it is recommended that docstrings with .. math:: are visually checked after wrapping.

Parameters:

docstring (str) – The docstring to be wrapped.
line_length (int) – The maximum line length of the docstring before it is wrapped.

Returns:

The wrapped docstring.

Return type:

str

Raises:

ValueError – If any indent has more characters than the line_length, as the wrapping cannot then preserve the correct indent

MDMC.common.df_operations module

Contains some utility functions related to pd.DataFrames, including filtering functions.

MDMC.common.df_operations.filter_dataframe(values: Sequence, dataframe: DataFrame, column_names: list[str]) → DataFrame[source]

MDMC.common.df_operations.filter_dataframe(values: Sequence, dataframe: DataFrame, column_regex: str) → DataFrame

Ignore duplicated rows (i.e. only return the first occurence of any duplicated row).

Parameters:

values (Sequence) – The values for which to filter. If any of these values occur in any of the columns defined by column_names or column_regex, the row will be included in the filtered return.
dataframe (pandas.DataFrame) – The pd.DataFrame object to be filtered.
column_names (list[str], optional) –
A list of str specifying the names of the columns which will be used to filter the Dataframe.

This cannot be passed if column_regex is also passed.
column_regex (str) –
A regular expression matching one or more column names. This specifies which columns will be used to filter the DataFrame.

This cannot be passed if column_names is also passed.

Returns:

A DataFrame which has been filtered so that each value in values must occur in one of the columns of DataFrame that are specified by column_names or matched by column_regex.

Return type:

pandas.DataFrame

Raises:

ValueError – If both column_names and column_regex were passed. If there are fewer column_names than values.

MDMC.common.df_operations.filter_ordered_dataframe(values: Sequence, dataframe: DataFrame, column_names: list[str], wildcard: str = None) → DataFrame[source]

MDMC.common.df_operations.filter_ordered_dataframe(values: Sequence, dataframe: DataFrame, column_regex: str, wildcard: str = None) → DataFrame

Filter a pd.DataFrame with an iterable of ordered values.

The values must occur in columns in the correct order, with the order specified by column_names, or by the order which column order which occurs from using column_regex.

This filter ignores rows which are duplicated (i.e. it only returns the first occurence of any duplicated rows).

Parameters:

values (Sequence) – The values for which to filter. If any of these values occur in any of the columns defined by column_names or column_regex, the row will be included in the filtered return.
dataframe (pandas.DataFrame) – The pd.DataFrame object to be filtered.
column_names (list[str], optional) –
A list of str specifying the names of the columns which will be used to filter the Dataframe.

This cannot be passed if column_regex is also passed.
column_regex (str) –
A regular expression matching one or more column names. This specifies which columns will be used to filter the DataFrame.

This cannot be passed if column_names is also passed.
wildcard (str) – A str which will be a match in any column.

Returns:

A DataFrame which has been filtered so that each value in values must occur in one of the columns of DataFrame that are specified by column_names or matched by column_regex.

Return type:

pandas.DataFrame

Raises:

ValueError – If both column_names and column_regex were passed. If there are fewer column_names than values.

MDMC.common.log module

This module configures logging for MDMC.

MDMC.common.log.create_logger(name: str = 'MDMC', logfile: str = 'MDMC.log', level: int = 20) → Logger[source]

Create a formatter logger which outputs to a log file.

Parameters:

name (str, optional) – The name of the logger.
logfile (str, optional) – The name of the log file.
level (int, optional) – The debug level of the logger.

Returns:

Logger to handle MDMC logging.

Return type:

logging.Logger

MDMC.common.log.start_logging(logfile: str = 'MDMC.log', level: int = 20, capture_warnings: bool = True)[source]

Start one or more loggers to capture log information from MDMC.

Parameters:

logfile (str, optional) – The base name of the logfile.
level (int, optional) – The logging level, corresponding to values in standard library logging module.
capture_warnings (bool, optional) – Whether warnings are captured by the logger (with a level of WARNING) or printed to stdout.

MDMC.common.mathematics module

A module containing mathematical functions.

MDMC.common.mathematics.UNIT_VECTOR = array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]): Array of standard unit vectors. Used as a standard basis of 3D space.

MDMC.common.mathematics.correlation(input1: ndarray, *, normalise: bool = False) → ndarray[source]

MDMC.common.mathematics.correlation(input1: ndarray, input2: ndarray, normalise: bool = False) → ndarray

Compute the correlation of two vectors.

The Fast Correlation Algorithm (FCA) is utilised.

If only a single input is provided, the autocorrelation is calculated.

Parameters:

input1 (numpy.ndarray) – A 1D array of data.
input2 (numpy.ndarray, optional) – A 1D array of data. If None, autocorrelation of input1 is calculated. Default is None.
normalise (bool, optional) – If True, the correlation is normalised at each point to the number of contributions to that point. Default is False.

Returns:

A 1D array of the same length as the input1 containing the correlation between input1 and input2 (or autocorrelation of input1 if input2 is None).

Return type:

numpy.ndarray

MDMC.common.mathematics.faster_autocorrelation(input1: ndarray, weights: ndarray | float = None) → ndarray[source]

The autocorrelation of a vector.

The Fast Correlation Algorithm (FCA) is utilised.

Parameters:

input1 (numpy.ndarray) – A 1D array of data.
weights (np.ndarray or float) – Either weights for each point or single weight for all points.

Returns:

A 1D array of the same length as the input1 containing the correlation between input1 and input2 (or autocorrelation of input1 if input2 is None).

Return type:

numpy.ndarray

MDMC.common.mathematics.faster_correlation(input1: ndarray, input2: ndarray) → ndarray[source]

Compute the correlation of two vectors.

The Fast Correlation Algorithm (FCA) is utilised.

Parameters:

input1 (numpy.ndarray) – A 1D array of data.
input2 (numpy.ndarray, optional) – A 1D array of data.

Returns:

A 1D array of the same length as the input1 containing the correlation between input1 and input2 (or autocorrelation of input1 if input2 is None).

Return type:

numpy.ndarray

MDMC.common.resolution_functions module

A module for containing all resolution functions.

MDMC.common.resolution_functions.gaussian(x: ndarray, sigma: float, mu: float = 0.0, norm: bool = True) → ndarray[source]

Calculate the Gaussian distribution.

Parameters:

x (numpy.ndarray) – The x values at which the Gaussian distribution is calculated.
sigma (float) – The standard deviation of the Gaussian.
mu (float, optional) – The offset of the Gaussian.
norm (bool, optional) – If True, resulting distribution is normalized to unity.

Returns:

A discretised Gaussian distribution of the same length as x.

Return type:

numpy.ndarray

MDMC.common.resolution_functions.lorentzian(x: ndarray, gamma: float, x_0: float = 0.0) → ndarray[source]

Calculate the Lorentzian (Cauchy) distribution.

Parameters:

x (numpy.ndarray) – The x values at which the Gaussian distribution is calculated.
gamma (float) – The full-width at half-maximum.
x_0 (float, optional) – The offset of the distribution.

Returns:

A discretised Lorentzian distribution of the same length as x.

Return type:

numpy.ndarray

MDMC.common.time_keeper module

TimeKeeper class designed to track per-function level execution time.

class MDMC.common.time_keeper.TimeKeeper[source]

Bases: object

Class to track per-function execution time.

A class designed for storing function timing information in class variable. The idea is to access the class variables throught a class instance, typically in a function decorator called time_function_execution.

execution_time: dict[str, float] = {}: Total accumulated time for given functions.

function_called(fname: str)[source]

Increment number of the function calls for specified function.

Parameters:

fname (str) –

A descriptive name of the function that has been called.

Typically this name will be generated by the time_function_execution decorator.

number_of_calls: dict[str, int] = {}: Number of times a function has been called.

started: float = 1732030535.7663622: Time at which TimeKeeper started.

summarise_results() → list[tuple[str, int, float]][source]

Convert all the recorded function timing data into a list.

Returns:: Function name, number of function calls and accumulated execution time.
Return type:: list[tuple[str, int, float]]

time_passed(fname: str, exp_time: float)[source]

Compute accumulated execution time.

Add the execution time of the function to the accumulated execution time from all the times that function has been called.

Parameters:

fname (str) –
A descriptive name of the function that has been called.

Typically this name will be generated by the time_function_execution decorator.
exp_time (float) – The wall time that has expired during the function execution.

total_time() → float[source]

Return the total wall time since we started timing.

Returns:: Number of seconds since we started timing any of the functions.
Return type:: float

MDMC.common.units module

Module for all unit definitions and operations.

This includes defining units used in MDMC, converting units, and subclassing data strucures (float, array) so that they have a unit attribute. This style follows that of the Atomic Simulation Environment.

As members of units.py are set dynamically, pylintrc excludes member checking for units.py using the generated-members keyword. Care must be taken to ensure members exist when importing from units.py, as these will not be linted.

MDMC.common.units.CODATA = {'2014': {'_Grav': 6.67408e-11, '_Nav': 6.022140857e+23, '_amu': 1.66053904e-27, '_c': 299792458.0, '_e': 1.6021766208e-19, '_hplanck': 6.62607004e-34, '_k': 1.38064852e-23, '_me': 9.10938356e-31, '_mp': 1.672621898e-27, '_mu0': 1.2566370614359173e-06}}: CODATA 2014 taken from ASE.units, originally from: http://arxiv.org/pdf/1507.07956.pdf.

MDMC.common.units.CODATA_VERSION = '2014': Version of CODATA constants to load.

class MDMC.common.units.Unit(string: str, components: defaultdict[list] = None)[source]

Bases: str

A class for defining unit strings.

It possesses additional * and / operands so that combined units can be returned.

Note

NON-INTEGER POWER OPERATIONS ARE CURRENTLY NOT IMPEMENTED

Parameters:

string (str) – The unit, which can contain / to specify divisors and ^ to specify powers. It can contain int which are used to specify order of magnitude (e.g. 10^6 Pa). It can also contain negative powers, but there must not be a space between the negative sign and the number (e.g. Ang ^ -1 NOT Ang ^ - 1). Brackets and parentheses are not supported, and any of the characters []() will be ignored.
components (defaultdict[list], optional) – Sets the components attribute (see Attributes). Default is None.

components

Contains the components of the Unit, separated into two list s (numerator and denominator) depending on which side of the fraction each component is on. If the Unit is a base unit i.e. initialized using Unit(), then the components only has a numerator and this is the Unit string. If it a combined Unit (created by either __mul__, __div__ or __pow__) then the Unit objects which combined to form it make up the components.

Type:: defaultdict[list]

conversion_factor

The factor by which to multiply a value in order to express it in system units. For example Unit('ps').conversion_factor is 1000. as the system units are femtoseconds.

Type:: float

Examples

Base units can be set:

>>> time_unit = Unit('s')

Compound units can be set with spaces separating base units which are multiplied:

>>> charge_unit = Unit('A s')

Compound units can be set with / separating base units which are divided:

>>> velocity_unit = Unit('m / s')

Units raised to a power can be set with ^:

>>> volume_unit = Unit('Ang ^ 3')

Compound units can be set with a combination of these operands:

>>> force_unit = Unit('kg m / s ^ 2')

To set an inverse unit, the power operation can be applied to a Unit:

>>> frequency = Unit('s') ** -1

Or set with ^ within the string:

>>> frequency = Unit('s ^ -1')

Or with / within the string:

>>> frequency = Unit('1 / s')

Orders of magnitude can also be included:

>>> pressure = Unit('10 ^ 6 Pa')

property base: bool

Get whether the Unit is a base or compound Unit.

Returns:: If True, Unit is a base Unit (only has a single element in the components numerator list).
Return type:: bool

property conversion_factor: float

Multiplicative factor to get system units.

Calculates the factor by which a value with this Unit should be multiplied in order to express it in system units. This takes into account any orders of magnitude and compound units.

The conversion_factor for a Unit composed only of system units is therefore always 1.

Returns:: The conversion factor to system units for the relevant property.
Return type:: float
Raises:: KeyError – If invalid unit provided.

property physical_property: str

The physical property (e.g. ‘LENGTH’, ‘TIME’, …) that the unit measures.

Note that compound units may not be supported, for the list of supported units see create_units.

Returns:: The physical property.
Return type:: str or None
Raises:: KeyError – If invalid unit provided.

class MDMC.common.units.UnitFloat(value: float, unit: Unit | str)[source]

Bases: float

Subclasses float so that it contains a unit attribute.

unit attribute is returned when __repr__ or __str__ are called.

Parameters:

value (float) – The value of the UnitFloat.
unit (Unit, str) – A Unit or a str representing the unit.

Notes

As both __repr__ and __deepcopy__ rely on the float being real, this class is not compatible with complex numbers. This should be immaterial as no quantity which possesses units is complex.

property unit: Unit

Get or set the unit.

Either a str or a Unit can be passed to the setter.

Returns:: The Unit equivalent to the passed unit parameter.
Return type:: Unit

class MDMC.common.units.UnitNDArray(shape, unit, dtype=<class 'float'>, buffer=None, offset=0, strides=None, order=None)[source]

Bases: ndarray

Subclasses ndarray so that it contains a unit attribute.

unit attribute is returned when __repr__ or __str__ are called

Parameters:

shape (tuple of ints) – Shape of created array.
unit (Unit, str) – A Unit or a str representing the unit.
dtype (data-type, optional) – Any object that can be interpreted as a NumPy data type.
buffer (object exposing NumPy buffer interface, optional) – Used to fill the array with data.
offset (int, optional) – Offset of array data in buffer.
strides (tuple of ints, optional) – Strides of data in memory.
order (str, optional) – Either C for row-major or F for column-major. Default is C.

property unit: None

Get or set the unit.

Either a str or a Unit can be passed to the setter.

Returns:: The Unit equivalent to the passed unit parameter.
Return type:: Unit

MDMC.common.units.create_units(codata_version: str) → dict[Unit, float][source]

Create a dict of Unit based on the CODATA version.

Parameters:: codata_version (str) – The CODATA version to be used.
Returns:: Contains (Unit: conversion factor) pairs.
Return type:: dict

MDMC.common.units.unit_array(obj, unit: Unit | str, dtype=None) → UnitNDArray[source]

Create a UnitNDArray from an array or any nested sequence.

This mimics the manner in which NumPy creates arrays (although is in Python not C), except several arguments are excluded.

Also, unlike np.array(None), passing obj=None to unit_array results in None being returned. This allows classes to have properties with units which can be either have a value or be undefined.

Parameters:

obj (None or array_like) – An object derived from collections.Sequence. If None, then None is returned.
unit (Unit, str) – A Unit or a str representing the unit.
dtype (data-type, optional) – Any object that can be interpreted as a NumPy data type.

Returns:

A UnitArray object satisfying the specified requirements.

Return type:

UnitArray

Module contents

Common functions and classes used by multiple other subpackages.

constants
decorators
df_operations
mathematics
resolution_functions
units