current_driven_wrapper_interface_contract.md

Current-Driven Wrapper Interface Contract

Purpose

This document records the current PyBaMMCellModel interface contract and the architectural consequences for Native PathSim parallel-pack research.

This is an interface and architecture audit only.

Existing Wrapper Contract

The current wrapper contract is:

Input:

• Applied current

State update:

• update(current, dt)

Outputs:

• Terminal voltage
• SOC
• Capacity
• Resistance

Equivalent interpretation:

• I -> cell physics -> V
• Not V -> cell physics -> I

Evidence From Current Code

Cell-model interface

The base interface requires current-driven state advance:

• update(current, dt) in CellModel
• No voltage-driven update contract exists in the current abstraction

PyBaMMCellModel input contract

PyBaMMCellModel injects a current input parameter into the PyBaMM simulation:

• internal input label: Cell current [A]
• PyBaMM parameter binding: Current function [A] = InputParameter(Cell current [A])
• initialization solve uses that current input with value 0.0

PyBaMMCellModel runtime update contract

Runtime progression occurs through:

• update(current, dt)
• stepping the PyBaMM simulation with the supplied current input

PyBaMMCellModel output contract

The wrapper exposes terminal voltage through:

• get_voltage()

It also exposes:

• get_soc()
• get_capacity()
• get_resistance()

Architectural Consequence

The current architecture is fundamentally:

Pack current -> current splitter -> branch currents Ia, Ib -> current-driven cell wrappers -> cell voltages Va, Vb

This means branch current is prescribed upstream of the cell wrappers.

Therefore the current architecture cannot generate spontaneous equalization current during rest.

Why Spontaneous Equalization Is Impossible In The Current Current-Splitting Architecture

The existing splitter logic computes branch currents directly from pack current:

• Ia = Ipack * (Rb / (Ra + Rb))
• Ib = Ipack * (Ra / (Ra + Rb))

At rest:

• Ipack = 0

Therefore:

• Ia = 0
• Ib = 0

Even if:

• SOC_A != SOC_B
• OCV_A != OCV_B
• Va != Vb

those mismatches do not create spontaneous equalization current inside the current-splitting topology, because the branch currents are already fixed by the external pack-current rule.

Clarification: Parallel Declaration Is Not Enough

Do not assume that simply declaring:

• CellA || CellB

automatically creates equalization current in the current codebase.

That statement is false for the current wrapper and topology.

The limitation is not PathSim alone. The limiting factor is the combination of:

• a current-driven cell wrapper contract, and
• a current-splitting pack topology that prescribes branch current from Ipack

Architectural Interpretation Of The Previous Ibal Equation

The previously used relation:

• Ibal = (Va - Vb) / (RcA + RcB)

should now be treated as:

• an external PoC approximation of the algebraic network solution
• not the final physical architecture by itself

That equation approximates what a network solver would produce when KCL/KVL constraints are explicitly solved.

Target Research Direction

The relevant research question is:

Can a PathSim algebraic network solve Ia, Ib, and Vbus first, and then provide the solved branch currents to the PyBaMM wrappers?

Target concept:

• PathSim network solves:
  • Ia
  • Ib
  • Vbus
• PyBaMM consumes:
  • Ia / Ib
• PyBaMM returns:
  • Va / Vb

Proposed Ownership Model

PyBaMM ownership

PyBaMM should own electrochemical cell physics.

Input:

• Current

Outputs:

• Voltage
• SOC
• Capacity
• Resistance

PathSim ownership

PathSim should own network physics.

Unknowns:

• Ia
• Ib
• Vbus

Constraints:

• KCL
• KVL

Adapter ownership

An adapter layer should:

• convert PathSim-solved branch current into PyBaMM current input
• expose PyBaMM terminal voltage back into the network equations
• manage timing/order between algebraic solve and cell-state update

Current Splitter Architecture vs KCL/KVL Algebraic Network Architecture

Current splitter architecture

Structure:

• Ipack provided externally
• splitter computes Ia, Ib
• cells consume branch current
• voltages are observed afterward

Properties:

• simple
• fast
• cannot create spontaneous rest equalization when Ipack = 0

KCL/KVL algebraic network architecture

Structure:

• Va, Vb, RcA, RcB, Ipack define the network state
• algebraic unknowns are solved:
  • Ia
  • Ib
  • Vbus
• solved branch currents are then fed into current-driven cell wrappers

Representative constraints:

• Ia + Ib = Ipack
• Vbus = Va - Ia * RcA
• Vbus = Vb - Ib * RcB

Properties:

• can produce spontaneous equalization when voltage mismatch exists
• is consistent with observed Native PathSim AlgebraicConstraint PoC behavior
• still requires careful interface control because the cell wrappers are not voltage-driven branch elements today

Interface Changes Required Before A True PathSim-Native Parallel-Cell Network Can Be Investigated

At minimum, the following must be resolved:

1. Explicit boundary contract

• Define whether the wrapper remains current-driven only, or whether a new branch-component wrapper is needed.

2. Solve/update ordering

• Define when Va and Vb are sampled.
• Define when Ia and Ib are solved.
• Define when cell states are advanced.

3. Adapter semantics

• Provide a stable adapter that bridges:
  • algebraic network solve
  • current-driven PyBaMM stepping

4. Voltage meaning

• Freeze the interpretation of get_voltage():
  • terminal voltage after imposed current step
  • sampled voltage before update
  • or another explicitly defined timing convention

5. Logging and diagnostics

• Log Ia, Ib, Vbus, Va, Vb, KCL residual, and KVL residual with phase-aware timing semantics.

6. Optional future interface extension

• Investigate whether a voltage/node-coupled wrapper abstraction is possible or whether current-driven adaptation is the permanent architecture.

Conclusion

The current PyBaMMCellModel wrapper is current-driven.

That contract is compatible with:

• external branch-current solution
• algebraic network solve followed by current injection into the wrapper

That contract is not currently compatible with:

• a direct voltage-driven branch element where branch current is solved internally from imposed terminal voltage

So, before a true PathSim-native parallel-cell network can be claimed, the project must explicitly separate:

• cell physics ownership in PyBaMM
• network physics ownership in PathSim
• adapter-layer responsibility between them

Important clarification:

The inability to generate spontaneous equalization current is not a limitation of PyBaMM itself.

It is a consequence of the current wrapper contract and current-splitting topology used in this project.