matlab-python/MATLAB_SYNC_GUIDE.md

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:

# 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:

   # 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

# 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

# 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

# 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

# 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

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:

% In CalcoloRSN.m, linea 234
% VECCHIO:
angle = atan2(ay, ax);

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

Python Update:

# 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:

% In CalcoloBiax_TuL.m
% AGGIUNTO:
correction_factor = params.correction_factor;
Yi = Yi * correction_factor;

Python Update:

# 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