aiida_vasp.data package

Submodules

A general archive class.

class aiida_vasp.data.archive.ArchiveData(*args, **kwargs)

Bases: Data

Compressed archive data node, contains a group of files that don’t need to be readily accessible on their own.

add_file(src_abs, dst_filename=None)

archive()

get_archive()

get_archive_list()

store(*args, **kwargs)

Store the node in the database while saving its attributes and repository directory.

After being called attributes cannot be changed anymore! Instead, extras can be changed only AFTER calling this store() function.

Note:

After successful storage, those links that are in the cache, and for which also the parent node is already stored, will be automatically stored. The others will remain unstored.

Representation of CHGCAR objects.

class aiida_vasp.data.chargedensity.ChargedensityData(file: str | Path | IO, filename: str | Path | None = None, **kwargs: Any)

Bases: SinglefileData

Representation of the POTCAR files.

Consists of two classes, PotcarData and PotcarFileData. Between the two data node classes exists a one to one mapping but never a DbLink of any kind. The mapping must be defined in terms of a POTCAR file hash sum.

Reasons for not using a file system based solution in general:

• simplicity -> no necessity to define an fs based storage / retrieval schema

• storage schema can be updated without manual user interaction

• with fs based it is possible to lose enhanced provenance locally by deleting a file

• This is easier to share between machines for same user / group members

Reasons for not using fs paths:

• migrating to a new machine involves reinstating file hierarchy, might be non-trivial

• corner cases with links, recursion etc

Reasons for not using pymatgen system:

• changing an environment variable would invalidate provenance / disable reusing potentials

• would block upgrading to newer pymatgen versions if they decide to change

Note:

An fs based solution can be advantageous but should be 'expert mode' and not
default solution due to provenance tradeoffs.

The following requirements have to be met:

• The file hash attribute of PotcarFileData is unique in the Db

• The file hash attribute of PotcarData is unique in the Db

• Both classes can easily and quickly be found via the hash attribute

• A PotcarData node can be exported without exporting the PotcarFileData node

• The corresponding PotcarData node can be created at any time from the PotcarFileData node

• PotcarFileData nodes are expected to be grouped in DbGroups called ‘families’

• The PotcarFileData nodes can be found according to their ‘functional type’ (pymatgen term)

The following would be nice to also allow optionally:

• To pre-upload the files to a remote computer from a db and concat them right on there (to save traffic)

• To use files directly on the remote computer (disclaimer: will never be as secure / tested)

• To use existing pymatgen-style potentials library (disclaimer: support might break)

It is not to be expected for hundreds of distinct Potcar families to be present in the same database.

The mechanism for reading a POTCAR file into the Db:

+-----------------------+
[ parsing a POTCAR file ]
+-----------------------+
        |
        v
        pmg_potcar = PotcarData.get_or_create_from_file()
        |
        v
 _----------------------------------------------_
( exists for PotcarFileData with pmg_potcar.sha512? )-----> no
 ^----------------------------------------------^         |
        |                                                 v
        v                                                 create
        yes                                               |
        |                                                 |
        v                                                 v
 _-------------------------_                             _-------------------------_
( Family given to parse to? ) -------------> no -+      ( Family given to parse to? )
 ^-------------------------^                     |       ^-------------------------^
        |                                        |        |         |
        v                                        |        |         no
        yes<------------------------------------]|[-------+         |
        |                                        |                  choose family according to functional type (with fallback?)
        v                                        |                  |
        add existing PotcarFileData to family<--]|[-----------------+
        |                                        |
        |                     +------------------+
        v                     v
 _--------------------------------_
( exists corresponding PotcarData? )-----> no -----> create
 ^--------------------------------^ <------------------+
        |
        v
        return corresponding PotcarData

The mechanism for writing one or more PotcarData to file (from a calculation):

+-----------------------+
[ Writing a POTCAR file ]
+-----------------------+
        |
        v
        for each PotcarData node:
            get corresponding PotcarFileData <-> query for same symbol, family, hash, do not use links
        |
        v
        write_file using the write() of MultiPotcarIo

class aiida_vasp.data.potcar.PotcarData(**kwargs)

Bases: Data, PotcarMetadataMixin, VersioningMixin

Store enough metadata about a POTCAR file to identify and find it.

Meant to be used as an input to calculations. This node type holds no licenced data and can be freely shared without legal repercussions.

classmethod export_family_archive(family_name, path=None, dry_run=False)

Export a family of POTCAR nodes into a compressed archive.

classmethod export_family_folder(family_name, path=None, dry_run=False)

Export a family of POTCAR nodes into a file hierarchy similar to the one POTCARs are distributed in.

Parameters:

• family_name – name of the POTCAR family

• path – path to a local directory, either a string or Path object, default to current directory

• dry_run – bool, if True, only collect the names of files that would otherwise be written.

If path already exists, everything will be written into a subdirectory with the name of the family.

classmethod file_not_uploaded(file_path)

classmethod find(**kwargs)

Extend PotcarMetadataMixin.find() with filtering by POTCAR family.

If no POTCAR is found, raise a NotExistent exception.

If multiple POTCAR are found, sort them by:

• POTCARS belonging to the active user first

• oldest first

find_file_node()

Find and return the matching PotcarFileData node.

get_content()

get_family_names()

List potcar families to which this instance belongs.

classmethod get_full_names(family_name=None, element=None)

Gives a set of symbols provided by this family.

Not every symbol may be supported for every element.

classmethod get_or_create(file_node)

Get or create (store) a PotcarData node.

classmethod get_or_create_from_contents(contents)

Get or create (store) a PotcarData node from a string containing the POTCAR contents.

classmethod get_or_create_from_file(file_path)

Get or create (store) a PotcarData node from a POTCAR file.

classmethod get_potcar_group(group_name)

Return the PotcarFamily group with the given name.

classmethod get_potcar_groups(filter_elements=None, filter_symbols=None)

List all names of groups of type PotcarFamily, possibly with some filters.

Parameters:

• filter_elements – list of strings. If present, returns only the groups that contains one POTCAR for every element present in the list. Default=None, meaning that all families are returned. A single element can be passed as a string.

• filter_symbols – list of strings with symbols to filter for.

classmethod get_potcars_dict(elements, family_name, mapping=None, auto_migrate=True)

Get a dictionary {element: PotcarData.full_name} for all given symbols.

Parameters:

• elements – The list of symbols to find POTCARs for

• family_name – The POTCAR family to be used

• mapping – A mapping[element] -> full_name, for example: mapping={‘In’: ‘In’, ‘As’: ‘As_d’}

• auto_migrate – A flag of wether to perform the migration automatically when migration is found to be needed.

Exceptions:

*If the mapping does not contain an item for a given element name, raise a ValueError. *If no POTCAR is found for a given element, a NotExistent error is raised.

If there are multiple POTCAR with the same full_name, the first one returned by PotcarData.find() will be used.

classmethod get_potcars_from_structure(structure, family_name, mapping=None)

Given a POTCAR family name and a AiiDA structure, return a dictionary associating each kind name with its PotcarData object.

Parameters:

• structure – An AiiDA structure

• family_name – The POTCAR family to be used

• mapping – A mapping[kind name] -> full_name, for example: mapping={‘In1’: ‘In’, ‘In2’: ‘In_d’, ‘As’: ‘As_d’}

The Dictionary looks as follows:

{
    kind1.name: PotcarData_for_kind1,
    kind2.name: ...
}

This is to make the output of this function suitable for giving directly as input to VaspCalculation.process() instances.

Raises:

• MultipleObjectsError – if more than one UPF for the same element is found in the group.

• NotExistent – if no UPF for an element in the group is found in the group.

Example:

## using VASP recommended POTCARs
from aiida_vasp.utils.default_paws import DEFAULT_LDA, DEFAULT_GW
vasp_process = CalculationFactory('vasp.vasp').process()
inputs = vasp_process.get_inputs_template()
inputs.structure = load_node(123)
inputs.potential = PotcarData.get_potcars_from_structure(
    structure=inputs.structure,
    family_name='PBE',
    mapping=DEFAULT_GW
)

## using custom POTCAR map
custom_mapping = {
    'In1': 'In',
    'In2': 'In_d',
    'As': 'As_d'
}
inputs.potential = PotcarData.get_potcars_from_structure(
    structure=inputs.structure,
    family_name='PBE',
    mapping=custom_mapping
)

classmethod query_by_attrs(query=None, **kwargs)

Find a Data node by attributes.

set_potcar_file_node(potcar_file_node)

Initialize from a PotcarFileData node.

store(*args, **kwargs)

Ensure uniqueness before storing.

classmethod upload_potcar_family(source, group_name, group_description=None, stop_if_existing=True, dry_run=False)

Upload a set of POTCAR potentials as a family.

Parameters:

• source – a path containing all POTCAR files to be added.

• group_name – the name of the group to create. If it exists and is non-empty, a UniquenessError is raised.

• group_description – a string to be set as the group description. Overwrites previous descriptions, if the group was existing.

• stop_if_existing – if True, check for the sha512 of the files and, if the file already exists in the DB, raises a MultipleObjectsError. If False, simply adds the existing UPFData node to the group.

• dry_run – If True, do not change the database.

class aiida_vasp.data.potcar.PotcarFileData(*args, **kwargs)

Bases: ArchiveData, PotcarMetadataMixin, VersioningMixin

Store a POTCAR file in the db, never use as input to a calculation or workchain.

Warning

Warning! Sharing nodes of this type may be illegal!

In general POTCAR files may lay under license agreements, such as the ones distributed by the VASP group to VASP license holders. Take care to not share such licensed data with non-license holders.

When writing a calculation plugin or workchain, do not use this as an input type, use aiida_vasp.data.potcar.PotcarData instead!

add_file(src_abs, dst_filename=None)

Add the POTCAR file to the archive and set attributes.

export_archive(archive, dry_run=False)

Add the stored POTCAR file to an archive for export.

export_file(path, dry_run=False)

Write the contents of the stored POTCAR file to a destination on the local file system.

Parameters:

path – path to the destination file or folder as a Path or string object

When given a folder, the destination file will be created in a subdirectory with the name of the symbol. This is for conveniently exporting multiple files into the same folder structure as the POTCARs are distributed in.

Examples:

potcar_file = PotcarFileData.get_or_create(<file>)
assert potcar_file.symbol == 'Si_d'

potcar_file.export('./POTCAR.Si')
## writes to ./POTCAR.Si

potcar_file.export('./potcars/')
## writes to
## ./
##  |-potcars/
##           |-Si_d/
##                 |-POTCAR

get_content()

classmethod get_contents_sha512(contents)

Get the sha512 sum for the contents of a POTCAR file (after normalization).

get_file_obj()

Open a readonly file object to read the stored POTCAR file.

get_file_obj_and_tar_obj()

Return both decompressed file object and the archive object

classmethod get_file_sha512(path)

Get the sha512 sum for a POTCAR file (after whitespace normalization).

classmethod get_or_create(filepath)

Get or create (store) a PotcarFileData node.

classmethod get_or_create_from_contents(contents)

Get or create (store) a PotcarFileData node from a string containing the POTCAR contents.

init_with_kwargs(**kwargs)

Delegate initialization to _init_with - methods.

store(*args, **kwargs)

Ensure uniqueness and existence of a matching PotcarData node before storing.

class aiida_vasp.data.potcar.PotcarGroup(label: str | None = None, user: User | None = None, description: str = '', type_string: str | None = None, backend: StorageBackend | None = None)

Bases: Group

A group for holding PotcarData objects that maps to various collections of POTCARs.

class aiida_vasp.data.potcar.PotcarMetadataMixin

Bases: object

Provide common Potcar metadata access and querying functionality.

property element

Chemical element described by the POTCAR (readonly).

classmethod exists(**kwargs)

Answers the question wether a node with attributes given in kwargs exists.

classmethod find(**kwargs)

Find nodes by POTCAR metadata attributes given in kwargs.

classmethod find_one(**kwargs)

Find one single node.

Raise an exception if there are multiple.

property full_name

The name of the original file uploaded into AiiDA.

property functional

Functional class of the POTCAR potential (readonly).

property original_file_name

The name of the original file uploaded into AiiDA.

property potential_set

The name of the original file uploaded into AiiDA.

classmethod query_by_attrs(query=None, **kwargs)

Find a Data node by attributes.

property sha512

Sha512 hash of the POTCAR file (readonly).

property symbol

Element symbol property (VASP term) of the POTCAR potential (readonly).

property title

Title of the POTCAR file (readonly).

verify_unique()

Raise a UniquenessError if an equivalent node exists.

class aiida_vasp.data.potcar.PotcarWalker(path)

Bases: object

Walk the file system and find POTCAR files under a given directory.

Build a list of potcars including their full path and wether they are archived inside a tar archive.

file_dispatch(root, dirs, file_name)

Add POTCAR files to the list and dispatch handling of different kinds of files to other methods.

classmethod handle_tarfile(dirs, file_path)

Handle .tar archives: extract and add the extracted folder to be searched.

walk()

Walk the folder tree to find POTCAR, extracting any tar archives along the way.

class aiida_vasp.data.potcar.VersioningMixin

Bases: object

Minimalistic Node versioning.

property model_version

classmethod old_versions_in_db()

Determine whether there are Nodes created with an older version of the model.

set_version()

aiida_vasp.data.potcar.by_older(left, right)

aiida_vasp.data.potcar.by_user(left, right)

aiida_vasp.data.potcar.extract_tarfile(file_path)

Extract a .tar archive into an appropriately named folder, return the path of the folder, avoid extracting if folder exists.

aiida_vasp.data.potcar.migrate_potcar_group()

Migrate existing potcar family groups to new specification. This creates copies of the old potcar family groups using the new PotcarGroup class.

Despite the name ‘migrate’, the potcar family group created are in fact left as they are.

aiida_vasp.data.potcar.normalize_potcar_contents(potcar_contents)

Normalize whitespace in a POTCAR given as a string.

aiida_vasp.data.potcar.sha512_potcar(potcar_contents)

Hash the contents of a POTCAR file (given as str).

aiida_vasp.data.potcar.temp_dir()

Temporary directory context manager that deletes the tempdir after use.

aiida_vasp.data.potcar.temp_potcar(contents)

Temporary POTCAR file from contents.

Representation of WAVECAR and WAVEDER objects.

class aiida_vasp.data.wavefun.WavefunData(file: str | Path | IO, filename: str | Path | None = None, **kwargs: Any)

Bases: SinglefileData