API Reference

This section provides comprehensive documentation for all LAMMPSKit modules, functions, and classes.

Package Overview

LAMMPSKit: A modular toolkit for LAMMPS molecular dynamics simulation analysis.

LAMMPSKit provides a streamlined framework for analyzing raw data from molecular dynamics simulations, with particular emphasis on electrochemical systems. The package follows a hierarchical design allowing both general-purpose trajectory analysis and specialized domain-specific workflows.

Modules

iomodule

LAMMPS trajectory file readers and data parsers. Handles standard LAMMPS dump formats with automatic column detection and efficient memory management for large datasets.

plottingmodule

Scientific visualization utilities with standardized styling and publication-ready output. Includes time series analysis, dual-axis plots, and statistical overlays.

configmodule

Centralized configuration management for file paths, analysis parameters, and computational settings. Supports both programmatic and file-based configuration.

ecellmodelmodule

Specialized analysis for electrochemical cell simulations. Provides filament tracking, charge distribution and displacement analyses, and clustering algorithms optimized for HfTaO systems.

Target Applications

• Electrochemical memory device simulations (ReRAM, memristors).

• Ion transport and defect migration studies.

• Phase transition analysis in oxide materials.

• General LAMMPS trajectory post-processing.

Performance Notes

Memory usage scales linearly with trajectory size. For datasets >1GB, use chunked reading via io.lammps_readers with appropriate buffer sizes.

Community Extensions

To extend for other MD simulation types: 1. Add new analysis modules following ecellmodel structure 2. Implement domain-specific atom type mappings in config. 3. Create specialized plotting functions for new data types. 4. Add validation functions for new simulation parameters.

Examples

Basic workflow for electrochemical analysis:

>>> import lammpskit as lk
>>> from lammpskit.config import DEFAULT_COLUMNS_TO_READ
>>> file_list = ['trajectory1.lammpstrj', 'trajectory2.lammpstrj']
>>> coords, timesteps, total_atoms, xlo, xhi, ylo, yhi, zlo, zhi = lk.io.read_coordinates(
...     file_list, skip_rows=9, columns_to_read=DEFAULT_COLUMNS_TO_READ)
>>> from lammpskit.ecellmodel.filament_layer_analysis import analyze_clusters
>>> analyze_clusters('trajectory1.lammpstrj')

General trajectory parsing and plotting:

>>> timestep, total_atoms, xlo, xhi, ylo, yhi, zlo, zhi = lk.io.read_structure_info('dump.lammpstrj')
>>> import numpy as np
>>> x_data, y_data = np.array([1, 2, 3]), np.array([[4, 5, 6]])
>>> lk.plotting.plot_multiple_cases(x_data, y_data, ['Case1'], 'X', 'Y', 'output', 8, 6)

Core Modules

I/O Operations

• lammpskit.io package
  • Key Features
  • Core Functions
  • Performance Considerations
  • Submodules
  • Module contents

The lammpskit.io module provides functions for reading LAMMPS trajectory files and extracting simulation metadata.

Key Functions:

• lammpskit.io.read_structure_info() - Extract timestep, atom count, and box dimensions

• lammpskit.io.read_coordinates() - Load atomic coordinates from multiple trajectory files

Plotting Utilities

• lammpskit.plotting package
  • Key Features
  • Package Architecture
  • Core Functions
  • Styling Standards
  • Usage Examples
  • Performance Notes
  • Related Modules
  • Submodules
  • Module contents

The lammpskit.plotting module provides general-purpose plotting functions and specialized time series visualization.

Key Functions:

• lammpskit.plotting.plot_multiple_cases() - General comparative plotting utility

• lammpskit.plotting.create_time_series_plot() - Standardized time series plots

• lammpskit.plotting.create_dual_axis_plot() - Dual-axis comparative plots

Configuration Management

• lammpskit.config module
  • Key Functions
  • Plot Configuration System
  • Font Configuration Examples
  • Analysis Configuration Usage
  • System Configuration Examples
  • Configuration Inheritance
  • Runtime Configuration Override
  • Validation and Type Safety
  • Best Practices
  • Related Components
  • Module Documentation

The lammpskit.config module provides validation functions and constants for robust LAMMPS analysis.

Key Functions:

• lammpskit.config.validate_file_list() - Validate trajectory file lists

• lammpskit.config.validate_cluster_parameters() - Validate geometric parameters

• lammpskit.config.validate_loop_parameters() - Validate timestep ranges

Constants:

• DEFAULT_COLUMNS_TO_READ - Core LAMMPS dump file columns

• EXTENDED_COLUMNS_TO_READ - Extended column set for comprehensive analysis

• DISPLACEMENT_DATA_LABELS - Labels for displacement analysis types

Electrochemical Analysis

• lammpskit.ecellmodel package
  • Package Overview
  • Key Capabilities
  • Architecture
  • Usage Workflow
  • Integration with LAMMPSKit Ecosystem
  • Performance Considerations
  • Submodules
  • Common Analysis Tasks
  • Research Applications
  • Related Documentation
  • Module contents

The lammpskit.ecellmodel module provides specialized analysis for electrochemical cell simulations.

Key Functions:

• lammpskit.ecellmodel.filament_layer_analysis.analyze_clusters() - OVITO-based cluster analysis

• lammpskit.ecellmodel.filament_layer_analysis.track_filament_evolution() - Filament connectivity tracking

• lammpskit.ecellmodel.filament_layer_analysis.plot_atomic_distribution() - Atomic distribution analysis

• lammpskit.ecellmodel.filament_layer_analysis.plot_atomic_charge_distribution() - Charge distribution analysis

• lammpskit.ecellmodel.filament_layer_analysis.plot_displacement_comparison() - Displacement analysis

• lammpskit.ecellmodel.filament_layer_analysis.plot_displacement_timeseries() - Time series displacement plots

Function Categories

Data I/O Functions

Functions for reading and parsing LAMMPS simulation output:

io.read_structure_info(filepath)	Extract simulation metadata from LAMMPS trajectory file header.
io.read_coordinates(file_list, skip_rows, ...)	Load atomic coordinates and metadata from multiple LAMMPS trajectory files.
ecellmodel.read_displacement_data(filepath, ...)	Read spatially-binned displacement data from LAMMPS thermodynamic output files.

Analysis Functions

Functions for scientific analysis of simulation data:

ecellmodel.analyze_clusters(filepath[, ...])	Perform comprehensive OVITO-based cluster analysis for metallic filament characterization.
ecellmodel.track_filament_evolution(...[, ...])	Comprehensive temporal tracking of filament formation and evolution dynamics.
ecellmodel.plot_atomic_distribution(...[, ...])	Generate comprehensive atomic distribution analysis for HfTaO electrochemical devices.
ecellmodel.plot_atomic_charge_distribution(...)	Generate electrostatic charge distribution analysis for HfTaO electrochemical devices.
ecellmodel.plot_displacement_comparison(...)	Generate comparative displacement analysis for multi-species ion migration in HfTaO devices.

Plotting Functions

Functions for creating scientific visualizations:

• lammpskit.plotting.plot_multiple_cases() - Create multi-case comparative plots

• lammpskit.plotting.create_time_series_plot() - Create standardized time series plots

• lammpskit.plotting.create_dual_axis_plot() - Create dual-axis correlation plots

• lammpskit.plotting.save_and_close_figure() - Save and cleanup figure objects

• lammpskit.ecellmodel.filament_layer_analysis.plot_displacement_timeseries() - Plot temporal displacement analysis

Validation Functions

Functions for input validation and parameter checking:

• lammpskit.config.validate_filepath() - Validate file paths and existence

• lammpskit.config.validate_file_list() - Validate lists of file paths

• lammpskit.config.validate_dataindex() - Validate data index parameters

• lammpskit.config.validate_loop_parameters() - Validate loop iteration parameters

• lammpskit.config.validate_chunks_parameter() - Validate chunk size parameters

• lammpskit.config.validate_cluster_parameters() - Validate clustering analysis parameters

Configuration Classes

Configuration classes for plotting and analysis:

plotting.TimeSeriesPlotConfig([alpha, ...])	Configuration class for standardized time series plotting with publication-ready defaults.
plotting.DualAxisPlotConfig([alpha, ...])	Configuration class for dual-axis plots supporting simultaneous visualization of two data series.