• Hardened Windows installer and PyInstaller build for SciPy/scikit-learn compatibility.
• Bundled Lisbon baseline CSV (average_values.csv) into Windows EXE so chart overlays always load.
• Fixed NSIS script compatibility with stock NSIS (SetRegView/LogSet placement).

• Fixed historical-prediction merge length mismatch across DST boundary (Lisbon 2022-10-30) by deduplicating ambiguous timestamps before merging.
• Updated internal resource path to use "data/" (was "Data/") for metadata fallback.
• More robust ranking color/description assignment after merges.

• Custom Station Simulation: simulate energy production for a chosen location and user-provided capacity (kWp)
• 21-Day Analysis Window: chosen date ±10 days across results and charts
• Lisbon 4-year baseline overlay (min/avg/max) in the hourly chart, scaled by installation capacity
• Improved weather coordinate resolution per installation (Excel fallback), simulator fallback
• Windows installer build via GitHub Actions (PyInstaller + pynsist)

Experience the power of intelligent caching! This release delivers unprecedented performance improvements:

• ⚡ 93% faster startup - From 3+ minutes to seconds after initial cache build
• 🧠 Smart cache management - Automatic validation and optimization
• 💾 SQLite-powered metadata - Reliable cache integrity checking
• 🎯 Hash-based validation - Ensures data consistency and reliability
• 🖥️ Professional Windows installer - Modern NSIS installer with shortcuts

FilantropiaSolar is an advanced solar energy analysis application designed specifically for Portuguese photovoltaic (PV) installations. It combines historical data analysis with machine learning predictions to provide comprehensive insights into solar energy production patterns, weather correlations, and performance optimization opportunities.

• 📊 Interactive Hourly Analysis: Detailed hourly energy production charts with weather correlation
• 📈 Historical Data Exploration: Analyze existing energy production data from multiple installations
• 🔮 Future Simulation: Predict energy production for any future date using advanced ML models
• 🌤️ Weather Integration: Comprehensive weather simulation and impact analysis
• ⭐ Performance Rankings: Intelligent performance ratings and optimization insights
• 📱 Interactive Navigation: Day-by-day chart navigation with detailed breakdowns
• 🎯 Multi-Installation Support: Analyze 9+ PV installations across Portugal
• ⚡ Smart Caching System: Lightning-fast performance with intelligent data management
• 🖥️ Cache Management GUI: Visual cache status, validation, and clearing controls

1. Download the Windows installer from Releases
2. Run FilantropiaSolar-1.2.1.exe
3. Installer is non-admin and minimal-interaction; shortcuts are created
4. Launch from Start Menu or desktop shortcut

# Clone the repository
git clone https://github.com/your-username/FilantropiaSolar.git
cd FilantropiaSolar

# Install dependencies
pip install -e .

# Run the application
python main.py

# Debian/Ubuntu
sudo dpkg -i FilantropiaSolar-v1.0.3-Linux.deb

# Portable AppImage
chmod +x FilantropiaSolar-v1.0.3-Linux.AppImage
./FilantropiaSolar-v1.0.3-Linux.AppImage

🕐 Initial startup (3-4 minutes):

• Data loading and preprocessing
• ML model training and validation
• Cache building and optimization
• This happens only once!

⚡ Subsequent runs (5-10 seconds):

• Smart cache loading
• Instant data access
• Lightning-fast performance

• In Simulation mode, you can choose either an existing installation OR enable "Custom Station (Simulation)" and provide:
  • Location (predefined list or advanced coordinates internally)
  • Capacity (kWp)
• Custom station results and charts behave like any installation (capacity-scaled, baseline overlay shown).

Choose Analysis Mode:

• 📈 Historical Analysis: Explore existing data from your installations

  • Select installation from dropdown
  • Choose from available historical dates
  • Perfect for understanding past performance patterns

• 🔮 Future Simulation: Predict energy production for any date

  • Select installation
  • Enter any future date (YYYY-MM-DD format)
  • Uses weather simulation for predictions

Generate Analysis:

• Click "🚀 Generate 21-Day Analysis"
• Wait for processing (30-60 seconds)
• View success notification with key metrics

Comprehensive Results Display:

• Analysis type and installation details
• 21-day period summary and key metrics
• Daily performance breakdown with star ratings
• Data source and ML model information
• Performance insights and recommendations

Main Hourly Chart:

• Hourly energy production for selected day
• Color-coded bars based on daily performance rating
• Peak hour highlighting in golden color
• Star rating display in chart title

Weather Correlation Charts:

• Temperature profile throughout the day
• Cloud cover percentage by hour
• Visual correlation with energy production patterns

15-Day Summary Chart:

• Overview of all 21 days in analysis period
• Color-coded daily bars by performance rating
• Selected day highlighting with arrow indicator

Navigation Controls:

• ◄ Previous: Navigate to previous day
• Center: Return to center date of analysis
• Next ►: Navigate to next day
• Real-time chart updates with day information

Cache Status Panel:

• Real-time cache statistics and health
• Data integrity validation results
• Cache size and performance metrics

Cache Controls:

• Validate Cache: Verify data integrity using hash validation
• Clear Cache: Remove cached data (rebuilds on next run)
• Rebuild Cache: Force cache regeneration with latest data

Real-World Impact:

• First-time users: Same experience (one-time setup)
• Daily users: Near-instant application startup
• Researchers: Rapid data exploration and analysis
• Commercial users: Immediate productivity gains

The system uses a 5-tier ranking based on specific energy (kWh/kWp):

Cache Architecture:
├── cache/
│   ├── metadata.db              # SQLite database for cache management
│   ├── data/
│   │   ├── processed_data.pkl   # Preprocessed datasets
│   │   └── data_hashes.json     # Hash validation table
│   └── models/
│       ├── trained_models.pkl   # ML model artifacts
│       └── model_metadata.json  # Model validation data

Cache Features:

• SQLite metadata management - Tracks cache state and integrity
• Hash-based validation - Ensures data hasn't been corrupted
• Automatic invalidation - Rebuilds cache when source data changes
• Incremental updates - Only processes changed data
• Performance monitoring - Tracks cache hit rates and performance gains

FilantropiaSolar/
├── main.py                      # Main application entry point (v1.0.3)
├── src/
│   ├── cache_manager.py         # Smart caching system (NEW)
│   ├── data_manager.py          # Enhanced data management
│   ├── gui_manager.py           # GUI with cache controls
│   ├── data_processing/
│   │   └── comprehensive_data_processor.py
│   ├── weather_api/
│   │   └── weather_client.py
│   ├── prediction/
│   │   └── enhanced_energy_predictor.py
│   └── utils/
│       └── energy_ranking.py
├── installer.cfg               # pynsist installer configuration (Windows)
├── filantropia_solar.spec      # PyInstaller spec (ignored by git; build locally or in CI)
├── .github/workflows/windows-installer.yml  # CI to build installer on Windows
├── cache/                      # Smart cache directory (dev). On Windows installer, cache lives in %LOCALAPPDATA%/FilantropiaSolar/cache
├── data/                       # Source datasets
├── weather_files/              # Weather data
├── models/                     # Legacy model storage
├── .github/workflows/          # CI/CD automation (NEW)
└── docs/                      # Documentation

• Caching: SQLite, Pickle, Hash validation (SHA256)
• Data Processing: Pandas, NumPy with performance optimizations
• Machine Learning: Scikit-learn (Random Forest, Gradient Boosting, Linear Regression)
• Visualization: Matplotlib, Seaborn
• GUI Framework: Tkinter with enhanced cache management
• Weather API: Open-Meteo (free tier)
• Packaging: PyInstaller, NSIS, GitHub Actions CI/CD

• Coverage: 4 Lisbon installations (2019-2022)
• Resolution: Hourly measurements
• Parameters: Produced Energy (kWh), Specific Energy (kWh/kWp)
• Format: Excel workbook with installation-specific sheets

• Coverage: Lisbon region (2019-2022)
• Resolution: Hourly measurements
• Parameters:
  • Temperature (°C)
  • Relative humidity (%)
  • Dew point (°C)
  • Apparent temperature (°C)
  • Cloud cover (%)
  • Wind speed (km/h)
  • Wind direction (°)
  • Solar radiation (W/m²) - Key parameter for predictions

The system trains three models and automatically selects the best performer:

1. Random Forest Regressor

   • Ensemble method with 100 trees
   • Handles non-linear relationships
   • Feature importance analysis

2. Gradient Boosting Regressor

   • Sequential learning approach
   • High accuracy for complex patterns
   • Robust to overfitting

3. Linear Regression

   • Baseline model with feature scaling
   • Fast prediction
   • Interpretable coefficients

• Weather Features: All meteorological parameters
• Time Features: Hour, month, day of year, cyclical encoding
• Interaction Features: Solar radiation × cloud cover, temperature/humidity ratios
• Solar Position: Simplified solar elevation angle calculation

Models are evaluated using:

• Mean Absolute Error (MAE): Primary selection metric
• R² Score: Coefficient of determination
• Cross-validation: Training/testing split (80%/20%)

• Historical Analysis: Analyze past performance with actual weather data
• Current Day: Real-time predictions with current weather
• Future Forecasting: Up to 7-day predictions using weather forecasts

• Short-term (1-3 days): High accuracy (typically R² > 0.8)
• Medium-term (4-7 days): Good accuracy (R² > 0.7)
• Confidence Intervals: Based on model performance metrics

• Energy Planning: Optimize appliance usage based on solar production
• Battery Management: Plan charging/discharging cycles
• Grid Interaction: Minimize grid consumption during peak solar hours

• Load Scheduling: Plan energy-intensive operations
• Cost Optimization: Reduce electricity costs
• Maintenance Planning: Schedule during low-production periods

• Performance Monitoring: Track installation efficiency
• Comparative Analysis: Compare multiple installations
• Seasonal Studies: Understand seasonal variations

The system uses Open-Meteo API (free tier) by default. For alternative services:

1. OpenWeatherMap: Requires API key

# In weather_client.py
client = OpenWeatherMapClient(api_key="your_api_key")

2. Custom Coordinates: Modify Lisbon coordinates if needed

# In weather_client.py
self.lisbon_coordinates = {"latitude": 38.7223, "longitude": -9.1393}

Customize ML models in energy_predictor.py:

# Adjust model parameters
models = {
    'random_forest': RandomForestRegressor(n_estimators=200, max_depth=15),
    'gradient_boost': GradientBoostingRegressor(learning_rate=0.1),
    'linear': LinearRegression()
}

• GitHub Actions workflow builds the frozen app and an installer.exe (Windows 10+, 64-bit)
• Trigger by tagging a release (vX.Y.Z) or via workflow_dispatch
• Artifacts: FilantropiaSolar-.exe under workflow run artifacts

Local build (Windows):

python -m pip install --upgrade pip wheel
pip install pyinstaller pynsist openpyxl
pyinstaller --noconfirm filantropia_solar.spec
python -m nsist installer.cfg

Error: Could not load PV data
Solution: Ensure Excel files are in the correct directory and not corrupted

Error: Could not retrieve weather data
Solution: Check internet connection; API may use default values offline

Error: Insufficient training samples
Solution: Ensure historical data contains enough records (minimum 50 samples)

Error: GUI not displaying properly
Solution: Check tkinter installation; may need to reinstall Python with tk support

Application logs are stored in logs/application.log for debugging.

• Multiple Location Support: Extend beyond Lisbon
• Advanced ML Models: Deep learning, ensemble methods
• Real-time Data Integration: Live PV production monitoring
• Mobile App: iOS/Android companion app
• Cloud Deployment: Web-based interface
• Battery Integration: Battery system optimization
• Economic Analysis: Cost-benefit calculations

• RESTful API: Programmatic access to predictions
• Webhook Support: Real-time notifications
• Batch Processing: Multiple prediction requests

# Install development dependencies
pip install -e .[dev]

# Run tests
python -m pytest tests/

# Code formatting
ruff format .
ruff check .

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Important: Any use of the data in this project must cite the original source:

Sarmas, Elissaios; Matias, Nuno; Pereira, Catarina; Antunes, Ana Rita (2025), 
"Photovoltaic Power Production Dataset", Mendeley Data, V3, 
doi: 10.17632/dbh93b6vp8.3

The data files used in FilantropiaSolar are CSV files created from Excel sheets specifically for this study, providing comprehensive photovoltaic power production data from Portuguese installations.

This project is licensed under the MIT License - see the LICENSE file for details.

For support, questions, or feature requests:

• GitHub Issues: Create an issue on the repository
• Email: [email protected]
• Documentation: Check the docs/ directory for detailed guides

• Data Sources: PV installation data provided by Portuguese solar energy providers
• Weather Data: Open-Meteo API for reliable weather forecasts
• Machine Learning: Scikit-learn community for robust ML algorithms
• Visualization: Matplotlib and Seaborn for beautiful charts

• Lines of Code: ~3,500+ lines
• Supported Installations: 9 Portuguese PV plants
• Historical Data: 4 years (2019-2022)
• Weather Parameters: 8 meteorological variables
• Prediction Accuracy: Up to 90% R² score
• Ranking System: 5-tier optimization framework
• Version: 1.0.0 (Production Ready)

FilantropiaSolar - Empowering solar energy decisions through intelligent prediction 🌞