# LAMMPSKit
[](https://github.com/simantalahkar/lammpskit/actions)
[](https://lammpskit.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/simantalahkar/lammpskit)
[](https://badge.fury.io/py/lammpskit)
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/gpl-3.0)
**LAMMPSKit** is a comprehensive Python toolkit for molecular dynamics (MD) simulation analysis with [LAMMPS](https://lammps.org/), 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 |
|--------------------------------|----------------------------------------------------------------|
| read_structure_info | Parse trajectory metadata (timestep, atom count, box dims) |
| read_coordinates | Load coordinates and cell info from trajectory files |
| read_displacement_data | Parse processed displacement data with robust error handling |
### Analysis Functions (`lammpskit.ecellmodel.filament_layer_analysis`)
| Function | Purpose |
|--------------------------------|----------------------------------------------------------------|
| analyze_clusters | OVITO-based cluster analysis and filament property extraction |
| track_filament_evolution | Track filament connectivity, gap, and size over time |
| plot_atomic_distribution | Analyze and plot atomic distributions by element type |
| plot_atomic_charge_distribution| Analyze and plot atomic charge distributions |
| plot_displacement_comparison | Compare displacement data across multiple cases |
| plot_displacement_timeseries | Plot time series of displacement data with customization |
### Plotting Utilities (`lammpskit.plotting`)
| Function | Purpose |
|--------------------------------|----------------------------------------------------------------|
| plot_multiple_cases | 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.0 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.0 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](https://hub.docker.com/r/simantalahkar/lammpskit).
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](https://docs.docker.com/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.0
```
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.0 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)
BASELINE_DIR_RELATIVE = "baseline"
# For tests in tests/test_ecellmodel/ directory (subdirectory)
BASELINE_DIR_RELATIVE = "../baseline"
@pytest.mark.mpl_image_compare(baseline_dir=BASELINE_DIR_RELATIVE, remove_text=True)
def test_plotting_function():
# 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
```
## Main Functions
### `read_structure_info(filepath)`
Reads a LAMMPS trajectory file and returns timestep, atom count, and box dimensions. Robust to missing/malformed data.
### `read_coordinates(file_list, skip_rows, columns_to_read)`
Loads atomic coordinates and simulation cell parameters from a list of trajectory files.
### `read_displacement_data(filepath, loop_start, loop_end, repeat_count=0)`
Reads binwise averaged displacement data from processed output files, handling chunked data and errors.
### `plot_multiple_cases(x_arr, y_arr, labels, xlabel, ylabel, output_filename, xsize, ysize, ...)`
General plotting utility for 1D/2D arrays, supporting various plot customizations.
### `plot_atomic_distribution(file_list, labels, skip_rows, z_bins, analysis_name, output_dir)`
Reads coordinates, computes atomic distributions (O, Hf, Ta, metals), and plots stoichiometry and atom counts.
### `plot_atomic_charge_distribution(file_list, labels, skip_rows, z_bins, analysis_name, output_dir)`
Computes and plots charge distributions and mean charges for atom types.
### `plot_displacement_comparison(file_list, loop_start, loop_end, labels, analysis_name, repeat_count, output_dir)`
Reads displacement data for multiple cases, plots z/lateral displacements vs. bin positions.
### `analyze_clusters(filepath)`
Uses OVITO to perform cluster analysis, coordination, and connectivity checks on metallic atoms, returning filament properties.
### `track_filament_evolution(file_list, analysis_name, time_step, dump_interval_steps, output_dir)`
Tracks filament connectivity/gap/separation/size over time, and generates summary plots.
### `plot_displacement_timeseries(file_list, datatype, dataindex, Nchunks, loop_start, loop_end, output_dir)`
Plots time series of displacement data for selected data indices.
### `run_analysis(...)`
Orchestrates all analysis workflows, setting up parameters, file lists, and calling the above functions for various scenarios.
## Changelog
See the [CHANGELOG.md](https://github.com/simantalahkar/lammpskit/blob/main/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](https://github.com/simantalahkar/lammpskit)
- [Documentation](https://lammpskit.readthedocs.io/en/latest/)
- [Changelog](./CHANGELOG.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/simantalahkar/lammpskit",
"name": "lammpskit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "LAMMPS, molecular-dynamics, ReRAM, electrochemical, memory-devices, filament-analysis, HfTaO, materials-science",
"author": "Simanta Lahkar",
"author_email": "Simanta Lahkar <simantalahkar@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a7/55/80b2e68647223331364247aac5c57ca474ad1a29c2feca378a7ad8df0ee8/lammpskit-1.2.0.tar.gz",
"platform": null,
"description": "# LAMMPSKit\r\n\r\n[](https://github.com/simantalahkar/lammpskit/actions)\r\n[](https://lammpskit.readthedocs.io/en/latest/?badge=latest)\r\n[](https://codecov.io/gh/simantalahkar/lammpskit)\r\n[](https://badge.fury.io/py/lammpskit)\r\n[](https://www.python.org/downloads/)\r\n[](https://www.gnu.org/licenses/gpl-3.0)\r\n\r\n**LAMMPSKit** is a comprehensive Python toolkit for molecular dynamics (MD) simulation analysis with [LAMMPS](https://lammps.org/), 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.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **\ud83d\udd2c Specialized Analysis**: Advanced filament evolution tracking for electrochemical memory devices\r\n- **\ud83d\udcca Comprehensive Visualization**: Publication-ready scientific plotting with customizable styling\r\n- **\u26a1 High Performance**: Optimized for large trajectory analysis (>1M atoms, >10K frames)\r\n- **\ud83e\uddea OVITO Integration**: Advanced cluster analysis and structural characterization\r\n- **\ud83d\udcd0 Robust Data Processing**: Memory-efficient streaming for multi-gigabyte datasets\r\n- **\ud83c\udfaf Modular Design**: Separate I/O, plotting, and analysis components for flexibility\r\n- **\ud83d\udd27 Configuration Management**: Centralized validation and parameter management\r\n- **\u2705 Complete Testing**: 96% code coverage with visual regression testing\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### From PyPI (Recommended)\r\n```bash\r\npip install lammpskit\r\n```\r\n\r\n### For Development\r\n```bash\r\ngit clone https://github.com/simantalahkar/lammpskit.git\r\ncd lammpskit\r\n\r\n# Primary method (modern pip with optional dependencies)\r\npip install -e .[dev]\r\n\r\n# Alternative method (if above fails)\r\npip install -e . && pip install -r requirements-dev.txt\r\n```\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n**Runtime Dependencies:**\r\n- Python 3.12+\r\n- numpy \u22652.3.1\r\n- matplotlib \u22653.10.3\r\n- ovito \u22653.12.4\r\n\r\n**Development Dependencies:**\r\n- All runtime requirements\r\n- Testing: pytest, pytest-cov, pytest-mpl\r\n- Documentation: sphinx, sphinx-rtd-theme\r\n- Code Quality: black, flake8, isort, mypy\r\n- Build Tools: build, twine, setuptools\r\n\r\n\r\n\r\n## Function Summary Table\r\n\r\n### Core I/O Functions (`lammpskit.io.lammps_readers`)\r\n| Function | Purpose |\r\n|--------------------------------|----------------------------------------------------------------|\r\n| read_structure_info | Parse trajectory metadata (timestep, atom count, box dims) |\r\n| read_coordinates | Load coordinates and cell info from trajectory files |\r\n| read_displacement_data | Parse processed displacement data with robust error handling |\r\n\r\n### Analysis Functions (`lammpskit.ecellmodel.filament_layer_analysis`)\r\n| Function | Purpose |\r\n|--------------------------------|----------------------------------------------------------------|\r\n| analyze_clusters | OVITO-based cluster analysis and filament property extraction |\r\n| track_filament_evolution | Track filament connectivity, gap, and size over time |\r\n| plot_atomic_distribution | Analyze and plot atomic distributions by element type |\r\n| plot_atomic_charge_distribution| Analyze and plot atomic charge distributions |\r\n| plot_displacement_comparison | Compare displacement data across multiple cases |\r\n| plot_displacement_timeseries | Plot time series of displacement data with customization |\r\n\r\n### Plotting Utilities (`lammpskit.plotting`)\r\n| Function | Purpose |\r\n|--------------------------------|----------------------------------------------------------------|\r\n| plot_multiple_cases | General scientific plotting utility with flexible styling |\r\n| timeseries_plots.* | Centralized timeseries plotting with font and style control |\r\n\r\n### Data Processing (`lammpskit.ecellmodel.data_processing`)\r\n| Function | Purpose |\r\n|--------------------------------|----------------------------------------------------------------|\r\n| Various validation functions | Centralized input validation and error handling |\r\n\r\n### Example Workflows (`usage/ecellmodel/`)\r\n| Script | Purpose |\r\n|--------------------------------|----------------------------------------------------------------|\r\n| run_analysis.py | Complete workflow demonstrating 4 main analysis types |\r\n\r\n\r\n## Quick Start\r\n\r\n### Using the Example Workflow\r\n\r\nLAMMPSKit v1.2.0 includes a comprehensive example workflow that demonstrates all major package capabilities:\r\n\r\n```python\r\n# Clone the repository and navigate to the usage example\r\ngit clone https://github.com/simantalahkar/lammpskit.git\r\ncd lammpskit/usage/ecellmodel\r\n\r\n# Run the complete analysis workflow\r\npython run_analysis.py\r\n```\r\n\r\nThis workflow demonstrates four main analysis types:\r\n1. **Filament Evolution Tracking** - Monitor filament connectivity and structural changes over time\r\n2. **Displacement Analysis** - Compare atomic displacements across different species (Hf, O, Ta)\r\n3. **Charge Distribution Analysis** - Analyze local charge distributions in electrochemical systems\r\n4. **Atomic Distribution Analysis** - Study atomic distributions under different applied voltages\r\n\r\nGenerated plots and analysis results are saved to `usage/ecellmodel/output/`.\r\n\r\n### Package Structure\r\n\r\nLAMMPSKit v1.2.0 features a modular architecture:\r\n\r\n```\r\nlammpskit/\r\n\u251c\u2500\u2500 io/ # Data reading and I/O operations\r\n\u251c\u2500\u2500 plotting/ # Visualization utilities and timeseries plots\r\n\u251c\u2500\u2500 ecellmodel/ # Electrochemical analysis functions\r\n\u2514\u2500\u2500 config.py # Centralized configuration management\r\n```\r\n\r\n## Docker Image\r\n\r\nAn official Docker image for **lammpskit** is available on [Docker Hub](https://hub.docker.com/r/simantalahkar/lammpskit).\r\nUsing the Docker container provides a portable, reproducible environment with all dependencies pre-installed for running and testing lammpskit anywhere Docker is supported.\r\n\r\n### How to Use\r\n\r\n1. **Install Docker** on your system. \r\n See [Get Docker](https://docs.docker.com/get-docker/) for instructions.\r\n\r\n2. **Pull the latest image:**\r\n ```sh\r\n docker pull simantalahkar/lammpskit:latest\r\n ```\r\n Or pull a specific version:\r\n ```sh\r\n docker pull simantalahkar/lammpskit:1.2.0\r\n ```\r\n\r\n3. **Run the container with your local data mounted as a volume:**\r\n ```sh\r\n docker run -it -v /path/to/your/data:/data simantalahkar/lammpskit:latest\r\n ```\r\n This starts a bash shell in the container. Your local data is accessible at `/data`.\r\n\r\n4. **Use the installed Python package:**\r\n ```sh\r\n python\r\n >>> import lammpskit\r\n # ...your analysis code...\r\n ```\r\n\r\n5. **Copy custom scripts or files into the container (from another terminal):**\r\n ```sh\r\n docker cp /path/to/local/script.py <container_id>:/home/lammpsuser/\r\n ```\r\n You can also install additional Python packages inside the container:\r\n ```sh\r\n pip install <package-name>\r\n ```\r\n\r\n6. **Exit the container after analysis:**\r\n ```sh\r\n exit\r\n ```\r\n The container will remain on your system for future use. \r\n To re-enter the container:\r\n ```sh\r\n docker start <container_id>\r\n docker exec -it <container_id> bash\r\n ```\r\n To delete the container completely:\r\n ```sh\r\n docker rm <container_id>\r\n ```\r\n\r\n## Installation (PyPI)\r\n\r\nFor end users (runtime):\r\n```sh\r\npip install lammpskit\r\n```\r\n\r\nFor development and testing:\r\n```sh\r\n# Method 1: Using optional dependencies (recommended)\r\npip install -e .[dev]\r\n\r\n# Method 2: Manual installation (fallback)\r\npip install -e .\r\npip install -r requirements-dev.txt\r\n```\r\n\r\n## Development and Testing Environment\r\n\r\nAll runtime dependencies are listed in `requirements.txt`. Development and test dependencies are available in multiple formats:\r\n- `[project.optional-dependencies]` in `pyproject.toml` (modern standard)\r\n- `requirements-dev.txt` (traditional method) \r\n- `extras_require` in `setup.py` (legacy compatibility)\r\n\r\nTo set up a development environment and run tests locally:\r\n```sh\r\n# Recommended approach with fallback\r\npip install -e .[dev] || (pip install -e . && pip install -r requirements-dev.txt)\r\npytest\r\n```\r\nTests are not shipped with the PyPI package, but are available in the source repository for development and validation.\r\n\r\n\r\n## Test Coverage & Visual Regression Testing\r\n\r\nLAMMPSKit v1.2.0 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.\r\n\r\n### Test Organization\r\n- `tests/test_io.py` - I/O function validation\r\n- `tests/test_plotting.py` - General plotting utilities \r\n- `tests/test_timeseries_plots.py` - Timeseries plotting functions\r\n- `tests/test_centralized_font_control.py` - Font and styling consistency\r\n- `tests/test_ecellmodel/` - Analysis function validation (subdirectory)\r\n- `tests/test_config.py` - Configuration management\r\n- `tests/baseline/` - **Centralized baseline images for all visual tests**\r\n\r\n### Running Tests Locally\r\n```sh\r\n# Install with development dependencies\r\npip install .[dev]\r\n\r\n# Run all tests\r\npytest\r\n\r\n# Run with visual regression testing\r\npytest --mpl\r\n\r\n# Generate new baseline images (when plots change intentionally)\r\npytest --mpl-generate-path=tests/baseline tests/\r\n\r\n# Run tests with coverage\r\npytest --cov=lammpskit --cov-report=html\r\n```\r\n\r\n### Visual Regression Testing Architecture\r\n\r\n**Centralized Baseline Directory Structure:**\r\n```\r\ntests/\r\n\u251c\u2500\u2500 baseline/ # All baseline images (centralized)\r\n\u251c\u2500\u2500 test_*.py # Root level tests \u2192 \"baseline\"\r\n\u251c\u2500\u2500 test_ecellmodel/ # Subdirectory tests \u2192 \"../baseline\"\r\n\u2502 \u2514\u2500\u2500 test_*.py # Use relative paths to centralized location\r\n\u2514\u2500\u2500 conftest.py # Shared pytest configuration\r\n```\r\n\r\n**Key Benefits:**\r\n- **Cross-platform compatibility**: Relative paths work on Windows, Linux, macOS\r\n- **Container compatibility**: Works identically in Docker and local environments \r\n- **Maintainability**: Single location for all baseline images\r\n- **CI/CD integration**: Simplified path handling in GitHub Actions and Docker\r\n\r\n**Implementation Pattern:**\r\n```python\r\n# For tests in tests/ directory (root level)\r\nBASELINE_DIR_RELATIVE = \"baseline\"\r\n\r\n# For tests in tests/test_ecellmodel/ directory (subdirectory) \r\nBASELINE_DIR_RELATIVE = \"../baseline\"\r\n\r\n@pytest.mark.mpl_image_compare(baseline_dir=BASELINE_DIR_RELATIVE, remove_text=True)\r\ndef test_plotting_function():\r\n # Test implementation returns matplotlib figure\r\n return figure\r\n```\r\n\r\nTests 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.\r\n\r\n\r\n## Data Format Examples\r\n\r\n### LAMMPS Trajectory File (`.lammpstrj`)\r\n```\r\nITEM: TIMESTEP\r\n1200000\r\nITEM: NUMBER OF ATOMS\r\n5\r\nITEM: BOX BOUNDS pp pp pp\r\n0.0 50.0\r\n0.0 50.0\r\n0.0 50.0\r\nITEM: ATOMS id type q x y z ix iy iz vx vy vz c_eng\r\n1 2 0.1 1.0 2.0 3.0 0 0 0 0 0 0 0\r\n2 1 -0.2 2.0 3.0 4.0 0 0 0 0 0 0 0\r\n... (one line per atom)\r\n```\r\n\r\n### Processed Displacement Data File\r\n```\r\n# header1\r\n# header2\r\n# header3\r\n0 2\r\n1.0 3.0\r\n2.0 4.0\r\n# end loop\r\n```\r\n\r\n## Main Functions\r\n\r\n### `read_structure_info(filepath)`\r\nReads a LAMMPS trajectory file and returns timestep, atom count, and box dimensions. Robust to missing/malformed data.\r\n\r\n### `read_coordinates(file_list, skip_rows, columns_to_read)`\r\nLoads atomic coordinates and simulation cell parameters from a list of trajectory files.\r\n\r\n### `read_displacement_data(filepath, loop_start, loop_end, repeat_count=0)`\r\nReads binwise averaged displacement data from processed output files, handling chunked data and errors.\r\n\r\n### `plot_multiple_cases(x_arr, y_arr, labels, xlabel, ylabel, output_filename, xsize, ysize, ...)`\r\nGeneral plotting utility for 1D/2D arrays, supporting various plot customizations.\r\n\r\n### `plot_atomic_distribution(file_list, labels, skip_rows, z_bins, analysis_name, output_dir)`\r\nReads coordinates, computes atomic distributions (O, Hf, Ta, metals), and plots stoichiometry and atom counts.\r\n\r\n### `plot_atomic_charge_distribution(file_list, labels, skip_rows, z_bins, analysis_name, output_dir)`\r\nComputes and plots charge distributions and mean charges for atom types.\r\n\r\n### `plot_displacement_comparison(file_list, loop_start, loop_end, labels, analysis_name, repeat_count, output_dir)`\r\nReads displacement data for multiple cases, plots z/lateral displacements vs. bin positions.\r\n\r\n### `analyze_clusters(filepath)`\r\nUses OVITO to perform cluster analysis, coordination, and connectivity checks on metallic atoms, returning filament properties.\r\n\r\n### `track_filament_evolution(file_list, analysis_name, time_step, dump_interval_steps, output_dir)`\r\nTracks filament connectivity/gap/separation/size over time, and generates summary plots.\r\n\r\n### `plot_displacement_timeseries(file_list, datatype, dataindex, Nchunks, loop_start, loop_end, output_dir)`\r\nPlots time series of displacement data for selected data indices.\r\n\r\n### `run_analysis(...)`\r\nOrchestrates all analysis workflows, setting up parameters, file lists, and calling the above functions for various scenarios.\r\n\r\n\r\n## Changelog\r\n\r\nSee the [CHANGELOG.md](https://github.com/simantalahkar/lammpskit/blob/main/CHANGELOG.md) for a detailed list of changes and updates.\r\n\r\n## Citation\r\n\r\nIf you use this package in your research, please cite:\r\n\r\nS. 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\r\n\r\n\r\n## License\r\n\r\nGPL-3.0-or-later\r\n\r\n## Author\r\n\r\nSimanta Lahkar\r\n\r\n## Links\r\n\r\n- [Homepage](https://github.com/simantalahkar/lammpskit)\r\n- [Documentation](https://lammpskit.readthedocs.io/en/latest/)\r\n- [Changelog](./CHANGELOG.md)\r\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A Python toolkit for advanced LAMMPS data processing and scientific simulation analysis.",
"version": "1.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/simantalahkar/lammpskit/issues",
"Changelog": "https://github.com/simantalahkar/lammpskit/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/simantalahkar/lammpskit/discussions",
"Documentation": "https://lammpskit.readthedocs.io/en/latest/",
"Homepage": "https://github.com/simantalahkar/lammpskit",
"Source": "https://github.com/simantalahkar/lammpskit"
},
"split_keywords": [
"lammps",
" molecular-dynamics",
" reram",
" electrochemical",
" memory-devices",
" filament-analysis",
" hftao",
" materials-science"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a75580b2e68647223331364247aac5c57ca474ad1a29c2feca378a7ad8df0ee8",
"md5": "f932b0fccc9c8ea3cb152f599ea93d2b",
"sha256": "4e4a5d3c3ebfcd0a9785e8db0e4013f1e9a3deb62693fc57257c91868ea08691"
},
"downloads": -1,
"filename": "lammpskit-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f932b0fccc9c8ea3cb152f599ea93d2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 9332431,
"upload_time": "2025-07-28T23:25:31",
"upload_time_iso_8601": "2025-07-28T23:25:31.717207Z",
"url": "https://files.pythonhosted.org/packages/a7/55/80b2e68647223331364247aac5c57ca474ad1a29c2feca378a7ad8df0ee8/lammpskit-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 23:25:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "simantalahkar",
"github_project": "lammpskit",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"2.3.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.10.3"
]
]
},
{
"name": "ovito",
"specs": [
[
">=",
"3.12.4"
]
]
}
],
"lcname": "lammpskit"
}
JSON
