min_shuffle module

class src.min_shuffle.min_shuffle(lattice_parameter, sigma, misorientation, inclination, period, folder, elem, reg_param, max_iters, box_expansion_factor=0, dimension=3)

Bases: object

Class to perform minimal atomic shuffling analysis between two grain boundary configurations using optimal transport (Sinkhorn algorithm).

This class reads initial and final atomic configurations from LAMMPS data files, identifies a region around a grain boundary and a disconnection, formats the data, applies periodic boundary conditions, replicates the simulation box if necessary, and runs the Sinkhorn optimal transport to find minimal atomic displacement mappings.

__init__(lattice_parameter, sigma, misorientation, inclination, period, folder, elem, reg_param, max_iters, box_expansion_factor=0, dimension=3)

Initializes the min_shuffle object with simulation parameters and placeholders for atomic data.

Parameters:

• lattice_parameter (float) – The lattice parameter of the crystal structure (in angstroms).

• sigma (float) – Sigma value related to the grain boundary type or misorientation.

• misorientation (float) – The misorientation angle between grains (in degrees).

• inclination (float) – The inclination angle of the grain boundary (in degrees).

• period (int) – The period or repeat length of the grain boundary.

• folder (str) – Directory path where output files and data will be stored.

• elem (str) – Chemical element symbol of the material (e.g., ‘Al’, ‘Cu’).

• reg_param (float) – Regularization parameter used in the Sinkhorn optimal transport algorithm.

• max_iters (int) – Maximum number of iterations allowed in the Sinkhorn solver.

• box_expansion_factor (float, optional) – Factor to expand the simulation box dimensions, defaults to 0 (no expansion).

• dimension (int, optional) – Dimensionality of the simulation system, defaults to 3 (3D).

grainA_pretransform

Atomic positions of grain A before transformation.

Type:

np.ndarray or None

grainB_pretransform

Atomic positions of grain B before transformation.

Type:

np.ndarray or None

grainA_posttransform

Atomic positions of grain A after transformation.

Type:

np.ndarray or None

grainB_posttransform

Atomic positions of grain B after transformation.

Type:

np.ndarray or None

initial_grain

Complete initial atomic configuration.

Type:

np.ndarray or None

final_grain

Complete final atomic configuration.

Type:

np.ndarray or None

box

Simulation box dimensions.

Type:

np.ndarray or None

gb_location

Grain boundary location coordinate.

Type:

float or None

step_height

Step height parameter defining the shuffle domain.

Type:

float or None

dislocation_start

Start coordinate of the dislocation region.

Type:

float or None

dislocation_end

End coordinate of the dislocation region.

Type:

float or None

atoms_minshuf

Atomic coordinates involved in minimal shuffle.

Type:

np.ndarray or None

types_minshuf

Number of atom types in minimal shuffle domain.

Type:

int or None

box_minshuf

Simulation box dimensions for minimal shuffle domain.

Type:

np.ndarray or None

initial_atoms_transformed_region

Initial atom coordinates of the transformed region.

Type:

np.ndarray or None

final_atoms_transformed_region

Final atom coordinates of the transformed region.

Type:

np.ndarray or None

format_input(folder)

Formats the input by selecting atoms in the minimal shuffle domain and writes data files.

Parameters:

folder (str) – Directory to write formatted data files.

Raises:

ValueError – If grain boundary info or atomic data is missing.

Sets:

self.atoms_minshuf (np.ndarray): Formatted atoms array for minimal shuffling. self.types_minshuf (int): Number of atom types. self.box_minshuf (np.ndarray): Simulation box for the minimal shuffle domain.

gb_info(filepath, st_height, disloc1, disloc2, min_shuffle_domain_expansion_factor=1.5, disconnection_extension=5)

Computes grain boundary location, step height, and dislocation region based on input parameters.

Parameters:

• filepath (str) – Path to the file to extract grain boundary info.

• st_height (float) – Step height direction and magnitude.

• disloc1 (tuple) – Coordinates of the start of the dislocation.

• disloc2 (tuple) – Coordinates of the end of the dislocation.

• min_shuffle_domain_expansion_factor (float, optional) – Expansion factor of minimal shuffle domain. Defaults to 1.5.

• disconnection_extension (int, optional) – Extension length for dislocation region. Defaults to 5.

Sets:

self.gb_location (float): Calculated grain boundary location. self.step_height (float): Adjusted step height of the shuffle domain. self.dislocation_start (float): Start coordinate of the dislocation region. self.dislocation_end (float): End coordinate of the dislocation region.

load_data(file_mode, file_flat, file_disconnection)

Loads atomic positions from initial and final LAMMPS data files.

Parameters:

• file_mode (str) – Mode for reading the LAMMPS data files.

• file_flat (str) – Path to the initial (flat) atomic configuration file.

• file_disconnection (str) – Path to the final atomic configuration file.

Sets:

self.grainA_pretransform (np.ndarray): Atoms in grain A before transformation. self.grainB_pretransform (np.ndarray): Atoms in grain B before transformation. self.grainA_posttransform (np.ndarray): Atoms in grain A after transformation. self.grainB_posttransform (np.ndarray): Atoms in grain B after transformation. self.box (np.ndarray): Simulation box. self.initial_grain (np.ndarray): Initial atomic data. self.final_grain (np.ndarray): Final atomic data.

pbcdist(dp, Lx, Ly, Lz)

Applies periodic boundary conditions to displacement vectors.

Parameters:

• dp (np.ndarray) – Displacement vectors.

• Lx (float) – Box length along x-axis.

• Ly (float) – Box length along y-axis.

• Lz (float) – Box length along z-axis.

Returns:

Adjusted displacement vectors considering periodic boundaries.

Return type:

np.ndarray

pbcwrap(d, box)

Wraps coordinates into the primary simulation box applying periodic boundary conditions.

Parameters:

• d (np.ndarray) – Coordinates to wrap.

• box (np.ndarray) – Simulation box dimensions.

Returns:

Coordinates wrapped within the simulation box.

Return type:

np.ndarray

static plot_min_shuffle_2d(folder, Xbasis, Ybasis, Gamma, sigma, reg_param)

Generates and saves a 2D plot of optimal transport mapping between source and target atomic configurations.

Parameters:

• folder (str) – Directory path to save the plot image.

• Xbasis (np.ndarray) – Source sample coordinates, shape (N, 2).

• Ybasis (np.ndarray) – Target sample coordinates, shape (N, 2).

• Gamma (np.ndarray) – Transport plan matrix.

• sigma (float) – Grain boundary sigma value for plot labeling.

• reg_param (float) – Regularization parameter for plot labeling.

Side Effects:

Saves the generated plot as a PNG file in the specified folder.

static plot_min_shuffle_3d(Xs, Ys, box, sigma, reg_param)

Creates a 3D scatter plot comparing initial and final atomic configurations within a simulation box.

Parameters:

• Xs (np.ndarray) – Coordinates of initial atomic positions, shape (N, 3).

• Ys (np.ndarray) – Coordinates of final atomic positions, shape (N, 3).

• box (np.ndarray) – Simulation box boundaries, shape (3, 2) with [[xlo, xhi], [ylo, yhi], [zlo, zhi]].

• sigma (float) – Grain boundary sigma value used for labeling.

• reg_param (float) – Regularization parameter used for labeling.

Returns:

Returns 1 upon completion (placeholder return value).

Return type:

int

replicate(rep_scheme, X, Y, box)

Replicates atomic configurations according to the specified replication scheme.

Parameters:

• rep_scheme (list) – List of 6 integers defining replication multipliers [xlo, xhi, ylo, yhi, zlo, zhi].

• X (np.ndarray) – Initial atomic coordinates.

• Y (np.ndarray) – Final atomic coordinates.

• box (np.ndarray) – Simulation box dimensions.

Returns:

(X_rep, Y_rep, rep_box)

X_rep (np.ndarray): Replicated initial coordinates. Y_rep (np.ndarray): Replicated final coordinates. rep_box (np.ndarray): Updated simulation box after replication.

Return type:

tuple

run()

Runs the Sinkhorn optimal transport algorithm to compute minimal shuffling displacement vectors between initial and final atomic configurations in the minimal shuffle domain.

Raises:

ValueError – If input formatting is not done or atoms mismatch.

Sets:

self.initial_atoms_transformed_region (np.ndarray): Initial atomic positions after transformation. self.final_atoms_transformed_region (np.ndarray): Final atomic positions after transformation.

write_images(folder, image_num)

Writes LAMMPS data files for atomic configurations at specified image numbers.

Parameters:

• folder (str) – Directory to save output files.

• image_num (int) – Image index (e.g., 0 for initial flat GB, 1 for final transformed state).