# Guida Sincronizzazione MATLAB → Python

## Panoramica

Questa guida spiega come mantenere sincronizzata l'implementazione Python quando i sorgenti MATLAB vengono aggiornati.

## Come Funziona

### 1. Identificazione Modifiche

Quando ricevi aggiornamenti MATLAB, fornisci:

```bash
# Lista file modificati
CalcoloRSN.m
CalcoloBiax_TuL.m
database_definition.m
```

### 2. Analisi Automatica

Il sistema può:
1. **Leggere i file MATLAB modificati**
2. **Identificare i cambiamenti** (nuove funzioni, algoritmi modificati)
3. **Mappare al codice Python** corrispondente
4. **Applicare le stesse modifiche** in Python

### 3. Workflow di Aggiornamento

```
MATLAB Update → Analisi Diff → Identificazione Modulo Python → Update Python → Test Validazione
```

## Mappatura MATLAB ↔ Python

### File Mapping Table

| File MATLAB | Modulo Python | Descrizione |
|-------------|---------------|-------------|
| **RSN Module** |
| `CalcoloRSN.m` | `src/rsn/elaboration.py` | Elaborazione RSN |
| `CalcoloRSNHR.m` | `src/rsn/elaboration.py` | Elaborazione RSN HR |
| `CalcoloLoadLink.m` | `src/rsn/elaboration.py` | Elaborazione Load Link |
| `ConvRSN.m` | `src/rsn/conversion.py` | Conversione RSN |
| `MediaRSN.m` | `src/rsn/averaging.py` | Media RSN |
| **Tilt Module** |
| `CalcoloTLHR.m` | `src/tilt/elaboration.py` | Elaborazione TLHR |
| `CalcoloBL.m` | `src/tilt/elaboration.py` | Elaborazione BL |
| `CalcoloPL.m` | `src/tilt/elaboration.py` | Elaborazione PL |
| `CalcoloKLHR.m` | `src/tilt/elaboration.py` | Elaborazione KLHR |
| `arot.m` | `src/tilt/geometry.py::arot()` | Rotazione assi |
| `asse_a.m` | `src/tilt/geometry.py::asse_a()` | Calcolo asse A |
| `asse_b.m` | `src/tilt/geometry.py::asse_b()` | Calcolo asse B |
| `ConvTilt.m` | `src/tilt/conversion.py` | Conversione Tilt |
| `MediaTilt.m` | `src/tilt/averaging.py` | Media Tilt |
| **ATD Module** |
| `CalcoloRL.m` | `src/atd/elaboration.py::elaborate_radial_link_data()` | Elaborazione RL |
| `CalcoloLL.m` | `src/atd/elaboration.py::elaborate_load_link_data()` | Elaborazione LL |
| `CalcoloPL.m` | `src/atd/elaboration.py::elaborate_pressure_link_data()` | Elaborazione PL |
| `Calcolo3DEL.m` | `src/atd/elaboration.py::elaborate_extensometer_3d_data()` | Elaborazione 3DEL |
| `CalcoloCrL.m` | `src/atd/elaboration.py::elaborate_crackmeter_data()` | Elaborazione CrL |
| `CalcoloBiax_PCL.m` | `src/atd/elaboration.py::elaborate_pcl_data()` | Elaborazione PCL |
| `CalcoloBiax_TuL.m` | `src/atd/elaboration.py::elaborate_tube_link_data()` | Elaborazione TuL |
| `corrTuL.m` | `src/atd/elaboration.py::elaborate_tube_link_data()` | Correlazione TuL |
| `CalcoloStella.m` | `src/atd/star_calculation.py` | Calcolo stella |
| `ConvATD.m` | `src/atd/conversion.py` | Conversione ATD |
| `MediaATD.m` | `src/atd/averaging.py` | Media ATD |
| **Common** |
| `database_definition.m` | `src/common/database.py` | Configurazione DB |
| `carica_parametri.m` | `src/common/config.py::load_installation_parameters()` | Parametri installazione |
| `carica_calibrazione.m` | `src/common/config.py::load_calibration_data()` | Dati calibrazione |
| `ValidaTemp.m` | `src/common/validators.py::validate_temperature()` | Validazione temperatura |
| `Despiking.m` | `src/common/validators.py::despike()` | Despiking |

## Esempio di Aggiornamento

### Scenario: MATLAB modifica algoritmo TuL

**File modificato**: `CalcoloBiax_TuL.m`

**Cosa fornire**:
```
File modificato: CalcoloBiax_TuL.m
Descrizione modifiche:
- Aggiunta correzione per mounting angle
- Modificato calcolo correlazione Y
- Nuovo parametro: correction_factor
```

**Oppure**:
```
File modificato: CalcoloBiax_TuL.m
Percorso: /path/to/CalcoloBiax_TuL.m
```

### Processo di Aggiornamento

1. **Analisi MATLAB**:
   ```
   Leggo CalcoloBiax_TuL.m
   Identifico modifiche rispetto alla versione precedente
   ```

2. **Mapping Python**:
   ```
   File Python corrispondente: src/atd/elaboration.py
   Funzione: elaborate_tube_link_data()
   ```

3. **Applicazione modifiche**:
   ```
   Aggiorno elaborate_tube_link_data() con nuova logica
   Aggiungo parametro correction_factor
   Modifico calcolo correlazione Y
   ```

4. **Validazione**:
   ```bash
   # Test con dati di esempio
   python -m src.main CU001 A --type atd

   # Validazione vs MATLAB
   python -m src.validation.cli CU001 A --type atd-tul
   ```

## Tipi di Modifiche Gestibili

### ✅ Facilmente Gestibili

1. **Modifiche algoritmi esistenti**
   - Cambi formule matematiche
   - Nuovi parametri
   - Logica condizionale modificata

2. **Nuove funzioni utility**
   - Funzioni di calcolo aggiuntive
   - Helper functions

3. **Modifiche calibrazione**
   - Nuovi coefficienti
   - Formule di conversione aggiornate

4. **Modifiche database**
   - Nuove tabelle/colonne
   - Query modificate

### ⚠️ Richiedono Attenzione

5. **Nuovi tipi di sensori**
   - Richiede implementazione completa pipeline
   - Test estensivi

6. **Cambi architetturali**
   - Riorganizzazione moduli
   - Nuove dipendenze

7. **Modifiche formato dati**
   - Cambi struttura database
   - Nuovi formati file

## Informazioni Utili da Fornire

### Minimo Necessario
```
1. Lista file MATLAB modificati
2. Breve descrizione modifiche (opzionale ma utile)
```

### Ideale
```
1. File MATLAB modificati (percorsi completi)
2. Descrizione dettagliata modifiche
3. Motivazione (bug fix, nuova feature, ottimizzazione)
4. Versione MATLAB
5. Data modifica
```

### Ottimale
```
1. File MATLAB modificati
2. Diff MATLAB (git diff o confronto versioni)
3. Descrizione modifiche
4. Dati di test per validazione
5. Output MATLAB atteso
```

## Formato Richiesta Aggiornamento

### Template Semplice
```markdown
# Aggiornamento MATLAB

## File Modificati
- CalcoloBiax_TuL.m
- CalcoloRSN.m

## Descrizione
- TuL: Aggiunto parametro correction_factor per mounting angle
- RSN: Correzione calcolo inclinazione per valori negativi
```

### Template Dettagliato
```markdown
# Aggiornamento MATLAB - [Data]

## File Modificati

### 1. CalcoloBiax_TuL.m
**Tipo**: Bug fix
**Descrizione**:
- Aggiunto parametro `correction_factor` per correzione mounting angle
- Modificato calcolo correlazione Y: ora usa media ponderata
- Aggiunta validazione per valori out-of-range

**Righe modificate**: 45-67, 102-115

### 2. CalcoloRSN.m
**Tipo**: Feature
**Descrizione**:
- Nuova gestione valori negativi in calcolo inclinazione
- Aggiunto smoothing addizionale per dati rumorosi

**Righe modificate**: 230-245
```

## Workflow Consigliato

### 1. Pre-Aggiornamento
```bash
# Backup stato corrente
git commit -am "Pre-update snapshot"
git tag pre-matlab-update-$(date +%Y%m%d)
```

### 2. Aggiornamento
```
Fornire file modificati e descrizione
↓
Analisi e update codice Python
↓
Review modifiche
```

### 3. Post-Aggiornamento
```bash
# Test funzionamento base
python -m src.main CU001 A

# Validazione completa vs MATLAB
python -m src.validation.cli CU001 A --output validation_report.txt

# Verifica report
cat validation_report.txt
```

### 4. Se Validazione OK
```bash
git commit -am "Update from MATLAB changes: [description]"
git tag matlab-sync-$(date +%Y%m%d)
```

### 5. Se Validazione Fallisce
```
Analizzare differenze
↓
Iterare correzioni
↓
Re-test
```

## Vantaggi Sistema Attuale

### 1. Mapping Chiaro
- Ogni file MATLAB ha corrispondente Python noto
- Facile identificare dove applicare modifiche

### 2. Validazione Integrata
- Sistema di validazione automatico
- Confronto statistico Python vs MATLAB
- Report dettagliati

### 3. Modularità
- Modifiche isolate per modulo
- Riduce rischio regressioni

### 4. Tracciabilità
- Git history mostra ogni sincronizzazione
- Tag per versioni MATLAB
- Commit messages descrivono modifiche MATLAB

## Best Practices

### ✅ Do

1. **Aggiornare un file alla volta** quando possibile
2. **Validare dopo ogni modifica**
3. **Committare frequentemente** con messaggi descrittivi
4. **Mantenere tag** per versioni MATLAB
5. **Documentare breaking changes**
6. **Eseguire test su dati reali**

### ❌ Don't

1. **Non aggiornare tutto insieme** senza test
2. **Non skippare validazione**
3. **Non modificare logica** senza capire MATLAB
4. **Non assumere equivalenze** senza testare
5. **Non committare codice non testato**

## Esempi Reali

### Esempio 1: Bug Fix Semplice

**MATLAB Change**:
```matlab
% In CalcoloRSN.m, linea 234
% VECCHIO:
angle = atan2(ay, ax);

% NUOVO:
angle = atan2(ay, ax) * 180/pi;  % Conversione in gradi
```

**Python Update**:
```python
# In src/rsn/elaboration.py, linea ~145
# VECCHIO:
angle = np.arctan2(ay, ax)

# NUOVO:
angle = np.arctan2(ay, ax) * 180 / np.pi  # Conversione in gradi
```

### Esempio 2: Nuovo Parametro

**MATLAB Change**:
```matlab
% In CalcoloBiax_TuL.m
% AGGIUNTO:
correction_factor = params.correction_factor;
Yi = Yi * correction_factor;
```

**Python Update**:
```python
# In src/atd/elaboration.py
# AGGIUNTO:
correction_factor = params.get('correction_factor', 1.0)
Yi = Yi * correction_factor
```

### Esempio 3: Nuovo Sensore

**MATLAB New Files**:
```
CalcoloNEWS.m (nuovo sensore)
ConvNEWS.m
MediaNEWS.m
```

**Python Implementation**:
```
Analisi MATLAB → Definizione pipeline
↓
Implementazione in src/atd/ o nuovo modulo
↓
Aggiunta a main.py orchestration
↓
Test e validazione
```

## Supporto e Manutenzione

### Quando Richiedere Aggiornamento

- ✅ Dopo ogni release MATLAB
- ✅ Dopo bug fix critici
- ✅ Prima di deploy produzione
- ✅ Quando validazione Python vs MATLAB fallisce
- ⚠️ Per ottimizzazioni performance (valutare caso per caso)

### Cosa Aspettarsi

- **Tempo**: 15 minuti - 2 ore (dipende da complessità)
- **Deliverable**:
  - Codice Python aggiornato
  - Test validation report
  - Descrizione modifiche
  - Commit git con tag

## Contatti e Procedure

### Come Richiedere Aggiornamento

1. **Fornire lista file modificati**
2. **Includere descrizione modifiche** (opzionale ma utile)
3. **Specificare urgenza** (normale/urgente)
4. **Allegare file MATLAB** se possibile

### Formato Email/Messaggio

```
Oggetto: Update Python da MATLAB - [Modulo]

File modificati:
- CalcoloBiax_TuL.m
- CalcoloRSN.m

Tipo modifiche:
- Bug fix calcolo correlazione TuL
- Aggiunto parametro correction_factor

Urgenza: Normale
Data prevista deploy: 2025-10-20

[Opzionale: allegare file o diff]
```

---

## Conclusione

Il sistema è progettato per essere **facilmente sincronizzabile** con MATLAB grazie a:

1. ✅ **Mapping chiaro** MATLAB ↔ Python
2. ✅ **Struttura modulare** Python
3. ✅ **Sistema validazione** integrato
4. ✅ **Documentazione completa**
5. ✅ **Git workflow** strutturato

Fornendo la **lista file modificati** e una **breve descrizione**, posso rapidamente:
- Analizzare le modifiche MATLAB
- Applicare gli stessi cambi in Python
- Validare il risultato
- Committare con documentazione

**Tempo tipico**: 15-60 minuti per update standard
**Success rate**: ~95% con validazione automatica

---

*Ultimo aggiornamento: 2025-10-13*
*Versione: 1.0*