# Function and class reference¶

 atomicrex.Job Class for handling an atomicrex fitjob. atomicrex.AtomicStructure Class for handling atomic structures.

This is the Python interface module for atomicrex. It primarily provides convenient access to the atomicrex job object and the atomic structures associated with it.

class atomicrex.Job

Class for handling an atomicrex fitjob.

add_ase_structure(structure_id, atoms, structure_group=None)

Add a structure based on an ASE atoms object.

Parameters: structure_id (string) – structure name; to be used later for accessing structure in dictionary atoms (ASE atoms object) – atomic configuration structure_group (reference to a structure group) – reference to structure group, to which this structure is to be assigned; the default (None) implies the root group
add_library_structure(id, structure, params, structure_group=None)

Add a structure from the library of predefined structures.

Parameters: id (string) – structure name that will be used later to access the structure in the dictionary structure (string) – type of structure single element: FCC, BCC, DIA, SC, HCP, DHCP, beta tin, omega etc. multiple elements: rocksalt, cesium chloride, zinc blende, D8a, L12, fluorite, C15, Bh, D2d, Ni17Th2, Th2Zn17, L10, wurtzite etc. params (dictionary) – structural parameters including e.g, alat, clat, ca_ratio, type, type_A, type_B etc. structure_group (reference to a structure group) – reference to structure group, to which this structure is to be assigned; the default (None) implies the root group
calculate_gradient(parameters=None, eps=0.0001)

Computes the gradient of the objective function with respect to the potential parameters using a central finite difference scheme.

Parameters: parameters (list of floats) – the parameter set, at which the derivative is to be computed eps – step length for numerical differentiation
calculate_hessian(parameters=None, eps=0.0001)

Computes the matrix of second derivative of the objective function with respect to the potential parameters using a central finite difference scheme.

Parameters: parameters (list of floats) – the parameter set, at which the derivative is to be computed eps – step length for numerical differentiation
calculate_residual(params=None, style='squared')

Calculates the the objective function to be minimized during fitting. This is the weighted sum of the deviations of all properties from their target values.

Parameters: params (list) – parameter vector, if specified it will overwrite the current parameter vector associated with this job style (string) – method employed for calculating the residual contribution of this property to the objective function; possible values are: squared, squared_relative, user_defined, absolute_diff
derived_properties

dict – derived-properties associated with job.

get_potential_parameters()
Returns: potential parameters (DOFs) associated with job list of floats
name

str – name of fitjob

output_results()

Write resulting potential parameters to file.

parse_input_file(filename)

Parse the general and potential parameters from an XML file.

Parameters: filename (str) – name of XML input file
perform_fitting()

Perform the actual fitting by minimizing the residual.

potentials

dict – potentials associated with job.

prepare_fitting()

Set up a list of all degrees of freedom and properties that are to be fitted. This function needs to be called prior to any computation. It is called automatically before a model is fitted via the perform_fitting() call.

print_potential_parameters(only_active=False)

Print potential parameters associated with job. By default all parameters (including inactive ones) are written to stdout.

Parameters: only_active (bool) – If True exclude inactive parameters
print_properties()

Print properties associated with job.

set_potential_parameters(values)
Parameters: the potential parameters (DOFs) associated with the job. (Sets) – values (array) – list of double values representing the parameters
set_verbosity(verbosity)

Set the verbosity.

Parameters: verbosity (int) – verbosity level (0=none, 1=minimum, 2=medium, 3=maximum, 4=debug)
structures

dict – structures associated with job.

class atomicrex.AtomicStructure

Class for handling atomic structures.

cell

matrix – simulation cell metric

cell_origin

vector – origin point of the simulation cell in world coordinates

compute_energy(compute_forces=False, is_fitting=False, suppress_relaxation=False)

Computes the total energy and optionally the forces for this structure.

The function returns a scalar representing the energy of the structure. If the forces are computed they are stored in the structure object.

Parameters: compute_forces (bool) – Turns on the computation of forces. is_fitting (bool) – Determines whether this DOF should be relaxed (usually the desired behavior depends on the program phase). suppress_relaxation (bool) – If True structure relaxation will be suppressed.
compute_properties(is_fitting=False)

Computes all enabled properties of the structure.

Parameters: is_fitting (bool) – Determines whether this DOF should be relaxed (usually the desired behavior depends on the program phase).
deactivate_property(id, fit_enabled=False, output_enabled=False)

Deactivates a property in the structure, i.e. removes its contribution to the residual (objective function).

Parameters: id (string) – property identifier fit_enabled (bool) – set to True in order to still include the property in the calculation of the objective function output_enabled (bool) – set to True in order to still include the property when printing the results
deform_simulation_cell(deformation)

Applies an affine transformation to the cell and the atoms.

Parameters: deformation (3x3 matrix) – deformation matrix that is applied to the simulation cell.
forces

N x 3 doubles – list of atomic forces

get_atoms(job)

Returns the structure as an ASE atoms object.

Parameters: job – atomicrex job object; this is used to translate the atomicrex atom types to element names as understood by ASE atomic structure ASE atoms object
get_cell()
Returns: cell metric matrix
get_forces()

Return the forces on the atoms in the form of an array.

Returns: atomic forces list of vectors
get_number_of_atoms()
Returns: number of atoms in structure int
get_pbc()

Periodic boundary conditions.

Returns: the periodic boundary conditions list containing three booleans
get_positions()

Return the positions of the atoms

Returns: atomic positions Nx3 array
get_potential_energy()
Returns: potential energy of structure float
get_pressure_tensor(voigtIndex)
Parameters: filename (int) – voigtIndex Index of the pressure tensor component in Voigt notation. pressure tensor entry double
get_target_forces()

Get the target forces for a structure.

Returns: the target forces Nx3 array of floats
get_types()

Return the atom types in the form of a list.

Notes

The atom type indices start at 0 (zero).

Returns: atom types N ints
modify_property(id, target_value=None, relative_weight=1.0, fit_enabled=None, output_enabled=True)

Parameters: id (string) – property identifier target_value (double) – the target value [default: no target value] relative_weight (double) – relative weight of the property if it is included in the calculation of the objective function fit_enabled (bool) – calculation of the objective function output_enabled (bool) – set to True in order to include the property when printing the results
pbc

list of three booleans – Periodic boundary conditions.

positions

N x 3 doubles – atomic positions

potential_energy

float – potential energy of the structure

print_properties(show_all=False)

Print properties that are enabled for output and/or fitting.

Parameters: show_all (bool) – set to True in order to show all properties regardless of their internal preference (as determined from output_enabled and fit_enabled)

Notes

Note that compute_properties() must be called first in order to update the stored values of the structure’s properties.

properties

dict – Properties associated with structure.

set_positions(positions)

Set atomic positions to some new values.

Parameters: pos (Nx3 array) – new atomic positions
set_target_forces(target_forces)

Set the target forces for a structure.

Parameters: target_forces (Nx3 array of floats) – list of atom vectors representing the target forces
set_types(types)

Set atom types.

Parameters: types (N array of ints) – new atom types

Notes

The atom type indices start at 0 (zero).

tags

list of integers – atom tags

target_forces

Get the target forces for a structure.

Returns: the target forces Nx3 array of floats
types

list of integers – atom types

write_lammps_dump(filename, ghosts = False)

Exports the structure to a LAMMPS dump file.

Parameters: filename (string) – Name of the output file. ghosts (bool) – If True, ghost atoms used during computation of the energy will be included in the output.
write_poscar(filename, ghosts = False)

Exports the structure to a POSCAR file.

Parameters: filename (string) – Name of the output file. ghosts (bool) – If True, ghost atoms used during computation of the energy will be included in the output.