vibe-viewerDocumentation

Electrochemistry and transport results: QVF contract audit

This page is the audit step of #209: it checks what the QVF format can carry for the electrochemistry and transport results of the Alvarez collaboration, against the pinned qvf release (v0.6.0, QVF_TAG) as of 2026-11-14. vibe-viewer reads results only through released QVF, so every gap below is a request to the qvf master. It is not a viewer schema extension and not a native reader for an instrument’s file.

Geometry alone predicts no sensor response, current, impedance, selectivity, electrode kinetics or conductivity. The viewer draws such quantities only when a producer or a measurement supplies them, and it labels each value as calculated or measured.

What the format and the viewer cover today

Quantity

QVF kind (v0.6.0)

Viewer

What is missing

Zero-bias transmission T(E), eigenchannels, spin

x_vibeqc.transport.transmission (vibe-qc vendor kind, schema version 1)

Chart, terminal plot and table export with units (transport charts, #212)

A canonical kind; a description of the electrodes and leads

Current I(V) and dI/dV

x_vibeqc.transport.iv (vendor kind)

Chart with the bias model, temperature and Fermi level; a rigid-shift curve is labelled as an approximation (#212)

The transmission at each bias of a per-bias curve is not stored, so T(E; V) cannot be drawn; the convention for the electrode chemical potentials under bias is not recorded

Total and projected DOS, spin-resolved

dos.total, dos.projected

Charts; PDOS summed over an atom group (nanotubes)

Named atom groups are viewer selections, not archive data, so two calculations cannot be compared by region name

Charge and density differences, ELF

volume.difference (with operand references, data = a − b), volume.elf, volume.density

Isosurfaces, slices, axial profiles

Nothing for display; integrated fragment charges are not a format quantity

Atomic charges and spins

atom_properties

Atom colouring and tables

Nothing for display

Adsorption and reaction energies

reaction.scheme; the step energies key is reserved in v0.6.0

vibe-viewer reaction sums correlated electronic totals only (reaction analysis)

qvf#16 step energies are adopted on qvf main but not released; DFT adsorption energies have no released route

Measured voltammetry: peak potential against pH, scan rate or concentration; CV and SWV curves

none

none

A kind for measured electrochemical series, and the conditions listed below

Calculated electrode potentials E(pH)

none

none

A calculated-potential series with its reference scale and the free energies it comes from

Impedance and capacitance

none

none

A frequency-resolved series with real and imaginary parts and its equivalent-circuit model, if any

Measured or calculated identity

none: provenance and run.record describe calculations

none

A field on every series saying which it is, with the measurement’s source

spectra.generic takes any x/y pair with declared units, but it describes a spectrum and has none of the conditions below. Writing a voltammogram into it would lose the reference electrode, the pH and the identity of the data, so the viewer does not use it for electrochemistry.

Fields requested from qvf

Proposed to the qvf master as qvf#33. In short:

  1. Measured or calculated identity on every electrochemical or transport series. A measured series records its source (DOI, figure or table), the technique and how the values were treated: raw, baseline-corrected, scaled, normalized, fitted, or digitized from a figure.

  2. Potential scale. The reference electrode with its filling solution when known, for example Ag/AgCl (3 M KCl), or a computational scale such as SHE. A calculated potential also records the absolute reference potential used to convert free energies to that scale, because published values differ.

  3. Kind of potential. A peak potential, a half-wave potential, a formal potential and a calculated equilibrium potential are different quantities. An irreversible peak is not an equilibrium potential, so the kind is a required field, not a label.

  4. Conditions: pH, temperature, electrolyte and concentration, analyte concentration, electrode, and the technique’s settings: the scan rate for CV; frequency, amplitude and step for SWV; the frequency range and perturbation amplitude for impedance. An unknown condition is written as unknown, so a reader can tell it apart from a field the producer omitted.

  5. Series axes: potential, pH, scan rate, concentration or frequency on x; current, current density, peak potential, impedance (real and imaginary) or capacitance on y, all with declared units. A fitted line is stored as a fit, with its parameters and their uncertainties, and is drawn apart from the points it was fitted to.

  6. Named atom regions on structure (interface, site, adsorbate, lead), so the viewer can match regions between calculations by name instead of by atom index.

  7. A release of qvf#16 step energies, so an adsorption energy is a reaction step with its runs, method and thermal conditions.

  8. Canonical transport kinds promoted from the vibe-qc vendor kinds, with a bias axis for a per-bias T(E; V) and the electrode chemical-potential convention.

The melatonin example

The fixture the request asks for follows the melatonin oxidation study at CNT-fibre microelectrodes by Kumar, Weerawarna and Alvarez, Electroanalysis 2024 (library key kumar2024carbon). It shows why each field above is needed:

  • The peak potentials are measured by square-wave voltammetry (10 Hz, 25 mV amplitude, 4 mV step) on 10 µM melatonin in phosphate buffer at pH 2.7–9.0, against Ag/AgCl (3 M KCl) (§2 and §3.2.2).

  • The paper fits E_p = −40.019 pH + 984.35 (mV, R² = 0.9897). The slope is not the 59 mV per pH unit of an equal electron and proton count (§3.2.2), so the fit is stored with its source, and the points come from the figure marked as digitized or, better, from the authors’ data.

  • It analyses the oxidation as completely irreversible and adsorption controlled, using Laviron’s equation with α taken as 0.5 (§3.2.2). E_p is therefore a peak potential that shifts with scan rate, not a formal or equilibrium potential, and a calculated E_eq(pH) is drawn as a separate series with its own legend entry.

  • An adsorption energy of melatonin on a CNT model is a separate calculated comparison. It does not imply a peak potential, a sensitivity or a selectivity.

What follows the release

When qvf releases these fields and a producer writes them, the viewer will:

  • read the series from the released kinds, after re-vendoring the qvf files at the new tag;

  • draw measured and calculated series with different marks and legend entries, and state the potential scale on the axis title, refusing to put series on different reference scales on one axis without the conversion being recorded;

  • show unknown conditions as “unknown” in captions and exported tables;

  • compare calculations by region name, refusing regions that do not correspond;

  • export the displayed data with units, conditions and source metadata;

  • test this against producer fixtures, including the melatonin example above.

Until then, the vibe-qc transport kinds from #212 are the only part of this family that the viewer plots.