atlas.core package

Subpackages

Submodules

atlas.core.clusters module

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

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

atlas.core.surfaces module

atlas.core.utils module

Module contents

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