LAMMPSKit

LAMMPSKit is a comprehensive Python toolkit for molecular dynamics (MD) simulation analysis with LAMMPS, specialized for electrochemical memory device characterization and filament analysis. It provides advanced post-processing capabilities for HfTaO-based resistive random access memory (ReRAM) devices, including filament formation tracking, charge redistribution analysis, and temporal evolution characterization.

🚀 Features

• 🔬 Specialized Analysis: Advanced filament evolution tracking for electrochemical memory devices
• 📊 Comprehensive Visualization: Publication-ready scientific plotting with customizable styling
• ⚡ High Performance: Optimized for large trajectory analysis (>1M atoms, >10K frames)
• 🧪 OVITO Integration: Advanced cluster analysis and structural characterization
• 📐 Robust Data Processing: Memory-efficient streaming for multi-gigabyte datasets
• 🎯 Modular Design: Separate I/O, plotting, and analysis components for flexibility
• 🔧 Configuration Management: Centralized validation and parameter management
• ✅ Complete Testing: 96% code coverage with visual regression testing

📦 Installation

From PyPI (Recommended)

bash pip install lammpskit

For Development

```bash git clone https://github.com/simantalahkar/lammpskit.git cd lammpskit

Primary method (modern pip with optional dependencies)

pip install -e .[dev]

Alternative method (if above fails)

pip install -e . && pip install -r requirements-dev.txt ```

📋 Requirements

Runtime Dependencies: - Python 3.12+ - numpy ≥2.3.1 - matplotlib ≥3.10.3 - ovito ≥3.12.4

Development Dependencies: - All runtime requirements - Testing: pytest, pytest-cov, pytest-mpl - Documentation: sphinx, sphinx-rtd-theme - Code Quality: black, flake8, isort, mypy - Build Tools: build, twine, setuptools

Function Summary Table

Core I/O Functions (lammpskit.io.lammps_readers)

| Function | Purpose | |--------------------------------|----------------------------------------------------------------| | readstructureinfo | Parse trajectory metadata (timestep, atom count, box dims) | | readcoordinates | Load coordinates and cell info from trajectory files | | readdisplacement_data | Parse processed displacement data with robust error handling |

Analysis Functions (lammpskit.ecellmodel.filament_layer_analysis)

| Function | Purpose | |--------------------------------|----------------------------------------------------------------| | analyzeclusters | OVITO-based cluster analysis and filament property extraction | | trackfilamentevolution | Track filament connectivity, gap, and size over time | | plotatomicdistribution | Analyze and plot atomic distributions by element type | | plotatomicchargedistribution| Analyze and plot atomic charge distributions | | plotdisplacementcomparison | Compare displacement data across multiple cases | | plotdisplacementtimeseries | Plot time series of displacement data with customization |

Plotting Utilities (lammpskit.plotting)

| Function | Purpose | |--------------------------------|----------------------------------------------------------------| | plotmultiplecases | General scientific plotting utility with flexible styling | | timeseries_plots.* | Centralized timeseries plotting with font and style control |

Data Processing (lammpskit.ecellmodel.data_processing)

| Function | Purpose | |--------------------------------|----------------------------------------------------------------| | Various validation functions | Centralized input validation and error handling |

Example Workflows (usage/ecellmodel/)

| Script | Purpose | |--------------------------------|----------------------------------------------------------------| | run_analysis.py | Complete workflow demonstrating 4 main analysis types |

Quick Start

Using the Example Workflow

LAMMPSKit v1.2.1 includes a comprehensive example workflow that demonstrates all major package capabilities:

```python

Clone the repository and navigate to the usage example

git clone https://github.com/simantalahkar/lammpskit.git cd lammpskit/usage/ecellmodel

Run the complete analysis workflow

python run_analysis.py ```

This workflow demonstrates four main analysis types: 1. Filament Evolution Tracking - Monitor filament connectivity and structural changes over time 2. Displacement Analysis - Compare atomic displacements across different species (Hf, O, Ta) 3. Charge Distribution Analysis - Analyze local charge distributions in electrochemical systems 4. Atomic Distribution Analysis - Study atomic distributions under different applied voltages

Generated plots and analysis results are saved to usage/ecellmodel/output/.

Package Structure

LAMMPSKit v1.2.1 features a modular architecture:

lammpskit/ ├── io/ # Data reading and I/O operations ├── plotting/ # Visualization utilities and timeseries plots ├── ecellmodel/ # Electrochemical analysis functions └── config.py # Centralized configuration management

Docker Image

An official Docker image for lammpskit is available on Docker Hub. Using the Docker container provides a portable, reproducible environment with all dependencies pre-installed for running and testing lammpskit anywhere Docker is supported.

How to Use

1. Install Docker on your system.
   See Get Docker for instructions.

2. Pull the latest image: sh docker pull simantalahkar/lammpskit:latest Or pull a specific version: sh docker pull simantalahkar/lammpskit:1.2.1

3. Run the container with your local data mounted as a volume: sh docker run -it -v /path/to/your/data:/data simantalahkar/lammpskit:latest This starts a bash shell in the container. Your local data is accessible at /data.

4. Use the installed Python package: ```sh python

   import lammpskit

   ...your analysis code...

   ```

5. Copy custom scripts or files into the container (from another terminal): sh docker cp /path/to/local/script.py <container_id>:/home/lammpsuser/ You can also install additional Python packages inside the container: sh pip install <package-name>

6. Exit the container after analysis: sh exit The container will remain on your system for future use.
   To re-enter the container: sh docker start <container_id> docker exec -it <container_id> bash To delete the container completely: sh docker rm <container_id>

Installation (PyPI)

For end users (runtime): sh pip install lammpskit

For development and testing: ```sh

Method 1: Using optional dependencies (recommended)

pip install -e .[dev]

Method 2: Manual installation (fallback)

pip install -e . pip install -r requirements-dev.txt ```

Development and Testing Environment

All runtime dependencies are listed in requirements.txt. Development and test dependencies are available in multiple formats: - [project.optional-dependencies] in pyproject.toml (modern standard) - requirements-dev.txt (traditional method)
- extras_require in setup.py (legacy compatibility)

To set up a development environment and run tests locally: ```sh

Recommended approach with fallback

pip install -e .[dev] || (pip install -e . && pip install -r requirements-dev.txt) pytest ``` Tests are not shipped with the PyPI package, but are available in the source repository for development and validation.

Test Coverage & Visual Regression Testing

LAMMPSKit v1.2.1 includes extensive test coverage with over 270 test functions and 90+ baseline images for visual regression testing. The test suite uses a centralized baseline approach for consistent and maintainable visual regression testing.

Test Organization

• tests/test_io.py - I/O function validation
• tests/test_plotting.py - General plotting utilities
  
• tests/test_timeseries_plots.py - Timeseries plotting functions
• tests/test_centralized_font_control.py - Font and styling consistency
• tests/test_ecellmodel/ - Analysis function validation (subdirectory)
• tests/test_config.py - Configuration management
• tests/baseline/ - Centralized baseline images for all visual tests

Running Tests Locally

```sh

Install with development dependencies

pip install .[dev]

Run all tests

pytest

Run with visual regression testing

pytest --mpl

Generate new baseline images (when plots change intentionally)

pytest --mpl-generate-path=tests/baseline tests/

Run tests with coverage

pytest --cov=lammpskit --cov-report=html ```

Visual Regression Testing Architecture

Centralized Baseline Directory Structure: tests/ ├── baseline/ # All baseline images (centralized) ├── test_*.py # Root level tests → "baseline" ├── test_ecellmodel/ # Subdirectory tests → "../baseline" │ └── test_*.py # Use relative paths to centralized location └── conftest.py # Shared pytest configuration

Key Benefits: - Cross-platform compatibility: Relative paths work on Windows, Linux, macOS - Container compatibility: Works identically in Docker and local environments
- Maintainability: Single location for all baseline images - CI/CD integration: Simplified path handling in GitHub Actions and Docker

Implementation Pattern: ```python

For tests in tests/ directory (root level)

BASELINEDIRRELATIVE = "baseline"

For tests in tests/test_ecellmodel/ directory (subdirectory)

BASELINEDIRRELATIVE = "../baseline"

@pytest.mark.mplimagecompare(baselinedir=BASELINEDIRRELATIVE, removetext=True) def testplottingfunction(): # Test implementation returns matplotlib figure return figure ```

Tests use pytest, pytest-mpl, and pytest-cov for automated validation, image comparison, and coverage analysis. The centralized baseline approach ensures consistent visual regression testing across all development and CI/CD environments.

Data Format Examples

LAMMPS Trajectory File (.lammpstrj)

ITEM: TIMESTEP 1200000 ITEM: NUMBER OF ATOMS 5 ITEM: BOX BOUNDS pp pp pp 0.0 50.0 0.0 50.0 0.0 50.0 ITEM: ATOMS id type q x y z ix iy iz vx vy vz c_eng 1 2 0.1 1.0 2.0 3.0 0 0 0 0 0 0 0 2 1 -0.2 2.0 3.0 4.0 0 0 0 0 0 0 0 ... (one line per atom)

Processed Displacement Data File

```

header1

header2

header3

0 2 1.0 3.0 2.0 4.0

end loop

```

Changelog

See the CHANGELOG.md for a detailed list of changes and updates.

Citation

If you use this package in your research, please cite:

S. Lahkar et al., Decoupling Local Electrostatic Potential and Temperature-Driven Atomistic Forming Mechanisms in TaOx/HfO2-Based ReRAMs using Reactive Molecular Dynamics Simulations, arXiv:2505.24468, https://doi.org/10.48550/arXiv.2505.24468

License

GPL-3.0-or-later

Author

Simanta Lahkar

Links

• Homepage
• Documentation
• Changelog