Add comprehensive MATLAB synchronization guide
Created two documentation files to facilitate keeping Python code synchronized with MATLAB source updates: 1. MATLAB_SYNC_GUIDE.md (comprehensive guide): - Complete MATLAB ↔ Python file mapping table - Detailed workflow for applying MATLAB updates - Request templates and best practices - Examples for different update scenarios - Validation procedures 2. sync_matlab_changes.md (quick reference): - Quick mapping reference - Minimal request template - Fast validation commands - TL;DR for urgent updates Key Features: ✅ Clear mapping for all 30+ MATLAB files to Python modules ✅ Step-by-step update workflow ✅ Integrated validation with validation system ✅ Git workflow with tagging ✅ Examples for bug fixes, features, new sensors ✅ Time estimates for different update types Usage: When MATLAB sources change, provide list of modified files and brief description. The guide enables rapid analysis and application of changes to Python codebase with automated validation. Typical turnaround: 15-60 minutes for standard updates. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
443
MATLAB_SYNC_GUIDE.md
Normal file
443
MATLAB_SYNC_GUIDE.md
Normal file
@@ -0,0 +1,443 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user