gRINN: Protein Energy Networks from Molecular Dynamics

🚧 Development Notice: This tool is currently under active development. We welcome users to test gRINN and report any issues they encounter in the Issues section.

gRINN (get Residue Interaction Energies and Networks) calculates pairwise residue interaction energies from GROMACS MD trajectories or conformational ensembles and builds energy-based protein networks. Includes an interactive web dashboard for 3D visualization and analysis.

Input Modes

Trajectory Mode - Analyze existing MD simulation:

• Structure: PDB (.pdb)
• Trajectory: XTC (.xtc)
• Topology: TOP (.top)

Ensemble Mode - Analyze conformational ensemble:

• Multi-model PDB file (multiple MODEL entries)
• Topology generated automatically

Quick Start

Docker (Recommended)

Build:

./build-grinn.sh 2024.1  # Linux/Mac - Full version with GROMACS
./build-grinn.sh --dashboard-only  # Lightweight dashboard-only (no GROMACS)
docker build --build-arg GROMACS_VERSION=2024.1 -t grinn:gromacs-2024.1 .  # Windows

💡 Tip: Use --dashboard-only for a lightweight (~500MB) image that only includes the visualization dashboard, perfect for viewing pre-computed results. See DASHBOARD-ONLY.md for details.

Run Trajectory Mode:

docker run -v /path/to/data:/data grinn:gromacs-2024.1 workflow \
  /data/protein.pdb /data/results --traj /data/trajectory.xtc --top /data/topology.top

Run Ensemble Mode:

docker run -v /path/to/data:/data grinn:gromacs-2024.1 workflow \
  /data/ensemble.pdb /data/results --ensemble_mode

Launch Dashboard:

# Basic dashboard
docker run -p 8060:8060 -v /path/to/data:/data grinn:gromacs-2024.1 dashboard /data/results

# Dashboard with AI chatbot (requires Docker socket + API key)
docker run -p 8060:8060 \
  -v /path/to/data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GEMINI_API_KEY=your_api_key \
  grinn:gromacs-2024.1 dashboard /data/results

# Open http://localhost:8060

Conda Alternative

conda env create -f environment.yml
conda activate grinn

# Trajectory mode
python grinn_workflow.py protein.pdb results/ --traj trajectory.xtc --top topology.top

# Ensemble mode
python grinn_workflow.py ensemble.pdb results/ --ensemble_mode

# Dashboard
python gRINN_Dashboard/grinn_dashboard.py results/

Common Options

• --ensemble_mode - Process multi-model PDB
• --create_pen - Generate Protein Energy Networks
• --skip N - Analyze every N-th frame (for large trajectories)
• --nt N - Number of threads (auto-detects by default)
• --force_field - Force field for topology (default: amber99sb-ildn)
• --test-only - Validate inputs without running analysis

Output Files

• energies_intEnTotal.csv - Total interaction energies
• energies_intEnElec.csv - Electrostatic interactions
• energies_intEnVdW.csv - Van der Waals interactions
• pen_*.gml - Protein Energy Network files (with --create_pen)
• system_dry.pdb - Processed structure

Troubleshooting

Permission denied (Linux):

sudo usermod -aG docker $USER  # Log out and back in
sudo systemctl start docker

Docker not running:

• Linux: sudo systemctl start docker
• Windows/Mac: Start Docker Desktop

Out of memory / large trajectories:

docker run -v /path/to/data:/data grinn:gromacs-2024.1 workflow \
  /data/protein.pdb /data/results --traj /data/trajectory.xtc --top /data/topology.top --skip 10

Windows paths:

docker run -v C:/Users/YourName/data:/data grinn:gromacs-2024.1 workflow ...
# With spaces: -v "C:/My Data":/data

Port 8060 in use:

docker run -p 8062:8060 -v /path/to/data:/data grinn:gromacs-2024.1 dashboard /data/results
# Access via http://localhost:8062

Input requirements:

• Structure: PDB format only
• Trajectory: XTC format (trajectory mode)
• Topology: TOP format (trajectory mode)
• Ensemble: Multi-model PDB with MODEL/ENDMDL entries

Report issues at Issues.

Contributing

See CONTRIBUTING.md for guidelines.

License

Copyright 2024-2025. Available for academic and research use only. See LICENSE for details.