Author a galvanic cell and predict electrochemical equilibrium

verifiedAgainst 6f58cea · verifiedOn 2026-09-10.

What you will build

In Voxamine, chemical metallurgy and aqueous extraction are not magical craft timers. When iron scraps precipitate copper metal from an acidic leach solution (cementation), or when an electric current decomposes water into hydrogen and oxygen, the reactions obey the laws of electrochemistry (MASTERPLAN.md §28.6).

You will compose a standard galvanic cell using the catalogued electrode couples in ElectrochemicalSeries.cs, evaluate spontaneous cell potential ($E^\circ_{\text{cell}}$) and electron balance using GalvanicCellMath.TryComposeStandardCell, derive standard Gibbs free energy ($\Delta G^\circ = -nFE^\circ$), compute concentration shifts via the Nernst equation, calculate the minimum required electrolysis potential for non-spontaneous routes, and inspect the resulting thermodynamic parameters inside the Electrochemistry Lab Voxel Workshop module (ElectrochemistryLabModule.cs).

// Evaluate spontaneous galvanic cementation (Cu2+/Cu cathode, Fe2+/Fe anode):
StandardElectrodeCouple cathode = ElectrochemicalSeries.At(9); // Cu2+ + 2 e- -> Cu (+0.342 V)
StandardElectrodeCouple anode = ElectrochemicalSeries.At(5);   // Fe2+ + 2 e- -> Fe (-0.447 V)

if (GalvanicCellMath.TryComposeStandardCell(in cathode, in anode, out GalvanicCellState cell))
{
    // cell.StandardCellPotentialVolts -> +0.789 V
    // cell.ElectronsTransferred -> 2
    // cell.StandardGibbsFreeEnergyKilojoulesPerMol -> -152.25 kJ/mol (spontaneous!)
}

Where this sits

The electrochemical framework sits entirely within the pure, allocation-free chemistry layer and connects authoring data to in-world industrial apparatus:

• Data & Sources (ElectrochemicalSeries) provides immutable, peer-reviewed standard reduction potentials ($E^\circ$ vs standard hydrogen electrode) sourced from CRC and NIST.
• Pure Math Solver (GalvanicCellMath) computes cell potentials, electron stoichiometry ($\text{lcm}(n_a, n_c)$), concentration shifts (Nernst), product mass (Faraday), and activation barriers (Tafel) without allocating heap memory.
• Thermodynamics Bridge (ThermodynamicMath) maintains the single-sourced $\Delta G^\circ = -nFE^\circ$ bridge so energy and voltage never drift or disagree.
• Voxel Workshop (ElectrochemistryLabModule) provides an interactive authoring tool to audit couple combinations, slide reaction quotients and temperatures, and view electrolysis drive requirements.

flowchart TD
  subgraph SOURCES["Data & Evidence (Docs/CHEMISTRY_SOURCES.md)"]
    SERIES["ElectrochemicalSeries\n(13 standard couples: K+ down to O2/H2O)"]
    COUPLE["StandardElectrodeCouple\n(E° vs SHE at 298.15 K, n electrons)"]
  end

  subgraph SOLVER["VoxelSandbox.Chemistry"]
    COMPOSE["GalvanicCellMath.TryComposeStandardCell\n(E°cell = E°cathode - E°anode)"]
    STATE["GalvanicCellState struct\n(E°cell, ElectronsTransferred, ΔG°)"]
    NERNST["GalvanicCellMath.TryNernstPotentialVolts\n(E = E° - (RT/nF) ln Q)"]
    ELECTROLYSIS["GalvanicCellMath.TryElectrolysisVoltageVolts\n(Vmin = -Ecell for non-spontaneous pairs)"]
    FARADAY["GalvanicCellMath.TryFaradayProductMoles\n(n = I·t / z·F)"]
  end

  subgraph BRIDGE["Thermodynamic Integrity"]
    THERMO["ThermodynamicMath\nΔG° = -n F E°cell"]
  end

  subgraph WORKSHOP["Voxel Workshop (Editor)"]
    MODULE["ElectrochemistryLabModule\n(Couple pickers, T & Q sliders, audit report)"]
  end

  SERIES --> COUPLE
  COUPLE --> COMPOSE
  COMPOSE --> THERMO
  THERMO --> STATE
  STATE --> NERNST
  STATE --> ELECTROLYSIS
  STATE --> FARADAY
  STATE --> MODULE

Before you start

Read Docs/MASTERPLAN.md §28.6 (“Electrochemical series and cell potentials”) and Docs/CHEMISTRY_SOURCES.md (“Electrochemical Series”), then review:

• StandardElectrodeCouple, the immutable representation of an IUPAC reduction half-reaction.
• GalvanicCellMath, the pure mathematical assembly of cell potentials, Nernst shifts, and electrolysis thresholds.
• ElectrochemistryLabModule, the Voxel Workshop preview module.
• GalvanicCellMathTests, test fixture asserting single-sourced thermodynamic consistency.

Review the fundamental electrochemistry conventions:

Quantity	Symbol	Formula	Rule
Standard Cell Potential	$E^\circ_{\text{cell}}$	$E^\circ_{\text{cathode}} - E^\circ_{\text{anode}}$	Positive $E^\circ_{\text{cell}}$ means the forward cell runs spontaneously.
Balanced Electron Count	$n$	$\text{lcm}(n_{\text{cathode}}, n_{\text{anode}})$	Overall electrons moved per formula unit; equalizes electrons gained and lost.
Standard Gibbs Energy	$\Delta G^\circ$	$-n \cdot F \cdot E^\circ_{\text{cell}}$	Derived via single-sourced Faraday constant ($F = 96485.33212\text{ C/mol}$). Never independently authored.
Nernst Cell Potential	$E$	$E^\circ - \frac{R \cdot T}{n \cdot F} \ln Q$	Evaluates deviation under non-standard concentrations and temperatures.
Minimum Electrolysis Voltage	$V_{\text{min}}$	$-E_{\text{cell}}$	When $E_{\text{cell}} < 0$, external electrical potential must exceed $-E_{\text{cell}}$ to drive the reverse reaction.

The build, step by step

1. Catalogued Reduction Couples

In ElectrochemicalSeries.cs, standard reduction potentials are stored in ascending ElectrodeCoupleId order. Each entry represents a reduction half-reaction written as:

$$\text{Ox} + n e^- \rightarrow \text{Red}$$

public readonly struct StandardElectrodeCouple
{
    public ElectrodeCoupleId Id { get; }
    public string OxidizedForm { get; }
    public string ReducedForm { get; }
    public int ElectronsTransferred { get; }
    public double StandardReductionPotentialVolts { get; }
}

The catalogue includes 13 real, peer-reviewed couples spanning strongly reducing metals ($K^+/K$ at $-2.931\text{ V}$) to strong aqueous oxidants ($O_2 + 4 H^+/2 H_2O$ at $+1.229\text{ V}$).

2. Composing Standard Galvanic Cells

In GalvanicCellMath.TryComposeStandardCell, couple potentials and electron counts are composed:

public static bool TryComposeStandardCell(
    in StandardElectrodeCouple cathode,
    in StandardElectrodeCouple anode,
    out GalvanicCellState cell)
{
    cell = default;
    if (!TryLeastCommonMultiple(cathode.ElectronsTransferred, anode.ElectronsTransferred, out int electronsTransferred))
    {
        return false;
    }

    double standardCellPotentialVolts = cathode.StandardReductionPotentialVolts - anode.StandardReductionPotentialVolts;
    if (!ThermodynamicMath.TryCalculateGibbsFreeEnergyFromCellPotentialKilojoulesPerMol(
            electronsTransferred, standardCellPotentialVolts, out double standardGibbsFreeEnergyKilojoulesPerMol))
    {
        return false;
    }

    cell = new GalvanicCellState(standardCellPotentialVolts, electronsTransferred, standardGibbsFreeEnergyKilojoulesPerMol);
    return true;
}

Notice that $\Delta G^\circ$ is derived, not authored. This prevents inconsistencies where potential and Gibbs energy disagree on the spontaneous reaction direction.

3. Automatic Spontaneous Cell Direction

When two half-cells are placed in contact without an external power source, physics selects the higher standard reduction potential as the cathode:

public static bool TryComposeSpontaneousCell(
    in StandardElectrodeCouple coupleA,
    in StandardElectrodeCouple coupleB,
    out GalvanicCellState cell,
    out ElectrodeCoupleId cathodeId,
    out ElectrodeCoupleId anodeId)
{
    // The couple with the more positive E° becomes the cathode:
    if (coupleA.StandardReductionPotentialVolts >= coupleB.StandardReductionPotentialVolts)
    {
        cathodeId = coupleA.Id;
        anodeId = coupleB.Id;
        return TryComposeStandardCell(in coupleA, in coupleB, out cell);
    }

    cathodeId = coupleB.Id;
    anodeId = coupleA.Id;
    return TryComposeStandardCell(in coupleB, in coupleA, out cell);
}

This ensures that calling TryComposeSpontaneousCell with copper and iron always resolves copper as cathode ($+0.342\text{ V}$) and iron as anode ($-0.447\text{ V}$), yielding $E^\circ_{\text{cell}} = +0.789\text{ V}$ regardless of parameter order.

4. Nernst Shifts and Electrolysis Thresholds

In actual vessels, solutions depart from standard state ($1\text{ M}$, $298.15\text{ K}$). In GalvanicCellMath.TryNernstPotentialVolts, calculate the real cell potential:

$$E = E^\circ - \frac{R \cdot T}{n \cdot F} \ln Q$$

public static bool TryNernstPotentialVolts(
    in GalvanicCellState standardCell,
    double temperatureKelvin,
    double reactionQuotient,
    out double potentialVolts)
{
    potentialVolts = 0d;
    if (reactionQuotient <= 0d || temperatureKelvin <= 0d)
    {
        return false;
    }

    // RT / nF term:
    double thermalVoltage = (ThermodynamicMath.GasConstantJoulesPerKelvinMol * temperatureKelvin)
                            / (standardCell.ElectronsTransferred * ThermodynamicMath.FaradayConstantCoulombsPerMol);
    double shift = thermalVoltage * Math.Log(reactionQuotient);
    potentialVolts = standardCell.StandardCellPotentialVolts - shift;
    return true;
}

When a reaction has $E_{\text{cell}} \le 0$ (such as splitting water, $E^\circ = -1.229\text{ V}$), GalvanicCellMath.TryElectrolysisVoltageVolts computes the minimum external power required to force the reaction backwards:

public static bool TryElectrolysisVoltageVolts(
    in GalvanicCellState cell,
    double temperatureKelvin,
    double reactionQuotient,
    out double minimumAppliedVoltageVolts)
{
    if (!TryNernstPotentialVolts(in cell, temperatureKelvin, reactionQuotient, out double actualPotentialVolts))
    {
        minimumAppliedVoltageVolts = 0d;
        return false;
    }

    // If cell potential is negative, applied voltage must at least equal -E:
    minimumAppliedVoltageVolts = actualPotentialVolts < 0d ? -actualPotentialVolts : 0d;
    return true;
}

5. In-Editor Audit with Electrochemistry Lab

Open ElectrochemistryLabModule.cs. The module provides dropdown pickers for both electrode couples, sliders for temperature and reaction quotient $Q$, and instantly computes:

1. Standard cell potential ($E^\circ_{\text{cell}}$), balanced electrons ($n$), and derived Gibbs energy ($\Delta G^\circ$).
2. Whether the pair forms a spontaneous battery or requires an external electrolysis power supply.
3. Nernst potential shift under non-standard conditions.
4. Theoretical minimum voltage required for forced electrolysis.

Screenshot pending

Capture electrochemistry-lab-cell-preview.png: Voxel Workshop → Electrochemistry Lab module window, showing “Cu2+ + 2 e- -> Cu (+0.342 V)” selected as First couple, “Fe2+ + 2 e- -> Fe (-0.447 V)” as Second couple, with E°cell = +0.789 V, ΔG° = -152.25 kJ/mol, and Nernst shifted potential visible. Editor dark theme.

Verify

1. Execute EditMode Tests Headlessly

Run the dedicated EditMode electrochemistry suite:

/opt/unity/Editor/Unity -batchmode -nographics \
  -projectPath /home/soulwax/workspace/engines/unity/minecraft/Minecraft-HD \
  -runTests -testPlatform EditMode \
  -testFilter VoxelSandbox.Tests.GalvanicCellMathTests

Verify that all key assertions pass:

• ComposeStandardCell_DerivesPotentialElectronCountAndGibbsEnergyConsistently: verifies $\Delta G^\circ = -nFE^\circ$ for copper-iron cementation.
• ComposeStandardCell_UsesTheLeastCommonMultipleOfHalfReactionElectronCounts: verifies $\text{lcm}(2, 3) = 6$ for copper-aluminum cells.
• GibbsAndPotential_RoundTripForEveryCouplePairInTheCatalogue: asserts mathematical consistency across all couple pairs without drift.
• ComposeSpontaneousCell_PicksTheHigherPotentialAsCathodeRegardlessOfArgumentOrder: verifies parameter order invariance.
• NernstPotential_ShiftsLogarithmicallyWithReactionQuotient: validates concentration-dependent cell voltages.

2. Inspect in Electrochemistry Lab

1. Open Tools → Voxel Sandbox → Voxel Workshop → Electrochemistry Lab.
2. Select Couple 1: Cu2+/Cu and Couple 2: Fe2+/Fe:
   • Confirm standard cell potential reports +0.789 V.
   • Confirm standard Gibbs energy reports -152.25 kJ/mol.
   • Confirm spontaneous badge indicates the cementation reaction proceeds freely.
3. Select Couple 1: 2 H+/H2 and Couple 2: O2 + 4 H+/2 H2O:
   • Confirm water formation reports +1.229 V spontaneous.
   • Reverse the orientation: confirm electrolysis reports minimum applied voltage of 1.229 V.

Now do your own

To catalogue a new standard electrode couple (e.g. Lead Accumulator $\text{Pb}^{2+}/\text{Pb}$ or Nickel $\text{Ni}^{2+}/\text{Ni}$):

1. Verify Literature Source: Sourced from CRC Handbook or NIST standard tables. Record citation in Docs/CHEMISTRY_SOURCES.md.
2. Assign Next Sequential ElectrodeCoupleId: Add to Couples array in ElectrochemicalSeries.cs ensuring strictly ascending ID order.
3. Declare Half-Reaction Species: Provide IUPAC oxidized and reduced string representations and number of transferred electrons ($n$).
4. Audit in Electrochemistry Lab: Open Electrochemistry Lab, select the new couple against the standard hydrogen electrode (SHE), and confirm $E^\circ$ matches the published literature value exactly.
5. Add Regression Tests: Add assertion cases in GalvanicCellMathTests.cs.

Pitfalls

Symptom	Cause	Fix
Cell potential has the wrong sign when calling TryComposeStandardCell.	The cathode and anode were swapped. In IUPAC convention, reduction happens at the cathode: $E^\circ_{\text{cell}} = E^\circ_{\text{cathode}} - E^\circ_{\text{anode}}$.	If you want the self-starting battery direction, use GalvanicCellMath.TryComposeSpontaneousCell.
GibbsFreeEnergy and CellPotential disagree on reaction spontaneity.	$\Delta G^\circ$ was authored separately from standard tables.	Never author $\Delta G^\circ$ independently for redox reactions. Use ThermodynamicMath.TryCalculateGibbsFreeEnergyFromCellPotentialKilojoulesPerMol so $\Delta G^\circ = -nFE^\circ$ holds by definition.
Nernst calculation returns false or NaN.	Reaction quotient $Q \le 0$ or temperature $T \le 0\text{ K}$.	Reaction quotient is a ratio of concentrations/pressures ($Q = \prod a_i^{\nu_i}$) and must be strictly positive ($Q > 0$).
Electrolysis occurs at voltages below the theoretical $V_{\text{min}}$.	The reaction simulation neglected thermodynamic equilibrium.	Electrolysis cannot proceed below $V_{\text{min}} = -E_{\text{cell}}$. Real systems also require additional activation overpotential $\eta$ via Tafel’s equation.
ElectrochemicalSeries throws an exception on startup.	An authored couple violated ascending ElectrodeCoupleId order.	The series enforces strictly monotonic ascending IDs in its static constructor to preserve deterministic array indexing.