Installation¶

BioNeuralNet is tested with Python 3.10, 3.11, and 3.12 and supports Windows, macOS, and Linux platforms. Follow these steps to install BioNeuralNet along with the necessary dependencies.

Recommended System Requirements¶

Recommended system requirements for running BioNeuralNet.¶
Component	Recommendation
Operating System	Linux, macOS, or Windows
Python Version	3.10 - 3.12
Processor (CPU)	Modern multi-core CPU (Intel i5/i7, AMD Ryzen 5/7); for large datasets/models: high-core CPUs like Intel Xeon or AMD EPYC
Memory (RAM)	Minimum 8GB; 16GB recommended for standard workflows; 32GB+ for large-scale models
Storage	Minimum 64GB for system and software; SSD recommended; 500GB+ for large datasets
GPU (Optional but recommended)	NVIDIA GPU with >= 6GB VRAM or Intel Arc GPU for faster training; ensure drivers and CUDA/cuDNN versions match PyTorch
Notes	GPU acceleration significantly improves training speed; hardware requirements increase with model and dataset size. If you have an NVIDIA graphics card or an M-series Mac chip, please see the respective installation instructions below.

Install BioNeuralNet via pip

The core modules, including graph embeddings, disease prediction (DPMON), and clustering, can be installed directly:
```
pip install bioneuralnet
```
This will also install the required Ray components for hyperparameter tuning (Ray Tune and Ray Train).
Install PyTorch and PyTorch Geometric (Required for GNNs and DPMON)

BioNeuralNet utilizes PyTorch and PyTorch Geometric for graph neural network computations (e.g., GNN embeddings and the DPMON model). These are not pinned automatically because GPU/CPU builds and CUDA versions vary by system, so you should install them separately.

Basic installation (CPU-only or simple environments):
```
pip install torch
pip install torch_geometric
```
If this fails or you need a GPU-enabled build, please follow the official installation guides to select the correct wheels for your OS, Python version, and CUDA:
- PyTorch Installation Guide
- PyTorch Geometric Installation Guide
Note

On Apple Silicon (M1/M2/M3) Macs, PyTorch can use the Metal (MPS) backend instead of CUDA. For details and recommended installation commands, see the official guide:
- PyTorch on Metal (Apple Developer)
Example tested GPU configuration (Windows/Linux + CUDA 11.8)

The following versions have been tested with DPMON and GNN-based workflows:
```
pip install "torch==2.7.0+cu118" --index-url https://download.pytorch.org/whl/cu118
pip install "torch_geometric==2.6.1"
```
Note

If you are working on Windows, we recommend installing Git Bash so that all shell commands in this documentation work as written. You can install Git for Windows (which includes Git Bash) from:
- Git for Windows Installer
Troubleshooting: CUDA / PyG compatibility

If you are using an NVIDIA graphics card, you must ensure that the CUDA version used by PyTorch and the wheels for PyTorch Geometric (and its extensions) match. When they do not, you may encounter segmentation faults during import.

The following block uninstalls all relevant torch and PyTorch Geometric libraries and reinstalls a known-working combination (Linux + CUDA 11.8). You can copy and paste this block into your terminal. If it fails, try running each line one by one:
```
pip uninstall pyg-lib torch torchvision torchaudio torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -y

pip install --no-cache-dir "torch==2.7.0+cu118" --index-url https://download.pytorch.org/whl/cu118
pip install --no-cache-dir pyg-lib -f https://data.pyg.org/whl/torch-2.7.0+cu118.html

pip install --no-cache-dir torch-scatter -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
pip install --no-cache-dir torch-sparse -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
pip install --no-cache-dir torch-cluster -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
pip install --no-cache-dir torch-spline-conv -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
pip install --no-cache-dir torch-geometric -f https://data.pyg.org/whl/torch-2.7.0+cu118.html
```
After running the above, you can verify your installation with:
```
python -c "import torch_geometric; from torch_scatter import scatter_add; print('OK')"
```
Ray for Hyperparameter Tuning (DPMON and Other HPO Workflows)

BioNeuralNet uses Ray Tune and Ray Train for hyperparameter optimization and checkpointing in components such as DPMON.

If you installed BioNeuralNet via pip in a standard environment, Ray with the necessary extras should be installed automatically. For reproducibility, or if your environment strips extras, you can explicitly install the tested Ray version:
```
pip install "ray[tune,train]==2.46.0"
```
This ensures compatibility with the hyperparameter tuning utilities used throughout the library.
Core Python Dependencies

BioNeuralNet is built on a standard scientific Python stack. While the installer handles these automatically, we are transparent about the specific versions used in our testing environment:
```
pandas = 2.2.3
numpy = 1.26.4
scipy = 1.13.1
matplotlib = 3.10.3
scikit-learn = 1.6.1
statsmodels = 0.14.4
networkx = 3.4.2
python-louvain = 0.16
pydantic >= 2.5
ray[tune,train] = 2.46.0
```
Our packaging specifies minimum versions for these dependencies; pip may install newer compatible releases depending on your environment.
Optional: Install R and External Tools (e.g., SmCCNet)

For advanced network construction using external R tools like SmCCNet, follow these additional steps:
- Install R (version 4.4.2 or newer recommended) from the R Project.
- Within R, install the required packages:
```
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

install.packages(c("dplyr", "jsonlite"))
BiocManager::install(c("impute", "preprocessCore", "GO.db", "AnnotationDbi"))
install.packages("SmCCNet")
install.packages("WGCNA")
```
See External Tools for further details on external tools.

Next Steps¶

After installation, explore our step-by-step tutorials: