aiida_lammps.data.potential

Base class for the LAMMPS potentials.

This class allows the storage/recovering of LAMMPS potentials, it allows one to store any LAMMPS potential as a SinglefileData object, which can then be either written to the LAMMPS input script and/or to a file, where it can be easily read by LAMMPS. This distinction depends on the assigned pair_style which require different pair_coeff entries in the input file.

Based on the pseudo class written by Sebastiaan Huber.

The potentials are also tagged by following the KIM-API schema, as to make them more easy to track and as compatible as possible to the KIM schema.

Module Contents

Classes

LammpsPotentialData

Base class for the LAMMPS potentials.

Functions

_validate_string(→ str)	Validate if the given data is a string
_validate_string_list(→ list[str])	Validate the a list of strings
_validate_datetime(→ int)	Validate and transform dates into integers
_validate_sources(→ list[dict])	Validate the sources for the potential.

aiida_lammps.data.potential._validate_string(data: str) → str

Validate if the given data is a string

Parameters:

data (str) – data to be validated

Raises:

TypeError – Raised if the data is not of the correct type

Returns:

validated string

Return type:

str

aiida_lammps.data.potential._validate_string_list(data: str | list[str]) → list[str]

Validate the a list of strings

Parameters:

data (Union[str, List[str]]) – string or list of strings

Raises:

• TypeError – raise if the data is not of type str or list

• TypeError – raise if an entry in the list is not fo type str

Returns:

the data as a list of strings

Return type:

List[str]

aiida_lammps.data.potential._validate_datetime(data: str | int | float | datetime.datetime) → int

Validate and transform dates into integers

Parameters:

data (Union[str,int,float, datetime.datetime]) – representation of a year

Raises:

TypeError – raise if the data is not of type str, int, float or datetime.datetime

Returns:

integer representing a year

Return type:

int

aiida_lammps.data.potential._validate_sources(data: dict | list[dict]) → list[dict]

Validate the sources for the potential.

This checks whether the entry is a dictionary that can be used to describe the citation for a potential.

Parameters:

data (Union[dict, List[dict]]) – citation data for a potential

Raises:

• TypeError – raises if the data is not a dict or list of dicts

• TypeError – raises if not all the entries in the list are dicts

Returns:

list of references for a potential

Return type:

List[dict]

class aiida_lammps.data.potential.LammpsPotentialData(file: str | pathlib.Path | IO, filename: str | pathlib.Path | None = None, **kwargs: Any)

Bases: aiida.orm.SinglefileData

Base class for the LAMMPS potentials.

This class allows the storage/recovering of LAMMPS potentials, it allows one to store any LAMMPS potential as a SinglefileData object, which can then be either written to the LAMMPS input script and/or to a file, where it can be easily read by LAMMPS. This distinction depends on the assigned pair_style which require different pair_coeff entries in the input file.

Based on the pseudo class written by Sebaastian Huber.

The potentials are also tagged by following the KIM-API schema, as to make them more easy to track and as compatible as possible to the KIM schema.

property atom_style: str

Return the default atomic_style of this potential. :return: the default atomic_style of this potential :rtype: str

property pair_style: str

Return the pair_style of this potential according to the LAMMPS notation :return: the pair_style of the potential :rtype: str

property species: list

Return the list of species which this potential can be used for. :return: The list of chemical species which are contained in this potential. :rtype: list

property default_units: str

Return the default units associated with this potential. :return: the default units associated with this potential :rtype: str

property content_origin: str

Return the place where this potential information can be found.

As based in the KIM schema. A description and/or web address to the online source where the material was obtained. Possible examples include ‘Original content’, ‘Obtained from developer’, ‘Included in LAMMPS’, a link to the relevant NIST IPR page, or the URL/ID/Access Date of a Materials Project entry.

Returns:

the place where this potential information can be found.

Return type:

str

property content_other_locations: str | list

Return other locations where the potential can be found.

As based in the KIM schema. A description of and/or web address(es) to other location(s) where the content is available.

Returns:

other locations where the potential can be found.

Return type:

Union[str, list]

property data_method: str

Return the data method used to generate the potential.

As based in the KIM schema. The method used to generate an instance of Reference Data. Must be one of: experiment, computation, or unknown

Returns:

data_method used to generate the potential

Return type:

str

property description: str

Return a description of the potential.

As based in the KIM schema. A short description describing its key features including for example: type of model (pair potential, 3-body potential, EAM, etc.), modeled elements (Ac, Ag, …, Zr), intended purpose, origin, and so on.

Returns:

description of the potential

Return type:

str

property developer: str | list

Return the developer information of this potential.

As based in the KIM schema. An array of strings, each of which is a KIM user uuid corresponding to a “developer” of the item. A developer of an item is someone who participated in creating the core intellectual content of the digital object, e.g. the functional form of an interatomic model or a specific parameter set for it.

Returns:

developer information of this potential

Return type:

Union[str, list]

property disclaimer: str

Return a disclaimer regarding the usage of the potential.

As based in the KIM schema. A short statement of applicability which will accompany any results computed using it. A developer can use the disclaimer to inform users of the intended use of this KIM Item.

Returns:

disclaimer regarding the usage of this potential

Return type:

str

property properties: str | list

Return the properties for which this potential was devised.

As based in the KIM schema. A list of properties reported by a KIM Item.

Returns:

properties fow which this potential was devised.

Return type:

Union[str, list]

property publication_year: str | datetime.datetime | int

Return the year of publication of this potential.

As based in the KIM schema. Year this item was published on openkim.org.

Returns:

year of publication of this potential

Return type:

Union[str, datetime.datetime, int]

property source_citations: str | list

Return the citation where the potential was originally published.

As based in the KIM schema. An array of BibTeX-style EDN dictionaries corresponding to primary published work(s) describing the KIM Item.

Returns:

the citation where the potential was originally published.

Return type:

Union[str, list]

property title: str

Return the title of the potential.

As based in the KIM schema. Used when displaying a KIM Item on openkim.org, as well as autogenerating its citation. The title should not include an ending period.

Returns:

the title of the potential

Return type:

str

property md5: int | None

Return the md5. :return: the md5 of the stored file.

property generation_method: str

Return the generation method of the potential.

In here one can describe how the potential itself was generated, if it was done via ML, fitting via specific codes, analytical fitting, etc.

Returns:

the generation method of the potential

Return type:

str

_key_element = 'element'

_key_md5 = 'md5'

_schema_file

_extra_keys: ClassVar[dict[str, Any]]

classmethod get_or_create(source: str | pathlib.Path | BinaryIO, filename: str | None = None, pair_style: str | None = None, species: list | None = None, atom_style: str | None = None, units: str | None = None, extra_tags: dict | None = None)

Get lammps potential data node from database or create a new one.

This will check if there is a potential data node with matching md5 checksum and use that or create a new one if not existent.

Parameters:

• source (Union[str, pathlib.Path, BinaryIO]) – the source potential content, either a binary stream, or a str or Path to the path of the file on disk, which can be relative or absolute.

• filename (str) – optional explicit filename to give to the file stored in the repository.

• pair_style (str) – Type of potential according to LAMMPS

• species (list) – Species that can be used for this potential.

• atom_style (str) – Type of treatment of the atoms according to LAMMPS.

• units (str) – Default units to be used with this potential.

• extra_tags (dict) – Dictionary with extra information to tag the potential, based on the KIM schema.

Returns:

instance of LammpsPotentialData, stored if taken from database, unstored otherwise.

Raises:

• TypeError – if the source is not a str, pathlib.Path instance or binary stream.

• FileNotFoundError – if the source is a filepath but does not exist.

classmethod get_entry_point_name()

Return the entry point name associated with this data class. :return: the entry point name.

static is_readable_byte_stream(stream) → bool

Return if object is a readable filelike object in binary mode or stream of bytes.

Parameters:

stream – the object to analyze.

Returns:

True if stream appears to be a readable filelike object in binary mode, False otherwise.

classmethod prepare_source(source: str | pathlib.Path | BinaryIO) → BinaryIO

Validate the source representing a file on disk or a byte stream.

Note

if the source is a valid file on disk, its content is read and returned as a stream of bytes.

Raises:

• TypeError – if the source is not a str, pathlib.Path instance or binary stream.

• FileNotFoundError – if the source is a filepath but does not exist.

validate_md5(md5: str)

Validate that the md5 checksum matches that of the currently stored file.

Parameters:

value – the md5 checksum.

Raises:

ValueError – if the md5 does not match that of the currently stored file.

validate_pair_style(pair_style: str)

Validate that the given pair_style is a valid lammps pair_style

Takes the given pair_style and compares it with those supported by lammps and see if there it a match.

Parameters:

pair_style (str) – Name of the LAMMPS potential pair_style

Raises:

• TypeError – If the pair_style is None.

• KeyError – If the pair_style is not supported by LAMMPS.

validate_species(species: list)

Validate that the given species are actual atomic species.

This checks that each of the entries in the species list are actual elements.

Parameters:

species (list) – list of atomic species for this potential

Raises:

TypeError – If the list of species is not provided

validate_atom_style(atom_style: str, pair_style: str)

Validate that the given atom_style is a proper LAMMPS atom_style

The idea is to check if the given atom_style is supported by LAMMPS if no atom_style is given a default one is assigned.

Parameters:

• atom_style (str) – Name of the given atom_style

• pair_style (str) – Name of the current pair_style

Raises:

ValueError – If the atom_style is not supported by LAMMPS

classmethod validate_element(element: str)

Validate the given element symbol.

Parameters:

element – the symbol of the element following the IUPAC naming standard.

Raises:

ValueError – if the element symbol is invalid.

validate_units(units: str, pair_style: str)

Validate the LAMMPS units.

Checks that the provided units for the potential are LAMMPS compatible, if no units are given default values are used instead.

Parameters:

• units (str) – Name of the given units for the calculation.

• pair_style (str) – Name of the used pair_style

Raises:

ValueError – If the units are not LAMMPS compatible.

validate_extra_tags(extra_tags: dict)

Validate the dictionary with the extra tags for the potential.

It will take the given dictionary and check that the keys provided correspond to the ones accepted by the class. It will also check that the type of the entries are of the appropriate python type. If the entries can take only a subset of values they are checked against them.

Parameters:

extra_tags (dict) – dictionary with the extra tags that can be used to tag the potential

Raises:

• TypeError – If the type of the entry does not matches the expected

• ValueError – If the value of the entry does not match the possible values

set_file(source: str | pathlib.Path | BinaryIO, filename: str | None = None, pair_style: str | None = None, species: list | None = None, atom_style: str | None = None, units: str | None = None, extra_tags: dict | None = None, **kwargs)

Set the file content.

Note

this method will first analyze the type of the source and if it is a filepath will convert it to a binary stream of the content located at that filepath, which is then passed on to the superclass. This needs to be done first, because it will properly set the file and filename attributes that are expected by other methods. Straight after the superclass call, the source seeker needs to be reset to zero if it needs to be read again, because the superclass most likely will have read the stream to the end. Finally it is important that the prepare_source is called here before the superclass invocation, because this way the conversion from filepath to byte stream will be performed only once. Otherwise, each subclass would perform the conversion over and over again.

Parameters:

• source (Union[str, pathlib.Path, BinaryIO]) – the source lammps potential content, either a binary stream, or a str or Path to the path of the file on disk, which can be relative or absolute.

• filename (str) – optional explicit filename to give to the file stored in the repository.

• pair_style (str) – Type of potential according to LAMMPS

• species (list) – Species that can be used for this potential.

• atom_style (str) – Type of treatment of the atoms according to LAMMPS.

• units (str) – Default units to be used with this potential.

• extra_tags (dict) – Dictionary with extra information to tag the potential, based on the KIM schema.

Raises:

• TypeError – if the source is not a str, pathlib.Path instance or binary stream.

• FileNotFoundError – if the source is a filepath but does not exist.

store(**kwargs)

Store the node verifying first that all required attributes are set. :raises StoringNotAllowed: if no valid element has been defined.