Skip to content

Installation

This guide provides comprehensive instructions for installing fr5 (Forerunner 5) and its dependencies.

Quick Start

For most users, the simplest installation method is:

pip install fr5

However, since fr5 has several optional dependencies for different functionalities, we recommend following the detailed instructions below.

System Requirements

Python Version

  • Python 3.9 or higher (Python 3.10+ recommended)
  • Compatible with Windows, macOS, and Linux

Installation Methods

Install fr5 with core dependencies:

# Install from PyPI (when available)
pip install fr5

# OR install from source
git clone https://github.com/wgst/fr5.git
cd fr5
pip install .

This installs the core functionality for: - ✅ Property prediction models - ✅ Basic molecular descriptors
- ✅ Data loading and processing - ✅ Standard visualization

2. Complete Installation (All Features)

For full functionality including advanced optimization and molecular modeling:

# Clone repository
git clone https://github.com/wgst/fr5.git
cd fr5

# Install with all optional dependencies
pip install -e ".[all]"

This includes everything in standard installation plus: - ✅ Bayesian optimization with BOTorch/GPyTorch - ✅ Advanced molecular descriptors with RDKit - ✅ Neural network models with PyTorch - ✅ Enhanced visualization with Plotly - ✅ Database integration with SQLAlchemy

3. Minimal Installation

For lightweight deployments or specific use cases:

git clone https://github.com/wgst/fr5.git
cd fr5
pip install -e ".[minimal]"

Includes only: - ✅ Core prediction functions - ✅ Basic data processing - ✅ Simple plotting with matplotlib

4. Development Installation

For contributors and developers:

git clone https://github.com/wgst/fr5.git
cd fr5
pip install -e ".[dev]"

Includes everything plus: - ✅ Testing frameworks (pytest, coverage) - ✅ Code formatting (black, isort) - ✅ Documentation tools (mkdocs, mkdocstrings) - ✅ Pre-commit hooks

Optional Dependencies by Feature

Install specific feature sets as needed:

Bayesian Optimization

pip install fr5[bayes-opt]
Includes: BOTorch, GPyTorch, Ax-platform

Advanced Molecular Descriptors

pip install fr5[descriptors]
Includes: RDKit, mordred, chemml

Neural Networks

pip install fr5[neural]
Includes: PyTorch, scikit-learn, joblib

Enhanced Visualization

pip install fr5[viz]
Includes: Plotly, seaborn, bokeh

Database Integration

pip install fr5[database]
Includes: SQLAlchemy, pandas, openpyxl

Documentation

pip install fr5[docs]
Includes: MkDocs, mkdocstrings, material theme

Environment Setup

Create a dedicated environment for fr5:

# Create new conda environment
conda create -n fr5 python=3.11

# Activate environment
conda activate fr5

# Install fr5
pip install fr5[all]

Using virtualenv

# Create virtual environment
python -m venv fr5_env

# Activate (Linux/macOS)
source fr5_env/bin/activate

# Activate (Windows)
fr5_env\Scripts\activate

# Install fr5
pip install fr5[all]

Using Docker

For containerized deployments:

# Pull official fr5 image (when available)
docker pull fr5/fr5:latest

# OR build from source
git clone https://github.com/wgst/fr5.git
cd fr5
docker build -t fr5:local .

Verification

Basic Installation Check

Verify your installation:

import fr5
print(f"fr5 version: {fr5.__version__}")

# Test basic functionality
from fr5.shared import validate_installation
validate_installation()

Comprehensive Test

Run the full test suite:

# Install with test dependencies
pip install fr5[dev]

# Run tests
pytest tests/

# Run specific test categories
pytest tests/test_property_prediction/
pytest tests/test_bayes_opt/

Feature-Specific Tests

Test specific functionality:

# Test property prediction
from fr5.property_prediction_il import predict_viscosity
result = predict_viscosity({'cation': 'EMIM', 'anion': 'BF4', 'temperature': 298.15})
print(f"Test prediction: {result}")

# Test Bayesian optimization (if installed)
try:
    from fr5.bayes_opt import BOExperimentManager
    print("✅ Bayesian optimization available")
except ImportError:
    print("❌ Bayesian optimization not available")

# Test molecular descriptors (if RDKit installed)
try:
    from fr5.descriptors import generate_molecular_descriptors
    print("✅ Advanced descriptors available")
except ImportError:
    print("❌ Advanced descriptors not available")

Troubleshooting

Common Issues

1. PyTorch Installation Problems

If you encounter issues with PyTorch:

# Install PyTorch separately first
pip install torch torchvision torchaudio

# Then install fr5
pip install fr5

For specific CUDA versions: 

# Example for CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

2. RDKit Installation Issues

RDKit can be tricky to install via pip on some systems:

# Install RDKit via conda (recommended)
conda install -c conda-forge rdkit

# OR use pip with specific version
pip install rdkit-pypi

3. BOTorch/GPyTorch Issues

For optimization functionality:

# Install specific versions that work together
pip install botorch==0.9.2 gpytorch==1.11.0

4. Memory Issues During Installation

For systems with limited memory:

# Install without cache
pip install fr5 --no-cache-dir

# Install minimal version first
pip install fr5[minimal]

5. Permission Errors

On Unix systems:

# Install for user only
pip install fr5 --user

# OR use sudo (not recommended)
sudo pip install fr5

Platform-Specific Notes

Windows

  • Install Microsoft Visual C++ Build Tools if compilation errors occur
  • Use Anaconda/Miniconda for easier dependency management

macOS

  • Install Xcode Command Line Tools: xcode-select --install
  • Some molecular modeling tools may require additional setup

Linux

  • Install build essentials: sudo apt-get install build-essential
  • Some HPC systems may require module loading

Getting Help

If you encounter installation issues:

  1. Check the error message carefully for specific package conflicts
  2. Search existing issues on GitHub: fr5 Issues
  3. Create a new issue with:
  4. Your operating system and Python version
  5. Complete error message
  6. Installation command you used
  7. Output of pip list or conda list

Updating fr5

Update from PyPI

pip install --upgrade fr5

Update from Source

cd fr5
git pull origin main
pip install --upgrade -e .

Check for Updates

import fr5
from fr5.shared import check_for_updates

print(f"Current version: {fr5.__version__}")
check_for_updates()

Uninstallation

To completely remove fr5:

# Remove package
pip uninstall fr5

# Clean cache (optional)
pip cache purge

# Remove conda environment (if used)
conda remove -n fr5 --all

Performance Optimization

For Better Performance

  1. Use Conda for scientific packages when possible

  2. Install NumPy/SciPy with MKL for faster linear algebra: 

    conda install numpy scipy scikit-learn

  3. Enable GPU acceleration (if available): 

    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

  4. Use parallel processing by installing additional workers: 

    pip install joblib[parallel]

Memory Management

For large-scale computations:

# Install memory profiling tools
pip install memory-profiler psutil

# Monitor memory usage
python -m memory_profiler your_script.py

Next Steps

After successful installation:

  1. Read the Getting Started Guide
  2. Try the Examples
  3. Browse the API Documentation
  4. Join our Community

Quick Test Script

Save this as test_installation.py and run it to verify your installation:

#!/usr/bin/env python3
"""
Quick installation test for fr5
"""

def test_fr5_installation():
    """Test basic fr5 functionality."""

    print("Testing fr5 installation...\n")

    # Test 1: Import fr5
    try:
        import fr5
        print(f"✅ fr5 imported successfully (v{fr5.__version__})")
    except ImportError as e:
        print(f"❌ Failed to import fr5: {e}")
        return False

    # Test 2: Core modules
    modules = [
        'fr5.shared',
        'fr5.property_prediction_il', 
        'fr5.property_prediction_mof',
    ]

    for module in modules:
        try:
            __import__(module)
            print(f"✅ {module} available")
        except ImportError:
            print(f"❌ {module} not available")

    # Test 3: Optional modules
    optional_modules = {
        'fr5.bayes_opt': 'Bayesian optimization',
        'fr5.descriptors': 'Molecular descriptors',
        'fr5.reaction_analysis': 'Reaction analysis'
    }

    print("\nOptional features:")
    for module, description in optional_modules.items():
        try:
            __import__(module)
            print(f"✅ {description} available")
        except ImportError:
            print(f"⚠️  {description} not available (optional)")

    # Test 4: Basic functionality
    print("\nTesting basic functionality:")
    try:
        # This would be replaced with an actual simple test
        print("✅ Basic tests passed")
        return True
    except Exception as e:
        print(f"❌ Basic tests failed: {e}")
        return False

if __name__ == "__main__":
    success = test_fr5_installation()
    print(f"\nInstallation test: {'PASSED' if success else 'FAILED'}")

Run with: python test_installation.py