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

1. Vai su python.org/downloads e clicca sul pulsante giallo per scaricare l'ultima versione (es. "Download Python 3.12.x").
2. Avvia il file scaricato (es. python-3.12.x-amd64.exe).
3. Nella prima schermata dell'installer, spunta in basso la casella "Add python.exe to PATH" — è il passaggio più importante, senza non funzionerà nulla dal terminale.
4. Clicca su "Install Now" e attendi il completamento.
5. Al termine, clicca "Close".

Il modulo venv (necessario al punto 4) è già incluso automaticamente in questa installazione: su Windows non serve installare nient'altro.

macOS

Scarica l'installer da python.org/downloads oppure, se hai Homebrew, esegui brew install python.

Linux (o WSL su Windows)

Su molte distribuzioni Python è già preinstallato, ma il modulo venv a volte è un pacchetto separato. Se al punto 4 ottieni un errore tipo ensurepip is not available, installalo con (Debian/Ubuntu):

sudo apt update
sudo apt install python3-venv

2. Verificare l'installazione

Apri il terminale — su Windows si chiama PowerShell (cercalo nel menu Start digitando "PowerShell") oppure "Prompt dei comandi"; su macOS/Linux è il "Terminale" — e digita:

python --version

Su Windows dovrebbe funzionare subito grazie al PATH configurato al punto 1. Su macOS/Linux, se python non è riconosciuto, prova con python3 --version. Dovresti vedere qualcosa come Python 3.11.x. Da qui in poi, ovunque leggi python, usa il comando che ha funzionato per te (python o python3).

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.

python -m venv .venv

Poi attivalo:

• Windows (PowerShell):

  .venv\Scripts\Activate.ps1
  

  Se compare un errore che parla di "esecuzione script disabilitata" (execution policy), apri PowerShell come amministratore ed esegui una sola volta:

  Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
  

  poi riprova ad attivare l'ambiente virtuale.
• 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:

python 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 python 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 python 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.