bicrystal module

class src.bicrystal.bicrystal(gb_data, axis, lat_par, lat_Vec, size_along_period=1, size_along_tilt_axis=1, non_periodic_direction_size=50)[source]

Bases: object

Represents a bicrystal

__init__(gb_data, axis, lat_par, lat_Vec, size_along_period=1, size_along_tilt_axis=1, non_periodic_direction_size=50)[source]

Initializes a bicrystal configuration based on grain boundary crystallography.

Parameters:

  • gb_data (np.ndarray) – Grain boundary bicrystallographic data, typically the output from a bicrystallography class.

  • axis (np.ndarray) – Tilt axis of the bicrystal.

  • lat_par (float) – Lattice parameter of the material.

  • lat_Vec (np.ndarray) – Lattice vectors of the material.

  • size_along_period (int, optional) – Number of CSL repeats along the GB period. Defaults to 1.

  • size_along_tilt_axis (int, optional) – Number of CSL repeats along the tilt axis. Defaults to 1.

  • non_periodic_direction_size (float, optional) – Size of the bicrystal normal to the GB plane, in angstroms. Defaults to 50.

gb_data

Grain boundary data input.

Type:

np.ndarray

axis

Tilt axis.

Type:

np.ndarray

lat_par

Lattice parameter.

Type:

float

lat_Vec

Lattice vectors.

Type:

np.ndarray

size_along_period

Size along GB period (CSL multiples).

Type:

int

size_along_tilt_axis

Size along tilt axis (CSL multiples).

Type:

int

non_periodic_direction_size

Size normal to the GB plane in angstroms.

Type:

float

nCells

Number of unit cells in the bicrystal. Computed as size_factor * size_along_period, where size_factor is 40 if size_along_period == 1, else 25.

Type:

int

grain1_orientation

Orientation matrix or parameters for grain 1 (initialized as None).

Type:

Any

grain2_orientation

Orientation matrix or parameters for grain 2 (initialized as None).

Type:

Any

grain1_flatgb

Flat grain boundary structure for grain 1 (initialized as None).

Type:

Any

grain2_flatgb

Flat grain boundary structure for grain 2 (initialized as None).

Type:

Any

grain1

Final structure of grain 1 (initialized as None).

Type:

Any

grain2

Final structure of grain 2 (initialized as None).

Type:

Any

box

Simulation or bounding box information (initialized as None).

Type:

Any

create_disconnection_containing_bicrystal(nodes, burgers_vector, step_height, gb_position, image_number, nImages=2, number_of_dipoles=3)[source]

Generates a grain boundary (GB) image with a disconnection dipole and possible steps based on the bicrystallographic configuration.

This method:

  • Determines regions affected by the dislocation dipole.

  • Applies displacement fields to atoms based on the dipole configuration and Burgers vector.

  • Combines atoms from transformed and non-transformed regions to form a new GB image.

Parameters:

  • image_number (int) – Identifier for the GB image being generated, used to determine whether dipole transitions are included.

  • gb_position (float) – X-coordinate of the GB plane, defining the boundary between grains.

  • nodes (np.ndarray) – 2x2 array of disconnection node coordinates in the GB plane.

  • step_height (float) – Height of the step at the GB (positive or negative), used to determine which grain is displaced.

  • burgers_vector (np.ndarray) – Displacement vector representing the dislocation.

  • number_of_dipoles (int) – Number of dipoles introduced in the bicrystal.

Sets:

grain1 (np.ndarray): Atom positions for grain 1, including plastic displacement and unique IDs. grain2 (np.ndarray): Atom positions for grain 2, similarly displaced and labeled.

Raises:

ValueError – If the flat GB structure has not been created via create_flat_gb_bicrystal.

Notes

  • Atoms in the transformed region are displaced based on the disconnection geometry.

  • Overlapping atoms are checked using Euclidean distance and matched to maintain continuity.

  • Diagnostics are written to file if mismatch occurs between atom counts in transformed regions.

Diagnostic Output:

If atom mismatches are detected in the transformed region, a diagnostic file is written to: /Users/hj-home/Desktop/Research/GB_kinetics_oop/output/grain_diagnostics.txt

create_fix_eco_orientationfile(folder)[source]

Writes the grain orientations to a .ori file compatible with the fix_eco command in LAMMPS, saving it to the specified folder.

The file contains the lattice orientations of both grains, scaled by the lattice parameter, and is named based on the grain boundary properties.

Parameters:

folder (str) – Directory path where the orientation file will be saved. The folder path should end with a slash (‘/’).

Raises:

ValueError – If the bicrystal has not been fully set up (i.e., orientations are None). You must run _setup_bicrystal before calling this method.

Outputs:

Creates a file named Sigma{sigma}_mis{mis}_inc{inc}.ori in the given folder, where sigma, mis (misorientation), and inc (inclination) are from gb_data. The file contains the orientation matrices for the two grains, row-wise.

Prints:

Confirmation message indicating the successful creation of the orientation file.

create_flat_gb_bicrystal(gb_position)[source]

Generates the initial flat grain boundary (GB) structure by constructing a dichromatic pattern from the two grain orientations and selecting atoms to form a bicrystal.

This function:

  • Constructs a 3D dichromatic pattern for both grains using lattice translations.

  • Selects atoms for each grain based on their position relative to the GB plane.

Parameters:

gb_position (float) – The X-coordinate (along GB normal) at which the GB plane is located.

Sets:

grain1_flatgb (np.ndarray): Filtered atomic positions for grain 1, including unique atom IDs. grain2_flatgb (np.ndarray): Filtered atomic positions for grain 2, including unique atom IDs. box (np.ndarray): Dimensions of the simulation box used for filtering and placement.

Notes

  • The structure is built from -nCells to +nCells in lattice units in all three dimensions.

ordered_write(folder, elem, image_num, xpos, h=0, start=0, stop=0, mode=2)[source]

Write a LAMMPS data file of the bicrystal atomic configuration including dislocation or disconnection region labeling.

Parameters:

  • folder (str) – Directory path to save the output file.

  • elem (str) – Element symbol or identifier used in filename.

  • h (int) – Flag indicating which grain configuration to use: 0 for flat grain boundary, else dislocated configuration.

  • image_num (int) – Identifier for the image number in the filename.

  • xpos (float) – Position value used for grain classification.

  • start (float) – Lower bound along y-axis for dislocation region.

  • stop (float) – Upper bound along y-axis for dislocation region.

  • mode (int, optional) – Index to select box dimension (default 2).

Returns:

The filename of the written data file.

Return type:

str

Outputs:

Writes a LAMMPS data file named like ‘data.{elem}s{sigma}inc{inc}_size{size}disc{image_num}’.

write(folder, elem, suffix, mode=2)[source]

Writes the bicrystal atomic configuration to a LAMMPS data file.

The output file contains atom positions for both grains along with box dimensions and metadata required for LAMMPS simulations.

Parameters:

  • folder (str) – Directory path where the data file will be saved. Should end with a ‘/’ or use os.path.join for safety.

  • elem (str) – Element symbol or identifier for naming the output file.

  • suffix (str) – Suffix string appended to the output filename.

  • mode (int, optional) – Index selecting the dimension for box size from self.box (default is 2).

Returns:

The filename of the written data file.

Return type:

str

Raises:

AttributeError – If bicrystal data (e.g., grain arrays or box) is not set.

Outputs:

Creates a LAMMPS data file named as: data.{elem}s{sigma}inc{inc}_{suffix}, containing atomic coordinates and simulation box details.

Prints:

Confirmation message after successful file write.