Value class to allow species-dependent inputs

[jhdark]

Description

Summary

Let's FESTIM input values depend on the concentration of other species. A callable value on ParticleSource and ParticleFluxBC can now take a species' concentration as an argument, alongside the existing space (x), time (t), and temperature (T).

The dependency is declared with species_dependent_value, a dict mapping each species-argument name in the callable to a festim.Species. FESTIM binds those arguments to the live species solution, so the term is evaluated — and differentiated in the Newton solve — against the coupled concentration field.

Related Issues

Motivation and Context

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 🔨 Code refactoring (no functional changes, no API changes)
• 📝 Documentation update
• ✅ Test update (adding missing tests or correcting existing tests)
• 🔧 Build/CI configuration change

Testing

• All existing tests pass locally (pytest)
• I have added new tests that prove my fix is effective or that my feature works

Code Quality Checklist

• My code follows the code style of this project (Ruff formatted: ruff format .)
• My code passes linting checks (ruff check .)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas

Documentation

• I have updated the documentation accordingly (if applicable)
• I have added docstrings to new functions/classes following the project conventions

Breaking Changes

Screenshots/Examples

import festim as F

A = F.Species("A")
B = F.Species("B")

# source on A proportional to the square of B's local concentration:
# the callable argument "B" is bound to species B's concentration
source = F.ParticleSource(
    value=lambda B: 2 * B**2,
    volume=my_volume,
    species=A,
    species_dependent_value={"B": B},
)

# composes with time, temperature and space too
flux = F.ParticleFluxBC(
    subdomain=my_surface,
    value=lambda t, T, B: t * B * F.k_B * T,
    species=A,
    species_dependent_value={"B": B},
)

Additional Notes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.16%. Comparing base (4ba388a) to head (6f95238).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1182      +/-   ##
==========================================
+ Coverage   95.08%   95.16%   +0.08%     
==========================================
  Files          53       53              
  Lines        3862     3888      +26     
==========================================
+ Hits         3672     3700      +28     
+ Misses        190      188       -2     

☔ 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.

[RemDelaporteMathurin]

ship it! just a few comments worth looking at

[RemDelaporteMathurin]

why has this loop disappeared?

[RemDelaporteMathurin]

we should start looking at the convergence rates instead of the isolated error

[jhdark]

Made a note of this in #1198