PopOff submodules

popoff.atom_types module

class popoff.atom_types.AtomType(atom_type_index, label, element_type, mass, charge, core_shell=None)

Bases: object

Class for each atom type.

property core_shell_string

Defines a string for a comment in a lammps input file format labelling cores/shells.

Parameters

None –

Returns

Either ‘core’, ‘shell’, or ‘’ if core_shell is None.

Return type

str

popoff.atoms module

class popoff.atoms.Atom(atom_index, molecule_index, coords, atom_forces, atom_type)

Bases: object

Class for each atom.

input_string()

Defines the a string in a lammps input file format for the atom data.

Parameters

None –

Returns

LAMMPS input string containing atom_index (int), molecule (int), atom_type_id (int), charge (float), and coordinates (list(float)).

Return type

str

popoff.bond_types module

class popoff.bond_types.BondType(bond_type_index, label, spring_coeff_1, spring_coeff_2=0.0)

Bases: object

Class for each bond type.

bond_string()

Defines the string input for the bond coefficient for LAMMPS.

Parameters

None –

Returns

Bond coefficient command for LAMMPS input.

Return type

str

popoff.bonds module

class popoff.bonds.Bond(bond_index, atom_indices, bond_type)

Bases: object

Class for each bond present between core-shell atoms.

input_string()

Defines the string in a LAMMPS input file format for the bond data.

Parameters

None –

Returns

LAMMPS input containing bond_index (int), bond_type_index (int), and atom_indices (list(int)).

Return type

str

popoff.collate_structures module

popoff.cross_validation module

popoff.fitting_code module

popoff.fitting_output module

popoff.fitting_output.create_directory(head_directory_name, local_struct_dir)

Returns a string of the joint file path to the output directory and creates the directory pathway.

Parameters

• head_directory_name (str) – Name of the main output directory.

• local_struct_dir (str) – fitted structure numbers joined by dashes.

Returns

directory pathway to output directory.

Return type

str

popoff.fitting_output.extract_stresses_and_forces(fit_data, values, args)

Returns the extracted forces and stress tensors for the dft training structures and then runs a shell relaxation (if core-shell) and single point canculation to get the forces and stress tensors using the fitted potential.

Parameters

• fit_data (FitModel) – all structural data and associated properties defined, with methods for implementing the fitting process using LAMMPS.

• args (list(str)) – Keys relating to the fitting parameters for the system, such as charge, springs, and buckingham parameter

• values (list(float)) – Values relating to the fitting arguments passes in.

Returns

3D array of dft forces in x,y,z for each atom in each structure; 3D array of fitted interatomic potential forces in x,y,z for each atom in each structure; 3D array of dft stress tensors in each structure; 3D array of fitted interatomic potential stress tensors in each structure.

Return type

np.array, np.array, np.array, np.array

popoff.fitting_output.save_data(struct_directory, labels, fit_output, dft_forces, ip_forces, dft_stresses, ip_stresses)

Collates the output data from the fit and saves it to different files within the designated output directory.

Parameters

• struct_directory (str) – directory pathway to local output directory.

• labels (list(str)) – List of parameters to be fitted.

• fit_output (OptimizeResult) – resulting values and fitting data from scipy. Full type is scipy.optimize.optimize.OptimizeResult.

• dft_forces (np.array) – 3D array of dft forces in x,y,z for each atom in each structure.

• ip_forces (np.array) – 3D array of fitted interatomic potential forces in x,y,z for each atom in each structure.

• dft_stresses (np.array) – 3D array of dft stress tensors in each structure.

• ip_stresses (np.array) – 3D array of fitted interatomic potential stress tensors in each structure.

Returns

None

popoff.from_structure module

popoff.from_structure.atoms_and_bonds_from_structure(structure, atom_types, bond_types)

Defines the atoms and bonds from the structure and given information from params.

Parameters

• structure (Structure) – A pymatgen structural object created from the transformed matrix structure, with forces included as site properties.

• atom_types (list(AtomType)) – AtomType objects including atom_type_index (int), label (str), mass (float), charge (float), and core_shell (str).

• bond_types (list(BondType)) – BondType objects including bond_type_index (int) and label (str).

Returns

Atom objects including atom_index (int), molecule_index (int), coords (np.array), forces (np.array), and atom_type (AtomType); Bond objects including bond_index (int), atom_indices (list(int)), and bond_type (BondType).

Return type

list(Atom), list(Bond)

popoff.from_structure.types_from_structure(structure, core_shell, charges, masses, cs_spring=None, verbose=True)

Defines the atom types and bond types from the structure and given information from params.

Parameters

• structure (Structure) – A pymatgen structural object created from the transformed matrix structure, with forces included as site properties.

• core_shell (dict) – A dictionary of booleans stating if any atoms should be made core-shell.

• charges (dict) – A dictionary of charges for each atom type. Key = atom label (str), value = charge(float)/sub_dict(dict). If atom is core-shell a sub dictionary will be the value, where sub_key = ‘core’ or ‘shell’ (str) and sub_value = charge (float).

• masses (dict) – A dictionary of masses for each atom type. Key = atom label (str), value = mass(float)/sub_dict(dict). If atom is core-shell a sub dictionary will be the value, where sub_key = ‘core’ or ‘shell’ and sub_value = mass (float).

• cs_spring (dict) – A dictionary of the cor-shell spring values. Key = atom labels separated by “-” (str), value = list of two values (float) for the spring values.

• verbose (bool(optional)) – Print verbose output. Default = True.

Returns

AtomType objects including atom_type_index (int), label (str), mass (float), charge (float), and core_shell (str); BondType objects including bond_type_index (int) and label (str).

Return type

list(AtomType), list(BondType)

popoff.input_checker module

popoff.input_checker.check_buckingham(label, bounds, params)

Checks the buckingham parameter input into the fitting fuction is correct. This includes checking the parameter is correctly formatted for a buckingham potential, that the elements exist within the system, neither bound is <=0, and the lower bound is smaller than the upper bound.

Parameters

• label (str) – buckingham parameter key, relating to the buckingham parameter to be fitted.

• bounds (tuple(float)) – Lower and upper bounds associated with the buckingham parameter.

• params (dict(dict)) – Setup dictionary containing the inputs for coreshell, charges, masses, potentials, and core-shell springs.

Returns

None

popoff.input_checker.check_coreshell(label, bounds, fit_data)

Checks core-shell inputs into the fitting fuctions are correct. This includes checking the charge ratio between the core and shell is applied to a core-shell atom, that the atoms exist within the system, the upper bound doesn’t exceed 2*formal charge, neither bound is <=0, and the lower bound is smaller than the upper bound.

Parameters

• label (str) – dQ parameter key, relating to the dQ to be applied to the stated element.

• bounds (tuple(float)) – Lower and upper bounds associated with the dQ parameter.

• fit_data (FitModel) – all structural data and associated properties defined, with methods for implementing the fitting process using LAMMPS.

Returns

None

popoff.input_checker.check_scaling_limits(bounds)

Checks scaling inputs into the fitting fuctions are correct. This includes checking the upper bound doesn’t exceed 1.0, neither bound is <=0, and the lower bound is smaller than the upper bound.

Parameters

bounds (tuple(float)) – Lower and upper bounds associated with the scaling parameter.

Returns

None

popoff.input_checker.check_spring(label, bounds, params)

Checks core-shell spring inputs into the fitting fuctions are correct. This includes checking the spring is applied to a core-shell atom, that the atoms exist within the system, the core and shell belong to the same element, neither bound is <=0, and the lower bound is smaller than the upper bound.

Parameters

• label (str) – core-shell spring parameter key, relating to the spring to be applied between the core and shell of an element.

• bounds (tuple(float)) – Lower and upper bounds associated with the spring parameter.

• params (dict(dict)) – Setup dictionary containing the inputs for coreshell, charges, masses, potentials, and core-shell springs.

Returns

None

popoff.input_checker.setup_error_checks(include_labels, bounds_list, fit_data, params)

Checks the labels list and bounds list are the same length, then iterated through each item to run specific checks ensuring the labels and associated bounds are appropriate.

Parameters

• include_labels (list(str)) – List of parameters to be fitted.

• bounds_list (list(tuple(float))) – List of lower and upper bound tuples associated with each parameter.

• fit_data (FitModel) – all structural data and associated properties defined, with methods for implementing the fitting process using LAMMPS.

• params (dict(dict)) – Setup dictionary containing the inputs for coreshell, charges, masses, potentials, and core-shell springs.

Returns

None

popoff.lammps_data module

popoff.lattice_parameters module

popoff.plotting module

popoff.plotting.plot_errors(error_dict, output_directory, xlabel_rotation=50, title='default', save=True)

Plots the chi squared errors for each fit in a sequence of fits, with the x-axis being the fit (labeled with the structure numbers in the fit) and the y-axis being the chi squared error.

Parameters

• error_dict (dict) – Keys are the structurs in the fit separated by a dash, i.e. ‘1-2-5’, and values are the chi squared error of that fit.

• output_directory (str) – Directory pathway to output directory.

• xlabel_rotation (int(optional)) – Rotation applied to the x-axis labels. Default=50.

• title (str(optional)) – plot title, default=’fitted errors ($chi^2$)’.

• save (bool(optional)) – True to save the plot, Flase to not save. Default=True.

Returns

None

popoff.plotting.plot_forces(dft_forces, ip_forces, output_directory, local_directory, alpha=0.02, save=True)

Plots the forces for each fit in a sequence of fits, with the x-axis being the fit (labeled with the structure numbers in the fit) and the y-axis being the forces.

Parameters

• dft_forces (np.array) – dft forces associated with each atom (x,y,and z) in each structure fitted.

• ip_forces (np.array) – Fitted forces associated with each atom (x,y,and z) in each structure fitted.

• output_directory (str) – Directory pathway to output directory.

• local_directory (str) – The individual fit directory in a series of fits or the singular fit directory.

• alpha (float(optional)) – Degree of transprancy for the plot series. Default=0.02.

• save (bool(optional)) – True to save the plot, Flase to not save. Default=True.

Returns

None

popoff.plotting.plot_parameters(potentials_dict, output_directory, xlabel_rotation=50, title='default', save=True)

Plots the potential parameters for each fit in a sequence of fits, with the x-axis being the fit (labeled with the structure numbers in the fit) and the y-axis being the parameter value.

Parameters

• potentials_dict (dict) – Keys are the potential parameter labels (str) and values are a tuple of the fitted structure numbers (str) and the associated parameter value (float).

• output_directory (str) – Directory pathway to output directory.

• xlabel_rotation (int(optional)) – Rotation applied to the x-axis labels. Default=50

• title (str(optional)) – Plot title, default=’’{} fitted parameter’.format(k)’.

• save (bool(optional)) – True to save the plot, Flase to not save. Default=True.

Returns

None

popoff.plotting.plot_stresses(dft_stresses, ip_stresses, output_directory, local_directory, save=True)

Plots the stresses for each fit in a sequence of fits, with the x-axis being the fit (labeled with the structure numbers in the fit) and the y-axis being the stresses.

Parameters

• dft_stresses (np.array) – dft stress tensors associated with each structure fitted.

• ip_stressed (np.array) – Fitted stress tensors associated with each structure fitted.

• output_directory (str) – Directory pathway to output directory.

• local_directory (str) – The individual fit directory in a series of fits or the singular fit directory.

• save (bool(optional)) – True to save the plot, Flase to not save. Default=True.

Returns

None

popoff.plotting.setup_error_dict(head_directory_name)

Returns a dictionary of the chi squared errors associated with each fit in the group.

Parameters

head_directory_name (str) – Name of the main output directory.

Returns

Error dictionary where the keys are the structurs in the fit separated by a dash, i.e. ‘1-2-5’, and values are the chi squared error of that fit.

Return type

dict

popoff.plotting.setup_potentials_dict(head_directory_name)

Returns a dictionary of the chi squared errors associated with each fit in the group.

Parameters

head_directory_name (str) – Name of the main output directory.

Returns

Potentials dictionary where the keys are the potential parameter labels (str) and values are a tuple of the fitted structure numbers (str) and the associated parameter value (float).

Return type

list(dict)

popoff.potential_parameters module

class popoff.potential_parameters.BuckinghamParameter(label_string, param_type, value)

Bases: object

Class that contains the information for each parameter in the buckingham potentials.

popoff.potential_parameters.buckingham_parameters(potentials)

Extracts and defines each buckingham parameter in the buckingham potentials.

Parameters

potentials (dict) – Contains buckingham potentials list(float), where the potentials keys are atom label pairs (str), example: ‘Li-O’.

Returns

BuckinghamParameter objects including label_string (str), param_type (str), and value (float).

Return type

list(BuckinghamParameter)

popoff.potentials module

class popoff.potentials.BuckinghamPotential(labels, atom_type_index, a, rho, c)

Bases: object

Class that contains the information for each buckingham potential, where parameters are BuckinghamParameter objects.

potential_string()

Prints potential string for lammps pair_coeff command.

Parameters

None –

Returns

LAMMPS input command for pair coefficients containing atype_index for atom pairs, and buckingham potential parameter values.

Return type

str

popoff.potentials.buckingham_potentials(potentials_dict, atom_types, parameters)

Defines the buckingham potential for each given atom pair. Making sure if core-shell models are used, the interations are on teh shell, not the core.

Parameters

• potentials (dict) – Contains buckingham potentials (list(float)), where the potentials keys are atom label pairs (str), example: ‘Li-O’.

• atom_types (list(AtomType)) – AtomType objects including atom_type_index (int), label (str), mass (float), charge (float), and core_shell (str).

• parameters (list(BuckinghamParameter)) – BuckinghamParameter objects including parameter_type (str), label_string (str), and value (float).

Returns

BuckinghamPotential objects including labels (list(str)), atom_type_index (list(int)), a (BuckinghamParameter), rho (BuckinghamParameter), and c (BuckinghamParameter).

Return type

list(BuckinghamPotential)

Module contents