atomman package

Functions and attributes

atomman.build_lammps_potential(pair_style, **kwargs)

Wrapper function for the PotentialLAMMPSBuilder subclasses.

Parameters
  • pair_style (str) – The LAMMPS pair_style setting associated with the potential.

  • **kwargs (dict) – Any keyword parameters supported by PotentialLAMMPSBuilder and the subclass that matches the pair_style.

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

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.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.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: Optional[Union[str, list]] = None, return_prop: bool = False) Union[ase.atoms.Atoms, Tuple[ase.atoms.Atoms, dict]]

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: typing.Optional[typing.Union[str, io.IOBase]] = None, atom_style: typing.Optional[str] = None, units: typing.Optional[str] = None, natypes: typing.Optional[int] = None, potential: <module 'potentials.record.BasePotentalLAMMPS' from 'c:\\users\\lmh1\\documents\\python-packages\\potentials\\potentials\\record\\BasePotentalLAMMPS.py'> = None, float_format: str = '%.13f', return_info: bool = True, prompt: bool = False, comments: bool = True, safecopy: bool = False) Optional[Union[str, Tuple[str, str]]]

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. If neither atom_style or potential is given, will set atom_style to ‘atomic’.

  • units (str, optional) – The LAMMPS units option associated with the data file. If neither units or potential is given, will set units ‘metal’.

  • natypes (int, optional) – Allows the natypes value to be manually changed. This is needed if natypes needs to be greater than the current number of atypes. If neither natypes or potential is given, will use system.natypes.

  • potential (atomman.lammps.Potential, optional) – Potential-specific values of atom_style, units, and natypes can be extracted from a Potential object. If both potential and any of the individual values are given, the individual values will be used.

  • 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. If potential is given, then the commands associated with the potential will be included. Default value is True.

  • prompt (bool, optional) – If True, then a screen prompt will appear for radioactive elements with no standard mass to ask for the isotope to use. If False (default), then the most stable isotope will be automatically used.

  • comments (bool, optional) – Used if return_pair_info is True. If comments is True (default), then metadata comments associated with the potential will be included in the pair_info.

  • safecopy (bool, optional) – The LAMMPS data format requires all atoms to be inside box bounds, i.e. “wrapped”. If safecopy is True then a copy of the system is made to keep the original unwrapped. Default value is False.

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. If return_pair_info is also True and potential is given, the LAMMPS input command lines for the potential are also included.

Raises

ValueError – If return_pair_info is True and return_info is False or potential is not given.

atomman.dump_atom_dump(system, f: Optional[Union[str, io.IOBase]] = None, lammps_units: str = 'metal', prop_name: Optional[list] = None, table_name: Optional[list] = None, shape: Optional[list] = None, unit: Optional[list] = None, dtype: Optional[list] = None, prop_info: Optional[list] = None, float_format: str = '%.13f', return_prop_info: bool = 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).

  • 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: Optional[Union[str, io.IOBase]] = None, header: str = '', symbols: Optional[tuple] = None, coordstyle: str = 'direct', box_scale: float = 1.0, float_format: str = '%.13e') Optional[str]

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.

  • coordstyle (str, optional) – The poscar coordinate style to use: ‘cartesian’ or ‘direct’ (i.e. box relative). Default value is ‘direct’.

  • box_scale (float, optional) –

    A universal scaling constant applied to the box vectors. Default value

    is 1.0.

    float_formatstr, 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: Optional[tuple] = None) pymatgen.core.structure.Structure

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: Optional[Union[str, io.IOBase]] = None, box_unit: Optional[list] = None, prop_name: Optional[list] = None, unit: Optional[list] = None, prop_unit: Optional[dict] = None, format: Optional[str] = None, indent: Optional[int] = None) Optional[Union[str, DataModelDict.DataModelDict.DataModelDict]]

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.

Returns

model – The generated model representation of the system. Will be a DataModelDict if format is not specified, and a JSON- or XML-formatted string if format is specified. Returned if f is not given.

Return type

DataModelDict.DataModelDict or str

atomman.dump_table(system, f=None, prop_name: Optional[list] = None, table_name: Optional[list] = None, shape: Optional[list] = None, unit: Optional[list] = None, dtype: Optional[list] = None, prop_info: Optional[list] = None, header: bool = False, float_format: str = '%.13f', return_prop_info: bool = False, extra: Optional[dict] = None) Optional[str]

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).

  • extra (dict, optional) – Allows extra per-atom data that is not part of the System to be included in the generated table. Useful when the per-atom data only has meaning in the tabular format and should not be added to System.

Returns

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

Return type

str

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, *args, **kwargs)

Load a System.

Parameters
  • style (str) – Indicates the format of the content to load as an atomman.System

  • args – Any positional-dependent arguments to pass to the underlying load methods.

  • kwargs – Any 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: ase.atoms.Atoms, symbols: Optional[tuple] = None, prop: Optional[dict] = None) atomman.core.System.System

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: Union[str, io.IOBase], pbc: Tuple[bool, bool, bool] = (True, True, True), symbols: Optional[tuple] = None, atom_style: Optional[str] = None, units: str = 'metal') atomman.core.System.System

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, optional) – The LAMMPS atom_style option associated with the data file. Optional as the data can list this value in a comment in the Atoms section header. If not given and not found in data, the default value of ‘atomic’ is used.

  • units (str, optional) – 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 working units.

Return type

atomman.System

Raises
  • FileNotFoundError – If data is (likely) a file name and no matching file is found.

  • FileFormatError – If required content fields not found.

  • ValueError – If atom_style is both given as a parameter and found in data, but are not the same

atomman.load_atom_dump(data: Union[str, io.IOBase], symbols: Optional[tuple] = None, lammps_units: str = 'metal', prop_name: Optional[list] = None, table_name: Optional[list] = None, shape: Optional[list] = None, unit: Optional[list] = None, dtype: Optional[list] = None, prop_info: Optional[list] = None, return_prop_info: bool = False) Union[atomman.core.System.System, Tuple[atomman.core.System.System, list]]

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: Union[str, io.IOBase], symbols: Optional[tuple] = None) atomman.core.System.System

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_crystal(name: Union[str, list, None] = None, key: Union[str, list, None] = None, method: Union[str, list, None] = 'dynamic', standing: Union[str, list, None] = 'good', family: Union[str, list, None] = None, parent_key: Union[str, list, None] = None, potential: Optional[Record] = None, potential_LAMMPS_id: Union[str, list, None] = None, potential_LAMMPS_key: Union[str, list, None] = None, potential_id: Union[str, list, None] = None, potential_key: Union[str, list, None] = None, symbols: Union[str, list, None] = None, natoms: Union[int, list, None] = None, natypes: Union[int, list, None] = None, prompt: bool = True, refresh_cache: bool = False, verbose: bool = False, database: Optional[Database] = None, local: bool = True, remote: bool = True) System

Loads a potential-dependent relaxed crystal record from the library. If multiple matches are found based on inputs a selection menu will appear.

Parameters
  • name (str or list) – The record name(s) to parse by. For relaxed crystal records, the names should correspond to the key.

  • key (str or list, optional) – UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

  • method (str or list or None, optional) – The relaxation method used. Allowed values are dynamic, static and box. Default value is dynamic (the most rigorous relaxation method). All will be loaded if set to None.

  • standing (str or list or None, optional) – “good” records are the unique crystals found with the most rigorous relaxation, and with known prototypes over DFT structures. “bad” are records filtered out, usually for being duplicates. Default value is “good”. All will be loaded if set to None.

  • family (str or atomman.library.CrystalPrototype or list, optional) – The crystal family associated with the relaxed crystal - either crystal prototype name or MP/OQMD database entry name.

  • parent_key (str or list, optional) – The UUID4 key(s) assigned to the calculation that the record is based on.

  • potential (atomman.lammps.Potential or list, optional) – A loaded LAMMPS potential object to limit the search by.

  • potential_LAMMPS_id (str or list, optional) – The id for a LAMMPS implemented potential to limit the search by.

  • potential_LAMMPS_key (str or list, optional) – The UUID4 for a LAMMPS implemented potential to limit the search by.

  • potential_id (str or list, optional) – The id for a potential to limit the search by.

  • potential_key (str or list, optional) – The UUID4 for a potential to limit the search by.

  • symbols (str or list, optional) – Element symbols in the crystal to limit the search by.

  • natypes (int or list, optional) – The number of unique element model symbols in the crystal to limit the search by.

  • natoms (int or list, optional) – The number of unique atoms in the crystal’s unit cell to limit the search by.

  • database (atomman.library.Database, optional) – A pre-defined Database object to use. If not given, will initialize a new Database object. Passing in a database can save time if multiple calls are made for the same record type.

  • local (bool, optional) – Indicates if the Database object is to look for local records. Default is True. Ignored if database is given.

  • remote (bool, optional) – Indicates if the Database object is to look for remote records. Default is True. Ignored if database is given.

  • prompt (bool) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

  • refresh_cache (bool, optional) – If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

  • verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns

system – The system object generated from the relaxed crystal.

Return type

atomman.System

atomman.load_lammps_potential(name: Optional[Union[str, list]] = None, key: Optional[Union[str, list]] = None, id: Optional[Union[str, list]] = None, potid: Optional[Union[str, list]] = None, potkey: Optional[Union[str, list]] = None, units: Optional[Union[str, list]] = None, atom_style: Optional[Union[str, list]] = None, pair_style: Optional[Union[str, list]] = None, status: Optional[Union[str, list]] = 'active', symbols: Optional[Union[str, list]] = None, elements: Optional[Union[str, list]] = None, pot_dir_style: Optional[str] = None, kim_models: Optional[list] = None, kim_api_directory: Optional[str] = None, kim_models_file: Optional[str] = None, local: Optional[bool] = None, remote: Optional[bool] = None, database: Optional[atomman.library.Database.Database] = None, getfiles: bool = False, prompt: bool = True, verbose: bool = False) <module 'potentials.record.BasePotentalLAMMPS' from 'c:\\users\\lmh1\\documents\\python-packages\\potentials\\potentials\\record\\BasePotentalLAMMPS.py'>

Loads a LAMMPS potential from the NIST Interatomic Potentials Repository or from a local copy of the repository. Will issue a prompt if multiple LAMMPS potentials match the parameters given.

Parameters
  • name (str or list) – The record name(s) to parse by. For potential records, the names should correspond to the id with a prefix of “potentials.” added to it.

  • key (str or list) – The unique UUID4 record key(s) to parse by.

  • id (str or list) – The unique record id(s) labeling the records to parse by.

  • potid (str or list) – The unique UUID4 record key(s) for the associated potential records to parse by.

  • potkey (str or list) – The unique record id(s) labeling the associated potential records to parse by.

  • units (str or list) – LAMMPS units option(s) to parse by.

  • atom_style (str or list) – LAMMPS pair_style(s) to parse by.

  • pair_style (str or list) – LAMMPS pair_style(s) to parse by.

  • status (None, str or list) – Limits the search by the status of the LAMMPS implementations: “active”, “superseded” and/or “retracted”. By default, only active implementations are returned. Giving a value of None will return implementations of all statuses.

  • symbols (str or list) – Model symbol(s) to parse by. Typically correspond to elements for atomic potential models.

  • elements (str or list) – Element(s) in the model to parse by.

  • pot_dir_style (str, optional) – Specifies how the pot_dir values will be set for the retrieved LAMMPS potentials. Allowed values are ‘working’, ‘id’, and ‘local’. ‘working’ will set all pot_dir = ‘’, meaning parameter files are expected in the working directory when the potential is accessed. ‘id’ sets the pot_dir values to match the potential’s id. ‘local’ sets the pot_dir values to the corresponding local database paths where the files are expected to be found. Default value is controlled by settings.

  • kim_models (list) – A list of full KIM model ids to build LAMMPS potentials for.

  • kim_api_directory (str) – The path to the directory containing a kim-api-collections-management executable to use to identify which KIM models are installed.

  • kim_models_file (str) – The path to a file containing a list of full KIM model ids to build LAMMPS potentials for.

  • local (bool, optional) – Indicates if the local location is to be searched. Default value matches the value set when the database was initialized.

  • remote (bool, optional) – Indicates if the remote location is to be searched. Default value matches the value set when the database was initialized.

  • database (potentials.Database, optional) – Allows for a previously defined Database object to be used to find the potential. If not given, a new Database object will be used with the default local and remote interaction settings.

  • getfiles (bool, optional) – If True, then the parameter files for the matching potentials will also be copied/downloaded to the potential directory.

  • prompt (bool) – If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

  • verbose (bool, optional) – If True, info messages will be printed during operations. Default value is False.

Returns

The potential object to use.

Return type

potentials.record.PotentialLAMMPS

Raises

ValueError – If no matching LAMMPS potentials are found.

atomman.load_poscar(poscar: Union[str, io.IOBase], symbols: Optional[tuple] = None, prop: Optional[dict] = None) atomman.core.System.System

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_prototype(name: Union[str, list, None] = None, id: Union[str, list, None] = None, key: Union[str, list, None] = None, commonname: Union[str, list, None] = None, prototype: Union[str, list, None] = None, pearson: Union[str, list, None] = None, strukturbericht: Union[str, list, None] = None, sg_number: Union[int, list, None] = None, sg_hm: Union[str, list, None] = None, sg_schoenflies: Union[str, list, None] = None, a: Optional[float] = None, b: Optional[float] = None, c: Optional[float] = None, alpha: Optional[float] = None, beta: Optional[float] = None, gamma: Optional[float] = None, symbols: Optional[tuple] = None, database: Optional[Database] = None, local: Optional[bool] = True, remote: Optional[bool] = True, prompt: bool = True, refresh_cache: bool = False, verbose: bool = False) System

Loads a crystal prototype record from the library. If multiple matches are found based on inputs a selection menu will appear.

namestr or list, optional.

Record names to search for. These should be the same values as id.

idstr or list, optional

Prototype ID(s) to search for. These are unique identifiers for each prototype based on comm.

keystr or list, optional

UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

commonnamestr or list, optional

Common name(s) to limit the search by.

prototypestr or list, optional

Prototype identifying composition(s) to limit the search by.

pearsonstr or list, optional

The Pearson symbol(s) to limit the search by.

strukturberichtstr or list, optional

The strukturbericht identifier(s) to limit the search by.

sg_numberint or list, optional

The space group number(s) to limit the search by.

sg_hmstr or list, optional

The space group Hermann-Maguin identifier(s) to limit the search by.

sg_schoenfliesstr or list, optional

The space group Schoenflies identifier(s) to limit the search by.

afloat, optional

The a lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.

bfloat, optional

The b lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.

cfloat, optional

The c lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.

alphafloat, optional

The alpha lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.

betafloat, optional

The beta lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.

gammagamma, optional

The alpha lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.

symbolstuple, optional

Allows the list of element symbols to be assigned during loading.

databaseatomman.library.Database, optional

A pre-defined Database object to use. If not given, will initialize a new Database object. Passing in a database can save time if multiple calls are made for the same record type.

localbool, optional

Indicates if the Database object is to look for local records. Default is True. Ignored if database is given.

remotebool, optional

Indicates if the Database object is to look for remote records. Default is True. Ignored if database is given.

promptbool, optional

If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.

refresh_cachebool, optional

If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.

verbosebool, optional

If True, info messages will be printed during operations. Default value is False.

Returns

system – The system object generated from the crystal prototype.

Return type

atomman.System

atomman.load_pymatgen_Structure(structure: pymatgen.core.structure.Structure, symbols: Optional[tuple] = None) atomman.core.System.System

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: Union[str, io.IOBase, DataModelDict.DataModelDict.DataModelDict], symbols: Optional[tuple] = None, key: str = 'atomic-system', index: int = 0) atomman.core.System.System

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: Union[str, io.IOBase], box: atomman.core.Box.Box, symbols: Optional[tuple] = None, system: Optional[atomman.core.System.System] = None, prop_name: Optional[list] = None, table_name: Optional[list] = None, shape: Optional[list] = None, unit: Optional[list] = None, dtype: Optional[list] = None, prop_info: Optional[list] = None, skiprows: Optional[int] = None, nrows: Optional[int] = None, comment: Optional[str] = None, usecols: Optional[int] = None, header: Optional[Union[int, list, str]] = 'infer') atomman.core.System.System

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.

  • usecols (int, optional) – Which columns are to be used. Will be passed to pandas.read_csv() usecols option.

  • 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 ‘#’.

  • header (int, list of int, str or None, optional) – Indicates how to handle header info. Will be passed to pandas.read_csv() header option.

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