ciclovolametrie/README.md

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, avvialo e spunta la casella "Add python.exe to PATH" prima di cliccare Install.
• macOS: scarica l'installer da python.org/downloads oppure, se hai Homebrew, 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.