diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c1f8543 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Davide Grilli + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..38148ae --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +# Ciclovoltametrie + +Pipeline Python per trasformare i file grezzi (`.txt`) esportati da un potenziostato CHI660C in CSV puliti, con l'ultimo ciclo di voltammetria isolato, il potenziale normalizzato e le colonne derivate per l'analisi (es. grafici tipo Randles-Sevcik). Alla fine viene generato automaticamente anche un grafico per ogni file. + +Questa guida non presume nessuna conoscenza di Python: segui i passaggi nell'ordine indicato. + +## 1. Installare Python + +Serve Python 3.10 o superiore. + +- **Windows**: scarica l'installer da [python.org/downloads](https://www.python.org/downloads/), avvialo e **spunta la casella "Add python.exe to PATH"** prima di cliccare Install. +- **macOS**: scarica l'installer da [python.org/downloads](https://www.python.org/downloads/) oppure, se hai [Homebrew](https://brew.sh), esegui `brew install python`. +- **Linux**: quasi sempre è già installato. Verifica con il comando del punto 2. + +## 2. Verificare l'installazione + +Apri il terminale (Prompt dei comandi/PowerShell su Windows, Terminale su macOS/Linux) e digita: + +``` +python3 --version +``` + +Se ottieni un errore, prova con `python --version`. Dovresti vedere qualcosa come `Python 3.11.x`. Da qui in poi, ovunque leggi `python3`, usa il comando che ha funzionato per te (`python3` o `python`). + +## 3. Scaricare il progetto + +Se non l'hai già fatto, scarica o clona questa cartella sul tuo computer. Poi apri il terminale **dentro la cartella del progetto** (quella che contiene questo file README). + +## 4. Creare l'ambiente virtuale e installare le dipendenze + +L'ambiente virtuale è una cartella isolata dove vengono installate le librerie necessarie, senza toccare il resto del tuo computer. Va creato una sola volta. + +``` +python3 -m venv .venv +``` + +Poi attivalo: + +- **Windows (PowerShell)**: + ``` + .venv\Scripts\Activate.ps1 + ``` +- **Windows (Prompt dei comandi)**: + ``` + .venv\Scripts\activate.bat + ``` +- **macOS/Linux**: + ``` + source .venv/bin/activate + ``` + +Se l'attivazione ha funzionato, vedrai `(.venv)` all'inizio della riga del terminale. A questo punto installa le librerie richieste: + +``` +pip install -r requirements.txt +``` + +**Nota**: ogni volta che apri un nuovo terminale per usare la pipeline, devi riattivare l'ambiente virtuale (comando di attivazione sopra) prima di lanciare gli script. + +## 5. Preparare i file da elaborare + +1. Nella cartella del progetto trovi (o crea) una cartella chiamata `raw`. +2. Copia dentro `raw` tutti i file `.txt` esportati dallo strumento (uno o più file, es. `AL12 10 mgml soluzione (-1.6_1.2 scan 0.1Vs).txt`). +3. Non serve rinominarli o modificarli: la velocità di scansione viene letta automaticamente dal nome del file (es. `0.1Vs`, `0.5Vs`, `1Vs`). + +## 6. Eseguire la pipeline + +Con l'ambiente virtuale attivo (vedi punto 4), lancia: + +``` +python3 main.py +``` + +Lo script esegue in sequenza tutti i passaggi ed elaborerà **tutti** i file presenti in `raw`: + +1. Converte ogni `.txt` in un CSV a due colonne (Potenziale, Corrente). +2. Isola l'ultimo ciclo completo di ogni misura. +3. Chiede il **potenziale di riferimento** (in Volt): digitalo e premi invio (es. `-0.152`). +4. Per ogni file chiede la **velocità di scansione**: viene proposto il valore trovato nel nome del file, basta premere invio per confermarlo, oppure puoi digitarne uno diverso. +5. Genera un grafico professionale (PNG) per ogni misura. + +## 7. Dove trovare i risultati + +- La cartella `raw` conterrà, oltre ai `.txt` originali, un CSV intermedio a due colonne per ciascun file. +- La cartella `output` conterrà, per ciascun file: + - il CSV finale con tutte le colonne (potenziale, corrente, potenziale normalizzato, colonne derivate); + - il grafico in formato PNG, pronto per essere usato in relazioni o presentazioni. + +## 8. Rilanciare la pipeline su nuovi dati + +Ogni volta che hai nuovi file da elaborare, ripeti solo i punti 5 e 6 (aggiungi i `.txt` in `raw` e rilancia `python3 main.py`) — non serve ricreare l'ambiente virtuale. + +Se vuoi rielaborare gli stessi file da zero (es. con un potenziale di riferimento diverso), puoi lanciare di nuovo `python3 main.py`: i file in `output` verranno sovrascritti con i nuovi risultati. + +## Struttura degli script + +Se vuoi eseguire solo un passaggio della pipeline invece di tutta la sequenza, ogni script può essere lanciato singolarmente (sempre con l'ambiente virtuale attivo): + +| Script | Cosa fa | +|---|---| +| `cv_to_csv.py` | Converte i `.txt` in `raw` in CSV a due colonne | +| `cv_last_cycle.py` | Estrae l'ultimo ciclo completo e lo salva in `output` | +| `cv_normalize_potential.py` | Aggiunge la colonna del potenziale normalizzato | +| `cv_current_over_sqrt_scanrate.py` | Aggiunge le colonne di corrente derivate dalla velocità di scansione | +| `cv_plot.py` | Genera i grafici PNG | +| `main.py` | Esegue tutti gli script sopra in sequenza | + +## Licenza + +Questo progetto è distribuito con licenza MIT — vedi il file [LICENSE](LICENSE).