atlas.benchmarks.mlip package

MLIP benchmark utilities for evaluating model performance.

Submodules

atlas.benchmarks.mlip.mlip_benchmark_utils module

General utilities for the MLIP benchmark suite in ATLForge.

class atlas.benchmarks.mlip.mlip_benchmark_utils.FoundationModelPath(foundation_model_spec)

Bases: object

A class to represent foundation models in a way compatible with file-based models.

This allows foundation models to be used alongside file-based models in the benchmark system.

class atlas.benchmarks.mlip.mlip_benchmark_utils.RichUIManager(benchmarks_to_run)

Bases: object

Manages the Rich CLI interface for the benchmark suite.

complete_benchmark(benchmark_name)

Mark a benchmark as completed.

create_layout()

Create the main layout structure.

create_log_panel()

Create the log display panel.

create_progress_panel()

Create the progress bar panel.

create_sidebar_panel()

Create the sidebar showing benchmark status.

log(message)

Add a log message.

start_benchmark(benchmark_name)

Mark a benchmark as started.

update_display()

Update the entire display.

atlas.benchmarks.mlip.mlip_benchmark_utils.adjust_color_brightness(hex_color, brightness_factor)

Adjust the brightness of a hex color.

Parameters:

• hex_color (str) – Hex color string (e.g., ‘#fe8019’)

• brightness_factor (float) – Factor to adjust brightness > 1.0 = brighter < 1.0 = darker 1.0 = no change

Returns:

Adjusted hex color string

Return type:

str

atlas.benchmarks.mlip.mlip_benchmark_utils.clear_model_data()

Clear the global model data dictionary.

atlas.benchmarks.mlip.mlip_benchmark_utils.clear_plot_data()

Clear the global plot data dictionary.

atlas.benchmarks.mlip.mlip_benchmark_utils.create_args_from_toml(toml_dict: dict) → Namespace

Create an argparse.Namespace object from TOML configuration.

Parameters:

toml_dict (dict) – Dictionary loaded from TOML file

Returns:

Arguments namespace populated with values from TOML

Return type:

Namespace

atlas.benchmarks.mlip.mlip_benchmark_utils.create_calculator_for_model(model_path, device='cuda', dtype='float64', **kwargs)

Create a calculator for either a file-based model or foundation model.

Parameters:

• model_path (Path or FoundationModelPath) – Path to model file or foundation model specification

• device (str, optional) – Device to run calculations on (default: ‘cuda’)

• dtype (str, optional) – Data type for calculations (default: ‘float64’)

• **kwargs – Additional arguments to pass to the calculator

Returns:

Calculator instance for the model

Return type:

calculator

atlas.benchmarks.mlip.mlip_benchmark_utils.create_final_multi_panel_plot(args)

Creates a single multi-panel figure with all benchmark plots.

atlas.benchmarks.mlip.mlip_benchmark_utils.create_foundation_model_calculator(foundation_model_spec, device='cuda', dtype='float64', **kwargs)

Create a calculator for a foundation model.

Parameters:

• foundation_model_spec (str) – Foundation model specification (e.g., “mace:small”)

• device (str, optional) – Device to run calculations on (default: ‘cuda’)

• dtype (str, optional) – Data type for calculations (default: ‘float64’)

Returns:

Calculator instance for the foundation model

Return type:

calculator

Raises:

• ValueError – If foundation model specification is invalid

• NotImplementedError – If the specified MLIP library is not supported

atlas.benchmarks.mlip.mlip_benchmark_utils.create_foundation_model_paths(foundation_model_specs)

Create FoundationModelPath objects from foundation model specifications.

Parameters:

foundation_model_specs (list of str) – List of foundation model specifications

Returns:

Foundation model path objects

Return type:

list of FoundationModelPath

Raises:

ValueError – If any foundation model specification is invalid

atlas.benchmarks.mlip.mlip_benchmark_utils.custom_print(message, level='info')

Custom print function that integrates with Rich UI and logs to file.

atlas.benchmarks.mlip.mlip_benchmark_utils.get_model_color(model_path)

Get the assigned color for a model.

Parameters:

model_path (Path or FoundationModelPath) – Model path or model object

Returns:

Hex color string assigned to this model

Return type:

str

atlas.benchmarks.mlip.mlip_benchmark_utils.get_model_colors_by_names(model_names)

Get colors for a list of model names in the order they appear.

Parameters:

model_names (list) – List of model display names

Returns:

List of hex color strings corresponding to the model names

Return type:

list

atlas.benchmarks.mlip.mlip_benchmark_utils.get_model_data()

Get the global model data dictionary.

atlas.benchmarks.mlip.mlip_benchmark_utils.get_model_display_name(model_path: Path) → str

Get the display name for a model.

Returns run name if available, otherwise filename stem.

atlas.benchmarks.mlip.mlip_benchmark_utils.get_model_display_names()

Get the global model display names dictionary.

atlas.benchmarks.mlip.mlip_benchmark_utils.get_plot_data()

Get the global plot data dictionary.

atlas.benchmarks.mlip.mlip_benchmark_utils.get_ui_manager()

Get the global UI manager instance.

atlas.benchmarks.mlip.mlip_benchmark_utils.initialize_model_data(model_paths)

Initialize the global model data dictionary with consistent color assignments.

Parameters:

model_paths (list) – List of model paths (can include FoundationModelPath objects)

atlas.benchmarks.mlip.mlip_benchmark_utils.load_model_from_aiida(identifier: int, output_dir: Path)

Load a model from an ATL AL Workchain.

atlas.benchmarks.mlip.mlip_benchmark_utils.load_toml_config(toml_path: Path) → dict

Load TOML configuration file.

Parameters:

toml_path (Path) – Path to the TOML configuration file

Returns:

Parsed TOML configuration

Return type:

dict

atlas.benchmarks.mlip.mlip_benchmark_utils.parse_arguments()

Parse command-line arguments.

atlas.benchmarks.mlip.mlip_benchmark_utils.save_plot_dual_format(base_path, dpi=300, bbox_inches='tight')

Save a matplotlib plot in both PNG and SVG formats.

Parameters:

• base_path (str or Path) – Path without extension (e.g., ‘plot’)

• dpi (int, optional) – DPI for PNG output (default: 300)

• bbox_inches (str, optional) – Bounding box setting for tight layout (default: ‘tight’)

Returns:

(png_path, svg_path) - Paths to the saved files

Return type:

tuple

atlas.benchmarks.mlip.mlip_benchmark_utils.set_model_display_name(path, name)

Set a model display name.

atlas.benchmarks.mlip.mlip_benchmark_utils.set_plot_data(key, value)

Set a value in the global plot data dictionary.

atlas.benchmarks.mlip.mlip_benchmark_utils.set_ui_manager(ui_manager)

Set the global UI manager instance.

atlas.benchmarks.mlip.mlip_benchmarks module

Collection of ATL-trained benchmarks for MLIPs.

atlas.benchmarks.mlip.mlip_benchmarks.coexistence_structure_melting_point(metal: str, benchmark_dir: Path, calculator, config_dict: dict) → Path

Prepare a solid-liquid coexistence structure using proper equilibration.

This function implements the multi-step preparation process: 1. Equilibrate solid phase at T < T_melt using NPT 2. Take the equilibrated cell, and heat at T > T_melt with NPAT to get liquid 3. Combine solid and liquid phases into coexistence structure, run short NPAT 4. Relax interfaces using NVE

Returns path to the final coexistence structure.

atlas.benchmarks.mlip.mlip_benchmarks.gen_magic_number_list_chini(n_max: int = 25) → list[float]

Return a list of magic numbers using the Chini series.

Ref: 10.1134/S0022476617070149

atlas.benchmarks.mlip.mlip_benchmarks.prepare_coexistence_structure_lammps(metal: str, supercell_size: list[int], benchmark_dir: Path, mace_model_path: Path, solid_temp_K: float, liquid_temp_K: float) → Path

Prepare a solid-liquid coexistence structure using LAMMPS for dynamics.

This function implements the multi-step preparation process: 1. Equilibrate solid phase at T < T_melt using NPT. 2. Melt a copy of the solid at T > T_melt. 3. Cool the liquid down to the solid temperature. 4. Combine solid and liquid phases into a coexistence structure. 5. Relax the interface using NVE dynamics.

Return type:

Path to the final coexistence structure.

atlas.benchmarks.mlip.mlip_benchmarks.run_defect_formation_energy_benchmark(args, model_paths: list[Path])

Calculates and plots the monovacancy formation energy.

atlas.benchmarks.mlip.mlip_benchmarks.run_elastic_properties_benchmark(args, model_paths: list[Path])

Calculates and plots elastic constants and bulk modulus.

atlas.benchmarks.mlip.mlip_benchmarks.run_energy_md_benchmark(args, model_paths: list[Path])

Run the energy MD benchmark.

Generates a surface slab, runs MD for each model, and plots the results.

atlas.benchmarks.mlip.mlip_benchmarks.run_evaluate_database(args, model_paths: list[Path])

Evaluate MLIP models against a user-provided structure database.

This benchmark loads structures from a database file and compares MLIP predictions with reference values stored in the structures. Reference energies should be in atoms.info[‘REF_energy’] and reference forces in atoms.arrays[‘REF_forces’].

atlas.benchmarks.mlip.mlip_benchmarks.run_final_db_size_benchmark(args, model_paths: list[Path])

Compares the final training database size for each AL run.

atlas.benchmarks.mlip.mlip_benchmarks.run_gsfe_benchmark(args, model_paths: list[Path])

Calculates and plots the Generalized Stacking Fault Energy (GSFE) curve.

atlas.benchmarks.mlip.mlip_benchmarks.run_high_temp_md_benchmark(args, model_paths: list[Path])

Runs a high-temperature MD simulation to test stability.

atlas.benchmarks.mlip.mlip_benchmarks.run_learning_curves_benchmark(args, model_paths: list[Path])

Plots learning curves (e.g., test RMSE vs. number of DFT calls).

atlas.benchmarks.mlip.mlip_benchmarks.run_magic_cluster_benchmark(args, model_paths: list[Path])

Calculates and plots energies for magic number cluster structures.

Magic number clusters are particularly stable cluster sizes that often correspond to closed-shell electronic configurations or geometric completeness (e.g., icosahedral or cuboctahedral structures).

This benchmark validates whether MLIPs can reproduce the correct ordering and stability of these special cluster sizes.

atlas.benchmarks.mlip.mlip_benchmarks.run_md_count_benchmark(args, model_paths: list[Path])

Count total MD calculations performed during Active Learning loops.

atlas.benchmarks.mlip.mlip_benchmarks.run_melting_point_benchmark(args, model_paths: list[Path])

atlas.benchmarks.mlip.mlip_benchmarks.run_phonon_dispersion_benchmark(args, model_paths: list[Path])

Calculates and plots the phonon dispersion curves.

atlas.benchmarks.mlip.mlip_benchmarks.run_surface_energies_benchmark(args, model_paths: list[Path])

Calculates and plots energies for low-index surfaces.

The surface energy represents the excess energy per unit area due to the creation of a surface. Lower values indicate more stable surfaces.

This benchmark validates whether the explored MLIPs reproduce the correct energetic ordering and magnitudes of surface energies compared to DFT or experimental values.

atlas.benchmarks.mlip.evaluate_mlip_performance module

Script to evaluate and compare the performance of MLIPs using MD simulations.

This script can take one or more MLIP models, trained via active learning or otherwise, and evaluates their performance on a configurable benchmark system. The benchmark system is a metal surface slab generated using ASE.

The script can load models from: - AiiDA SimpleActiveLearningBaseWorkChain output (given a workchain pk/uuid). - A user-specified path to a .model file.

The evaluation consists of running an MD simulation for each model and plotting the energy evolution for comparison.

atlas.benchmarks.mlip.evaluate_mlip_performance.main()

Main function to run the evaluation.

Module contents