# MCP LAMMPS Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) for molecular dynamics simulations.

## Status

This is still in experimental status. This package is developed in collaboration with AI coder.

### Update 06.12.2025
Note: all tests are performed with Sonnet 4.5

Add support for organic liquids simulations with gaff

simple test prompt:

Organic Liquid Simulation
```
Create a complete organic liquid simulation with these parameters:
- Name: "ethanol_liquid_md"
- Molecules: [{"smiles": "CCO", "count": 500, "name": "ethanol"}]
- Target density: 0.789 g/cm³
- Force field: GAFF
- Temperature: 298.15 K
- Pressure: 1.0 atm
- Timestep: 0.5 fs
- Equilibration: 10000 steps
- Production: 100000 steps
```

Multi-Component Simulation
```
Set up a ternary mixture simulation called "organic_solvent_mix":
- Ethanol (CCO): 30% mole fraction
- Acetone (CC(=O)C): 40% mole fraction  
- Toluene (Cc1ccccc1): 30% mole fraction
- Temperature: 300 K
- Pressure: 1 atm
- Equilibration: 20000 steps
- Production: 200000 steps
```


## Overview

This MCP is part of our workflow for the autonomous computational materials design with LLM. This MCP server provides a standardized interface for controlling LAMMPS molecular dynamics simulations through natural language commands. It enables AI assistants to:

- Set up and configure molecular dynamics simulations
- Run equilibration and production simulations
- Monitor simulation progress in real-time
- Analyze simulation results
- Manage simulation workflows

## Features

### Core Capabilities
- **Simulation Management**: Create, configure, and run LAMMPS simulations
- **Molecular Structure Processing**: Convert SMILES to 3D structures, assign GAFF atom types
- **Force Field Support**: GAFF (General AMBER Force Field) parameter assignment
- **LAMMPS Data File Generation**: Create simulation input files from molecular structures
- **Real-time Monitoring**: Track simulation progress and system properties
- **Analysis Tools**: Process trajectories and calculate thermodynamic properties (with MDAnalysis)
- **Charge Calculation**: Gasteiger, MMFF94, and GAFF charge estimation methods
- **Workflow Automation**: Define and execute multi-step simulation workflows
- **SLURM Integration**: Submit and manage simulations on HPC clusters (optional)

### Supported Molecular Systems
- Small organic molecules
- Liquid systems and mixtures
- Polymer systems
- Custom molecular structures via SMILES or coordinate files

## Installation

### Prerequisites
- Python 3.9 or higher
- LAMMPS with Python interface
- RDKit (for molecular structure processing)
- **Packmol** (for organic liquid box creation with proper molecular packing)

### System Dependencies

**Packmol Installation** (Required for organic liquid simulations):
```bash
# Ubuntu/Debian
sudo apt install packmol

# macOS (Homebrew)
brew install packmol

# From source
# Download from http://m3g.iqm.unicamp.br/packmol/
```

### Optional Dependencies
- MDAnalysis (for advanced trajectory analysis)
- OpenBabel (for additional molecular format conversion - requires system Open Babel libraries)
- pytraj (for additional trajectory analysis - requires cpptraj)
- SLURM (for HPC cluster job submission and management)

### Quick Start

1. **Clone the repository**:
   ```bash
   git clone https://github.com/mcp-lammps/mcp-lammps.git
   cd mcp-lammps
   ```

2. **Create a virtual environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Install in development mode**:
   ```bash
   pip install -e .
   ```

## Usage

### Basic Usage

Start the MCP server:

```bash
python -m mcp_lammps.server
```

### Configuration

The server can be configured through environment variables or configuration files:

```bash
export MCP_LAMMPS_LOG_LEVEL=INFO
export MCP_LAMMPS_WORK_DIR=/path/to/workspace
python -m mcp_lammps.server
```

### SLURM Cluster Integration

For HPC cluster environments, MCP LAMMPS supports SLURM job submission:

1. Configure `slurm_config.yaml` in your workspace:
```yaml
global_defaults:
  partition: "compute"
  nodes: 1
  ntasks_per_node: 4
  time_limit: "24:00:00"
```

2. Submit simulations to SLURM cluster via AI commands or programmatically

See [SLURM Integration Guide](docs/slurm-guide.md) for detailed instructions.

### Example Prompts

**Basic Organic Molecule Simulation:**
```
Create a complete ethanol liquid simulation:
- SMILES: CCO
- 200 molecules
- Temperature: 298 K
- Pressure: 1 atm
- GAFF force field
- 10,000 equilibration steps, 50,000 production steps
```

**Multi-Component Mixture:**
```
Set up a binary mixture simulation:
- Component 1: Ethanol (CCO, 100 molecules)
- Component 2: Acetone (CC(=O)C, 100 molecules)
- Temperature: 300 K
- NPT ensemble
- GAFF force field
```

**Custom Molecule from SMILES:**
```
Create a simulation for ibuprofen:
- SMILES: CC(C)CC1=CC=C(C=C1)C(C)C(=O)O
- 50 molecules
- Calculate partial charges using Gasteiger method
- NVT ensemble at 310 K
```

## Development

### Project Structure
```
mcp_lammps/
├── src/mcp_lammps/
│   ├── server.py              # Main MCP server
│   ├── lammps_interface.py    # LAMMPS wrapper and control
│   ├── simulation_manager.py  # Simulation lifecycle management
│   ├── data_handler.py        # Data processing and file I/O
│   ├── tools/                 # MCP tool implementations
│   │   ├── setup_tools.py     # Simulation setup tools
│   │   ├── control_tools.py   # Simulation control tools
│   │   ├── analysis_tools.py  # Analysis and property calculation
│   │   ├── monitoring_tools.py # Real-time monitoring
│   │   └── organic_tools.py   # Organic molecule handling
│   ├── utils/                 # Utility modules
│   │   ├── molecular_utils.py # Molecular structure processing
│   │   ├── forcefield_utils.py # GAFF force field handling
│   │   ├── converters.py      # Format conversion utilities
│   │   └── helpers.py         # General helper functions
│   ├── parsers/               # Parameter file parsers
│   │   └── gaff_parser.py     # GAFF force field parser
│   └── data/                  # Force field data files
│       └── gaff_parameters.json
├── tests/                     # Comprehensive test suite
├── examples/                  # Usage examples and sample data
└── docs/                      # Documentation
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

This project is licensed under the Apache License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- LAMMPS development team for the molecular dynamics engine
- Model Context Protocol community for the MCP framework
- Scientific computing community for inspiration and feedback
- LLM for writing the code