Skip to content

Troubleshooting

Jump to bottom
Raphael Constantinis edited this page Jul 23, 2025 · 1 revision

Troubleshooting Guide

This guide provides solutions for common issues encountered when using entropic_measurement.

Table of Contents

Installation Issues

Problem: pip install fails

Symptoms: Error messages during pip install entropic_measurement

Solutions:

  1. Update pip: pip install --upgrade pip
  2. Use virtual environment: 
    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install entropic_measurement
  3. Install dependencies manually: 
    pip install numpy scipy
pip install entropic_measurement

Problem: Permission denied errors

Symptoms: "Permission denied" or "Access is denied" during installation

Solutions:

  1. Use user installation: pip install --user entropic_measurement
  2. Run as administrator (Windows) or use sudo (Linux/Mac)
  3. Use virtual environment (recommended)

Problem: Dependency conflicts

Symptoms: Package version conflicts during installation

Solutions:

  1. Create fresh virtual environment
  2. Check requirements: Ensure Python >= 3.7
  3. Update conflicting packages: pip install --upgrade numpy scipy

Import and Usage Errors

Problem: ImportError or ModuleNotFoundError

Symptoms: ImportError: No module named 'entropic_measurement'

Solutions:

  1. Verify installation: pip list | grep entropic
  2. Check Python path: Ensure you're using the correct Python environment
  3. Reinstall package: pip uninstall entropic_measurement && pip install entropic_measurement

Problem: Function not found errors

Symptoms: AttributeError: module has no attribute 'function_name'

Solutions:

  1. Check import statement: 
    # Correct
from entropic_measurement import calculate_entropy

# Or
import entropic_measurement as em
result = em.calculate_entropy(data)
  2. Verify function name: Check documentation for correct function names
  3. Update package: pip install --upgrade entropic_measurement

Calculation Problems

Problem: NaN or infinite results

Symptoms: Results contain NaN, inf, or -inf values

Solutions:

  1. Check input data:

    • Ensure no zero probabilities in entropy calculations
    • Verify data is properly normalized
    • Remove or handle missing values

  2. Use safe calculation modes:

    # Use base parameter to avoid log(0)
entropy = calculate_entropy(data, base=2, handle_zeros=True)

Problem: Unexpected calculation results

Symptoms: Results don't match expected values

Solutions:

  1. Verify input format: Check data structure and types
  2. Check parameters: Ensure correct base (2, e, 10) for entropy calculations
  3. Validate preprocessing: Confirm data normalization is correct
  4. Compare with manual calculation: Test with simple known cases

Problem: Memory errors with large datasets

Symptoms: MemoryError or system slowdown

Solutions:

  1. Process in chunks: 
    def process_large_dataset(data, chunk_size=1000):
    results = []
    for i in range(0, len(data), chunk_size):
        chunk = data[i:i+chunk_size]
        result = calculate_entropy(chunk)
        results.append(result)
    return results
  2. Use data streaming for very large files
  3. Increase system memory or use a machine with more RAM

Performance Issues

Problem: Slow calculation speed

Symptoms: Functions take longer than expected to complete

Solutions:

  1. Use vectorized operations: Ensure input data is numpy arrays
  2. Optimize data types: Use appropriate dtypes (float32 vs float64)
  3. Profile your code: 
    import cProfile
cProfile.run('your_entropy_calculation()')
  4. Consider parallel processing for independent calculations

Problem: High memory usage

Symptoms: Excessive RAM consumption

Solutions:

  1. Use generators instead of lists for large datasets
  2. Delete intermediate variables: Use del variable_name
  3. Monitor memory usage: 
    import psutil
import os
process = psutil.Process(os.getpid())
print(f"Memory usage: {process.memory_info().rss / 1024 / 1024} MB")

Debugging Tips

Enable verbose output

import logging
logging.basicConfig(level=logging.DEBUG)

# Your entropy calculations here

Validate input data

def validate_input(data):
    print(f"Data type: {type(data)}")
    print(f"Data shape: {getattr(data, 'shape', 'Not array-like')}")
    print(f"Data range: {min(data)} to {max(data)}")
    print(f"Contains NaN: {any(x != x for x in data)}")
    return data

# Use before calculations
validated_data = validate_input(your_data)
result = calculate_entropy(validated_data)

Test with simple cases

# Test with known entropy values
test_data = [0.5, 0.5]  # Should give entropy = 1.0 (base 2)
result = calculate_entropy(test_data, base=2)
print(f"Expected: 1.0, Got: {result}")

Check environment

import sys
import numpy as np
import entropic_measurement

print(f"Python version: {sys.version}")
print(f"NumPy version: {np.__version__}")
print(f"entropic_measurement version: {entropic_measurement.__version__}")

Common Error Messages and Solutions

Error Message Likely Cause Solution
ValueError: probabilities must sum to 1 Unnormalized probability distribution Normalize your data: data / data.sum()
RuntimeWarning: divide by zero Zero probabilities in entropy calculation Use handle_zeros=True parameter or filter zeros
TypeError: unsupported operand type(s) Wrong data type Convert to numpy array: np.array(data)
IndexError: list index out of range Empty or malformed input Check input data length and structure

Getting Help

If you're still experiencing issues:

  1. Check the documentation: Review function docstrings and examples
  2. Search existing issues: Look through GitHub Issues
  3. Create a minimal example: Reproduce the issue with the smallest possible code
  4. Report bugs: Open a new issue with:
    • Python version
    • Package version
    • Complete error message
    • Minimal reproducible example

Creating a Bug Report

# Include this information in your bug report
import sys
import numpy as np
import entropic_measurement

print(f"Python: {sys.version}")
print(f"NumPy: {np.__version__}")
print(f"entropic_measurement: {entropic_measurement.__version__}")
print(f"Platform: {sys.platform}")

# Your minimal example here

Version Compatibility

  • Python: 3.7+
  • NumPy: 1.18+
  • SciPy: 1.5+ (if using advanced features)

For legacy Python versions, use entropic_measurement < 1.0.0

Last updated: July 23, 2025

Clone this wiki locally