aiida_vasp.data package¶
Submodules¶
A general archive class.
- class aiida_vasp.data.archive.ArchiveData(*args, **kwargs)[source]¶
Bases:
Data
Compressed archive data node, contains a group of files that don’t need to be readily accessible on their own.
- store(*args, **kwargs)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Export a family of POTCAR nodes into a compressed archive.
- classmethod export_family_folder(family_name, path=None, dry_run=False)[source]¶
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 find(**kwargs)[source]¶
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
- classmethod get_full_names(family_name=None, element=None)[source]¶
Gives a set of symbols provided by this family.
Not every symbol may be supported for every element.
- classmethod get_or_create_from_contents(contents)[source]¶
Get or create (store) a PotcarData node from a string containing the POTCAR contents.
- classmethod get_or_create_from_file(file_path)[source]¶
Get or create (store) a PotcarData node from a POTCAR file.
- classmethod get_potcar_group(group_name)[source]¶
Return the PotcarFamily group with the given name.
- classmethod get_potcar_groups(filter_elements=None, filter_symbols=None)[source]¶
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)[source]¶
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 there are multiple POTCAR with the same
full_name
, the first one returned byPotcarData.find()
will be used.
- classmethod get_potcars_from_structure(structure, family_name, mapping=None)[source]¶
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 upload_potcar_family(source, group_name, group_description=None, stop_if_existing=True, dry_run=False)[source]¶
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)[source]¶
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)[source]¶
Add the POTCAR file to the archive and set attributes.
- export_archive(archive, dry_run=False)[source]¶
Add the stored POTCAR file to an archive for export.
- export_file(path, dry_run=False)[source]¶
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
- classmethod get_contents_sha512(contents)[source]¶
Get the sha512 sum for the contents of a POTCAR file (after normalization).
- classmethod get_file_sha512(path)[source]¶
Get the sha512 sum for a POTCAR file (after whitespace normalization).
- 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)[source]¶
Bases:
Group
A group for holding PotcarData objects that maps to various collections of POTCARs.
- class aiida_vasp.data.potcar.PotcarMetadataMixin[source]¶
Bases:
object
Provide common Potcar metadata access and querying functionality.
- property element¶
Chemical element described by the POTCAR (readonly).
- classmethod exists(**kwargs)[source]¶
Answers the question wether a node with attributes given in kwargs exists.
- classmethod find_one(**kwargs)[source]¶
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.
- 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).
- class aiida_vasp.data.potcar.PotcarWalker(path)[source]¶
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)[source]¶
Add POTCAR files to the list and dispatch handling of different kinds of files to other methods.
- class aiida_vasp.data.potcar.VersioningMixin[source]¶
Bases:
object
Minimalistic Node versioning.
- property model_version¶
- aiida_vasp.data.potcar.extract_tarfile(file_path)[source]¶
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()[source]¶
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)[source]¶
Normalize whitespace in a POTCAR given as a string.
- aiida_vasp.data.potcar.sha512_potcar(potcar_contents)[source]¶
Hash the contents of a POTCAR file (given as str).
- aiida_vasp.data.potcar.temp_dir()[source]¶
Temporary directory context manager that deletes the tempdir after use.
Representation of WAVECAR and WAVEDER objects.