:py:mod:`aiida_lammps.data.potential` ===================================== .. py:module:: aiida_lammps.data.potential .. autoapi-nested-parse:: 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 :py:class:`~aiida.orm.nodes.data.singlefile.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 ~~~~~~~ .. autoapisummary:: aiida_lammps.data.potential.LammpsPotentialData Functions ~~~~~~~~~ .. autoapisummary:: aiida_lammps.data.potential._validate_string aiida_lammps.data.potential._validate_string_list aiida_lammps.data.potential._validate_datetime aiida_lammps.data.potential._validate_sources .. py:function:: _validate_string(data: str) -> str Validate if the given data is a string :param data: data to be validated :type data: str :raises TypeError: Raised if the data is not of the correct type :return: validated string :rtype: str .. py:function:: _validate_string_list(data: Union[str, list[str]]) -> list[str] Validate the a list of strings :param data: string or list of strings :type data: Union[str, List[str]] :raises TypeError: raise if the data is not of type str or list :raises TypeError: raise if an entry in the list is not fo type str :return: the data as a list of strings :rtype: List[str] .. py:function:: _validate_datetime(data: Union[str, int, float, datetime.datetime]) -> int Validate and transform dates into integers :param data: representation of a year :type data: Union[str,int,float, datetime.datetime] :raises TypeError: raise if the data is not of type str, int, float or datetime.datetime :return: integer representing a year :rtype: int .. py:function:: _validate_sources(data: Union[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. :param data: citation data for a potential :type data: Union[dict, List[dict]] :raises TypeError: raises if the data is not a dict or list of dicts :raises TypeError: raises if not all the entries in the list are dicts :return: list of references for a potential :rtype: List[dict] .. py:class:: LammpsPotentialData(file: str | pathlib.Path | IO, filename: str | pathlib.Path | None = None, **kwargs: Any) Bases: :py:obj:`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 :py:class:`~aiida.orm.nodes.data.singlefile.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. .. py:property:: atom_style :type: str Return the default `atomic_style` of this potential. :return: the default `atomic_style` of this potential :rtype: str .. py:property:: pair_style :type: str Return the `pair_style` of this potential according to the LAMMPS notation :return: the `pair_style` of the potential :rtype: str .. py:property:: species :type: 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 .. py:property:: default_units :type: str Return the default units associated with this potential. :return: the default units associated with this potential :rtype: str .. py:property:: content_origin :type: 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. :return: the place where this potential information can be found. :rtype: str .. py:property:: content_other_locations :type: Union[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. :return: other locations where the potential can be found. :rtype: Union[str, list] .. py:property:: data_method :type: 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 :return: data_method used to generate the potential :rtype: str .. py:property:: description :type: 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. :return: description of the potential :rtype: str .. py:property:: developer :type: Union[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. :return: developer information of this potential :rtype: Union[str, list] .. py:property:: disclaimer :type: 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. :return: disclaimer regarding the usage of this potential :rtype: str .. py:property:: properties :type: Union[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. :return: properties fow which this potential was devised. :rtype: Union[str, list] .. py:property:: publication_year :type: Union[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. :return: year of publication of this potential :rtype: Union[str, datetime.datetime, int] .. py:property:: source_citations :type: Union[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. :return: the citation where the potential was originally published. :rtype: Union[str, list] .. py:property:: title :type: 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. :return: the title of the potential :rtype: str .. py:property:: md5 :type: Optional[int] Return the md5. :return: the md5 of the stored file. .. py:property:: generation_method :type: 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. :return: the generation method of the potential :rtype: str .. py:attribute:: _key_element :value: 'element' .. py:attribute:: _key_md5 :value: 'md5' .. py:attribute:: _schema_file .. py:attribute:: _extra_keys :type: ClassVar[dict[str, Any]] .. py:method:: get_or_create(source: Union[str, pathlib.Path, BinaryIO], filename: Optional[str] = None, pair_style: Optional[str] = None, species: Optional[list] = None, atom_style: Optional[str] = None, units: Optional[str] = None, extra_tags: Optional[dict] = None) :classmethod: 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. :param source: 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. :type source: Union[str, pathlib.Path, BinaryIO] :param filename: optional explicit filename to give to the file stored in the repository. :type filename: str :param pair_style: Type of potential according to LAMMPS :type pair_style: str :param species: Species that can be used for this potential. :type species: list :param atom_style: Type of treatment of the atoms according to LAMMPS. :type atom_style: str :param units: Default units to be used with this potential. :type units: str :param extra_tags: Dictionary with extra information to tag the potential, based on the KIM schema. :type extra_tags: dict :return: 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. :raises FileNotFoundError: if the source is a filepath but does not exist. .. py:method:: get_entry_point_name() :classmethod: Return the entry point name associated with this data class. :return: the entry point name. .. py:method:: is_readable_byte_stream(stream) -> bool :staticmethod: Return if object is a readable filelike object in binary mode or stream of bytes. :param stream: the object to analyze. :returns: True if ``stream`` appears to be a readable filelike object in binary mode, False otherwise. .. py:method:: prepare_source(source: Union[str, pathlib.Path, BinaryIO]) -> BinaryIO :classmethod: 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. :raises FileNotFoundError: if the source is a filepath but does not exist. .. py:method:: validate_md5(md5: str) Validate that the md5 checksum matches that of the currently stored file. :param value: the md5 checksum. :raises ValueError: if the md5 does not match that of the currently stored file. .. py:method:: 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. :param pair_style: Name of the LAMMPS potential `pair_style` :type pair_style: str :raises TypeError: If the `pair_style` is None. :raises KeyError: If the `pair_style` is not supported by LAMMPS. .. py:method:: 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. :param species: list of atomic species for this potential :type species: list :raises TypeError: If the list of species is not provided .. py:method:: 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. :param atom_style: Name of the given `atom_style` :type atom_style: str :param pair_style: Name of the current `pair_style` :type pair_style: str :raises ValueError: If the `atom_style` is not supported by LAMMPS .. py:method:: validate_element(element: str) :classmethod: Validate the given element symbol. :param element: the symbol of the element following the IUPAC naming standard. :raises ValueError: if the element symbol is invalid. .. py:method:: 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. :param units: Name of the given units for the calculation. :type units: str :param pair_style: Name of the used pair_style :type pair_style: str :raises ValueError: If the `units` are not LAMMPS compatible. .. py:method:: 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. :param extra_tags: dictionary with the extra tags that can be used to tag the potential :type extra_tags: dict :raises TypeError: If the type of the entry does not matches the expected :raises ValueError: If the value of the entry does not match the possible values .. py:method:: set_file(source: Union[str, pathlib.Path, BinaryIO], filename: Optional[str] = None, pair_style: Optional[str] = None, species: Optional[list] = None, atom_style: Optional[str] = None, units: Optional[str] = None, extra_tags: Optional[dict] = 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. :param source: 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. :type source: Union[str, pathlib.Path, BinaryIO] :param filename: optional explicit filename to give to the file stored in the repository. :type filename: str :param pair_style: Type of potential according to LAMMPS :type pair_style: str :param species: Species that can be used for this potential. :type species: list :param atom_style: Type of treatment of the atoms according to LAMMPS. :type atom_style: str :param units: Default units to be used with this potential. :type units: str :param extra_tags: Dictionary with extra information to tag the potential, based on the KIM schema. :type extra_tags: dict :raises TypeError: if the source is not a ``str``, ``pathlib.Path`` instance or binary stream. :raises FileNotFoundError: if the source is a filepath but does not exist. .. py:method:: store(**kwargs) Store the node verifying first that all required attributes are set. :raises :py:exc:`~aiida.common.StoringNotAllowed`: if no valid element has been defined.