Installation¶
This guide walks you through installing LearnM8 and its dependencies.
Prerequisites¶
Python Version: LearnM8 requires Python 3.11.9 or compatible versions. We recommend using Conda for environment management.
System Requirements:
- 64-bit operating system (Linux, macOS, or Windows)
- 4+ GB RAM (8+ GB recommended for large compound libraries)
- Internet connection for initial installation
Basic Installation¶
Step 1: Create Conda Environment¶
LearnM8 provides an environment configuration file for easy setup:
This creates a new Conda environment named learnm8 with all core dependencies.
Step 2: Install LearnM8¶
Install LearnM8 in editable mode:
The -e flag installs in development/editable mode, allowing you to modify the source code if needed.
Step 3: Verify Installation¶
Test that LearnM8 is correctly installed:
You should see the main help message with available subcommands (run, validate).
Optional Dependencies¶
LearnM8's core functionality works with the basic installation. Additional features require optional dependencies.
PyTorch Models (MLP, MCDropout, Fastprop)¶
PyTorch-based neural network models require PyTorch:
For GPU acceleration:
Visit pytorch.org for platform-specific installation instructions.
Chemprop (Graph Neural Networks)¶
For state-of-the-art graph neural network models:
Chemprop requires PyTorch. It works directly with SMILES strings without requiring featurizers.
XGBoost (Gradient Boosting)¶
For high-performance gradient boosting:
All Optional Dependencies¶
Install all optional features at once:
Testing Your Installation¶
Basic Functionality Test¶
Verify core functionality with pytest:
This runs unit tests that don't require optional dependencies.
Full Test Suite¶
If you have all optional dependencies installed:
Quick CLI Test¶
Test the command-line interface:
Or from Python to list available components:
from learnm8.api import list_available_learners
from learnm8.features import FEATURIZER_REGISTRY
from learnm8.acquisition import ACQUISITION_REGISTRY
print(list_available_learners())
print(sorted(FEATURIZER_REGISTRY))
print(sorted(ACQUISITION_REGISTRY))
Development Installation¶
If you plan to contribute to LearnM8 or modify the source code:
Install with Test Dependencies¶
This installs additional testing tools:
pytest- Test frameworkpytest-cov- Coverage reportinghypothesis- Property-based testing
Run Tests with Coverage¶
Coverage reports are generated in htmlcov/index.html.
Install Documentation Dependencies¶
For building documentation locally:
Troubleshooting¶
RDKit Installation Issues¶
RDKit is included in the Conda environment file. If you encounter issues:
SMILES Validation Fails¶
LearnM8 uses datamol for SMILES validation. Ensure it's installed:
Cache Directory Errors¶
Feature caching requires write permissions. If you see cache-related errors:
# Specify a custom cache directory
learnm8 run compounds.csv --target Activity --learner gp --featurizer morgan --cache-dir /tmp/learnm8_cache
GPU Not Detected (PyTorch Models)¶
Verify PyTorch sees your GPU:
If False, reinstall PyTorch with CUDA support (see PyTorch installation section above).
Platform-Specific Notes¶
Linux¶
No special considerations. All dependencies install cleanly on modern Linux distributions.
macOS¶
Conda installation is recommended on macOS. If using Apple Silicon (M1/M2):
Windows¶
Use Conda for Windows. Windows Subsystem for Linux (WSL2) is recommended for best compatibility.
Updating LearnM8¶
To update to the latest version:
If dependencies have changed, recreate the Conda environment:
conda env remove -n learnm8
conda env create -f environment.yml
conda activate learnm8
pip install -e .
Next Steps¶
With LearnM8 installed, you're ready to:
- Run your first experiment - Get started in under 5 minutes
- Understand core concepts - Learn active learning fundamentals
- Explore tutorials - Detailed workflow guides