atlas.core package

Subpackages

Submodules

atlas.core.clusters module

Generate clusters and structures for the database.

atlas.core.clusters.apply_gauss_perturb_db(repeat: int, db_obj, center: float = 0.04, max_structures=None, phase: Phase = None)
atlas.core.clusters.apply_gauss_perturb_list(repeat: int, cluster_list: list, center: float = 0.04)
atlas.core.clusters.apply_replacement_cluster(db_obj: InitialDatabase, cluster: Cluster, phase: Phase, num_struct: int, num_repeat: int)
atlas.core.clusters.apply_replacement_cluster_db(db_obj: InitialDatabase, phase: Phase, num_struct: int, num_repeat: int, similarity_check=True, save_in_db=True, max_structures=None)
atlas.core.clusters.bottom_structure(structure: Structure, offset: int = 2) → Structure

Move the structure towards the bottom of the cell, leaving a offset wide margin at the bottom.

Parameters:

  • structure (Structure) – Target structure to move to the bottom.

  • offset (int, optional) – Separation to be left between the bottom of the cell and the structure, by default 2, in Angstrom.

Returns:

Pymatgen structure containing a structure placed on the bottom, with the same attributes as the original.

Return type:

Structure

atlas.core.clusters.center_structure(structure: Structure) → Structure

Move the center of mass of the structure towards the center of the cell.

Parameters:

structure (Structure) – Target structure to move to the center.

Returns:

Pymatgen structure containing a structure placed on the center of the cell, with the same attributes as the original.

Return type:

Structure

atlas.core.clusters.get_center_of_mass(structure: Structure)

Get the center of mass (COM) of a given structure.

The center of mass is computed by using:

COM = sum(r_i*m_i)/sum(m_i)

Where r_i are the coordinates for each atom and m_i their atomic masses.

Parameters:

structure (Structure) – Structure for which the COM will be found

Returns:

Coordinates of the COM

Return type:

np.array

atlas.core.clusters.get_element_constants(element_symbol: str) → dict

Retrieves the conventional lattice constants for any element, using ASE’s and Pymatgen’s data sources, automatically handling cubic, HCP, and other crystal systems.

atlas.core.clusters.make_clean_cluster(indb_obj, size, phase: Phase, method: str = 'wulff', basin_hopping: bool = False, bh_totalsteps: int = 50, bh_fmax: float = 0.05, lj_sigma: float | None = None, lj_epsilon: float = 1.0)
atlas.core.clusters.make_clean_dimer(indb_obj, phase: Phase)

atlas.core.code_utils module

Utility functions for code manipulation.

class atlas.core.code_utils.ATLHighlighter

Bases: RegexHighlighter

Apply custom highlighting to log messages using Regex.

This highlights patterns in the message body, such as file paths, numbers, or specific status keywords.

base_style: ClassVar[str] = 'atl.'
highlights: ClassVar[Sequence[str]] = ['(?P<path>[\\w.\\-/]+\\.(py|log|txt|json|yaml))', '(?P<number>\\b\\d+\\b)', '(?P<success>Done|Success|Completed)', '(?P<failure>Error|Failed|Exception)']
class atlas.core.code_utils.ATLRichHandler(level: int | str = 0, console: Console | None = None, *, show_time: bool = True, omit_repeated_times: bool = True, show_level: bool = True, show_path: bool = True, enable_link_path: bool = True, highlighter: Highlighter | None = None, markup: bool = False, rich_tracebacks: bool = False, tracebacks_width: int | None = None, tracebacks_code_width: int | None = 88, tracebacks_extra_lines: int = 3, tracebacks_theme: str | None = None, tracebacks_word_wrap: bool = True, tracebacks_show_locals: bool = False, tracebacks_suppress: Iterable[str | ModuleType] = (), tracebacks_max_frames: int = 100, locals_max_length: int = 10, locals_max_string: int = 80, log_time_format: str | FormatTimeCallable = '[%x %X]', keywords: List[str] | None = None)

Bases: RichHandler

Custom RichHandler that rewrites logging level names locally.

This allows us to display ‘[ i ]’ instead of ‘INFO’ on the console without using logging.addLevelName() to change it globally (which would affect file logs and other libraries).

emit(record: LogRecord) → None

Intercept the log record to modify the levelname before rendering.

Parameters:

record (logging.LogRecord) – The log record to be processed.

class atlas.core.code_utils.LevelNameFilter(levels_to_keep)

Bases: Filter

Filters log records based on a list of allowed level names.

filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

atlas.core.code_utils.atl_show_progress(iterable, total=None, interval=100, level_tag='[ i ]', prepend='MACE:')

Shows a rich progress bar with a custom format matching ATL logs.

Parameters:

  • iterable (iterable) – The iterable to wrap.

  • total (int, optional) – The total number of items in the iterable.

  • interval (int, optional) – The number of iterations between updates of the timestamp.

  • level_tag (str, optional) – The logging level tag to display.

  • prepend (str, optional) – The string to prepend to the progress bar.

atlas.core.code_utils.check_atl_version(logger=None)

Check and print if the current version of ATLAS is up-to-date.

Returns:

Current version of ATLAS and the last tagged version in the repository.

Return type:

tuple[Version, Version]

atlas.core.code_utils.create_handler_filters(handler: str)
atlas.core.code_utils.custom_print(string: str, print_type: str = 'default', end='\n', extra_tab=False, logger=None, extras: dict = None)

Prints a string using different formatting styles for easier debugging.

Parameters:

  • string (str) – Text to be printed

  • print_type (str, optional, default=info) –

    Style to use when printing. Available styles are:

    • info/default: prefixes [ i ] before the string.

    • warning/warn: prefixes [ ! ] before the string.

    • debug/extra: prefixes […] before the string.

    • done/ok: prefixes [ ✔ ] before the string.

    • error/problem: prefixes [ X ] before the string.

    • none/clean/clear/empty: leaves an empty space before the string.

  • end (str, optional, default=n) – String appended after the last value, default a newline.

  • extra_tab (bool, optional, default=False) – If True, adds an extra tab before the string.

  • logger (logging.Logger, optional, default=None) – Logger to use for printing. If None, a new logger named ‘mdb’ is created

Returns:

Logger used for printing the string

Return type:

logging.Logger

atlas.core.code_utils.deprecated(reason, since_ver=None)

Decorator to mark a function as deprecated.

Parameters:

reason (str) – Reason to print for the deprecation of the old function

Example

Use it as a decorator:

>>> @deprecated(reason="Use to_cluster instead.", since_ver="0.6.2")
>>> def to_atoms():
>>>     pass
atlas.core.code_utils.display_qr_in_cli(data: str)

Generates and displays a QR code in the terminal.

Parameters:

data (str) – The data to encode in the QR code (e.g., a URL).

atlas.core.code_utils.get_atl_version_info()

Get the current version of ATLAS and the last tagged version in the repository.

Returns:

  • Version – Current version of ATLAS

  • Version – Last tagged version in the repository

  • str – Hash of the current commit

atlas.core.code_utils.get_cache_path() → Path

Get the path to ATLAS’s the cacheuration directory.

atlas.core.code_utils.get_config_path() → Path

Get the path to ATLAS’s the configuration directory.

atlas.core.code_utils.get_console_handler() → tuple[RichHandler, Console]

Sets up the custom console and handler with the ATL theme.

Returns:

The configured handler and console instance.

Return type:

tuple[RichHandler, Console]

atlas.core.code_utils.get_last_tagged_version()

Get the last tagged version from the GitHub repository (via SSH). If SSH access fails, fall back to checking the local Git repository.

Returns:

  • str – Last tagged version in the repository.

  • str – Hash of the current commit.

atlas.core.code_utils.get_last_tagged_version_local(repo_dir_path: str = None)

Get the last tagged version from the local Git repository.

Returns:

  • str – Last tagged version in the local repository.

  • str – Hash of the current commit.

atlas.core.code_utils.get_list_of_tags(repo_path: str | Path | None = None) → list[Version]

Get a list of tags from the git repository in the CWD.

Parameters:

repo_path (str, optional) – Path to the git repository. If None, uses the current working directory.

Returns:

List of tags in the repository.

Return type:

list[str]

atlas.core.code_utils.init_cache_dir(cache_dir)

Create the mdb cache directory.

atlas.core.code_utils.init_config_dir(config_dir, config_file: str)

Create the configuration directory and the secrets file template.

atlas.core.code_utils.init_logger(source: str, log_path=None, show_log_path: bool = True) -> (<class 'logging.Logger'>, <class 'str'>)
atlas.core.code_utils.logging_set_levels()
atlas.core.code_utils.save_qr_to_file(data: str, filename: str = 'qr_code.png')

Generates a QR code and saves it as an image file.

atlas.core.exceptions module

Custom exceptions for the ATLAS package.

exception atlas.core.exceptions.AtomNotFoundForCluster

Bases: Exception

Raised when the atom type is not found in the cluster.

exception atlas.core.exceptions.BaseStructureNotFound

Bases: Exception

Raised when the base structure is not found in the database.

exception atlas.core.exceptions.CompositionNotMatchingElementListError(composition, element_list, name='unknown')

Bases: Exception

Raised when the composition does not match the element list.

exception atlas.core.exceptions.EmptyDataBase

Bases: Exception

Raised when the database is empty.

exception atlas.core.exceptions.FilterError

Bases: Exception

Raised when the filter is not valid.

exception atlas.core.exceptions.IncompatibleDataBase

Bases: Exception

Raised when the database type is not understood.

exception atlas.core.exceptions.IncompatiblePhaseError(phase_diagram_ele_list, phase)

Bases: Exception

Raised when the phase has elements not expected by the phase diagram.

exception atlas.core.exceptions.MissingElementError(element, element_list, name='unknown')

Bases: Exception

Raised when the element is not found in the element_list.

exception atlas.core.exceptions.MissingMandatoryParameterError

Bases: Exception

Raised when a mandatory parameter is missing in the toml dictionary.

exception atlas.core.exceptions.PhaseDiagramEmpty

Bases: Exception

Raised when the phase diagram is empty.

exception atlas.core.exceptions.PhaseNotFound(phase_diagram, given_phase)

Bases: Exception

Raised when the phase is not found in the phase diagram.

atlas.core.initial_db module

Generates a pandas dataframe containing a set of base (unperturbed) structures and a certain number of structures with an applied perturbation with respect to the temperature.

class atlas.core.initial_db.InitialDatabase(database_name: str = 'initial_database', max_num_atoms: int = 64, load_db: bool = False, phase_diagram: BinaryPhaseDiagram = None, use_offset: bool = True, database_path: str | Path = '.', create_db=True)

Bases: object

Object that creates an initial database where structures will be stored. Materials are downloaded using the materials project API. Contains methods related to gathering, preparing, visualizing and modifying the initial database. The structures are stored internally as a pandas Dataframe.

df

Dataframe containing the structures for the initial database.

Type:

pd.Dataframe

database_name

Orientative name for the database. Will be used for saving it into a file.

Type:

str

database_path

Path where the database will be saved.

Type:

str | pl.Path

max_num_atoms

Maximum number of atoms present in any structure generated, by default 64.

Type:

int

secrets

Object containing the API key for the materials project database.

Type:

dict

use_offset

Use an offset for the phase ratios to allow them to overlap, by default True.

Type:

bool, optional

Returns:

Object containing the database and methods.

Return type:

InitialDatabase

Raises:

KeyError – This error is raised when a wrong phase is given.

Notes

In order to be able to gather structures from the MP API, the initial setup of ATLAS must have been completed, or a ‘secrets.json’ file should be located in the same directory. The json file containing the secrets should have the following structure:

>>> {
>>>        "API_KEY": "XXXXXX"
>>> }
Ang2Bohr = 1.8897261246257702
Bohr2Ang = 0.529177210903
Eh2eV = 27.211386245988
add_single_atoms(vacuum: float = 10)

Add structures containing a single atom of each species in the database.

Some MLIPs such as MACE require specifically labelled structures to be used for their reference energies. The structures are defined as a single atom of one of the species present in the MLIP training database. Structures are centered in the cell with some vacuum around them.

Parameters:

vacuum (float, optional) – Amount of vacuum to add around the atom in Angstroms, by default 10.

apply_min_deformation(frac_max: float = 0.05, frac_min: float = 0.01, repeat: int = 1, filters: list[str] = None, only_use_base: bool = True, use_phase: Phase = None, rng_seed: int = None, limit_num_structures: int = None)

Apply small deformations to the lattice parameters of relaxed structures.

This method perturbs the lattice parameters of structures by applying small deformations to their lattice matrix elements. The perturbations are repeated a specified number of times, creating multiple perturbed structures for each initial structure. This helps in generating structures with slightly higher energies and forces, useful for generating training data for neural network potentials (NNP) intended for molecular dynamics (MD) simulations.

Parameters:

  • frac_max (float, optional) – Maximum fraction of the lattice parameter perturbation, by default 0.05.

  • use_phase (atl_pd.Phase, optional) – Phase to be used for the perturbation.

  • filters (list[str], optional) – List of filters to apply to the database, by default None. It can be one of ‘bulk’, ‘surface’, ‘cluster’, ‘vacancy’ or ‘perturb’.

  • only_use_base (bool, optional) – If True, only the base structures will be perturbed, by default True in order to maintain the perturbation strategy consistent with previous versions.

  • frac_min (float, optional) – Minimum fraction of the lattice parameter perturbation, by default 0.01.

  • repeat (int, optional) – Number of times to apply the perturbation to each structure, by default 1.

  • rng_seed (int, optional) – Seed for the random number generator, by default None.

  • limit_num_structures (int, optional) – Limit the number of structures to be perturbed, by default None.

Raises:

NotImplementedError – If the perturbation strategy is applied to an unsupported structure type.

Notes

The perturbed structures are then converted to the appropriate type (Bulk or Surface) and saved to the database.

Example

>>> initial_db = InitialDatabase()
>>> initial_db.apply_min_deformation(
>>>     frac_max=0.05, frac_min=0.01, repeat=5
>>> )
apply_vacancies_random(filters: list, seed: int, repeat=2, element_list: list = None, max_vac_perc: float = 0.75, min_vac_perc: float = 0.25, lim_num_struc: int = None, phase: Phase = None)

Apply random vacancies to the structures in the database.

db_struct_to_ase(row) → Atoms
descriptors_concave_hull(descriptor_type: str = 'soap', dimensionality_reduction_method: str = 'autoencoder', descriptor_settings: dict = None, load_autoencoder_path: str = None, rng_seed: int = None, device: str = None, plot_filename: str = None, boundary_method: str = 'concave_hull', morph_disk_size: int = 10, morph_threshold: int = 250, morph_dpi: int = 100)
display_db_ase()

Display the the structures in the database using ase.visualize.view.

eV2Eh = 0.03674932217565499
export_db(out_format: str = 'extxyz', file_name: str = None, file_path: str | Path = None)

Export the structures of the database to a file using ASE.

find_repeat_structures(delete=False, filters: list = None, phase: Phase = None)

Find and delete repeated structures in the database.

The SOAP descriptor is used to fingerprint structures in the database.

gather_base_structures(phase_diag_phases)
gen_init_md_frames(filters: list, seed: int, md_gen_dict: dict, lim_num_struc: int = None, phase: Phase = None)

Run MD simulations for some structures in the database.

gen_report() → dict

Generate a report containing the database information.

Returns:

Dictionary containing the database information in different categories.

Return type:

dict

generate_bulk_structures(prototype: str, phase: str, num_struct: int, num_repeats: int, get_different_supercells: bool, min_num_atoms: int, supercell_max_idx: int, convert_to_base: bool = True, read: bool = True, overwrite_read_from_db_list: list = None, seed: int = None)

Allows to create several variations of a certain phase structure by randomly replacing atoms in the base structure.

Parameters:

  • prototype (str) – Materials project id of the prototype structure to be used as template.

  • phase (str) – Name of the phase to be used.

  • num_struct (int) – Number of different atomic compositions to be generated.

  • num_repeats (int) – Number of random replacements done for each atomic composition.

  • get_different_supercells (bool) – Whether to store just a single supercell or several of them. If False, a single supercell is chosen so that the resulting structure has a total number of atoms under a certain threshold. If True, the same structure is chosen, but additionally, any possible structure with smaller supercells is also added.

  • read (bool) – Whether to read structures from the db or use the MP API to get them, by default True.

  • overwrite_read_from_db_list (list) – List of structures to read from the db instead of the MP API, will ignore the read flag if this is not empty.

  • convert_to_base (bool) – Whether to convert all atoms from the structure to the base atom, in order to increase randomness when replacing.

Raises:

KeyError – Raised if the given phase is not found. All of the available phases are given on the self.phase_diagram dictionary. More phases could be added there if necessary.

generate_clusters(size_range: list, get_replacements=False, get_perturbed=False, add_dimer=False, save_in_db=False, limit_per_phase: int = None, phase: Phase = None, num_struct: int = 2, num_repeat: int = 2, method: str = 'wulff', basin_hopping: bool = False, bh_totalsteps: int = 50, bh_fmax: float = 0.05, lj_sigma: float | None = None, lj_epsilon: float = 1.0)
generate_n2p2_input_aiida(aiida_group_list: list, filter_dict: dict, path: str = None)
get_base_structs_current_phase(phase)
get_db_shape() → tuple
get_soap_descriptors(**kwargs) → ndarray
get_structure_list() → list[Atoms]

Retrieve all structures from the dataframe and return them as a list.

Returns:

A list of ASE Atoms objects representing the structures in the dataframe.

Return type:

list[ase.Atoms]

kB = 8.314
limit_structure_number_phases(structure_limit: int, structure_types: list, phases_to_use: list = None)
classmethod load_database(database_path: Path | str) → Self | DataFrame

Load a ATL database from a specific path.

Returns:

Object containing structure data for the initial database.

Return type:

InitialDatabase | pd.DataFrame

plot_database_composition(temperature_K: float = 273.0, rc_params: dict = None, fig_path: str | Path = '.', fig_name: str = 'database_composition', max_phases_pie: int = 6)
query_mp_api_prototype(prototype)
read_base_structures(path: str, target_structures=None)

Reads base structures from a given path and stores them in the database.

remove_structs_out_of_atom_count_range(min_num_atoms: int, max_num_atoms: int, remove_base=False)
remove_structs_out_of_cell_size_range(min_cell_size: float, remove_base=False)
save_database(path: str = None, suffix: str = None)

Saves the database dataframe into a pkl object.

Parameters:

  • path (str, optional.) – Location where the pickle object will be saved, by default None, which defaults to storing the file in the CWD.

  • suffix (str, optional.) – String that will be added at the end of the filename.

standardize_struct_ids(atoms_list: list[Atoms]) → list[Atoms]

Ensure every ASE structure has standardized atl_* info keys.

Delegates to atlas.active_learning.active_learning_utils.standardize_atoms_info(), which migrates legacy mdb_* keys to atl_* and ensures every structure has an atl_id UUID.

Parameters:

atoms_list (list of ase.Atoms) – The list of ASE atoms objects to process.

Returns:

The updated list with standardized keys in info.

Return type:

list of ase.Atoms

atlas.core.initial_db.cli_gen_db_report(database_path: Path | str)

Generate a report of the database.

Parameters:

database_path (str | Path) – Path to the database.

Returns:

Report of the database.

Return type:

dict

atlas.core.initial_db.cli_run_gen_initial_database(db_path: str | Path, db_dict: dict, phase_diagram_dict: dict, gen_dict: dict, selected_phases, config_dict: dict)
atlas.core.initial_db.get_database_report(structures: InitialDatabase)
atlas.core.initial_db.get_step_to_structure_mapping(database: Atoms | list[Atoms] | InitialDatabase) → dict
atlas.core.initial_db.get_struct_idx_from_uuid(database: InitialDatabase | Atoms | list[Atoms], uuid: str) → int | None
atlas.core.initial_db.output_db_status(database: InitialDatabase)
atlas.core.initial_db.report_completed_step(phase: Phase, structures: InitialDatabase, added_structs: int, step_name: str = 'unknown')

Report the completion of a step in the database generation process.

Parameters:

  • phase (atl_pd.Phase) – The phase for which the step was completed.

  • structures (InitialDatabase) – The database object containing the structures.

  • added_structs (int) – The number of structures added in this step.

  • step_name (str, optional) – The name of the step that was completed, by default ‘unknown’.

atlas.core.phase_diagram module

General classes for representing phase diagrams of materials.

class atlas.core.phase_diagram.BasePhaseDiagram(material: str, element_list: list, base_elem: str, *phases: Phase)

Bases: object

Base class representing a phase diagram of materials.

Parameters:

  • material (str) – The name of the material.

  • base_elem (str) – The base element of the phase diagram.

  • *phases (Phase) – Variable number of Phase objects representing the phases in the diagram.

phases

List of Phase objects representing the phases in the diagram.

Type:

list

material

The name of the material.

Type:

str

add_phase(phase)

Add a phase to the phase diagram.

get_phase(phase) → Phase

Get a phase object from the phase diagram.

class atlas.core.phase_diagram.BinaryPhaseDiagram(material: str, element_list: list, base_elem: str, *phases: Phase)

Bases: BasePhaseDiagram

Binary phase diagram class for two elements.

plot_diagram(max_temp_K: float = 1000, min_temp_K: float = 300, rc_params=None, show_plot=True, ax=None) → Axes

Plot a basic binary phase diagram of the material with temperature and composition axes.

Parameters:

  • max_temp_K (float, optional) – The maximum temperature in Kelvin for the y-axis (default is 1000 K).

  • min_temp_K (float, optional) – The minimum temperature in Kelvin for the y-axis (default is 300 K).

  • rc_params (dict, optional) – Dictionary of matplotlib rcParams to override default plotting parameters (default is None).

Returns:

The matplotlib Axes object containing the plot.

Return type:

plt.Axes

Notes

  • The function generates a plot with the x-axis representing the composition (in at. %) of the base element in the material, and the y-axis representing the temperature in Kelvin.

  • Each phase is represented by a filled patch in the diagram, and the phases are labeled at their centroid positions.

  • The function uses the viridis colormap to assign colors to phases.

Examples

>>> diagram.plot_diagram(
>>>    max_temp_K=1200,
>>>    min_temp_K=400,
>>>    rc_params={'figure.figsize': (10, 6)}
>>> )
class atlas.core.phase_diagram.Phase(name: str, element_list: list, composition: dict, prototype: str | list, offset: float = 0, phase_diagram: PhaseDiagram = None, cluster_elem: str = None, replace_dict: dict = None, base_elem: str = None, allow_modifications: bool = True, use_cache: bool = False, spacegroup: str = None, symbol: str = None)

Bases: object

Class representing a phase in a phase diagram.

Parameters:

  • name (str) – The name of the phase.

  • base_elem – The base element of the phase.

  • prototype (str | list) – The prototype(s) for the current phase. Either a string representing an ID from the Materials Project database or a list of IDs.

  • offset (float) – The offset value of the phase.

  • phase_diagram (PhaseDiagram) – The parent PhaseDiagram object that the phase belongs to.

  • replace_dict (dict) – A dictionary of replacements for the prototype structure.

  • spacegroup (str) – The spacegroup of the phase.

  • symbol (str) – The symbol of the phase.

get_base_elem_perc(structure) → float

Get the percentage of the base element in a structure.

perc_in_phase(perc: float, offset: bool = True) → bool

Check if a given composition percentage is within the phase.

atlas.core.phase_diagram.PhaseDiagram(material: str, element_list: list, base_elem: str, *phases: Phase)

Factory method to return a BinaryPhaseDiagram or TernaryPhaseDiagram depending on the number of elements in the element_list.

Parameters:

  • material (str) – The name of the material.

  • element_list (list) – List of elements in the phase diagram.

  • base_elem (str) – Symbol of the base element.

  • *phases (Phase) – Variable number of Phase objects representing the phases in the diagram.

Return type:

BinaryPhaseDiagram | TernaryPhaseDiagram

class atlas.core.phase_diagram.SinglePhaseDiagram(material: str, element_list: list, base_elem: str, *phases: Phase)

Bases: BasePhaseDiagram

Binary phase diagram class for one element.

plot_diagram(**kwargs)
class atlas.core.phase_diagram.TernaryPhaseDiagram(material: str, element_list: list, base_elem: str, *phases: Phase)

Bases: BasePhaseDiagram

Ternary phase diagram class for three elements.

plot_diagram()

atlas.core.structure module

Module for the Structure class.

class atlas.core.structure.Bulk(**kwargs)

Bases: Structure

Class for bulk structures.

class atlas.core.structure.Cluster(**kwargs)

Bases: Structure

Class for cluster structures.

class atlas.core.structure.IsolatedAtom(**kwargs)

Bases: Structure

Class for cluster structures.

class atlas.core.structure.Structure(structure=None, material_name: str = None, material_id=None, phase=None, base: bool = None, isolated_atom: bool = False, perturb: bool = None, deformation: bool = None, supercell=None, surface: bool = False, bulk: bool = False, cluster: bool = False, formula=None, replacement: bool = False, replacement_ind=None, vacancy: bool = False, symmetry=None, energy_per_atom=None, temperature: float = None, magnetic_properties=None, calc_energy_per_atom=None, calc_energy_toten=None, calc_energy=None, calc_performed=False, calc_type=None, calc_output=None, surface_miller=None, targeted_modification: str = None, al_loop_step: int = 0, unique_id=None, init_md: bool = False)

Bases: object

Wrapper around a pymatgen structure object with extra fields for ATLForge.

Parameters:

  • structure (pymatgen.core.Structure, optional) – A pymatgen Structure object representing the atomic structure, by default None

  • material_name (str, optional) – The name of the material, by default None

  • material_id (str or int, optional) – The unique identifier for the material, by default None

  • phase (str, optional) – The phase of the material (e.g., solid, liquid, gas), by default None

  • base (bool, optional) – Flag indicating if this is a base structure, by default False

  • isolated_atom (bool, optional) – Flag indicating if this is an isolated_atom structure, by default False

  • perturb (bool, optional) – Flag indicating if the structure should be perturbed, by default False

  • supercell (tuple of int, optional) – The dimensions of the supercell, specified as a tuple of integers (e.g., (2, 2, 2)), by default None

  • surface (bool, optional) – Flag indicating if this is a surface structure, by default False

  • bulk (bool, optional) – Flag indicating if this is a bulk structure, by default False

  • cluster (bool, optional) – Flag indicating if this is a cluster structure, by default False

  • vacancy (bool, optional) – Flag indicating if the structure contains a vacancy, by default False

  • formula (str, optional) – The chemical formula of the material, by default None

  • replacement (bool, optional) – Flag indicating if an atomic replacement should be performed, by default False

  • replacement_ind (int, optional) – The index of the atom to be replaced, by default None

  • symmetry (str, optional) – The symmetry information of the structure, by default None

  • energy_per_atom (float, optional) – The energy per atom of the structure, by default None

  • temperature (float, optional) – The temperature at which the properties are calculated, by default None

  • magnetic_properties (dict, optional) – A dictionary containing magnetic properties of the structure, by default None

  • calc_energy_per_atom (float, optional) – The calculated energy per atom from a computational method, by default None

  • calc_energy_toten (float, optional) – The total energy from a computational method, by default None

  • calc_energy (float, optional) – The calculated energy of the structure, by default None

  • calc_performed (bool, optional) – Flag indicating if a calculation has been performed, by default False

  • calc_type (str, optional) – The type of calculation performed (e.g., DFT, MD), by default None

  • calc_output (dict, optional) – The output of the calculation, by default None

  • surface_miller (tuple of int, optional) – The Miller indices of the surface, specified as a tuple of integers, by default None

classmethod from_ase_atoms(ase_atoms: Atoms)

Creates a Structure object from an ASE Atoms object.

Parameters:

ase_atom (ase.Atoms) – The ASE Atoms object to convert (must have .info dictionary populated).

Returns:

The resulting Structure object.

Return type:

Structure

from_db_row(row: Series, columns: list)
from_vasprun(vasprun: Vasprun | str | Path, **kwargs)

Create a Structure object by parsing a vasprun.xml file.

The structure will contain the energy information and the structure information from the vasprun fil

Parameters:

vasprun (vasp.Vasprun | str | pl.Path) – The vasprun file containing information for a DFT calculation.

Returns:

Structure object containing the energy and structure information.

Return type:

Structure

save_to_db(db_obj)
to_ase_atoms()
to_bulk()

Create a Bulk instance by passing the current Structure attributes.

to_cluster()

Create a cluster instance by passing the current Structure attributes.

to_surface()

Create a surface instance by passing the current Structure attributes.

class atlas.core.structure.Surface(**kwargs)

Bases: Structure

Class for slab structures.

atlas.core.surfaces module

Module containing functions to generate surfaces from structures.

atlas.core.surfaces.adjust_vacuum(db_obj, slab: Slab, vacuum_size: float) → Slab
atlas.core.surfaces.apply_replacement_surface(db_obj: InitialDatabase, slabs_to_replace: list, save_in_db: bool = False, num_replacement_structs: int = 3, num_replacement_repeats: int = 2, limit_replacements: int = None)
atlas.core.surfaces.check_correct_vacuum_size(db_obj, slab: Slab | Structure, vacuum_size: float, tolerance: float = 0.5) → bool
atlas.core.surfaces.gen_perc_surfaces(phase: Phase, num_struct: int, current_perc: float, relative=True) → list

Generate num_struct percentages for a structure in a given phase. The percentages represent the ratio of the base element of the structure’s phase.

Parameters:

  • phase (Phase) – Phase that will be used to define the limits of the percentage values by checking its base_elem range.

  • num_struct (int) – Number of percentages that will be generated

  • current_perc (float) – Percentage of the current structure

  • relative (bool, optional) – Whether to return the percentages by themselves or relative to the percentage of the current structure, by default True

Returns:

List of floats containing the generated percentages.

Return type:

list[float]

atlas.core.surfaces.gen_surfaces_diff_miller_parallel(db_obj: InitialDatabase, phase: Phase, max_miller_index: int, min_miller_index: int = 2, min_slab_size: float = 6, min_vacuum_size: float = 10, get_supercells=False, num_replacements: int = 10, num_repeat_replace: int = 3, fixed_layers: int = 0, min_num_atoms: int = 12, overwrite_max_num_atoms: int = None, save_in_db=False, rng_seed: int = 42, frac_slabs_save: float = 1.0, frac_supercells_save: float = 1.0, limit_total_num_struct: int = 0, max_slab_num: int = 15, n_workers=None)
atlas.core.surfaces.get_miller_index_str(miller_source)

Generate a miller index string from several sources, either a Slab structure, a numpy array with the indices or a string. The intended use of this string is for labeling structures and helping identification.

Parameters:

miller_source (Slab | np.ndarray | str) – Information about the miller indices used to generate the string.

Returns:

Miller indices coded as a string, without including brackets. Negative signs are added in front of the symbols.

Return type:

str

atlas.core.surfaces.process_row_parallel(row, phase, phase_diagram, max_miller_index, min_miller_index, min_slab_size, min_vacuum_size, get_supercells, num_replacements, num_repeat_replace, fixed_layers, min_num_atoms, overwrite_max_num_atoms, frac_slabs_save, frac_supercells_save, limit_total_num_struct, rng_seed, max_slab_num, row_idx, temp_folder)
atlas.core.surfaces.slab_to_bottom(slab: Slab | Structure, offset: int = 2, return_atl_struct=True) → Structure

Move the slab towards the bottom of the cell, leaving a offset wide margin at the bottom.

Parameters:

  • slab (Union[Slab, Structure]) – Target slab to move to the bottom.

  • offset (int, optional) – Separation to be left between the bottom of the cell and the slab, by default 2, in Angstrom.

Returns:

Pymatgen structure containing slab placed on the bottom, with the same attributes as the original.

Return type:

Structure

atlas.core.utils module

Module containing general utilities for database creation.

class atlas.core.utils.AdsorbateAdder(cutoff=1.5, coverage=1.0)

Bases: object

Class to add adsorbates to surfaces.

is_exposed(pos, all_positions, z_pos, z_max)

Check if an atom is exposed.

atlas.core.utils.add_adsorbates(repeat: int, db_obj: InitialDatabase, filters: list, phase: Phase, adsorbate_species: list[str], limit_num_structures: int = None)
atlas.core.utils.apply_central_atom_octahedral(db_obj: InitialDatabase, filter_phase_list: list[str], filter_struct_types: list[str], central_element: str | Element, num_repeats: int, max_perturbation_ang: float, limit_num_structures: int, seed: int)
atlas.core.utils.apply_filters_db(db_obj, filters: list[str], phase: Phase | str | list = None, filter_mode: str = 'keep')

Apply filters based on database columns.

This filtering function applies several filters using an OR logic, and allows to keep or remove the filtered structures.

Parameters:

  • db_obj (InitialDatabase) – Structure database to filter

  • filters (list[str]) – Series of column names to use as filters

  • phase (atl_pd.Phase | str | list, optional) – Series of phases to use as filters, by default None

  • filter_mode (str, optional) – Either ‘keep’ or ‘remove’, by default ‘keep’

Returns:

DataFrame with/without the filtered structures.

Return type:

pd.DataFrame

atlas.core.utils.apply_gauss_perturb_db(repeat: int, db_obj: InitialDatabase, filters: list, phase: Phase, center: float = 0.04, limit_num_structures: int = None)
atlas.core.utils.apply_replacement(structure: Structure, phase, n_target_at: int | float, phase_diagram: PhaseDiagram, rng=None)
atlas.core.utils.apply_replacement_no_db(structure: Structure, phase, n_atoms: int, replace_elem: str | Element, rng=None)
atlas.core.utils.check_incorrect_ratios(df, curr_phase_diag)
atlas.core.utils.clear_previous_print()
atlas.core.utils.create_symmetrical_prototype(structure: Structure, phase_diagram: PhaseDiagram, phase: Phase, structure_obj: Structure)
atlas.core.utils.display_dataframe_ase(dataframe)

Display the structures in the given dataframe using the ase gui.

Wrapper function for _display_indb_dataframe.

atlas.core.utils.display_struct_list_ase(struct_list)

Display the structures in a list using the ase gui.

Wrapper function for _display_indb_dataframe.

atlas.core.utils.find_supercell_indices(structure, get_different_supercells, min_atoms, max_atoms, initial_supercell_size=5, verbose=True)
atlas.core.utils.fit_replacements_phase(phase, structure, subst_base_elem_perc)
atlas.core.utils.fix_bottom_layers(structure: Structure, n_layers: int) → Structure

Fixes the bottom n layers of a pymatgen Structure by setting the selective dynamics to False for the atoms in those layers.

Parameters:

  • structure (pymatgen.core.Structure) – The structure to modify.

  • n_layers (int) – The number of bottom layers to fix.

Returns:

A new Structure object with selective dynamics updated.

Return type:

Structure

atlas.core.utils.gather_secrets()

Gather Materials project API key from file/env var.

The API key can be gathered from a secrets.json file that can be placed in the config directory or in the current working directory. If the file is not found, the function will check for an environment variable named ‘MP_API_KEY’.

Notes

The json file should have the following structure:

>>> {
>>>     "API_KEY": "XXXXXX"
>>> }
Returns:

object containing the api key

Return type:

dict

atlas.core.utils.gauss_perturb(structure: Structure, center: float = 0.04)
atlas.core.utils.gen_base_elem_perc(phase, num_struct)
atlas.core.utils.limit_num_structures_phase(db_obj: InitialDatabase, phase: Phase, num_limit: int, rng_seed: int, stratify_by_size: bool = False)
atlas.core.utils.similarity_check_list(db_obj, replaced_structures, r_cut=None, n_max=None, l_max=None, save_in_db=True)

Module contents

Main module for the core package of atlas. This includes structures, initial database creation, and other core functionalities.