Generalise VectorField to N components

[aabills]

Summary

• Generalise VectorField from fixed 2D (lr, tb) to N components (needed for 3D unstructured FV).
• Add Component / Norm operators and matching discretisation + solution handling.
• First of a stacked split of Unstructured finite volume #5397 (plan B).

Stack

1. This PR (Generalise VectorField to N components #5686) — VectorField N-comp
2. Add unstructured mesh infrastructure #5687 — Meshing
3. Add unstructured finite volume spatial method #5688 — Spatial method + ProcessedVariable
4. Add VTK plotting for unstructured meshes #5689 — VTK plotting
5. Add unstructured 2D/3D DFN battery models #5690 — Unstructured DFN models

Full pre-split branch preserved as backup/unstructured-finite-volume-full and original #5397 (unstructured-finite-volume).

Test plan

• test_finite_volume_2d/test_tensor_field.py (includes new VectorField N-comp cases)
• CI unit suite

Also in this stack: #5691 deprecates pybamm.Magnitude.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.11%. Comparing base (1827bda) to head (bef253d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5686      +/-   ##
==========================================
+ Coverage   98.09%   98.11%   +0.02%     
==========================================
  Files         340      340              
  Lines       32671    32732      +61     
==========================================
+ Hits        32049    32116      +67     
+ Misses        622      616       -6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[rtimms]

Reviewed this PR, then checked the findings against the rest of the stack (ufv-1 … ufv-5) to avoid raising things that are already handled downstream. Verified behaviour by running the code at both this branch and the stack tip; targeted unit suites are green at both (1733 serialisation + expression-tree tests, 755 spatial-method/solver/discretisation tests).

Three things I think need fixing before this lands, then some dead surface and housekeeping.

Already covered downstream — ignore these

For the record, so they don't get re-raised:

• Magnitude vs Component duplication. Magnitude(vf, "lr"|"tb") is exactly Component(vf, 0|1), and Magnitude is misnamed (it extracts a component; the new Norm is the actual magnitude). #5691 handles this properly — deprecation warning, both BasicDFN2D call sites migrated, FiniteVolume2D._edge_direction so edge-averaging still resolves a direction. Deprecating is the right call for a public symbol.
• _disc_state_vector has a real writer. It's set at finite_volume_unstructured.py:617 in #5688, with genuine coverage at test_finite_volume_unstructured.py:874. See the note below about where it belongs, but the concept isn't dead.

Blockers

1. Mismatched component counts silently drop data

n is taken from whichever side happens to be a VectorField, with no check that both agree (discretisation.py:973-975). Once N can vary, that's a correctness hole:

2-comp + 3-comp -> returns 2 components; the third is silently dropped, no error
3-comp + 2-comp -> IndexError: list index out of range

Both reproduce on this branch. Suggest an explicit check before the loop:

if disc_left.n_components != disc_right.n_components:
    raise pybamm.DiscretisationError(
        f"Cannot combine VectorFields with {disc_left.n_components} and "
        f"{disc_right.n_components} components"
    )

Worth fixing here rather than downstream, because finite_volume_unstructured.py:948-977 in #5688 is a near-verbatim second copy of this block — same n logic, same missing guard, same hasattr/break. Either fix both, or factor the "broadcast the scalar side, then zip components" step into one shared helper that both call.

2. solution["<vector field>"] is unreadable on structured 2D meshes

The solution.py change stores a list of casadi functions, but process_variable routes structured 2D FV meshes to ProcessedVariable2DFVM at processed_variable.py:1750, before the VectorField dispatch — and that dispatch is gated on UnstructuredSubMesh, so it never catches this case even at the tip of the stack. Result, verified on both this branch and ufv-5:

processed class: ProcessedVariable2DFVM
call(0.5)  -> TypeError: unhashable type: 'list'
entries    -> TypeError: unhashable type: 'list'
data       -> TypeError: unhashable type: 'list'

Not a functional regression — on main this path raises TypeError: Cannot convert symbol of type VectorField to CasADi — but it swaps a clear message for an opaque one, on a path that stays broken through all six PRs. Either hoist an isinstance(base_variables[0], pybamm.VectorField) check above line 1750, or raise NotImplementedError there so the failure names the actual limitation.

Also worth noting: the added test only asserts isinstance(casadi_components, list), which is why it passes despite every read path raising. If the plumbing stays in this PR, the test should read a value.

Separately, if you'd rather drop the solution.py change from this PR and land it with its consumer in #5688, drop VectorField._to_casadi with it — with _to_casadi present and the special case gone, solution["flux"] silently returns wrong shapes instead of erroring.

3. hasattr sniffing of a private attribute across objects

result = pybamm.VectorField(*new_comps)
for src in (disc_left, disc_right):
    if hasattr(src, "_disc_state_vector"):
        result._disc_state_vector = src._disc_state_vector
        break
return result

By the tip of the stack this pattern exists in three places (discretisation.py:993, discretisation.py:1194, finite_volume_unstructured.py:974). Declaring the attribute removes the duck-typing from all three:

class VectorField(TensorField):
    _disc_state_vector = None

result._disc_state_vector = disc_left._disc_state_vector or disc_right._disc_state_vector
# and in the unary branch
result._disc_state_vector = disc_child._disc_state_vector

Given the only writer is in #5688, the propagation plus test_disc_state_vector_propagation would sit more naturally there — the test here has to fabricate the attribute by hand (disc_vf._disc_state_vector = marker), so it doesn't exercise anything this PR ships.

Dead surface

Grepped all six branches; none of the following has a single use in src/:

• fb_field — unused even by the unstructured 3D models in #5690, and vf[2] already works via TensorField.__getitem__. It's also documented as a "backward-compatible alias" when it's brand new. Suggest dropping it and its two tests until something needs a third component.
• pybamm.component() / pybamm.norm() — zero call sites anywhere in the stack; every real caller writes pybamm.Component(N_e, 0). They're also bare constructor aliases with no simplify_if_constant, unlike neighbours such as sign().
• Norm — zero uses in src/ across the stack, and finite_volume_unstructured.gradient_squared (#5688, lines 936-942) hand-rolls exactly the sum-of-squares that the Norm discretisation branch builds. Either give Norm that caller or defer it.

Reuse and style

• TensorField already exposes components and __getitem__, but private _components access grows from 7 sites in this PR to 13 in src/ by the tip (processed_variable.py:1232,1238, finite_volume_unstructured.py:770,940,967). Worth switching to the public accessors while the count is still small.
• VectorField._to_casadi reimplements the inherited helper; casadi.vertcat(*self._children_to_casadi(t, y, y_dot, inputs, casadi_symbols)) is equivalent.
• The Norm discretisation branch reads more directly as return sum(c**2 for c in disc_child.components) ** 0.5.
• n_components is a third spelling of len(components) / shape[0]. Fine to keep, but the codebase should settle on one.
• New disc branches raise bare ValueError; AGENTS.md asks for DiscretisationError. (The adjacent Magnitude branch sets the precedent, but it'd be good not to extend it.)

Housekeeping

• The CHANGELOG bullet has no PR link — AGENTS.md requires one, and the surrounding bug-fix bullets have them. Same applies to the other four feature bullets added across the stack.
• New public Component / Norm have no docs/source/api/expression_tree/unary_operator.rst entry. (VectorField / TensorField were already undocumented, so this is arguably pre-existing.)

[aabills]

Thanks for the thorough review — and for checking against the rest of the stack so we don't churn on things already handled downstream.

Blockers

1. Mismatched component counts — Agreed. Added a DiscretisationError guard and factored the "broadcast scalar side, then zip components" step into _process_vector_field_binary so the same logic can be reused downstream.

2. solution["<vector field>"] on structured 2D — Raising a clear NotImplementedError naming the limitation (instead of the opaque TypeError: unhashable type: 'list'). Updated the test to assert that failure mode.

3. hasattr / _disc_state_vector — Declared _disc_state_vector = None on VectorField and assign directly. Propagation coverage for the real writer can land with Add unstructured finite volume spatial method #5688.

Dead surface

• Dropped fb_field (and its tests); vf[2] is enough for now.
• Dropped pybamm.component() / pybamm.norm() — callers use the constructors.
• Keeping Norm.

Reuse / style / housekeeping

• Switched to public components / __getitem__ instead of _components.
• VectorField._to_casadi now uses _children_to_casadi.
• Simplified the Norm disc branch to sum(c**2 for c in disc_child.components) ** 0.5.
• New disc branches raise DiscretisationError instead of bare ValueError.
• CHANGELOG bullet now links to this PR; Component / Norm added to the unary-operator API docs.

Will push the follow-up shortly.

[rtimms]

thanks!