diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..7a60b85e148f80966a550e5ab6a762a907c69ca6
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc
diff --git a/README.md b/README.md
index 66890eb02e3bc0a1b7f45da03227149beec743e8..2b75549c1ac2f319b4d508d791ab20dce1357573 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,33 @@
---
-title: Ecflow
-emoji: 👀
-colorFrom: red
-colorTo: blue
+title: ECFlow
+emoji: ⚡
+colorFrom: blue
+colorTo: purple
sdk: gradio
-sdk_version: 6.9.0
+sdk_version: "4.44.0"
app_file: app.py
pinned: false
+license: mit
+short_description: Bayesian inference for CV & TPD analysis
---
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ECFlow — Amortized Bayesian Inference for Electrochemistry & Catalysis
+
+Upload cyclic voltammetry (CV) or temperature-programmed desorption (TPD) data to automatically:
+
+1. **Identify the reaction mechanism** from 6 candidates per domain
+2. **Infer kinetic parameters** with full Bayesian posterior uncertainty
+
+Inference takes ~50 ms on CPU. Accepts CSV files or plot images.
+
+## Supported Mechanisms
+
+**Electrochemistry (CV):** Nernst, Butler-Volmer, Marcus-Hush-Chidsey, Adsorption, EC, Langmuir-Hinshelwood
+
+**Catalysis (TPD):** First-order, Second-order, LH Surface, Mars-van Krevelen, Coverage-dependent, Diffusion-limited
+
+## Citation
+
+```
+[Citation to be added upon publication]
+```
diff --git a/app.py b/app.py
new file mode 100644
index 0000000000000000000000000000000000000000..984f8a0a3ee616e86cb9a1a438703774744e37da
--- /dev/null
+++ b/app.py
@@ -0,0 +1,958 @@
+"""
+ECFlow — Amortized Bayesian Inference for Electrochemistry & Catalysis
+
+Gradio web interface for mechanism classification and parameter inference
+from cyclic voltammetry (CV) and temperature-programmed desorption (TPD) data.
+"""
+
+import os
+import sys
+import json
+import tempfile
+from pathlib import Path
+
+import numpy as np
+import gradio as gr
+
+
+
+from inference import ECFlowPredictor
+from preprocessing import (
+ nondimensionalize_cv,
+ estimate_E0,
+ parse_cv_csv,
+ parse_tpd_csv,
+)
+from plotting import (
+ plot_mechanism_probs,
+ plot_posteriors,
+ plot_parameter_table,
+ plot_reconstruction,
+ plot_concentration_profiles,
+)
+
+# ---------------------------------------------------------------------------
+# Model paths (relative to repo root)
+# ---------------------------------------------------------------------------
+REPO_ROOT = Path(__file__).resolve().parent
+
+EC_CHECKPOINT = REPO_ROOT / "checkpoints" / "ec_best.pt"
+TPD_CHECKPOINT = REPO_ROOT / "checkpoints" / "tpd_best.pt"
+
+# Allow override via environment variables
+EC_CHECKPOINT = Path(os.environ.get("ECFLOW_EC_CHECKPOINT", str(EC_CHECKPOINT)))
+TPD_CHECKPOINT = Path(os.environ.get("ECFLOW_TPD_CHECKPOINT", str(TPD_CHECKPOINT)))
+
+predictor = None
+
+
+def get_predictor():
+ global predictor
+ if predictor is None:
+ ec_ckpt = str(EC_CHECKPOINT) if EC_CHECKPOINT.exists() else None
+ tpd_ckpt = str(TPD_CHECKPOINT) if TPD_CHECKPOINT.exists() else None
+ predictor = ECFlowPredictor(
+ ec_checkpoint=ec_ckpt,
+ tpd_checkpoint=tpd_ckpt,
+ device="cpu",
+ )
+ return predictor
+
+
+# =========================================================================
+# CV Analysis
+# =========================================================================
+
+def analyze_cv(files, scan_rates_text, E0_V, T_K, A_cm2,
+ C_mM, D_cm2s, n_electrons, n_samples):
+ """Analyze CV data from potentiostat CSV files.
+
+ Accepts CSV files with columns for potential (V) and current (A/mA/µA).
+ If the CSV includes a Time (s) column, the scan rate is auto-detected.
+ Otherwise, scan rates must be provided.
+ """
+ if not files:
+ return _ec_error("Please upload at least one CSV file.")
+
+ scan_rates_text = scan_rates_text.strip() if scan_rates_text else ""
+
+ user_rates = None
+ if scan_rates_text:
+ try:
+ user_rates = [float(s.strip()) for s in scan_rates_text.split(",")]
+ except ValueError:
+ return _ec_error("Invalid scan rates. Enter comma-separated numbers in V/s.")
+ if len(files) != len(user_rates):
+ return _ec_error(
+ f"Number of files ({len(files)}) must match number of "
+ f"scan rates ({len(user_rates)}).")
+
+ C_molcm3 = float(C_mM) * 1e-6 if C_mM else 1e-6
+ n = int(n_electrons) if n_electrons else 1
+ T = float(T_K) if T_K else 298.15
+ A = float(A_cm2) if A_cm2 else 0.0707
+
+ parsed_data = []
+ scan_rates = []
+ for idx, f in enumerate(files):
+ content = Path(f.name).read_text()
+ parsed = parse_cv_csv(content)
+ parsed_data.append(parsed)
+
+ if user_rates is not None:
+ v = user_rates[idx]
+ elif "scan_rate_Vs" in parsed:
+ v = parsed["scan_rate_Vs"]
+ else:
+ return _ec_error(
+ f"Cannot determine scan rate for file '{Path(f.name).name}'. "
+ "Either provide scan rates (V/s) or upload CSV files that "
+ "include a Time (s) column.")
+ scan_rates.append(v)
+
+ if E0_V:
+ e0 = float(E0_V)
+ e0_source = "user"
+ else:
+ e0_estimates = [estimate_E0(p["E_V"], p["i_A"]) for p in parsed_data]
+ e0 = float(np.median(e0_estimates))
+ e0_source = "auto"
+
+ D = float(D_cm2s) if D_cm2s else 1e-5
+
+ potentials, fluxes, sigmas_list = [], [], []
+ for idx, (parsed, v) in enumerate(zip(parsed_data, scan_rates)):
+ E, i_A = parsed["E_V"], parsed["i_A"]
+
+ theta, flux, sigma = nondimensionalize_cv(
+ E, i_A, v, e0, T, A, C_molcm3, D, n
+ )
+ potentials.append(theta)
+ fluxes.append(flux)
+ sigmas_list.append(sigma)
+
+ result = _run_ec_analysis(potentials, fluxes, sigmas_list, n_samples)
+
+ preproc_info = "\n\n---\n*Preprocessing:* "
+ rate_strs = [f"{v*1000:.1f} mV/s (σ={s:.2f})" for v, s in zip(scan_rates, sigmas_list)]
+ preproc_info += f"Scan rates: {', '.join(rate_strs)}. "
+ if e0_source == "auto":
+ preproc_info += (
+ f"E₀ auto-estimated as {e0:.4f} V from peak midpoints. "
+ "For better accuracy, provide E₀ under Advanced parameters."
+ )
+ else:
+ preproc_info += f"E₀ = {e0:.4f} V (user-provided)."
+
+ result_list = list(result)
+ if isinstance(result_list[1], str):
+ result_list[1] += preproc_info
+ return tuple(result_list)
+
+
+def analyze_cv_image(image, scan_rate_text, E0_V, threshold, n_samples,
+ x_min, x_max, y_min, y_max):
+ """Analyze CV from an uploaded plot image.
+
+ Extracts the CV curve via image digitization, then nondimensionalizes
+ and runs inference identically to the CSV path.
+ Axis bounds are auto-detected via OCR if not provided.
+ """
+ if image is None:
+ return _ec_error("Please upload an image.")
+
+ try:
+ from digitizer import digitize_plot, auto_detect_axis_bounds
+ except ImportError:
+ return _ec_error("OpenCV not available for image digitization.")
+
+ scan_rate_text = scan_rate_text.strip() if scan_rate_text else ""
+ if not scan_rate_text:
+ return _ec_error("Please enter the scan rate (V/s).")
+ try:
+ v_Vs = float(scan_rate_text)
+ except ValueError:
+ return _ec_error("Invalid scan rate. Enter a number in V/s.")
+
+ img_arr = np.array(image)
+
+ # Determine axis bounds: user overrides take priority, else auto-detect
+ has_user_bounds = all(
+ v is not None and v != 0 for v in [x_min, x_max, y_min, y_max]
+ )
+ if has_user_bounds:
+ bounds = {
+ "x_min": float(x_min), "x_max": float(x_max),
+ "y_min": float(y_min), "y_max": float(y_max),
+ }
+ bounds_source = "user"
+ else:
+ bounds = auto_detect_axis_bounds(img_arr)
+ if bounds is None:
+ return _ec_error(
+ "Could not auto-detect axis bounds from the image. "
+ "Please enter E min, E max, I min, I max under "
+ "'Advanced: axis overrides'.")
+ bounds_source = "auto"
+
+ try:
+ E_V, I_raw = digitize_plot(
+ img_arr, bounds["x_min"], bounds["x_max"],
+ bounds["y_min"], bounds["y_max"],
+ threshold=int(threshold),
+ )
+ except Exception as e:
+ return _ec_error(f"Digitization failed: {e}")
+
+ # Convert current units: OCR reads axis labels so I_raw is in the
+ # display unit (µA, mA, A). Assume A unless values are large.
+ i_max = np.max(np.abs(I_raw))
+ if i_max > 100:
+ i_A = I_raw * 1e-6 # likely µA
+ i_unit_guess = "µA"
+ elif i_max > 0.1:
+ i_A = I_raw * 1e-3 # likely mA
+ i_unit_guess = "mA"
+ else:
+ i_A = I_raw
+ i_unit_guess = "A"
+
+ if E0_V is not None and E0_V != 0:
+ e0 = float(E0_V)
+ e0_source = "user"
+ else:
+ e0 = float(estimate_E0(E_V, i_A))
+ e0_source = "auto"
+
+ D = 1e-5
+ T = 298.15
+ A = 0.0707
+ C_molcm3 = 1e-6
+ n = 1
+
+ theta, flux, sigma = nondimensionalize_cv(
+ E_V, i_A, v_Vs, e0, T, A, C_molcm3, D, n
+ )
+
+ result = _run_ec_analysis([theta], [flux], [sigma], n_samples)
+
+ preproc_info = "\n\n---\n*Preprocessing (image):* "
+ preproc_info += f"Scan rate: {v_Vs*1000:.1f} mV/s (σ={sigma:.2f}). "
+ preproc_info += f"Axis bounds ({bounds_source}): E=[{bounds['x_min']:.3f}, {bounds['x_max']:.3f}] V, "
+ preproc_info += f"I=[{bounds['y_min']:.2f}, {bounds['y_max']:.2f}] {i_unit_guess}. "
+ if e0_source == "auto":
+ preproc_info += f"E₀ auto-estimated as {e0:.4f} V."
+ else:
+ preproc_info += f"E₀ = {e0:.4f} V (user-provided)."
+
+ result_list = list(result)
+ if isinstance(result_list[1], str):
+ result_list[1] += preproc_info
+ return tuple(result_list)
+
+
+def _ec_error(msg=""):
+ """Return empty outputs for EC error cases."""
+ return None, msg, None, gr.update(choices=[], value=None), None, None, None
+
+
+def _run_ec_analysis(potentials, fluxes, sigmas, n_samples):
+ """Core EC analysis: predict + reconstruct for top mechanism."""
+ pred = get_predictor()
+ result = pred.predict_ec(potentials, fluxes, sigmas, n_samples=int(n_samples))
+ top_mech = result["predicted_mechanism"]
+ recon = pred.reconstruct_ec(result, potentials, fluxes, sigmas)
+
+ fig_probs = plot_mechanism_probs(result["mechanism_probs"], domain="ec")
+ summary = _build_summary_text(result, recon=recon, domain="ec")
+
+ sorted_mechs = sorted(result["mechanism_probs"].items(), key=lambda x: -x[1])
+ mech_choices = [f"{m} ({p:.1%})" for m, p in sorted_mechs]
+
+ state = {
+ "result": result,
+ "potentials": [p.tolist() for p in potentials],
+ "fluxes": [f.tolist() for f in fluxes],
+ "sigmas": sigmas,
+ }
+
+ fig_post, fig_recon, fig_conc = _render_ec_mechanism(
+ top_mech, result, recon, sigmas
+ )
+
+ return (
+ fig_probs, summary, state,
+ gr.update(choices=mech_choices, value=mech_choices[0]),
+ fig_post, fig_recon, fig_conc,
+ )
+
+
+def _render_ec_mechanism(mech, result, recon, sigmas):
+ """Render posteriors, reconstruction, and concentration for one EC mechanism."""
+ stats = result["parameter_stats"].get(mech)
+ samples = result["posterior_samples"].get(mech)
+
+ fig_posteriors = None
+ if stats and samples is not None:
+ fig_posteriors = plot_posteriors(samples, stats["names"], mech, domain="ec")
+
+ fig_recon = None
+ fig_conc = None
+ if recon is not None:
+ scan_labels = [f"\u03c3 = {s:.2f}" for s in sigmas] if sigmas else None
+ fig_recon = plot_reconstruction(
+ recon["observed"], recon["reconstructed"], domain="ec",
+ nrmses=recon.get("nrmse"), r2s=recon.get("r2"),
+ scan_labels=scan_labels,
+ )
+ conc_curves = recon.get("concentrations")
+ if conc_curves:
+ fig_conc = plot_concentration_profiles(conc_curves, scan_labels=scan_labels)
+
+ return fig_posteriors, fig_recon, fig_conc
+
+
+def _on_ec_mechanism_change(mech_choice, state):
+ """Callback when user selects a different EC mechanism from the dropdown."""
+ if not state or not mech_choice:
+ return None, None, None
+
+ mech = mech_choice.split(" (")[0]
+ result = state["result"]
+ potentials = [np.array(p) for p in state["potentials"]]
+ fluxes = [np.array(f) for f in state["fluxes"]]
+ sigmas = state["sigmas"]
+
+ pred = get_predictor()
+ recon = pred.reconstruct_ec(result, potentials, fluxes, sigmas, mechanism=mech)
+ return _render_ec_mechanism(mech, result, recon, sigmas)
+
+
+# =========================================================================
+# TPD Analysis
+# =========================================================================
+
+def analyze_tpd(files, heating_rates_text, n_samples):
+ """Analyze TPD data."""
+ if not files:
+ return _tpd_error("Please upload at least one CSV file.")
+
+ temperatures, rates = [], []
+ csv_betas = []
+ for f in files:
+ content = Path(f.name).read_text()
+ parsed = parse_tpd_csv(content)
+ temperatures.append(parsed["T_K"])
+ rates.append(parsed["signal"])
+ if "beta_Ks" in parsed:
+ csv_betas.append(parsed["beta_Ks"])
+
+ heating_rates_text = heating_rates_text.strip() if heating_rates_text else ""
+ if heating_rates_text:
+ try:
+ betas = [float(s.strip()) for s in heating_rates_text.split(",")]
+ except ValueError:
+ return _tpd_error("Invalid heating rates. Enter comma-separated numbers in K/s.")
+ if len(files) != len(betas):
+ return _tpd_error(
+ f"Number of files ({len(files)}) must match heating rates ({len(betas)}).")
+ elif len(csv_betas) == len(files):
+ betas = csv_betas
+ else:
+ return _tpd_error(
+ "Please enter the heating rate (β in K/s) for each file. "
+ "This value is critical for correct inference. "
+ "Alternatively, include a 'Time (s)' column in your CSV so β can be computed automatically.")
+
+ return _run_tpd_analysis(temperatures, rates, betas, n_samples)
+
+
+def analyze_tpd_image(image, heating_rates_text, threshold, n_samples,
+ x_min, x_max, y_min, y_max):
+ """Analyze TPD from an uploaded plot image.
+
+ Axis bounds are auto-detected via OCR if not provided.
+ """
+ if image is None:
+ return _tpd_error("Please upload an image.")
+
+ try:
+ from digitizer import digitize_plot, auto_detect_axis_bounds
+ except ImportError:
+ return _tpd_error("OpenCV not available for image digitization.")
+
+ heating_rates_text = heating_rates_text.strip() if heating_rates_text else ""
+ if not heating_rates_text:
+ return _tpd_error(
+ "Please enter the heating rate (β in K/s). "
+ "This value is critical for correct inference.")
+ try:
+ betas = [float(s.strip()) for s in heating_rates_text.split(",")]
+ except ValueError:
+ return _tpd_error("Invalid heating rates.")
+
+ img_arr = np.array(image)
+
+ has_user_bounds = all(
+ v is not None and v != 0 for v in [x_min, x_max, y_min, y_max]
+ )
+ if has_user_bounds:
+ bounds = {
+ "x_min": float(x_min), "x_max": float(x_max),
+ "y_min": float(y_min), "y_max": float(y_max),
+ }
+ else:
+ bounds = auto_detect_axis_bounds(img_arr)
+ if bounds is None:
+ return _tpd_error(
+ "Could not auto-detect axis bounds from the image. "
+ "Please enter T min, T max, Signal min, Signal max "
+ "under 'Advanced: axis overrides'.")
+
+ try:
+ x_data, y_data = digitize_plot(
+ img_arr, bounds["x_min"], bounds["x_max"],
+ bounds["y_min"], bounds["y_max"],
+ threshold=int(threshold),
+ )
+ except Exception as e:
+ return _tpd_error(f"Digitization failed: {e}")
+
+ return _run_tpd_analysis([x_data], [y_data], betas[:1], n_samples)
+
+
+def _tpd_error(msg=""):
+ """Return empty outputs for TPD error cases."""
+ return None, msg, None, gr.update(choices=[], value=None), None, None
+
+
+def _run_tpd_analysis(temperatures, rates, betas, n_samples):
+ """Core TPD analysis: predict + reconstruct for top mechanism."""
+ pred = get_predictor()
+ result = pred.predict_tpd(temperatures, rates, betas, n_samples=int(n_samples))
+ top_mech = result["predicted_mechanism"]
+ recon = pred.reconstruct_tpd(result, temperatures, rates, betas)
+
+ fig_probs = plot_mechanism_probs(result["mechanism_probs"], domain="tpd")
+ summary = _build_summary_text(result, recon=recon, domain="tpd")
+
+ sorted_mechs = sorted(result["mechanism_probs"].items(), key=lambda x: -x[1])
+ mech_choices = [f"{m} ({p:.1%})" for m, p in sorted_mechs]
+
+ state = {
+ "result": result,
+ "temperatures": [t.tolist() for t in temperatures],
+ "rates": [r.tolist() for r in rates],
+ "betas": betas,
+ }
+
+ fig_post, fig_recon = _render_tpd_mechanism(top_mech, result, recon, betas)
+
+ return (
+ fig_probs, summary, state,
+ gr.update(choices=mech_choices, value=mech_choices[0]),
+ fig_post, fig_recon,
+ )
+
+
+def _render_tpd_mechanism(mech, result, recon, betas):
+ """Render posteriors and reconstruction for one TPD mechanism."""
+ stats = result["parameter_stats"].get(mech)
+ samples = result["posterior_samples"].get(mech)
+
+ fig_posteriors = None
+ if stats and samples is not None:
+ fig_posteriors = plot_posteriors(samples, stats["names"], mech, domain="tpd")
+
+ fig_recon = None
+ if recon is not None:
+ scan_labels = [f"\u03b2 = {b:.2f} K/s" for b in betas] if betas else None
+ fig_recon = plot_reconstruction(
+ recon["observed"], recon["reconstructed"], domain="tpd",
+ nrmses=recon.get("nrmse"), r2s=recon.get("r2"),
+ scan_labels=scan_labels,
+ )
+
+ return fig_posteriors, fig_recon
+
+
+def _on_tpd_mechanism_change(mech_choice, state):
+ """Callback when user selects a different TPD mechanism from the dropdown."""
+ if not state or not mech_choice:
+ return None, None
+
+ mech = mech_choice.split(" (")[0]
+ result = state["result"]
+ temperatures = [np.array(t) for t in state["temperatures"]]
+ rates = [np.array(r) for r in state["rates"]]
+ betas = state["betas"]
+
+ pred = get_predictor()
+ recon = pred.reconstruct_tpd(result, temperatures, rates, betas, mechanism=mech)
+ return _render_tpd_mechanism(mech, result, recon, betas)
+
+
+# =========================================================================
+# Shared helpers
+# =========================================================================
+
+def _build_summary_text(result, recon=None, domain="ec"):
+ """Build a markdown summary of inference results."""
+ mech = result["predicted_mechanism"]
+ prob = result["mechanism_probs"][mech]
+
+ lines = [
+ f"## Predicted Mechanism: **{mech}** ({prob:.1%} confidence)\n",
+ ]
+
+ stats = result["parameter_stats"].get(mech)
+ if stats:
+ lines.append("### Parameter Estimates (90% Credible Interval)\n")
+ lines.append("| Parameter | Mean | 90% CI |")
+ lines.append("|-----------|------|--------|")
+ for i, name in enumerate(stats["names"]):
+ mean = stats["mean"][i]
+ q05 = stats["q05"][i]
+ q95 = stats["q95"][i]
+ lines.append(f"| {name} | {mean:.4f} | [{q05:.4f}, {q95:.4f}] |")
+
+ if recon is not None:
+ lines.append("\n### Signal Reconstruction Quality\n")
+ lines.append(f"- **Average NRMSE**: {recon['mean_nrmse']:.4f}")
+ lines.append(f"- **Average R\u00b2**: {recon['mean_r2']:.4f}")
+ if len(recon["nrmse"]) > 1:
+ lines.append("\n| Curve | NRMSE | R\u00b2 |")
+ lines.append("|-------|-------|-----|")
+ for i, (n, r) in enumerate(zip(recon["nrmse"], recon["r2"])):
+ lines.append(f"| {i + 1} | {n:.4f} | {r:.4f} |")
+
+ lines.append("\n### All Mechanism Probabilities\n")
+ lines.append("| Mechanism | Probability |")
+ lines.append("|-----------|-------------|")
+ sorted_mechs = sorted(result["mechanism_probs"].items(), key=lambda x: -x[1])
+ for m, p in sorted_mechs:
+ marker = " \u2190 predicted" if m == mech else ""
+ lines.append(f"| {m} | {p:.4f} |{marker}")
+ lines.append("\n*Use the dropdown below to view posteriors and reconstruction for any mechanism.*")
+
+ result_json = {
+ "predicted_mechanism": mech,
+ "mechanism_probs": result["mechanism_probs"],
+ "parameter_stats": {
+ k: {kk: vv for kk, vv in v.items() if kk != "samples"}
+ for k, v in result["parameter_stats"].items()
+ } if result["parameter_stats"] else {},
+ }
+ if recon:
+ result_json["reconstruction"] = {
+ "mean_nrmse": recon["mean_nrmse"],
+ "mean_r2": recon["mean_r2"],
+ }
+ lines.append(f"\nRaw JSON
\n\n```json\n{json.dumps(result_json, indent=2)}\n```\n