[jorgensd]

Reworks the kinetics of #17 , and restructures RedoxHalfCell so that a full cell can build both of its sides from it.

Electrode reactions are rate reactions

• ElectrodeReaction is now a RateReaction. Its rate is the volumetric current over n F, and it adds the current exchange between the solid and electrolyte potentials. Every reaction in sumfem now states its species the same way, with reactants and products and their coefficients.
• ButlerVolmer, MassTransferButlerVolmer and PistonVelocityButlerVolmer take reactants and products by ion name. They default to the reduced and oxidized ions alone; e.g. VO²⁺ + H₂O → VO₂⁺ + 2H⁺ + e⁻ is reactants={"VO": 1, "H2O": 1}, products={"VO2": 1, "H": 2}. Ions of the reaction other than the couple need fields.
• They replace the stoichiometry and others arguments of the previous commit.
• ExchangeCurrentButlerVolmer keeps its signature.
• RateReaction:
  • A measure of cells or facets now gives the reaction's domain, so species may live on overlapping subdomains (e.g. vanadium on an electrode, water on the electrolyte region).
  • A subclass may have no species fields, as ExchangeCurrentButlerVolmer, which only moves charge.

RedoxCouple

• New frozen dataclass for a couple and its reaction: the reduced and oxidized ions, rate constant, formal potential, direction on discharge, electrons, transfer coefficients, and reactants/products.
• check(ions) rejects ions missing from the electrolyte and reactions that do not conserve charge.
• Exported from sumfem.electrochemistry, and documented on the API page.

RedoxHalfCell

• New signature: RedoxHalfCell(domain, ions, reservoir, couple, electrode, ...). The couple replaces seven arguments.
• Split constructor: it now outlines named steps, each a method:
  • _check_reservoir
  • _create_fields
  • _create_electrolyte
  • _create_parameters
  • _create_reaction
  • _create_models
  • _create_functionals
• New arguments:
  • fiber_distance: kinetics limited by piston velocities, with or without flow.
  • collector=None and membrane=None: for a cell whose collector and membrane are resolved. It then puts no currents on those boundaries, and voltage and balance_currents raise.
  • phi_s, phi_l and fields: existing fields to use, e.g. an electrolyte potential and water shared with a membrane.
  • electrolyte_name: prefix of the electrolyte's parameters, so that two half-cells can coexist.
• Renamed models: model names get the prefix <name>_, e.g. cell_reaction, so that two half-cells in one system do not collide.
• Unchanged: results and parameter names.

Demos

The 1D, 2D and 3D vanadium half-cells state their couple as a RedoxCouple, and the 1D demo explains it.

Tests

• The positive couple with protons and water against plain UFL, now with reactants/products.
• A reaction whose reactants lack the reduced ion, or with an ion given by electroneutrality, is rejected.
• A positive half-cell (Shah et al. 2008) produces protons and consumes water, has consistent units, and is rejected without its other species or without water in the electrolyte.
• Given fields are used, resolved boundaries carry no currents, and two half-cells share the electrolyte potential and water with distinct names and consistent units.
• The test helper has the RFBniCS couple as reference.COUPLE.