mlff_attack.attacks module

This module provides high-level convenience functions for performing adversarial attacks on MLFF models, including attack execution, perturbation saving/loading, and visualization.

Contains implementation for FGSM, I-FGSM, and PGD attacks on MLFF models.

mlff_attack.attacks.load_perturbation(load_path)[source]

Load perturbation data from a saved file.

Parameters:

load_path (str or Path) – Path to the saved .npz file

Returns:

Dictionary containing all saved perturbation data with keys:

  • atoms_originalase.Atoms

    Reconstructed original ASE Atoms object

  • atoms_perturbedase.Atoms

    Reconstructed perturbed ASE Atoms object

  • displacementnp.ndarray

    Position displacement array

  • epsilonfloat

    Perturbation step size

  • energy_originalfloat

    Original energy

  • energy_perturbedfloat

    Perturbed energy

  • energy_changefloat

    Energy change

  • gradientsnp.ndarray

    Gradient array

  • timestampstr

    Save timestamp

  • metadatadict

    Dictionary of any additional metadata

Return type:

dict

mlff_attack.attacks.make_attack(model_path, device, atoms, epsilon, target_energy, output_cif, attack_type='fgsm', n_steps=1, clip=False)[source]

Perform an adversarial attack on the given atomic structure using a MACE model.

This is a convenience wrapper around the FGSM_MACE class.

Parameters:

  • model_path (str or Path) – Path to the MACE model file

  • device (str) – Device to run the model on (“cpu” or “cuda”)

  • atoms (ase.Atoms) – ASE Atoms object representing the structure to attack

  • epsilon (float) – Perturbation step size in Angstroms

  • target_energy (float or None) – Target energy for the attack (if None, maximize energy)

  • output_cif (str or Path) – Path to save the perturbed CIF file

  • attack_type (str, optional) – Type of attack to perform, by default “fgsm”

  • n_steps (int, optional) – Number of steps for iterative attacks (only used for I-FGSM/PGD), by default 1

  • clip (bool, optional) – Whether to clip the perturbations, by default False

Returns:

  • str – Path to the saved perturbed CIF file

  • ase.Atoms – Atoms object after attack

  • attack.attack_history (dict) – Contains details and history of the attack

mlff_attack.attacks.save_perturbation(atoms_original, atoms_perturbed, epsilon, energy_original, energy_perturbed, gradients, save_path, metadata=None)[source]

Save perturbation data to a file for later analysis.

Parameters:

  • atoms_original (ase.Atoms) – Original ASE Atoms object

  • atoms_perturbed (ase.Atoms) – Perturbed ASE Atoms object

  • epsilon (float) – Step size used for perturbation

  • energy_original (float) – Original energy (eV)

  • energy_perturbed (float) – Perturbed energy (eV)

  • gradients (torch.Tensor or np.ndarray) – Gradients used for perturbation

  • save_path (str or Path) – Path to save the data (will save as .npz file)

  • metadata (dict, optional) – Optional dictionary with additional metadata, by default None

Returns:

Path to the saved file

Return type:

Path

mlff_attack.attacks.visualize_perturbation(atoms_before, atoms_after, epsilon=0.01, outdir=None)[source]

Visualize the difference between original and perturbed atomic structures.

Parameters:

  • atoms_before (ase.Atoms) – Original ASE Atoms object

  • atoms_after (ase.Atoms) – Perturbed ASE Atoms object

  • epsilon (float, optional) – Perturbation magnitude used, by default 0.01

  • outdir (str or Path, optional) – Optional output directory to save plots, by default None

Returns:

Matplotlib figure object

Return type:

matplotlib.figure.Figure