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: derivedproperties associated with job.

get_potential_parameters
()¶ Returns: potential parameters (DOFs) associated with job Return type: 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 Returns: atomic structure Return type: ASE atoms object

get_cell
()¶ Returns: cell metric Return type: matrix

get_forces
()¶ Returns: atomic forces Return type: list of vectors

get_number_of_atoms
()¶ Returns: number of atoms in structure Return type: int

get_pbc
()¶ Periodic boundary conditions.
Returns: the periodic boundary conditions Return type: list containing three booleans

get_positions
()¶ Returns: atomic positions Return type: list of vectors

get_potential_energy
()¶ Returns: potential energy of structure Return type: float

get_pressure_tensor
(voigtIndex)¶ Parameters: filename (int) – voigtIndex Index of the pressure tensor component in Voigt notation. Returns: pressure tensor entry Return type: double

get_target_forces
()¶ Get the target forces for a structure.
Returns: the target forces Return type: Nx3 array of floats

modify_property
(id, target_value=None, relative_weight=1.0, fit_enabled=None, output_enabled=True)¶ Add and/or modify a property.
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_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
list of integers: atom tags

target_forces
¶ Get the target forces for a structure.
Returns: the target forces Return type: 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.
