Installation

Requirements

Runtime requirements (for using the package):

Python 3.12+
numpy ≥ 2.3.1
matplotlib ≥ 3.10.3
ovito ≥ 3.12.4

Development & testing requirements (for contributing, testing, or building):

All runtime requirements above
pytest ≥ 8.4.1
pytest-cov ≥ 6.2.1
pytest-mpl ≥ 0.17.0
sphinx ≥ 8.2.3
sphinx-autodoc-typehints ≥ 3.2.0
sphinx-rtd-theme ≥ 3.0.2

Install from PyPI

For end users (runtime):

pip install lammpskit

For development and testing:

# Primary method (modern pip with optional dependencies)
pip install lammpskit[dev]

# Alternative method (if above fails with older pip versions)
pip install lammpskit
pip install -r https://raw.githubusercontent.com/simantalahkar/lammpskit/main/requirements-dev.txt

Install from Source

Clone the repository and install:

git clone https://github.com/simantalahkar/lammpskit.git
cd lammpskit
pip install -e .

For development:

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 with older pip versions)
pip install -e . && pip install -r requirements-dev.txt

Docker Installation

An official Docker image is available on Docker Hub:

docker pull simantalahkar/lammpskit:latest

Run the container with your data mounted:

docker run -it -v /path/to/your/data:/data simantalahkar/lammpskit:latest

Verification

Verify your installation:

import lammpskit
print(lammpskit.__version__)

# Test basic functionality
from lammpskit.config import DEFAULT_COLUMNS_TO_READ
print("Installation successful!")

Development Setup

For contributing to LAMMPSKit:

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

# Recommended approach with automatic fallback
pip install -e .[dev] || (pip install -e . && pip install -r requirements-dev.txt)

# Run tests to verify setup
pytest

Alternative Installation Methods:

The package supports multiple dependency installation approaches for maximum compatibility:

Modern approach (Python 3.8+, pip 21.2+):
```
pip install -e .[dev]
```

Traditional approach (any pip version):

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

Hybrid approach (automatic fallback):

pip install -e .[dev] || (pip install -e . && pip install -r requirements-dev.txt)

The test suite includes 270+ test functions and 205 baseline images for visual regression testing.

Dependency Management

Automatic Dependency Detection in Documentation:

When dependencies change in pyproject.toml or requirements-dev.txt, documentation builds will automatically detect and use the updated dependencies because:

CI/CD Integration: GitHub Actions workflows install dependencies from the current repository state during each build
Live Installation: Documentation builds use pip install -e .[dev] which reads the current pyproject.toml
Read the Docs: Automatically pulls the latest repository state and installs current dependencies
Version Synchronization: The conf.py imports the package to get the current version dynamically

Dependency Configuration Files:

The package maintains dependencies in multiple formats for compatibility:

pyproject.toml - Modern Python packaging standard ([project.optional-dependencies])
requirements-dev.txt - Traditional pip requirements format
setup.py - Legacy setuptools format (extras_require)

Changes to any of these files are automatically reflected in the next documentation build cycle.

Troubleshooting

Common Installation Issues:

“No module named sphinx” Error:

Use the fallback installation method:
```
pip install -e . && pip install -r requirements-dev.txt
```
Optional Dependencies Not Found:

Older pip versions may not support [project.optional-dependencies]. Use:
```
pip install --upgrade pip
pip install -e .[dev]
```

CI/CD Build Failures:

GitHub Actions uses the hybrid approach automatically:

pip install -e .[dev] || (pip install -e . && pip install -r requirements-dev.txt)

Verify Installation:

python -c "import lammpskit; print('LAMMPSKit {} installed successfully'.format(lammpskit.__version__))"
python -m sphinx --version  # For development installations