aiida_pseudo.groups.family ========================== .. py:module:: aiida_pseudo.groups.family .. autoapi-nested-parse:: Module with group plugins to represent pseudo potential families. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/aiida_pseudo/groups/family/cutoffs/index /autoapi/aiida_pseudo/groups/family/pseudo/index /autoapi/aiida_pseudo/groups/family/pseudo_dojo/index /autoapi/aiida_pseudo/groups/family/sssp/index Attributes ---------- .. autoapisummary:: aiida_pseudo.groups.family.__all__ Classes ------- .. autoapisummary:: aiida_pseudo.groups.family.CutoffsPseudoPotentialFamily aiida_pseudo.groups.family.PseudoPotentialFamily aiida_pseudo.groups.family.PseudoDojoConfiguration aiida_pseudo.groups.family.PseudoDojoFamily aiida_pseudo.groups.family.SsspConfiguration aiida_pseudo.groups.family.SsspFamily Package Contents ---------------- .. py:class:: CutoffsPseudoPotentialFamily(*args, **kwargs) Bases: :py:obj:`aiida_pseudo.groups.mixins.RecommendedCutoffMixin`, :py:obj:`aiida_pseudo.groups.family.pseudo.PseudoPotentialFamily` Subclass of ``PseudoPotentialFamily`` designed to represent a family with recommended cutoffs. This is mostly used for testing the functionality around the ``RecommendedCutoffMixin``. .. py:class:: PseudoPotentialFamily(*args, **kwargs) Bases: :py:obj:`aiida.orm.Group` Group to represent a pseudo potential family. This is a base class that provides most of the functionality but does not actually define what type of pseudo potentials can be contained. If ``_pseudo_types`` is not defined, any pseudo potential type is accepted in this family, as long as it is a subclass of ``PseudoPotentialData``. Subclasses can limit which pseudo types can be hosted by setting ``_pseudo_types`` to a tuple of ``PseudoPotentialData`` subclasses. .. py:attribute:: _key_pseudo_type :value: '_pseudo_type' .. py:attribute:: _pseudo_types .. py:attribute:: _pseudos :value: None .. py:method:: __repr__() Represent the instance for debugging purposes. .. py:method:: __str__() Represent the instance for human-readable purposes. .. py:method:: pseudo_types() Return the pseudo potential types that this family accepts. :return: the tuple of subclasses of ``PseudoPotentialData`` that this family can host nodes of. If it returns ``None``, that means all subclasses are supported. .. py:method:: _validate_pseudo_type(pseudo_type) :classmethod: Validate the ``pseudo_type`` passed to ``parse_pseudos_from_directory``. :return: the pseudo type to be used. .. py:method:: _validate_dirpath(dirpath) :classmethod: Validate the ``dirpath`` passed to ``parse_pseudos_from_directory``. :return: the directory path to be used. .. py:method:: parse_pseudos_from_directory(dirpath, pseudo_type=None, deduplicate=True) :classmethod: Parse the pseudo potential files in the given directory into a list of data nodes. .. note:: The directory pointed to by `dirpath` should only contain pseudo potential files. Optionally, it can contain just a single directory, that contains all the pseudo potential files. If any other files are stored in the basepath or the subdirectory, that cannot be successfully parsed as pseudo potential files the method will raise a ``ValueError``. :param dirpath: absolute path to a directory containing pseudo potentials. :param pseudo_type: subclass of ``PseudoPotentialData`` to be used for the parsed pseudos. If not specified and the family only defines a single supported pseudo type in ``_pseudo_types`` then that will be used otherwise a ``ValueError`` is raised. :param deduplicate: if True, will scan database for existing pseudo potentials of same type and with the same md5 checksum, and use that instead of the parsed one. :return: list of data nodes :raises ValueError: if ``dirpath`` is not a directory or contains anything other than files. :raises ValueError: if ``dirpath`` contains multiple pseudo potentials for the same element. :raises ValueError: if ``pseudo_type`` is explicitly specified and is not supported by this family class. :raises ValueError: if ``pseudo_type`` is not specified and the class supports more than one pseudo type. :raises ParsingError: if the constructor of the pseudo type fails for one of the files in the ``dirpath``. .. py:method:: create_from_folder(dirpath, label, *, description='', pseudo_type=None, deduplicate=True) :classmethod: Create a new ``PseudoPotentialFamily`` from the pseudo potentials contained in a directory. :param dirpath: absolute path to the folder containing the UPF files. :param label: label to give to the ``PseudoPotentialFamily``, should not already exist. :param description: description to give to the family. :param pseudo_type: subclass of ``PseudoPotentialData`` to be used for the parsed pseudos. If not specified and the family only defines a single supported pseudo type in ``_pseudo_types`` then that will be used otherwise a ``ValueError`` is raised. :param deduplicate: if True, will scan database for existing pseudo potentials of same type and with the same md5 checksum, and use that instead of the parsed one. :raises ValueError: if a ``PseudoPotentialFamily`` already exists with the given name. :raises ValueError: if ``dirpath`` is not a directory or contains anything other than files. :raises ValueError: if ``dirpath`` contains multiple pseudo potentials for the same element. :raises ValueError: if ``pseudo_type`` is explicitly specified and is not supported by this family class. :raises ValueError: if ``pseudo_type`` is not specified and the class supports more than one pseudo type. :raises ParsingError: if the constructor of the pseudo type fails for one of the files in the ``dirpath``. .. py:property:: pseudo_type Return the type of the pseudopotentials that are hosted by this family. :return: the pseudopotential type or ``None`` if none has been set yet. .. py:method:: update_pseudo_type() Update the pseudo type, stored as an extra, based on the current nodes in the family. .. py:method:: add_nodes(nodes) Add a node or a set of nodes to the family. .. note: Each family instance can only contain a single pseudo potential for each element. :param nodes: a single or list of ``Node`` instances of type that is in ``PseudoPotentialFamily._pseudo_types``. :raises ModificationNotAllowed: if the family is not stored. :raises TypeError: if nodes are not an instance or list of instance of any of the classes listed by ``PseudoPotentialFamily._pseudo_types``. :raises ValueError: if any of the nodes are not stored or their elements already exist in this family. .. py:method:: remove_nodes(nodes) Remove a pseudopotential or a set of pseudopotentials from the family. :param nodes: a single or list of ``PseudoPotentialData`` instances or subclasses thereof. .. py:method:: clear() Remove all the pseudopotentials from this family. .. py:property:: pseudos Return the dictionary of pseudo potentials of this family indexed on the element symbol. :return: dictionary of element symbol mapping pseudo potentials .. py:property:: elements Return the list of elements for which this family defines a pseudo potential. :return: list of element symbols .. py:method:: get_pseudo(element) Return the pseudo potential for the given element. :param element: the element for which to return the corresponding pseudo potential. :return: pseudo potential instance if it exists :raises ValueError: if the family does not contain a pseudo potential for the given element .. py:method:: get_pseudos(*, elements: Optional[Union[List[str], Tuple[str]]] = None, structure: Union[structures_classes] = None) -> Mapping[str, Union[structures_classes]] Return the mapping of kind names on pseudo potential data nodes for the given list of elements or structure. :param elements: list of element symbols. :param structure: the ``StructureData`` or ``LegacyStructureData`` node. :return: dictionary mapping the kind names of a structure on the corresponding pseudo potential data nodes. :raises ValueError: if the family does not contain a pseudo for any of the elements of the given structure. .. py:class:: PseudoDojoConfiguration Bases: :py:obj:`NamedTuple` Named tuple that represents a PseudoDojo configuration. .. py:attribute:: version :type: str .. py:attribute:: functional :type: str .. py:attribute:: relativistic :type: str .. py:attribute:: protocol :type: str .. py:attribute:: pseudo_format :type: str .. py:method:: __str__() Represent the configuration as a string. .. py:class:: PseudoDojoFamily(label=None, **kwargs) Bases: :py:obj:`aiida_pseudo.groups.mixins.RecommendedCutoffMixin`, :py:obj:`aiida_pseudo.groups.family.pseudo.PseudoPotentialFamily` Subclass of ``PseudoPotentialFamily`` designed to represent a PseudoDojo configuration. The ``PseudoDojoFamily`` is essentially a ``PseudoPotentialFamily`` with some additional constraints. It can only be used to contain the pseudo potentials and corresponding metadata of an official PseudoDojo configuration. .. py:attribute:: _pseudo_types .. py:attribute:: _pseudo_repo_file_extensions :value: ('djrepo',) .. py:attribute:: label_template :value: 'PseudoDojo/{version}/{functional}/{relativistic}/{protocol}/{pseudo_format}' .. py:attribute:: default_configuration .. py:attribute:: valid_configurations .. py:attribute:: url_base :value: 'http://www.pseudo-dojo.org/pseudos/' .. py:attribute:: urls :type: ClassVar[dict[str, str]] .. py:method:: get_valid_labels() -> Sequence[str] :classmethod: Return the tuple of labels of all valid PseudoDojo configurations. .. py:method:: format_configuration_label(configuration: PseudoDojoConfiguration) -> str :classmethod: Format a label for an `PseudoDojoFamily` with the required syntax. :param configuration: the PseudoDojo configuration. :return: label. .. py:method:: get_url_archive(label) :classmethod: Return the URL for the pseudopotential archive file for a given family label. :param label: the family label as formatted by ``format_configuration_label``. :return: the URL from which the pseudopotential archive can be downloaded. :raises: `ValueError` if the label is not a valid configuration label. .. py:method:: get_url_metadata(label) :classmethod: Return the URL for the pseudopotential metadata file for a given family label. :param label: the family label as formatted by ``format_configuration_label``. :return: the URL from which the pseudopotential metadata can be downloaded. :raises: `ValueError` if the label is not a valid configuration label. .. py:method:: get_md5_from_djrepo(djrepo, pseudo_type) :classmethod: Get the appropriate md5 hash from a DJREPO file. :param djrepo: dictionary loaded from DJREPO JSON file. :reutnrs: md5 string. .. py:method:: get_cutoffs_from_djrepo(djrepo, pseudo_type) :classmethod: Collect and organize the suggested cutoffs (hints) from a DJREPO file. DJREPO files only provide a kinetic energy cutoff, so for pseudo types which contain norm-conserving pseudos from PseudoDojo, we use a dual of 8.0 to generate the charge density (rho) cutoff. For PAW potentials from PseudoDojo (which are assumed to be JthXmlData), a dual of 2.0 is used. The cutoffs in DJREPO files are given in Hartree, which is converted to eV. :param djrepo: dictionary loaded from DJREPO JSON file :returns: cutoffs dictionary (in eV) where keys are stringency levels and values are {'cutoff_wfc': ..., 'cutoff_rho': ...} .. py:method:: parse_djrepos_from_folder(dirpath: pathlib.Path, pseudo_type) :classmethod: Parse the djrepo files in the given directory into a list of data nodes. .. note:: The directory pointed to by `dirpath` should only contain djrepo files. Optionally, it can contain just a single directory, that contains all the djrepo files. If any other files are stored in the basepath or the subdirectory that cannot be successfully parsed as djrepo files the method will raise a `ValueError`. :param dirpath: absolute path to a directory containing djrepos. :return: list of data nodes. :raises ValueError: if `dirpath` is not a directory or contains anything other than files. :raises ValueError: if `dirpath` contains multiple djrepos for the same element. :raises ParsingError: if the constructor of the pseudo type fails for one of the files in the `dirpath`. .. py:method:: parse_djrepos_from_archive(filepath_metadata: pathlib.Path, fmt=None, pseudo_type=None) :classmethod: Parse metadata from a djrepo .tgz archive. .. warning:: the archive should not contain any subdirectories, but just the djrepo files. :param filepath_metadata: the path to the metadata .tgz archive. :param fmt: the format of the archive, if not specified will attempt to guess based on extension of `filepath`. :param pseudo_type: subclass of ``PseudoPotentialData`` to be used for the parsed pseudos. If not specified and the family only defines a single supported pseudo type in ``_pseudo_types`` then that will be used otherwise a ``ValueError`` is raised. :return: element: value dictionaries containing md5s and cutoffs. :raises OSError: if the archive could not be unpacked or the djrepos in it could not be parsed into md5s and cutoffs. .. py:class:: SsspConfiguration Bases: :py:obj:`NamedTuple` Named tuple that represents an SSSP configuration. .. py:attribute:: version :type: str .. py:attribute:: functional :type: str .. py:attribute:: protocol :type: str .. py:method:: __str__() Represent the configuration as a string. .. py:class:: SsspFamily(label=None, **kwargs) Bases: :py:obj:`aiida_pseudo.groups.mixins.RecommendedCutoffMixin`, :py:obj:`aiida_pseudo.groups.family.pseudo.PseudoPotentialFamily` Subclass of ``PseudoPotentialFamily`` designed to represent an SSSP configuration. The ``SsspFamily`` is essentially a ``PseudoPotentialFamily`` with some additional constraints. It can only be used to contain the pseudo potentials and corresponding metadata of an official SSSP configuration. .. py:attribute:: _pseudo_types .. py:attribute:: label_template :value: 'SSSP/{version}/{functional}/{protocol}' .. py:attribute:: filename_template :value: 'SSSP_{version}_{functional}_{protocol}' .. py:attribute:: default_configuration .. py:attribute:: valid_configurations .. py:method:: get_valid_labels() -> Sequence[str] :classmethod: Return the tuple of labels of all valid SSSP configurations. .. py:method:: format_configuration_label(configuration: SsspConfiguration) -> str :classmethod: Format a label for an `SsspFamily` with the required syntax. :param configuration: the SSSP configuration :return: label .. py:method:: format_configuration_filename(configuration: SsspConfiguration, extension: str, patch_version: Optional[str] = None) -> str :classmethod: Format the filename for a file of a particular SSSP configuration as it is available from MC Archive. :param configuration: the SSSP configuration. :param extension: the filename extension without the leading dot. :param patch_version: patch version of the files which overrides the ``version`` specified in the ``configuration``. This is necessary because we only let users specify the minor version, not install configurations with a specific patch version. The filename on the archive however will contain the patch version, so this needs to be substituted. :return: filename .. py:data:: __all__