276 lines
7.2 KiB
Markdown
276 lines
7.2 KiB
Markdown
# 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
|
||
|
||
```python
|
||
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
|
||
|
||
```python
|
||
# Apply to database
|
||
reservations = optimizer.apply_optimized_reservations(result['reservations'])
|
||
print(f"Applied {len(reservations)} reservations")
|
||
```
|
||
|
||
### API Usage
|
||
|
||
```bash
|
||
# 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:
|
||
```bash
|
||
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):
|
||
```python
|
||
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):
|
||
```python
|
||
# 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:
|
||
```python
|
||
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. |