atomman package

Functions and attributes

atomman.rootdir

The absolute path to the iprPy package’s root directory used to locate contained data files.

Type:str
atomman.displacement(system_0, system_1, box_reference='final')

Compute the displacement vectors between all matching atoms for two systems.

Parameters:
  • system_0 (atomman.System) – The initial system to calculate displacements from.
  • system_1 (atomman.System) – The final system to calculate displacements to.
  • box_reference (str or None) – Specifies which system’s boundary conditions to use. ‘initial’ uses system_0’s box and pbc. ‘final’ uses system_1’s box and pbc (Default) None computes the straight difference between the positions without accounting for periodic boundaries.
Returns:

The displacement vectors for all atoms.

Return type:

numpy.ndarray

Raises:

ValueError – If the systems have different numbers of atoms or for invalid box_reference values.

atomman.dump(style, system, **kwargs)

Convert a System to another format.

Parameters:
  • style (str) – Indicates the format of the content to dump the atomman.System as.
  • system (atomman.System) – The system to convert.
  • kwargs (any, optional) – Any extra keyword arguments to pass to the underlying dump methods.
Returns:

Any content returned by the underlying dump methods.

Return type:

str, object or tuple

atomman.dump_ase_Atoms(system, symbols=None, return_prop=False)

Convert an atomman.System into an ase.Atoms.

Parameters:
  • system (atomman.System) – A atomman representation of a system.
  • symbols (tuple, optional) – List of the element symbols that correspond to the atom types. If not given, will use system.symbols if set, otherwise no element content will be included.
  • return_prop (bool, optional) – Indicates if the extra per-atom properties are to be returned in a dictionary. Default value is False.
Returns:

  • aseatoms (ase.Atoms) – An ase representation of a collection of atoms.
  • prop (dict) – Dictionary containing any extra per-atom properties to include. Returned if return_prop is True.

atomman.dump_atom_data(system, f=None, atom_style='atomic', units='metal', float_format='%.13f', return_info=True)

Write a LAMMPS-style atom data file from a System.

Parameters:
  • system (atomman.System) – The system to write to the atom data file.
  • f (str or file-like object, optional) – File path or file-like object to write the content to. If not given, then the content is returned as a str.
  • atom_style (str, optional) – The LAMMPS atom_style option associated with the data file. Default value is ‘atomic’.
  • units (str, optional) – The LAMMPS units option associated with the data file. Default value is ‘metal’.
  • float_format (str, optional) – c-style formatting string for floating point values. Default value is ‘%.13f’.
  • return_info (bool, optional) – Indicates if the LAMMPS command lines associated with reading in the file are to be returned as a str. Default value is True.
Returns:

  • content (str) – The data file contents (returned if f is not given).
  • read_info (str) – The LAMMPS input command lines to read the created data file in (returned if return_info is True).

atomman.dump_atom_dump(system, f=None, lammps_units='metal', scale=False, prop_name=None, table_name=None, shape=None, unit=None, dtype=None, prop_info=None, float_format='%.13f', return_prop_info=False)

Write a LAMMPS-style atom data file from a System.

Parameters:
  • system (atomman.System) – The system to write to the atom data file.
  • f (str or file-like object, optional) – File path or file-like object to write the content to. If not given, then the content is returned as a str.
  • lammps_units (str, optional) – The LAMMPS units option associated with the table values. This is used for the box dimensions and default units for standard dump properties (not compute/fix definitions).
  • scale (bool, optional) – Flag indicating if atom positions are to be scaled relative to the box (True) or given in absolute Cartesian values (False, default).
  • prop_name (list, optional) – The Atoms properties to include. If neither prop_name or prop_info are given, all system properties will be included.
  • table_name (list, optional) – The dump table column name(s) that correspond to each prop_name. If not given, the table_name values will be based on the prop_name and shape values.
  • shape (list, optional) – The shape of each per-atom property. If not given, will be inferred from the length of each table_name value.
  • unit (list, optional) – Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in box-scaled units. If not given, unit values will be taken based on lammps_units if prop_name corresponds to a standard LAMMPS property, otherwise will be set to None (no conversion).
  • dtype (list, optional) – Allows for the data type of each property to be explicitly given. Values of None will infer the data type from the corresponding property values. If not given, all values will be None.
  • prop_info (list of dict, optional) – Structured form of property conversion parameters, in which each dictionary in the list corresponds to a single atoms property. Each dictionary must have a ‘prop_name’ field, and can optionally have ‘table_name’, ‘shape’, ‘unit’, and ‘dtype’ fields.
  • float_format (str, optional) – c-style formatting string for floating point values. Default value is ‘%.13f’.
  • return_prop_info (bool, optional) – Flag indicating if the filled-in prop_info is to be returned. Having this allows for 1:1 load/dump conversions. Default value is False (prop_info is not returned).
Returns:

  • content (str) – The generated atom_data content. Only returned if f is None.
  • prop_info (list of dict) – The filled-in prop_info structure. Only returned if return_prop_info is True.

atomman.dump_poscar(system, f=None, header='', symbols=None, style='direct', box_scale=1.0, float_format='%.13e')

Generates a poscar-style coordination file for the system.

Parameters:
  • system (atomman.System) – The system whose coordinates you are saving
  • f (str or file-like object, optional) – File path or file-like object to write the content to. If not given, then the content is returned as a str.
  • header (str, optional) – The comment line to place at the top of the file. Default value is ‘’.
  • symbols (tuple, optional) – List of the element symbols that correspond to the atom types. If not given, will use system.symbols if set, otherwise no element content will be included.
  • style (str, optional) – The poscar coordinate style. Default value is ‘direct’.
  • box_scale (float, optional) –
    A universal scaling constant applied to the box vectors. Default value
    is 1.0.
    float_format : str, optional
    c-style format for printing the floating point numbers. Default value is ‘%.13e’.
Returns:

poscar_str – String of the poscar object (only returned if fname is not given).

Return type:

str

atomman.dump_pymatgen_Structure(system, symbols=None)

Convert an atomman.System into a pymatgen.Structure.

Parameters:
  • system (atomman.System) – A atomman representation of a system.
  • symbols (tuple, optional) – List of the element symbols that correspond to the atom types. If not given, will use system.symbols if set, otherwise no element content will be included.
Returns:

structure – A pymatgen representation of a structure.

Return type:

pymatgen.Structure

atomman.dump_system_model(system, f=None, box_unit=None, prop_name=None, unit=None, prop_unit=None, format=None, indent=None, symbols=None)

Dumps a JSON/XML System.model() representation of the system.

Parameters:
  • system (atomman.System) – The system to generate the data model for.
  • f (str or file-like object, optional) – File path or file-like object to write the content to. If not given, then the content is returned as a DataModelDict.
  • box_unit (str, optional) – Length unit to use for the box. Default value is ‘angstrom’.
  • prop_name (list, optional) – The Atoms properties to include. If neither prop_name nor prop_unit are given, all system properties will be included.
  • unit (list, optional) – Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in box-scaled units. If neither unit nor prop_units given, pos will be given in Angstroms and all other values will not be converted.
  • prop_unit (dict, optional) – dictionary where the keys are the property keys to include, and the values are units to use. If neither unit nor prop_units given, pos will be given in Angstroms and all other values will not be converted.
  • format (str, optional) – File format ‘xml’ or ‘json’ to save the content as if f is given. If f is a filename, then the format will be automatically inferred from f’s extension. If format is not given and cannot be inferred, then it will be set to ‘json’.
  • indent (int or None, optional) – Indentation option to use for XML/JSON content if f is given. A value of None (default) will add no line separatations or indentations.
  • symbols (list, optional) – list of atom-model symbols corresponding to the atom types. If not given, will use system.symbols.
Returns:

model – A JSON/XML data model for the current System object. Returned if f is not given.

Return type:

DataModelDict.DataModelDict or str

atomman.dump_table(system, f=None, prop_name=None, table_name=None, shape=None, unit=None, dtype=None, prop_info=None, header=False, float_format='%.13f', return_prop_info=False)

Converts a system’s atoms’ values to a string table.

Parameters:
  • system (atomman.System) – An atomman representation of a system.
  • f (str or file-like object, optional) – File path or file-like object to write the content to. If not given, then the content is returned as a str.
  • prop_name (list, optional) – The Atoms properties to include. Must be given if prop_info is not.
  • table_name (list, optional) – The table column name(s) that correspond to each prop_name. If not given, the table_name values will be based on the prop_name values.
  • shape (list, optional) – The shape of each per-atom property. If not given, will be inferred from the length of each table_name value.
  • unit (list, optional) – Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in box-scaled units. If not given, all unit values will be set to None (i.e. no conversions).
  • dtype (list, optional) – Allows for the data type of each property to be explicitly given. Values of None will infer the data type from the corresponding property values. If not given, all values will be None.
  • prop_info (list of dict, optional) – Structured form of property conversion parameters, in which each dictionary in the list corresponds to a single atoms property. Each dictionary must have a ‘prop_name’ field, and can optionally have ‘table_name’, ‘shape’, ‘unit’, and ‘dtype’ fields.
  • header (bool, optional) – Flag indicating whether to include the column names in the outputted table. Default value is False (no column names).
  • float_format (str, optional) – c-style formatting string for floating point values. Default value is ‘%.13f’.
  • return_prop_info (bool, optional) – Flag indicating if the filled-in prop_info is to be returned. Having this allows for 1:1 load/dump conversions. Default value is False (prop_info is not returned).
Returns:

The generated data table. Only returned if fp is None.

Return type:

str

atomman.dmag()

Computes the shortest distance between pos_0 and pos_1 using box dimensions and accounting for periodic boundaries.

Parameters:
  • pos_0 (numpy.ndarray, list, or tuple) – Absolute Cartesian vector position(s) to use as reference point(s).
  • pos_1 (numpy.ndarray, list, or tuple) – Absolute Cartesian vector position(s) to find relative to pos_0.
  • box (atomman.Box) – Defines the system/box dimensions
  • pbc (list, tuple, or numpy.ndarray of bool.) – Three Boolean values indicating which of the three box vectors are periodic (True means periodic).
Returns:

The shortest vector magnitude from each pos_0 to pos_1 positions.

Return type:

numpy.ndarray

atomman.dvect()

Computes the shortest vector between pos_0 and pos_1 using box dimensions and accounting for periodic boundaries.

Parameters:
  • pos_0 (numpy.ndarray, list, or tuple) – Absolute Cartesian vector position(s) to use as reference point(s).
  • pos_1 (numpy.ndarray, list, or tuple) – Absolute Cartesian vector position(s) to find relative to pos_0.
  • box (atomman.Box) – Defines the system/box dimensions
  • pbc (list, tuple, or numpy.ndarray of bool.) – Three Boolean values indicating which of the three box vectors are periodic (True means periodic).
Returns:

The shortest vectors from each pos_0 to pos_1 positions.

Return type:

numpy.ndarray

atomman.load(style, input, **kwargs)

Load a System.

Parameters:
  • style (str) – Indicates the format of the content to load as an atomman.System
  • input (str, file-like object or object) – The content to load.
  • kwargs – Any extra keyword arguments to pass to the underlying load methods.
Returns:

system – The system object associated with the data model.

Return type:

atomman.System

atomman.load_ase_Atoms(aseatoms, symbols=None, prop={})

Convert an ase.Atoms into an atomman.System.

Parameters:
  • aseatoms (ase.Atoms) – An ase representation of a collection of atoms.
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading. Useful if the symbols for the model differ from the standard element tags.
  • prop (dict, optional) – Dictionary containing any extra per-atom properties to include.
Returns:

system – A atomman representation of a system.

Return type:

atomman.System

atomman.load_atom_data(data, pbc=(True, True, True), symbols=None, atom_style='atomic', units='metal')

Read a LAMMPS-style atom data file.

Parameters:
  • data (str or file-like object) – The atom data content to read. Can be str content, path name, or open file-like object.
  • pbc (list of bool) – Three boolean values indicating which System directions are periodic. Default value is (True, True, True).
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading.
  • atom_style (str) – The LAMMPS atom_style option associated with the data file. Default value is ‘atomic’.
  • units (str) – The LAMMPS units option associated with the data file. Default value is ‘metal’.
Returns:

The corresponding system. Note all property values will be automatically converted to atomman.unitconvert’s set working units.

Return type:

atomman.System

atomman.load_atom_dump(data, symbols=None, lammps_units='metal', prop_name=None, table_name=None, shape=None, unit=None, dtype=None, prop_info=None, return_prop_info=False)

Reads in a LAMMPS atomic dump file into a System.

Parameters:
  • data (str or file-like object) – The content, file path or file-like object containing the content to read.
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading.
  • lammps_units (str) – The LAMMPS units option associated with the parameters. Default value is ‘metal’.
  • prop_name (list, optional) – The Atoms properties to generate.
  • table_name (list, optional) – The table column name(s) that correspond to each prop_name. If prop_name, table_name and prop_info are not given, prop_name and table_name will be read in from data.
  • shape (list, optional) – The shape of each per-atom property. If not given, will be taken from standard LAMMPS parameter names, or left at () for direct property-table conversion.
  • unit (list, optional) – Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in box-scaled units. If not given, all unit values will be set to None (i.e. no conversions).
  • dtype (list, optional) – Allows for the data type of each property to be explicitly given. Values of None will infer the data type from the corresponding property values. If not given, all values will be None.
  • prop_info (list of dict, optional) – Structured form of property conversion parameters, in which each dictionary in the list corresponds to a single atoms property. Each dictionary must have a ‘prop_name’ field, and can optionally have ‘table_name’, ‘shape’, ‘unit’, and ‘dtype’ fields.
  • return_prop_info (bool, optional) – Flag indicating if the full prop_info is to be returned. Default value is False.
Returns:

  • system (atomman.System) – The generated system.
  • prop_info (list of dict) – The full prop_info detailing the property-table conversion. Returned if return_prop_info is True.

atomman.load_cif(cif, symbols=None)

Reads in a CIF crystal file. Requires diffpy.Structure.

Parameters:
  • cif (str or file-like object) – The cif content to read.
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading. Useful if the symbols for the model differ from the standard element tags.
Returns:

system – An atomman representation of a system.

Return type:

atomman.System

atomman.load_poscar(poscar, symbols=None, prop={})

Reads a poscar-style coordination file for a system.

Parameters:
  • poscar (str or file-like object) – The POSCAR content to read
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading. Useful if the symbols for the model differ from the standard element tags or if the poscar file has no elemental information.
  • prop (dict, optional) – Dictionary containing any extra per-atom properties to include.
Returns:

system – The system object associated with the poscar file.

Return type:

atomman.System

atomman.load_pymatgen_Structure(structure, symbols=None)

Convert a pymatgen.Structure into an atomman.System.

Parameters:
  • structure (pymatgen.Structure) – A pymatgen representation of a structure.
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading. Useful if the symbols for the model differ from the standard element tags.
Returns:

system – A atomman representation of a system.

Return type:

atomman.System

atomman.load_system_model(model, symbols=None, key='atomic-system', index=0)

Read in a data model containing a crystal structure.

Parameters:
  • model (str, file-like object or DataModelDict) – The data model to read.
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading.
  • key (str, optional) – The key identifying the root element for the system definition. Default value is ‘atomic-system’.
  • index (int, optional.) – If the full model has multiple key entries, the index specifies which to access. Default value is 0 (first, or only entry).
Returns:

system – The system object associated with the data model.

Return type:

atomman.System

atomman.load_table(table, box, symbols=None, system=None, prop_name=None, table_name=None, shape=None, unit=None, dtype=None, prop_info=None, skiprows=None, nrows=None, comment=None)

Reads in tabular data into atomic properties.

Parameters:
  • table (str or file-like object) – The table content, file path or file-like object containing the content to read.
  • box (atomman.Box) – The atomic box to use when generating a System around the data.
  • symbols (tuple, optional) – Allows the list of element symbols to be assigned during loading.
  • system (atomman.System, optional) – The atomic system to load the values to. If not given, a new system will be constructed.
  • prop_name (list, optional) – The Atoms properties to generate. Must be given if prop_info is not.
  • table_name (list, optional) – The table column name(s) that correspond to each prop_name. If not given, the table_name values will be based on the prop_name values.
  • shape (list, optional) – The shape of each per-atom property. If not given, will be inferred from the length of each table_name value.
  • unit (list, optional) – Lists the units for each prop_name as stored in the table. For a value of None, no conversion will be performed for that property. For a value of ‘scaled’, the corresponding table values will be taken in box-scaled units. If not given, all unit values will be set to None (i.e. no conversions).
  • dtype (list, optional) – Allows for the data type of each property to be explicitly given. Values of None will infer the data type from the corresponding property values. If not given, all values will be None.
  • prop_info (list of dict, optional) – Structured form of property conversion parameters, in which each dictionary in the list corresponds to a single atoms property. Each dictionary must have a ‘prop_name’ field, and can optionally have ‘table_name’, ‘shape’, ‘unit’, and ‘dtype’ fields.
  • skiprows (int, optional) – Number of rows to skip before reading the data.
  • nrows (int, optional) – Number of rows of data to read.
  • comment (str, optional) – Specifies a character which indicates all text on a given line after is to be considered to be a comment and ignored by parser. This is often ‘#’.
Returns:

The generated system.

Return type:

atomman.System

atomman.nlist()

Calculates a neighbor list for all atoms in a System taking periodic boundaries into account.

Parameters:
  • system (atomman.System) – The system to calculate the neighbor list for.
  • cutoff (float) – Radial cutoff distance for identifying neighbors.
  • initialsize (int, optional) – The number of neighbor positions to initially assign to each atom. Default value is 20.
  • deltasize (int, optional) – Specifies the number of extra neighbor positions to allow each atom when the number of neighbors exceeds the underlying array size. Default value is 10.
Returns:

Array listing number of neighbors and neighbor ids for each atom in System. First term in each row is the atom’s coordination number, c. The next c values are the atom’s neighbor ids.

Return type:

numpy.ndarray of int