dfttk.configuration

Configuration class for DFTTK.

Manages all settings, input generation, job submission, and data processing for high-throughput DFT calculations of the Helmholtz energy and related thermodynamic properties. Supports automated workflows for volume relaxation, convergence tests, energy-volume curves, phonon calculations, Debye model, thermal electronic contributions, and quasi-harmonic analysis using VASP and DFTTK.

class dfttk.configuration.MetaData(vasp_version=None, mpdd_id=None, parent_database=None, parent_database_id=None, parent_database_url=None, affiliation='DFTTK', comment=None)[source]

Bases: object

A class to store metadata information for a configuration.

class dfttk.configuration.Configuration(path, name, vasp_cmd, alias=None, multiplicity=None)[source]

Bases: object

Main configuration class for automating DFTTK workflows for Helmholtz energy calculations.

Parameters:

  • path (str) – Path to the working directory.

  • name (str) – Name for this configuration.

  • vasp_cmd (list[str]) – The command and arguments to run VASP, e.g., [‘mpirun’, ‘vasp_std’].

  • alias (str) – Alias for the configuration, used for easier identification. Defaults to None.

  • multiplicity (int) – Configuration multiplicity. Defaults to None.

add_metadata(vasp_version=None, mpdd_id=None, parent_database=None, parent_database_id=None, parent_database_url=None, affiliation='DFTTK', comment=None)[source]

Add metadata information to the configuration.

Parameters:

  • vasp_version (str) – Version of VASP used. Defaults to None.

  • mpdd_id (ObjectId) – The MongoDB ObjectId for the MPDD entry. Defaults to None.

  • parent_database (str) – The name of the parent database. Defaults to None.

  • parent_database_id (str) – The ID of the parent database entry. Defaults to None.

  • parent_database_url (str) – The URL of the parent database. Defaults to None.

  • affiliation (str) – Database affiliation. Defaults to “DFTTK”.

  • comment (str) – Additional comments. Defaults to None.

Return type:

None

run_volume_relax(material_type, error_msgs=['tet', 'ksymm', 'inv_rot_mat', 'brmix', 'subspacematrix', 'tetirr', 'incorrect_shift', 'real_optlay', 'rspher', 'dentet', 'too_few_bands', 'triple_product', 'rot_matrix', 'brions', 'pricel', 'zpotrf', 'amin', 'zbrent', 'pssyevx', 'pdsyevx', 'eddrmm', 'edddav', 'algo_tet', 'grad_not_orth', 'nicht_konv', 'zheev', 'eddiag', 'elf_kpar', 'elf_ncl', 'rhosyg', 'posmap', 'point_group', 'pricelv', 'symprec_noise', 'dfpt_ncore', 'bravais', 'nbands_not_sufficient', 'hnform', 'coef', 'set_core_wf', 'read_error', 'auto_nbands', 'ibzkpt', 'fexcf', 'spin_polarized_harris'], max_errors=10, encut=520, kppa=4000, magmom_fm=False, potcar_functional='PBE_54', incar_functional='PBE', other_settings=None, vaspjob_kwargs=None, custodian_kwargs=None)[source]

Set up and submit a volume relaxation job.

Parameters:

  • material_type (str) – Type of material (e.g., “metal” or “non_metal”).

  • error_msgs (list[str]) – List of error messages for VaspErrorHandler. Defaults to all known messages.

  • max_errors (int) – Maximum number of errors allowed before Custodian stops. Defaults to 10.

  • encut (int) – Plane-wave cutoff energy. Defaults to 520.

  • kppa (int) – K-points per reciprocal atom. Defaults to 4000.

  • magmom_fm (bool) – Use ferromagnetic magmom. Defaults to False.

  • potcar_functional (str) – POTCAR functional. Defaults to “PBE_54”.

  • incar_functional (str) – INCAR functional. Defaults to “PBE”.

  • other_settings (dict) – Additional VASP INCAR/KPOINTS settings. Defaults to None.

  • vaspjob_kwargs (dict) – Additional keyword arguments to pass to VaspJob (e.g., output_file, stderr_file).

  • custodian_kwargs (dict) – Additional keyword arguments to pass to Custodian (e.g., scratch_dir, gzipped_output).

Return type:

None

Returns:

None

run_conv_test(encut=520, kppa=4000, magmom_fm=False, potcar_functional='PBE_54', incar_functional='PBE', other_settings={}, encut_list=[270, 320, 370, 420, 470, 520, 570, 620, 670, 720, 770, 820], kppa_list=[1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000], force_gamma=True, backup=False, max_errors=10)[source]

Set up and submit convergence tests for ENCUT and k-point mesh.

Parameters:

  • encut (int) – Plane-wave cutoff energy. Defaults to 520.

  • kppa (int) – K-points per reciprocal atom. Defaults to 4000.

  • magmom_fm (bool) – Use ferromagnetic magmom. Defaults to False.

  • potcar_functional (str) – POTCAR functional. Defaults to “PBE_54”.

  • incar_functional (str) – INCAR functional. Defaults to “PBE”.

  • other_settings (dict) – Additional VASP settings. Defaults to empty dict.

  • encut_list (list[int]) – List of ENCUT values to test. Defaults to [270, …, 820].

  • kppa_list (list[float]) – List of KPPA values to test. Defaults to [1000, …, 10000].

  • force_gamma (bool) – Force gamma-centered mesh. Defaults to True.

  • backup (bool) – Enable backup. Defaults to False.

  • max_errors (int) – Maximum number of errors allowed. Defaults to 10.

Return type:

None

analyze_encut_conv(plot=True)[source]

Analyze the ENCUT convergence test results.

Parameters:

plot (bool) – Whether to generate a plot of the results. Defaults to True.

Returns:

DataFrame of ENCUT convergence data and the corresponding plotly Figure.

Return type:

tuple[DataFrame, Figure]

analyze_kpoints_conv(plot=True)[source]

Analyze the k-point convergence test results.

Parameters:

plot (bool) – Whether to generate a plot of the results. Defaults to True.

Returns:

DataFrame of k-point convergence data and the corresponding plotly Figure.

Return type:

tuple[DataFrame, Figure]

ev_curve_settings(material_type, volumes, encut=520, kppa=4000, magmom_fm=False, potcar_functional='PBE_54', incar_functional='PBE', other_settings={}, restarting=False, keep_wavecar=False, keep_chgcar=False, copy_magmom=False, override_2relax=None, override_3static=None, max_errors=10)[source]

Set the settings for the energy-volume (E-V) curve workflow.

Parameters:

  • material_type (str) – Type of material (e.g., “metal” or “non_metal”).

  • volumes (list[float]) – List of volumes to use for the E-V curve.

  • encut (int) – Plane-wave cutoff energy. Defaults to 520.

  • kppa (int) – K-points per reciprocal atom. Defaults to 4000.

  • magmom_fm (bool) – Use ferromagnetic magmom. Defaults to False.

  • potcar_functional (str) – POTCAR functional. Defaults to “PBE_54”.

  • incar_functional (str) – INCAR functional. Defaults to “PBE”.

  • other_settings (dict) – Additional VASP settings. Defaults to empty dict.

  • restarting (bool) – Whether to restart from previous calculations. Defaults to False.

  • keep_wavecar (bool) – Keep WAVECAR file. Defaults to False.

  • keep_chgcar (bool) – Keep CHGCAR file. Defaults to False.

  • copy_magmom (bool) – Copy magmom from previous runs. Defaults to False.

  • override_2relax (list) – Override settings for 2nd relaxation. Defaults to None.

  • override_3static (list) – Override settings for 3rd static run. Defaults to None.

  • max_errors (int) – Maximum number of errors allowed. Defaults to 10.

Return type:

None

run_ev_curve()[source]

Set up and submit the energy-volume (E-V) curve workflow.

This method prepares VASP input files and generates a run script for the E-V curve series using the settings stored in self.ev_curve_settings_data. It then submits the job using SLURM.

Raises:

AttributeError – If E-V curve settings have not been set (call ev_curve_settings() first).

Return type:

None

process_ev_curve(incar_keys=['1relax', '2relax', '3static'], incar_names=['INCAR.1relax', 'INCAR.2relax', 'INCAR.3static'], kpoints_keys=['1relax', '2relax', '3static'], kpoints_names=['KPOINTS.1relax', 'KPOINTS.2relax', 'KPOINTS.3static'], selected_volumes=None, read_initial_poscar=True, outcar_name='OUTCAR.3static', oszicar_name='OSZICAR.3static', contcar_name='CONTCAR.3static', collect_mag_data=False, magmom_tolerance=0.05, total_magnetic_moment_tolerance=0.1, mass_average='geometric', eos_name='BM4', volume_min=None, volume_max=None, num_volumes=1000)[source]

Process the energy-volume (E-V) curve data for the configuration.

This method initializes the EvCurveData object, extracts VASP input and output data, and fits the energy-volume data to an equation of state.

Parameters:

  • incar_keys (list[str]) – List of INCAR keys for dictionary keys. Defaults to [“1relax”, “2relax”, “3static”].

  • incar_names (list[str]) – List of INCAR names to read. Defaults to [“INCAR.1relax”, “INCAR.2relax”, “INCAR.3static”].

  • kpoints_keys (list[str]) – List of KPOINTS keys for dictionary keys. Defaults to [“1relax”, “2relax”, “3static”].

  • kpoints_names (list[str]) – List of KPOINTS names to read. Defaults to [“KPOINTS.1relax”, “KPOINTS.2relax”, “KPOINTS.3static”].

  • selected_volumes (list[float]) – List of volumes to process. Defaults to None.

  • read_initial_poscar (bool) – Whether to read the initial POSCAR file. Defaults to True.

  • outcar_name (str) – Name of the OUTCAR file. Defaults to “OUTCAR.3static”.

  • oszicar_name (str) – Name of the OSZICAR file. Defaults to “OSZICAR.3static”.

  • contcar_name (str) – Name of the CONTCAR file. Defaults to “CONTCAR.3static”.

  • collect_mag_data (bool) – Whether to collect magnetic data. Defaults to False.

  • magmom_tolerance (float) – Tolerance for magnetic moment. Defaults to 0.05.

  • total_magnetic_moment_tolerance (float) – Tolerance for total magnetic moment. Defaults to 0.1.

  • mass_average (str) – Method for mass averaging. Defaults to “geometric”.

  • eos_name (str) – Name of the equation of state to fit. Defaults to “BM4”.

  • volume_min (float) – Minimum volume for fitting. Defaults to None.

  • volume_max (float) – Maximum volume for fitting. Defaults to None.

  • num_volumes (int) – Number of volumes for fitting. Defaults to 1000.

Return type:

None

process_debye(volumes, temperatures, scaling_factor=0.617, gruneisen_x=0.6666666666666666)[source]

Process the Debye-Grüneisen model for the configuration.

This method initializes the DebyeGruneisen object and computes thermodynamic properties over a range of volumes and temperatures using the Debye model.

Parameters:

  • scaling_factor (float) – Scaling factor for the Debye temperature. Defaults to 0.617.

  • gruneisen_x (float) – Grüneisen parameter exponent. Defaults to 2/3.

  • temperatures (array) – Array of temperatures to evaluate.

phonons_settings(phonon_volumes, kppa, scaling_matrix=((1, 0, 0), (0, 1, 0), (0, 0, 1)), copy_magmom=True, backup=False, max_errors=10, relax=True)[source]

Set the settings for the phonon calculation workflow.

Parameters:

  • phonon_volumes (list[float]) – List of volumes to use for phonon calculations.

  • kppa (float) – K-points per reciprocal atom.

  • scaling_matrix (tuple[tuple[int]]) – Supercell scaling matrix. Defaults to identity matrix.

  • copy_magmom (bool) – Copy magmom from previous runs. Defaults to True.

  • backup (bool) – Enable backup. Defaults to False.

  • max_errors (int) – Maximum number of errors allowed. Defaults to 10.

  • relax (bool) – Whether to relax the structure before phonon calculation. Defaults to True.

Return type:

None

run_phonons(run_file='run_dfttk_phonons.py')[source]

Set up and submit the phonon calculation workflow.

This method generates a Python script to run the phonon calculations in parallel using the settings stored in self.phonons_settings_data, then executes the script.

Parameters:

run_file (str) – Name of the temporary Python script to run. Defaults to “run_dfttk_phonons.py”.

Raises:

AttributeError – If phonons settings have not been set (call phonons_settings() first).

Return type:

None

generate_phonon_dos()[source]

Generate the phonon density of states (DOS) using YPHON.

This method initializes the YphonPhononData object and processes the phonon DOS using the results in the working directory.

process_phonons(number_of_atoms, volumes_fit, temperatures, selected_volumes=None, order=2)[source]

Process phonon data for the configuration.

This method initializes the YphonPhononData object, extracts VASP input and output data, and processes harmonic phonon data for the specified number of atoms, temperatures, and order of fitting.

Parameters:

  • number_of_atoms (int) – Number of atoms to scale for the phonon calculation.

  • volumes_fit (ndarray) – 1D array of volumes to evaluate the fitted properties.

  • temperatures (ndarray) – Array of temperatures to evaluate.

  • selected_volumes (list[float]) – List of volumes to process. Defaults to None.

  • order (int) – Order of polynomial fitting. Defaults to 2.

thermal_electronic_settings(volumes, kppa, scaling_matrix=((1, 0, 0), (0, 1, 0), (0, 0, 1)), NEDOS=10001, backup=False, max_errors=10)[source]

Set the settings for the thermal electronic calculation workflow.

Parameters:

  • volumes (list[float]) – List of volumes to use for the calculation.

  • kppa (float) – K-points per reciprocal atom.

  • scaling_matrix (tuple[tuple[int]]) – Supercell scaling matrix. Defaults to identity matrix.

  • NEDOS (int) – Number of points in the DOS. Defaults to 10001.

  • backup (bool) – Enable backup. Defaults to False.

  • max_errors (int) – Maximum number of errors allowed. Defaults to 10.

Return type:

None

run_thermal_electronic(run_file='run_dfttk_thermal_electronic.py')[source]

Set up and submit the thermal electronic calculation workflow.

This method generates a Python script to run the thermal electronic calculations in parallel using the settings stored in self.thermal_electronic_settings_data, then executes the script.

Parameters:

run_file (str) – Name of the temporary Python script to run. Defaults to “run_dfttk_thermal_electronic.py”.

Raises:

AttributeError – If thermal electronic settings have not been set (call thermal_electronic_settings() first).

process_thermal_electronic(volumes_fit, temperatures, incar_keys=['elec_dos'], incar_names=['INCAR.elec_dos'], kpoints_keys=['elec_dos'], kpoints_names=['KPOINTS.elec_dos'], contcar_name='CONTCAR.elec_dos', vasprun_name='vasprun.xml.elec_dos', selected_volumes=None, selected_folders=None, folder_prefix='elec', order=1)[source]

Process thermal electronic data for the configuration.

This method initializes the ThermalElectronicData object, extracts VASP input and output data, and processes thermal electronic data for the specified temperature range and order of fitting.

Parameters:

  • volumes_fit (ndarray) – 1D array of volumes to evaluate the fitted properties.

  • temperatures (ndarray) – Array of temperatures to evaluate.

  • incar_keys (list[str]) – List of INCAR keys for dictionary keys. Defaults to [“elec_dos”].

  • incar_names (list[str]) – List of INCAR names to read. Defaults to [“INCAR.elec_dos”].

  • kpoints_keys (list[str]) – List of KPOINTS keys for dictionary keys. Defaults to [“elec_dos”].

  • kpoints_names (list[str]) – List of KPOINTS names to read. Defaults to [“KPOINTS.elec_dos”].

  • contcar_name (str) – Name of the CONTCAR file. Defaults to “CONTCAR.elec_dos”.

  • vasprun_name (str) – Name of the vasprun.xml file. Defaults to "vasprun.xml.elec_dos".

  • selected_volumes (ndarray | None) – Array of volumes to process. Defaults to None.

  • selected_folders (list[str] | None) – List of selected folders to keep the electron DOS data. Defaults to None.

  • folder_prefix (str) – Prefix for the folders containing electronic DOS data. Defaults to “elec”.

  • order (int) – Order of polynomial fitting. Defaults to 1.

process_qha(method, P=0.0)[source]

Perform quasi-harmonic approximation (QHA) calculations for a range of volumes. This method calculates thermodynamic quantities (Helmholtz free energy, entropy, and heat capacity) as functions of volume and temperature, and determines pressure-related properties using the specified QHA method.

Parameters:

  • method (str) – The method to use for QHA. Options are: - “debye” - “debye_thermal_electronic” - “phonons” - “phonons_thermal_electronic”

  • P (float) – Pressure in GPa. Defaults to 0.00.

Raises:

  • AttributeError – If required data is missing, including: - If the energy-volume curve is not processed. - If the Debye-Grüneisen model is not processed (for “debye” or “debye_thermal_electronic”). - If the phonons data is not processed (for “phonons” or “phonons_thermal_electronic”). - If the thermal electronic data is not processed (for “debye_thermal_electronic” or “phonons_thermal_electronic”).

  • ValueError –

    • If the temperature arrays for Debye/phonons and thermal electronic do not match (for “debye_thermal_electronic” or “phonons_thermal_electronic”) - If the volume arrays for Debye/phonons and thermal electronic do not match (for “debye_thermal_electronic” or “phonons_thermal_electronic”) - If an unknown method is provided.

to_mongodb(connection_string, db_name, collection_name, insert=True)[source]

This method initializes the MongoDB client, selects the specified database and collection, and prepares the object for subsequent data insertion or updates.

Parameters:

  • connection_string (str) – The MongoDB connection string.

  • db_name (str) – The name of the MongoDB database to use.

  • collection_name (str) – The name of the collection within the database.

  • insert (bool) – Whether to insert/update the document in MongoDB. Defaults to True.

Returns:

A dictionary representation of the configuration object, ready for insertion into MongoDB.

Return type:

dict

add_experiments(experiments)[source]
dfttk.configuration.plot_multiple_ev(config_objects, config_names, highlight_minimum=True, per_atom=False, title=None, cmap='plotly', marker_alpha=1, marker_size=10)[source]

Plot multiple energy-volume (E-V) curves on a single figure.

Parameters:

  • config_objects (dict[str, Configuration]) – Dictionary mapping configuration names to Configuration objects.

  • config_names (list[str]) – List of configuration names to plot.

  • highlight_minimum (bool) – Whether to highlight the minimum energy point. Defaults to True.

  • per_atom (bool) – Whether to plot energy per atom. Defaults to False.

  • title (str) – Title for the plot. Defaults to None.

  • cmap (str) – Colormap to use for the plot. Defaults to “plotly”.

  • marker_alpha (float) – Alpha (opacity) for markers. Defaults to 1.

  • marker_size (int) – Size of the markers. Defaults to 10.

Returns:

The combined Plotly figure containing all E-V curves.

Return type:

plotly.graph_objects.Figure