admin-edu-space/GENETIC_ALGORITHM_README.md

AI Genetic Algorithm for Room Reservations

This module implements a genetic algorithm-based optimization system for intelligent room reservation assignments in educational institutions.

Overview

The system uses genetic algorithms to optimize room assignments taking into account:

• Capacity efficiency
• Time preferences
• Conflict resolution
• Resource matching
• Student enrollment numbers

Key Components

1. Genetic Algorithm Core (app/models/genetic_algorithm.py)

Main Classes:

• ReservationRequest: Represents a reservation request from the teaching committee
• Gene: Single reservation assignment (classroom + commission + time)
• Individual: Complete reservation schedule (chromosome)
• GeneticAlgorithm: Main algorithm implementation
• ReservationOptimizer: High-level interface layer

Algorithm Configuration:

• Population Size: 50 individuals
• Generations: 100 evolution cycles
• Mutation Rate: 10%
• Crossover Rate: 80%

2. API Endpoints (app/routes/genetic_algorithm.py)

• POST /api/genetic/optimize: Run optimization
• POST /api/genetic/preview-optimization: Preview results without applying
• POST /api/genetic/apply-optimization: Apply optimized reservations
• GET /api/genetic/commissions: Get available commissions
• GET /api/genetic/algorithm-status: Get system status

3. Frontend Interface

Access Point:

• URL: /genetic-optimizer
• Permissions: Admin and Teacher roles only

Features:

• Commission selection interface
• Real-time preview of optimization results
• Fitness score visualization
• Conflict detection and reporting
• One-click reservation application

Fitness Function Components

The algorithm optimizes for multiple objectives:

1. Capacity Efficiency (40% weight)

• Perfect match: 1.0
• <10% waste: 1.0
• <30% waste: 0.8
• <50% waste: 0.6

• 50% waste: 0.4

• Overfilled: 0.0

2. Time Preference Satisfaction (30% weight)

• Within 30 minutes: 1.0
• Within flexibility window: 0.8 - 0.5
• Beyond flexibility: max(0.0, 0.5 - penalty)

3. Conflict Penalty (20% weight)

• No conflicts: 1.0
• Each conflict: -0.5 penalty

4. Resource Matching (10% weight)

• Based on classroom resources and subject requirements

Usage Examples

Basic Optimization

from app.models.genetic_algorithm import ReservationOptimizer

optimizer = ReservationOptimizer()

# Optimize for specific commissions
result = optimizer.optimize_schedule(
    commission_ids=[1, 2, 3],
    admin_user_id=1,
    start_date=datetime(2024, 1, 15),
    end_date=datetime(2024, 1, 20)
)

print(f"Fitness Score: {result['fitness_score']}")
print(f"Reservations Created: {result['assigned_reservations']}")

Applying Optimized Reservations

# Apply to database
reservations = optimizer.apply_optimized_reservations(result['reservations'])
print(f"Applied {len(reservations)} reservations")

API Usage

# Preview optimization
curl -X POST http://localhost:5000/api/genetic/preview-optimization \
  -H "Content-Type: application/json" \
  -d '{"commission_ids": [1, 2, 3]}'

# Run full optimization
curl -X POST http://localhost:5000/api/genetic/optimize \
  -H "Content-Type: application/json" \
  -d '{"commission_ids": [1, 2, 3]}'

# Apply reservations
curl -X POST http://localhost:5000/api/genetic/apply-optimization \
  -H "Content-Type: application/json" \
  -d '{"reservations": [...]}'

Frontend Integration

HTML Template: app/templates/genetic_optimizer.html

The interface provides:

• Commission selection with filtering
• Real-time algorithm status
• Preview vs. full optimization modes
• Results visualization
• Download functionality for results

JavaScript: app/static/js/genetic-algorithm.js

Key features:

• AJAX communication with backend
• Local storage for intermediate results
• Progress indicators
• Error handling
• CSV export functionality

Testing

Unit Tests: tests/test_genetic_algorithm.py

Run tests:

python -m pytest tests/test_genetic_algorithm.py -v

Test coverage includes:

• Fitness calculation validation
• Conflict detection
• Crossover and mutation operations
• Tournament selection
• Complete optimization process

Performance Considerations

Optimization Complexity:

• Time Complexity: O(P × G × N) where P=population, G=generations, N=requests
• Space Complexity: O(P × N)

Scalability:

• Handles 50+ reservation requests efficiently
• Configurable population size for larger datasets
• Parallel evolution possible for very large datasets

Configuration Options

Algorithm Parameters (can be modified in routes):

genetic_algorithm = GeneticAlgorithm(
    population_size=100,    # Increase for better results
    generations=200,        # Increase for convergence
    mutation_rate=0.15,     # Adjust diversity
    crossover_rate=0.85     # Adjust inheritance
)

Fitness Weights (can be tuned):

# In Individual.calculate_fitness()
score += capacity_score * 0.4    # 40% weight
score += time_score * 0.3        # 30% weight  
score += conflict_score * 0.2    # 20% weight
score += resource_score * 0.1    # 10% weight

Monitoring and Debugging

Debug Information:

• Individual fitness scores
• Conflict detection reports
• Generation progress
• Resource utilization metrics

Logging:

All major operations are logged with appropriate levels:

• INFO: Optimization progress
• WARNING: Conflicts detected
• ERROR: Algorithm failures

Future Enhancements

Planned Features:

1. Multi-objective optimization: Pareto-optimal solutions
2. Real-time optimization: Live scheduling updates
3. Machine learning integration: Historical pattern recognition
4. Advanced resource matching: Equipment and facility requirements
5. Mobile optimization: Mobile-friendly interface

Algorithm Improvements:

1. Adaptive parameters: Dynamic mutation/crossover rates
2. Island model: Multi-population evolution
3. Local search: Hill climbing integration
4. Constraint handling: Advanced constraint satisfaction

Security Considerations

Access Control:

• Role-based permissions (admin/teacher only)
• CSRF token validation
• Input sanitization

Data Protection:

• No sensitive data in genetic representation
• Secure API endpoints
• Audit logging for all operations

Troubleshooting

Common Issues:

1. Poor optimization results:

   • Increase population size
   • Adjust fitness weights
   • Check data quality

2. Slow performance:

   • Reduce population size temporarily
   • Limit commission selection
   • Check database performance

3. High conflicts:

   • Increase flexibility hours
   • Add more classrooms
   • Check existing reservations

Debug Mode:

Add to app.py for detailed logging:

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

Contributing

Code Style:

• Follow PEP 8 conventions
• Add comprehensive docstrings
• Include type hints
• Write unit tests

Pull Request Checklist:

• Tests pass
• Documentation updated
• Code follows style guide
• No security vulnerabilities
• Performance acceptable

License

This module is part of the admin-edu-space project and follows the same licensing terms.