BioGrids Capsules

BioGrids uses a modern "capsule" environment system that provides isolated, containerized software environments. This approach ensures consistent behavior, prevents software conflicts, and makes version management simple and reliable.

What are BioGrids Capsules?

Capsules are lightweight, isolated environments that contain: - Pre-compiled software binaries - All necessary dependencies - Environment configurations - Runtime libraries

Each software package runs in its own capsule, preventing conflicts between different applications or versions.

Benefits of the Capsule System

Isolation and Consistency

• No conflicts: Software packages can't interfere with each other
• Reproducible results: Same behavior across different systems
• Clean environment: No dependency pollution

Easy Version Management

• Multiple versions: Install and use multiple versions simultaneously
• Quick switching: Change versions instantly with environment variables
• No conflicts: Different versions don't interfere with each other

Performance Optimization

• Pre-compiled: Optimized binaries for best performance
• Fast startup: Quick initialization compared to traditional containers
• Low overhead: Minimal performance impact

How Capsules Work

Automatic Activation

When you run BioGrids software, the capsule system:

1. Detects the requested application
2. Loads the appropriate capsule
3. Sets up the environment
4. Runs the software

This happens transparently - you just run software by name.

Environment Variables

The capsule system respects environment variables for version control:

# Use specific version
export SAMTOOLS_X=1.12  # Linux
export SAMTOOLS_M=1.12  # macOS
samtools --version

Dependency Resolution

Capsules automatically handle dependencies: - Shared libraries are included or referenced correctly - Python/R packages are isolated per application - No system-wide dependency conflicts

Using Capsules

Basic Usage

Simply initialize BioGrids and run software:

source /programs/biogrids.shrc
samtools --help
blast --version
python --version

Version Control

Check available versions:

biogrids-info -l samtools

Use specific versions:

export SAMTOOLS_X=1.12
samtools --version

Environment Inspection

See what's in your current environment:

echo $BIOGRIDS_VERSION
biogrids-list samtools

Capsule Architecture

File System Layout

/programs/
├── capsules/           # Capsule definitions
├── x86_64-linux/       # Linux binaries
├── i386-mac/           # macOS binaries
├── shared/             # Shared resources
└── environment/        # Environment scripts

Capsule Components

Each capsule contains: - Binary executables: The actual software - Libraries: Required shared libraries - Configuration: Default settings and paths - Metadata: Version information and dependencies

Runtime Environment

When a capsule activates: - PATH is updated to include capsule binaries - LD_LIBRARY_PATH includes necessary libraries - Environment variables are set appropriately - Working directory remains unchanged

Advanced Features

Custom Configurations

You can customize capsule behavior:

# Set custom options for specific software
export BLAST_OPTIONS="--num-threads=8"

# Use custom data paths
export BLAST_DB_PATH="/data/blast-db"

Integration with Job Schedulers

Capsules work seamlessly with HPC schedulers:

#!/bin/bash
#SBATCH --nodes=1
#SBATCH --tasks-per-node=8

source /programs/biogrids.shrc
export BLAST_X=2.12.0
blastn -query input.fasta -db nt -out results.txt

Container Compatibility

Capsules can run inside containers:

FROM ubuntu:20.04
RUN apt-get update && apt-get install -y curl
COPY biogrids-install.sh /tmp/
RUN /tmp/biogrids-install.sh
ENV PATH="/programs/bin:$PATH"

Troubleshooting Capsules

Common Issues

Software not found:

# Check if BioGrids is initialized
echo $BIOGRIDS_VERSION

# Reinitialize if needed
source /programs/biogrids.shrc

Wrong version:

# Check current version
biogrids-info -l software-name

# Set specific version
export SOFTWARE_X=desired-version

Performance issues:

# Check if running from slow storage
df -h /programs

# Consider local installation for better performance

Environment Debugging

# Show all BioGrids environment variables
env | grep -i biogrids

# List loaded capsules
biogrids-status

# Show capsule details
biogrids-info -v software-name

Comparison with Other Systems

vs. Traditional Package Managers

Feature	BioGrids Capsules	System Packages
Isolation	✓ Complete	✗ Shared
Multiple Versions	✓ Yes	✗ Limited
No Root Required	✓ Yes	✗ No
Performance	✓ Optimized	~ Variable

vs. Docker/Singularity

Feature	BioGrids Capsules	Containers
Startup Speed	✓ Fast	~ Slower
Resource Overhead	✓ Minimal	~ Higher
File System Access	✓ Native	~ Mounted
Integration	✓ Seamless	~ Complex

vs. Environment Modules

Feature	BioGrids Capsules	Modules
Dependency Management	✓ Automatic	~ Manual
Version Conflicts	✓ Prevented	✗ Possible
Setup Complexity	✓ Simple	~ Complex

Migration from Legacy Systems

From Module Systems

If you're used to environment modules:

# Instead of: module load samtools/1.12
export SAMTOOLS_X=1.12
samtools

# Instead of: module list
biogrids-info -l

From Conda/Mamba

If you're coming from Conda:

# Instead of: conda activate myenv
source /programs/biogrids.shrc

# Instead of: conda install samtools=1.12
# Software is already available, just specify version
export SAMTOOLS_X=1.12

From Manual Installations

Replace manual PATH management:

# Instead of: export PATH=/path/to/software/bin:$PATH
# Just initialize BioGrids:
source /programs/biogrids.shrc

Future Developments

Planned Features

• Custom capsules: Create your own software capsules
• Capsule sharing: Share capsule definitions between institutions
• Cloud integration: Seamless cloud deployment of capsules
• GPU capsules: Specialized capsules for GPU-accelerated software

Performance Improvements

• Lazy loading: Load capsules only when needed
• Caching: Intelligent caching of frequently used capsules
• Parallelization: Faster capsule initialization

Getting Help

Documentation

• Quick Start Guide: Basic usage examples
• Installation Overview: Installation guidance
• FAQ: Common questions and answers

Support

• Email: help@biogrids.org
• Community: Mailing list
• Help Center: Support resources

---

Ready to use capsules? Initialize your BioGrids environment and start using isolated, optimized software packages today!