Installation#

This guide provides detailed instructions for installing Ex-Fuzzy on different platforms and environments.

Quick Install#

The easiest way to install Ex-Fuzzy is using pip:

pip install ex-fuzzy

This will install Ex-Fuzzy and all required dependencies.

Requirements#

System Requirements#

  • Python: 3.8 or later

  • Operating System: Windows, macOS, or Linux

  • Memory: At least 2GB RAM (4GB+ recommended for large datasets)

Dependencies#

Ex-Fuzzy depends on several well-established scientific Python packages:

Core Dependencies:

Package

Version

Purpose

numpy

≥1.19.0

Numerical computations and array operations

pandas

≥1.3.0

Data manipulation and analysis

scikit-learn

≥1.0.0

Machine learning utilities and metrics

matplotlib

≥3.3.0

Plotting and visualization

pymoo

≥0.6.0

Multi-objective evolutionary optimization

Optional Dependencies:

Package

Version

Purpose

evox

≥0.8.0

GPU-accelerated evolutionary optimization

torch

≥1.9.0

PyTorch for GPU acceleration (required by EvoX)

jupyter

≥1.0.0

For running notebook examples

seaborn

≥0.11.0

Enhanced statistical visualizations

plotly

≥5.0.0

Interactive plotting (experimental)

Installation Methods#

Method 2: Using conda#

Note

Conda package is coming soon! For now, use pip even in conda environments.

If you’re using conda, you can still install Ex-Fuzzy with pip:

conda create -n exfuzzy python=3.9
conda activate exfuzzy
pip install ex-fuzzy

Method 3: Development Installation#

For contributors or users who want the latest features:

# Clone the repository
git clone https://github.com/fuminides/ex-fuzzy.git
cd ex-fuzzy

# Install in development mode
pip install -e .

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

This installs Ex-Fuzzy in “editable” mode, so changes to the source code are immediately available.

Method 4: From Source Archive#

Download and install from a source archive:

# Download the latest release
wget https://github.com/fuminides/ex-fuzzy/archive/v1.0.0.tar.gz
tar -xzf v1.0.0.tar.gz
cd ex-fuzzy-1.0.0

# Install
pip install .

Platform-Specific Instructions#

Windows#

Option 1: Using Python from python.org

  1. Download Python 3.8+ from python.org

  2. During installation, check “Add Python to PATH”

  3. Open Command Prompt or PowerShell and run:

pip install ex-fuzzy

Option 2: Using Anaconda

  1. Download Anaconda from anaconda.com

  2. Open Anaconda Prompt and run:

pip install ex-fuzzy

macOS#

Option 1: Using Homebrew

# Install Python if not already installed
brew install python

# Install Ex-Fuzzy
pip3 install ex-fuzzy

Option 2: Using Anaconda

  1. Download Anaconda for macOS

  2. Open Terminal and run:

pip install ex-fuzzy

Linux (Ubuntu/Debian)#

# Install Python and pip if not already installed
sudo apt update
sudo apt install python3 python3-pip

# Install Ex-Fuzzy
pip3 install ex-fuzzy

Linux (CentOS/RHEL/Fedora)#

# Install Python and pip if not already installed
sudo yum install python3 python3-pip  # CentOS/RHEL
# OR
sudo dnf install python3 python3-pip  # Fedora

# Install Ex-Fuzzy
pip3 install ex-fuzzy

Virtual Environments#

It’s highly recommended to use virtual environments to avoid dependency conflicts:

Using venv (Python built-in)#

# Create virtual environment
python -m venv exfuzzy_env

# Activate it
# On Windows:
exfuzzy_env\\Scripts\\activate
# On macOS/Linux:
source exfuzzy_env/bin/activate

# Install Ex-Fuzzy
pip install ex-fuzzy

Using conda#

# Create conda environment
conda create -n exfuzzy python=3.9

# Activate it
conda activate exfuzzy

# Install Ex-Fuzzy
pip install ex-fuzzy

Using pipenv#

# Install pipenv if not already installed
pip install pipenv

# Create environment and install Ex-Fuzzy
pipenv install ex-fuzzy

# Activate the environment
pipenv shell

Verification#

Test your installation by running this simple Python script:

# test_installation.py
try:
    import ex_fuzzy
    print(f"✅ Ex-Fuzzy successfully imported!")
    print(f"📦 Version: {ex_fuzzy.__version__}")

    # Test basic functionality
    import ex_fuzzy.fuzzy_sets as fs
    import ex_fuzzy.evolutionary_fit as evf
    import numpy as np

    # Create a simple dataset
    X = np.random.rand(100, 4)
    y = np.random.randint(0, 3, 100)

    # Create a classifier
    classifier = evf.BaseFuzzyRulesClassifier(nRules=3, verbose=False)
    print("✅ Classifier created successfully!")

    print("🎉 Installation test passed!")

except ImportError as e:
    print(f"❌ Import error: {e}")
    print("Please check your installation.")
except Exception as e:
    print(f"⚠️  Warning: {e}")
    print("Basic import works, but there might be issues with dependencies.")

Save this as test_installation.py and run:

python test_installation.py

GPU Support#

Ex-Fuzzy currently runs on CPU only. GPU acceleration is planned for future releases.

Note

While Ex-Fuzzy doesn’t directly use GPUs, some operations may benefit from optimized BLAS libraries like Intel MKL or OpenBLAS, which are automatically used by NumPy when available.

Troubleshooting#

Common Issues#

Issue: pip install ex-fuzzy fails with permission errors

Solution: Use the --user flag or a virtual environment:

pip install --user ex-fuzzy

Issue: Import errors related to missing dependencies

Solution: Ensure all dependencies are installed:

pip install numpy pandas scikit-learn matplotlib pymoo

Issue: Older Python version

Solution: Ex-Fuzzy requires Python 3.8+. Upgrade your Python installation:

# Check your Python version
python --version

Issue: Installation fails on Apple Silicon Macs

Solution: Use Rosetta or install dependencies through conda:

# Create conda environment with compatible packages
conda create -n exfuzzy python=3.9
conda activate exfuzzy
conda install numpy pandas scikit-learn matplotlib
pip install pymoo ex-fuzzy

GPU Acceleration Setup#

Ex-Fuzzy supports GPU-accelerated evolutionary optimization through the EvoX backend.

Prerequisites#

To use GPU acceleration, you need:

  1. CUDA-compatible GPU (NVIDIA) with compute capability ≥3.5

  2. CUDA Toolkit (11.8 or 12.1 recommended)

  3. cuDNN (optional but recommended)

Installing GPU Support#

Option 1: Automatic Installation

pip install ex-fuzzy evox torch

This installs PyTorch with CPU support. For GPU support:

Option 2: CUDA-Specific Installation

# For CUDA 11.8
pip install ex-fuzzy evox
pip install torch --index-url https://download.pytorch.org/whl/cu118

# For CUDA 12.1
pip install ex-fuzzy evox
pip install torch --index-url https://download.pytorch.org/whl/cu121

Verifying GPU Installation#

Check if GPU is available:

import torch
from ex_fuzzy import evolutionary_backends

# Check available backends
backends = evolutionary_backends.list_available_backends()
print(f"Available backends: {backends}")

# Check GPU availability
if torch.cuda.is_available():
    print(f"✓ GPU available: {torch.cuda.get_device_name(0)}")
    print(f"  CUDA version: {torch.version.cuda}")
    print(f"  GPU memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.2f} GB")
else:
    print("⚠ No GPU detected. EvoX will use CPU.")

Expected Output:

Available backends: ['pymoo', 'evox']
✓ GPU available: NVIDIA GeForce RTX 3080
  CUDA version: 11.8
  GPU memory: 10.00 GB

Troubleshooting GPU Setup#

Issue: GPU not detected

Solution 1: Verify CUDA installation:

nvidia-smi  # Should show GPU information

Solution 2: Check PyTorch CUDA version matches your drivers:

import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")

Solution 3: Reinstall PyTorch with correct CUDA version:

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

Issue: Out of memory errors with GPU

Solution: Ex-Fuzzy automatically batches operations, but you can:

  1. Reduce population size: pop_size=30 instead of 100

  2. Monitor GPU memory: nvidia-smi or watch -n 1 nvidia-smi

  3. Use CPU mode temporarily: Set backend='pymoo'

Performance Comparison#

Typical speedup with GPU (RTX 3080) vs CPU (Intel i7):

Dataset Size

PyMoo (CPU)

EvoX (GPU)

Speedup

1,000 samples

12s

15s

0.8x (GPU overhead)

10,000 samples

98s

35s

2.8x

100,000 samples

856s

89s

9.6x

Note

GPU acceleration is most beneficial for large datasets (>10,000 samples) and complex rule bases. For small datasets, CPU (PyMoo) may be faster due to GPU transfer overhead.

Performance Optimization#

For better performance, consider installing optimized versions of NumPy and SciPy:

Intel-Optimized Packages#

# Uninstall existing numpy/scipy
pip uninstall numpy scipy

# Install Intel-optimized versions
pip install intel-numpy intel-scipy

Or use conda with Intel MKL:

conda install numpy scipy scikit-learn -c intel

Docker Installation#

Use our official Docker image for a consistent environment:

# Pull the image
docker pull exfuzzy/ex-fuzzy:latest

# Run with Jupyter
docker run -p 8888:8888 exfuzzy/ex-fuzzy:latest

Or build your own:

FROM python:3.9-slim

RUN pip install ex-fuzzy[all]

WORKDIR /workspace
CMD ["python"]

Getting Help#

If you encounter issues during installation:

  1. Check the logs: Look for specific error messages in the installation output

  2. Update pip: pip install --upgrade pip

  3. Clear cache: pip cache purge

  4. Check dependencies: Ensure all required packages are compatible

  5. Ask for help: Open an issue on GitHub

Next Steps#

Once Ex-Fuzzy is installed, check out: