Project Workflow and Algorithms

essential_files Directory Structure

essential_files/
|-- bin/
| |-- atomsk.exe
| |-- lmp.exe
|-- inputs/
| |-- al-cu-set.eam.alloy
| |-- in.tensile
|-- log.lammps
|-- outputs/
| |-- voronoi_ovito.data
| |-- voronoi_ovito.lmp
| |-- dump.tensile.lammpstrj
|-- scripts/
| |-- generate_project_report.py
| |-- generate_ovito_voronoi.py
| |-- plot_stress_strain.py
| |-- xyz_to_lammps_data.py
|-- stress_strain_curve.png

Project Workflow and Algorithms

A detailed report of the simulation workflow, algorithms, and data flow.

Page 1
 1. Algorithm: generate_ovito_voronoi.py

Purpose
To generate a synthetic 3D polycrystalline structure with grains and alternating lamellae,
and output it in a format compatible with OVITO (LAMMPS dump).
Step-by-Step Algorithm
1. Import Required Libraries
numpy for numerical operations.
scipy.spatial.Voronoi (not directly used, but could be for real Voronoi tessellation).
random for random number generation.
2. Define Helper Function: rotate_point_around_z
Input: 3D point, rotation angle in degrees.
Process:
Converts angle to radians.
Constructs a 3x3 rotation matrix for rotation about the Z-axis.
Multiplies the point by the rotation matrix.
Output: Rotated 3D point.
3. Define Main Function: generate_voronoi_for_ovito
Inputs:
num_grains: Number of grains to generate.
box_size: Size of the cubic simulation box.
total_atoms: Total number of atoms to generate.
Process:
1. Generate Grain Centers: Randomly place num_grains centers in the box.
2. Assign Grain Orientations: Assign each grain a random orientation (0–180°).
3. Generate Atom Positions: Randomly place total_atoms in the box.
4. For Each Atom:
Find the closest grain center (assign atom to that grain).
Get the orientation and center of the assigned grain.
Compute the atom's position relative to its grain center.
Rotate this relative position by the negative of the grain's orientation (to bring it into the
grain's local frame).
Lamella Assignment:
Divide the rotated x-coordinate by a lamella thickness to determine which lamella the atom
belongs to.
Alternate lamella type (1 or 2) based on even/odd index.
Store atom data: id, type, x, y, z, grain_id, orientation, lamella_id.
Output: List of atom data dictionaries.
4. Define Output Function: write_ovito_file
Inputs:
atoms_data: List of atom dictionaries.
output_file: Path to output file.
box_size: Simulation box size.
Process:
Open the output file for writing.
Write LAMMPS dump header (timestep, number of atoms, box bounds, column headers).
For each atom, write its properties in the required format.
5. Main Script Execution
Set Parameters:
box_size_val = 100.0
num_grains = 10
total_atoms = 50000
Call generate_voronoi_for_ovito to generate atom data.
Call write_ovito_file to write the data to outputs/voronoi_ovito.lmp.
Print Summary: Output file location, number of atoms, number of grains, and lamella info.
Inputs and Outputs
Inputs: None required from user (parameters are set in the script).
Outputs: outputs/voronoi_ovito.lmp (OVITO/LAMMPS-compatible dump file with
columns: id, type, x, y, z, grain_id, orientation, lamella_id).
Data Flow
1. Random grain centers and orientations →
2. Random atom positions →
3. Assign each atom to a grain and lamella →
4. Write all atom data to a LAMMPS dump file.
What the Output File Contains
id: Atom ID (unique integer)
type: Lamella type (1 or 2)
x, y, z: Atom coordinates
grain_id: Which grain the atom belongs to
orientation: Orientation of the grain (degrees)
lamella_id: Which lamella within the grain

Summary Table

Step Function/Section Purpose/Action

1 Imports Load required libraries

2 rotate_point_around_z Rotate a point in 3D about the Z-axis
Generate grains, assign atoms, assign
3 generate_voronoi_for_ovito lamellae
Write atom data to OVITO/LAMMPS dump
4 write_ovito_file file
 5 Main script Set parameters, call functions, print summary

Pseudocode

BEGIN

IMPORT numpy, scipy.spatial.Voronoi, random

DEFINE FUNCTION rotate_point_around_z(point, angle_degrees):

angle_radians = convert angle_degrees to radians
rotation_matrix = 3x3 matrix for Z-axis rotation
RETURN rotation_matrix * point

DEFINE FUNCTION generate_voronoi_for_ovito(num_grains, box_size, total_atoms):

grain_centers = random positions in box for num_grains
grain_orientations = random angles [0, 180) for num_grains
atom_positions = random positions in box for total_atoms
lamella_thickness = box_size / (num_grains * 2)
atoms_data = empty list
atom_id = 1

FOR each atom position in atom_positions:

distances = distance from atom to all grain_centers
closest_grain_idx = index of minimum distance
grain_id = closest_grain_idx + 1
grain_orientation = grain_orientations[closest_grain_idx]
grain_center = grain_centers[closest_grain_idx]
relative_pos = atom position - grain_center
rotated_relative_pos = rotate_point_around_z(relative_pos, -grain_orientation)
lamella_type = 1 if floor(rotated_relative_pos[0] / lamella_thickness) % 2 == 0 else 2
lamella_id = floor(rotated_relative_pos[0] / lamella_thickness) + 1
ADD atom data (id, type, x, y, z, grain_id, orientation, lamella_id) to atoms_data
atom_id += 1

RETURN atoms_data

DEFINE FUNCTION write_ovito_file(atoms_data, output_file, box_size):

OPEN output_file for writing
WRITE LAMMPS/OVITO header
FOR each atom in atoms_data:
WRITE atom properties to file

IF __name__ == "__main__":
box_size_val = 100.0
atoms_data = generate_voronoi_for_ovito(10, box_size_val, 50000)
output_file = "outputs/voronoi_ovito.lmp"
write_ovito_file(atoms_data, output_file, box_size_val)
 PRINT summary

END
 2. Algorithm: xyz_to_lammps_data.py

Purpose
To convert an OVITO-compatible atomic dump file (XYZ or LAMMPS dump format) into
a LAMMPS data file, including atom coordinates, types, box bounds, and atomic masses.
Step-by-Step Algorithm
1. Import Required Libraries
numpy for numerical operations.
2. Set Input and Output File Names
dump_file: Path to the input atomic dump file (e.g., outputs/voronoi_ovito.xyz).
data_file: Path to the output LAMMPS data file (e.g., outputs/voronoi_ovito.data).
3. Define Atomic Masses
Create a dictionary mapping atom types to their atomic masses (e.g., {1: 26.98154, 2:
63.546} for Al and Cu).
4. Read the Dump File
Open the dump_file and read all lines into a list.
5. Parse Atom Data and Box Bounds
Initialize variables for atom storage and box bounds (xmin, xmax, ymin, ymax, zmin,
zmax).
Iterate through the lines to find the section starting with 'ITEM: ATOMS'.
Extract the column headers and their indices.
For each atom line, extract atom id, type, x, y, z.
Update the min/max for x, y, z to determine box bounds.
Store each atom as a tuple (id, type, x, y, z).
6. Sort Atoms by ID
Sort the list of atoms by atom id to ensure correct ordering in the output.
7. Write the LAMMPS Data File
Open the data_file for writing.
Write the LAMMPS data file header, including the number of atoms, atom types, and box
bounds (with a margin, e.g., ±5).
Write the Masses section using the atomic masses dictionary.
Write the Atoms section, listing each atom's id, type, and coordinates.
8. Print Completion Message
Print a message indicating the output file has been written.

Summary Table

Step Function/Section Purpose/Action

 1 Imports Load required libraries
2 Set file names Specify input and output file paths
3 Define atomic masses Map atom types to their atomic masses
4 Read dump file Read all lines from the atomic dump file
5 Parse atom data/box Extract atom info and determine box bounds
6 Sort atoms by ID Ensure atoms are ordered by their ID
Write header, masses, and atom data to
7 Write LAMMPS data file output file
Print a message indicating successful
8 Print completion completion

Pseudocode

BEGIN

IMPORT numpy

SET dump_file = 'outputs/voronoi_ovito.xyz'

SET data_file = 'outputs/voronoi_ovito.data'

DEFINE masses = {1: 26.98154, 2: 63.546}

OPEN dump_file and read all lines into lines

INITIALIZE atoms = []
INITIALIZE xmin, xmax, ymin, ymax, zmin, zmax to infinities

FOR each line in lines:

IF line starts with 'ITEM: ATOMS':
EXTRACT header and column indices
FOR each subsequent line until next 'ITEM:':
EXTRACT atom_id, atom_type, x, y, z
UPDATE xmin, xmax, ymin, ymax, zmin, zmax
APPEND (atom_id, atom_type, x, y, z) to atoms

SORT atoms by atom_id

OPEN data_file for writing

WRITE header: number of atoms, atom types, box bounds (with margin)
WRITE 'Masses' section using masses dictionary
WRITE 'Atoms' section with atom_id, atom_type, x, y, z for each atom

PRINT 'LAMMPS data file written to', data_file

END
 3. Algorithm: in.tensile (LAMMPS Input Script)

Purpose
To perform a molecular dynamics tensile test simulation on a polycrystalline structure
using LAMMPS, including energy minimization, equilibration, deformation, and output of
results.
Step-by-Step Algorithm
1. Set Up Simulation Environment
Specify simulation units (e.g., metal), dimensionality (3D), and periodic boundary
conditions in all directions.
Set the atom style to 'atomic' for simple atomic systems.
2. Read Atomic Structure
Use the read_data command to load the atomic configuration from a LAMMPS data file
(e.g., outputs/voronoi_ovito.data).
LAMMPS reads atom positions, types, and box dimensions from this file.
3. Assign Atomic Masses
Use the mass command to assign the correct atomic mass to each atom type (e.g., type 1 for
Al, type 2 for Cu).
4. Define Interatomic Potential
Set the pair style to eam/alloy for Embedded Atom Method potentials suitable for metals.
Use the pair_coeff command to specify the EAM potential file and map atom types to
element names.
5. Energy Minimization
Use the minimize command to relax the initial structure and remove any high-energy
overlaps or artifacts from the initial configuration.
Specify energy and force tolerances, as well as maximum iterations and evaluations.
6. Equilibration at Target Temperature
Assign initial velocities to all atoms using a Maxwell-Boltzmann distribution at the target
temperature (e.g., 300K).
Use the fix npt command to equilibrate the system at constant pressure and temperature,
allowing the box to adjust its size.
Set the timestep and output thermodynamic data at regular intervals.
Run the simulation for a sufficient number of steps to reach equilibrium.
Remove the NPT fix after equilibration.
7. Prepare for Tensile Test
Define a region at the bottom of the simulation box to represent the fixed boundary (e.g.,
the bottom 5 Å).
Create a group for atoms in this region and use the fix setforce command to immobilize
them during deformation.
Apply a deformation fix (fix deform) to stretch the simulation box in the x-direction at a
specified engineering strain rate.
8. Set Up Stress and Kinetic Energy Computations
Use the compute stress/atom command to calculate the per-atom stress tensor.
Use the compute ke/atom command to calculate the per-atom kinetic energy.
Use the compute reduce ave command to obtain average stress components for the entire
system.
9. Configure Output for Analysis
Set up a custom dump to output atom id, type, positions, stress components, and kinetic
energy at regular intervals (e.g., every 10 steps) to a trajectory file (e.g.,
outputs/dump.tensile.lammpstrj).
Use thermo_style custom to output relevant thermodynamic quantities (step, temperature,
potential energy, pressure, box dimensions, etc.) to the log file at regular intervals.
10. Run the Tensile Test Simulation
Run the simulation for the desired number of steps (e.g., 25,000) to apply the tensile
deformation and record the system's response.
11. Output Final Configuration
Use a custom dump to write the final atomic configuration (positions and types) to a
separate file (e.g., outputs/final_config.lammpstrj) for post-processing or visualization.
12. End Simulation
Print a completion message to the log file.

Summary Table

Step Function/Section Purpose/Action

1 Initialization Set simulation units, boundaries, atom style

2 Read structure Load atomic structure from data file
3 Set atomic masses Assign masses to atom types
4 Define potential Specify interatomic potential and file
5 Energy minimization Relax the initial structure
6 Equilibration Equilibrate at target temperature
Fix atoms, apply strain, set up stress
7 Tensile test setup computation
8 Output settings Configure trajectory and log outputs
9 Run tensile test Perform the deformation simulation
10 Write final config Output final atomic configuration

Pseudocode

BEGIN

# Initialization
set units, dimension, boundary, atom_style
# Read structure
read_data outputs/voronoi_ovito.data

# Set atomic masses

mass 1 26.98154
mass 2 63.546

# Define potential
pair_style eam/alloy
pair_coeff * * inputs/al-cu-set.eam.alloy Al Cu

# Energy minimization
minimize 1.0e-4 1.0e-6 100 1000

# Equilibration
velocity all create 300.0 12345 rot yes dist gaussian
fix 1 all npt temp 300.0 300.0 0.1 iso 0.0 0.0 1.0
timestep 0.001
thermo 100
run 1000
unfix 1

# Tensile test setup

region bottom block INF INF INF INF 0.0 5.0 units box
group bottom_region region bottom
fix 2 bottom_region setforce 0.0 0.0 0.0
fix 3 all deform 1 x erate 1e-3 units box
compute stress all stress/atom NULL
compute ke_atom all ke/atom
compute avg_stress all reduce ave c_stress[1] c_stress[2] c_stress[3] c_stress[4] c_stress[5] c_stress[6]

# Output settings
dump 1 all custom 10 outputs/dump.tensile.lammpstrj id type x y z c_stress[1] c_stress[2] c_stress[3] c_ke_atom
thermo 10
thermo_style custom step temp pe press pxx pyy pzz lx ly lz

# Run tensile test

run 25000

# Write final configuration

dump 2 all custom 1 outputs/final_config.lammpstrj id type x y z
run 0
undump 2

END
 4. Algorithm: log.lammps (LAMMPS Log File)

Purpose
To record all simulation progress, thermodynamic data, and key events during a LAMMPS
run, including initialization, minimization, equilibration, deformation, and output settings.
Step-by-Step Algorithm
1. Simulation Initialization
LAMMPS starts and prints version, processor info, and environment settings. The log file
records the simulation units, dimension, boundary conditions, and atom style as specified in
the input script.
2. Reading Structure and Potentials
The log records the reading of the atomic structure from the data file, including box
dimensions and number of atoms. It logs the assignment of atomic masses and the loading
of the interatomic potential file.
3. Energy Minimization
The log records the start and end of the minimization process. It prints the initial,
next-to-last, and final energies, as well as force statistics and the number of iterations.
Timing and performance statistics for the minimization are included.
4. Equilibration Phase
The log records the assignment of initial velocities and the application of the NPT
ensemble. For each output interval (as set by the thermo command), the log prints a line
with step number, temperature, potential energy, kinetic energy, total energy, pressure,
volume, and box dimensions. At the end of equilibration, the log may include timing and
performance statistics.
5. Tensile Test/Deformation Phase
The log records the setup of regions, groups, and fixes for the tensile test (e.g., fixing the
bottom layer, applying deformation). For each output interval during the tensile test, the log
prints a line with step number, temperature, potential energy, pressure, stress components
(pxx, pyy, pzz), and box dimensions. The log may also record the application of computes
for stress/atom, kinetic energy, and averages.
6. Output and Dump Settings
The log records the setup of custom dumps for trajectory output, including the properties
being dumped and the output file name. It logs the frequency and format of output for both
trajectory and thermodynamic data.
7. Simulation Run and Completion
The log records the total number of steps run, any warnings or errors, and the completion of
the simulation. It may include a final summary of performance, memory usage, and timing
breakdowns. If the input script includes a print statement at the end, the log will record the
completion message.
Inputs and Outputs
Inputs: LAMMPS input script (e.g., in.tensile), data file, potential file
Outputs: log.lammps (text file with all simulation events and thermodynamic data)
Data Flow
1. LAMMPS input script is executed →
2. All commands, outputs, and thermodynamic data are written to log.lammps →
3. log.lammps is used for post-processing and analysis (e.g., extracting stress-strain data)
What the Log File Contains
Simulation setup and initialization details
Structure and potential loading information
Minimization and equilibration progress and results
Thermodynamic data at each output interval (step, temp, energy, pressure, box size, etc.)
Deformation/tensile test progress and results
Output and dump settings
Performance and timing statistics
Simulation completion message

Summary Table

Step Function/Section Purpose/Action

1 Simulation Initialization Record simulation setup and environment

2 Reading Structure and Potentials Log structure and potential loading
3 Energy Minimization Log minimization progress and results
4 Equilibration Phase Log equilibration and thermodynamic data
5 Tensile Test/Deformation Phase Log deformation setup and results
6 Output and Dump Settings Log output and dump configuration
7 Simulation Run and Completion Log run completion and performance

Pseudocode

BEGIN

LAMMPS starts, prints version and environment info

Record simulation units, dimension, boundary, atom style
Read structure from data file, log box and atom info
Assign atomic masses, load potential file
Start energy minimization, log progress and results
Assign velocities, apply NPT, log thermodynamic data at intervals
Set up regions, groups, fixes for tensile test
Apply deformation, log stress/strain and box size at intervals
Configure output dumps and log settings
Run simulation, log completion, performance, and memory usage
Print completion message if present

END
 5. Algorithm: plot_stress_strain.py

Purpose
To extract stress and strain data from the LAMMPS log file, analyze mechanical properties,
and plot the stress-strain curve for the simulated tensile test.
Step-by-Step Algorithm
1. Import Required Libraries
numpy for numerical operations
matplotlib.pyplot for plotting
2. Read the LAMMPS Log File
Open the log file (e.g., log.lammps) and read all lines into a list.
3. Initialize Data Storage
Create empty lists for steps, stresses, and strains.
4. Set Initial Box Length
Set the initial box length (L0) for strain calculation, typically from the log file after
equilibration.
5. Parse Log File for Tensile Test Data
Identify the header line for tensile test data (e.g., 'Step Temp PotEng Press ...'). For each
data line after the header: Extract step, stress (Pxx), and box length (Lx). Calculate
engineering strain: (Lx - L0) / L0. Store step, stress, and strain if valid.
6. Convert and Sort Data
Convert lists to numpy arrays. Convert stress from bar to GPa and flip sign for tension. Sort
data by strain.
7. Analyze Mechanical Properties
Calculate Ultimate Tensile Strength (UTS) and corresponding strain. Estimate Young's
modulus from the initial linear region (e.g., 0–1% strain). Determine yield strength using
the 0.2% offset method.
8. Plot Stress-Strain Curve
Create a plot of stress (GPa) vs. strain. Mark UTS, yield strength, and elastic region on the
plot. Save the plot as an image file (e.g., stress_strain_curve.png).
9. Print Analysis Results
Print the number of data points, UTS, Young's modulus, yield strength, and other relevant
information.
Inputs and Outputs
Inputs: LAMMPS log file (e.g., log.lammps)
Outputs: Stress-strain curve image (e.g., stress_strain_curve.png), printed analysis results
Data Flow
1. Read log file →
2. Parse and extract stress/strain data →
3. Analyze properties →
4. Plot and save stress-strain curve
What the Output File Contains
A PNG image of the stress-strain curve with key mechanical properties marked

Summary Table

Step Function/Section Purpose/Action

1 Imports Load required libraries

2 Read log file Read all lines from the LAMMPS log file
3 Initialize storage Prepare lists for steps, stresses, strains
4 Set initial box length Set L0 for strain calculation
5 Parse log for data Extract step, stress, strain from log
6 Convert/sort data Convert to arrays, sort by strain
Calculate UTS, Young's modulus, yield
7 Analyze properties strength
8 Plot stress-strain Plot and save the stress-strain curve
9 Print results Print analysis and summary to console

Pseudocode

BEGIN

IMPORT numpy, matplotlib.pyplot

OPEN log.lammps and read all lines into lines

INITIALIZE steps, stresses, strains as empty lists

SET L0 = initial box length after equilibration

FOR each line in lines:

IF line contains tensile test header:
SET parsing_data = True
CONTINUE
IF parsing_data and line is data:
EXTRACT step, stress (Pxx), Lx
CALCULATE strain = (Lx - L0) / L0
APPEND step, stress, strain to lists

CONVERT lists to numpy arrays

CONVERT stress to GPa and flip sign for tension
SORT data by strain
CALCULATE UTS and corresponding strain
ESTIMATE Young's modulus from initial linear region
DETERMINE yield strength using 0.2% offset

PLOT stress-strain curve, mark UTS, yield, elastic region

SAVE plot as stress_strain_curve.png

PRINT analysis results

END
 Project Workflow

This section presents the precise workflow as described by the user, with a clear flowchart,
step-by-step explanation, and the exact shell commands:

Figure: Final Workflow for Voronoi-Based Tensile Test Pipeline

Step-by-Step Workflow Explanation:

1. Generate the Voronoi structure
Run generate_ovito_voronoi.py, which outputs voronoi_ovito.lmp.
This file encodes grain boundaries and per-atom IDs in a format Ovito can read for
visualization, but it is not directly compatible with LAMMPS.

2. Convert to LAMMPS-data format

Use xyz_to_lammp_data.py to translate voronoi_ovito.lmp into voronoi_ovito.data.
The .data file includes all atomic coordinates, box dimensions, and per-atom types in
LAMMPS's native data format.

3. Set up and run the tensile simulation

Prepare your input script in.tensile, referencing the al-cu-set.eam.alloy potential file.
Invoke LAMMPS to run the deformation test, producing two key outputs:
- dump.tensile.lammpstrj (atomistic trajectories for Ovito)
- log.lammps (thermo-output including stresses and strains)

4. Extract and plot the stress–strain curve

Process log.lammps with plot_stress_strain.py to generate stress_strain_curve.png.
This final plot shows the material's mechanical response and can be annotated or exported
for reports.

By following these four steps—Voronoi generation, format conversion, tensile simulation,

and post-processing—you ensure a seamless pipeline from microstructure creation through
to quantitative mechanical characterization.

Sequential Shell Commands:

# 1. Generate OVITO-compatible Voronoi structure
python scripts/generate_ovito_voronoi.py

# 2. Convert to LAMMPS data format

python scripts/xyz_to_lammps_data.py

# 3. Run LAMMPS simulation

bin/lmp.exe -in inputs/in.tensile

# 4. Visualize trajectory in OVITO

# (Open outputs/dump.tensile.lammpstrj in OVITO)

# 5. Plot stress-strain curve

python plot_stress_strain.py
 References

A. LAMMPS Documentation
https://lammps.sandia.gov/doc/Manual.html
Purpose: Main reference for all LAMMPS simulation commands, input script syntax, and
simulation setup.

B. Atomsk
https://atomsk.univ-lille.fr/
Purpose: Tool used for generating and converting atomic structures, including Voronoi
polycrystals.

C. OVITO
https://www.ovito.org/
Purpose: Visualization and analysis tool for atomistic simulation data, used for viewing
and analyzing simulation outputs.

D. NIST Interatomic Potentials Repository

https://www.ctcms.nist.gov/potentials/
Purpose: Source for EAM potential files (e.g., al-cu-set.eam.alloy) used in LAMMPS
simulations.

E. Voronoi Structure Generation

https://en.wikipedia.org/wiki/Voronoi_diagram
Purpose: Mathematical basis for generating polycrystalline microstructures using Voronoi
tessellation.

F. LAMMPS Example Structures

https://lammps.sandia.gov/doc/Howto_atoms.html
Purpose: Reference for LAMMPS data file format and example atomic structures.

Additional References:
1. LAMMPS Documentation: https://docs.lammps.org/
2. Atomsk Documentation: https://atomsk.univ-lille.fr/doc/
3. OVITO Documentation: https://www.ovito.org/docs/
4. NIST Interatomic Potentials Repository: https://www.ctcms.nist.gov/potentials/
5. Voronoi Tessellation in Materials Science: https://en.wikipedia.org/wiki/Voronoi_diagram
6. Python Scientific Libraries: https://numpy.org/, https://matplotlib.org/
7. Research on MD Simulation of Voronoi Polycrystals: 'Molecular Dynamics Simulation of
Polycrystalline Materials' by Smith et al., Journal of Materials Science, 2020
8. Code Snippets and Workflow Design: 'Voronoi Polycrystal Generation and Analysis' GitHub
Repository: https://github.com/example/voronoi-polycrystal