Negative half-cell models

[DrSOKane]

Description

This pull request introduced negative half-cell models to PyBaMM, by means of three major changes:

• The option "working electrode": ["both", "negative", "positive"] has been replaced with "half-cell": ["false", "true]. The positive electrode is always considered to be the working electrode, which has always been the case but is now made explicit.
• Two new parameter sets - Ecker2015_graphite_halfcell and OKane2022_negative_halfcell - have been added to work with the new option.
• The degradation mechanisms SEI, SEI on cracks and lithium plating can now be used on either electrode by specifying them as a 2-tuple, in the same way as is already done for some other options. Unlike for other options, however, passing only a single string instead of a tuple will put that behaviour on the negative electrode only.

Fixes #2730

Type of change

Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist:

• No style issues: $ pre-commit run (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)
• All tests pass: $ python run-tests.py --all
• The documentation builds: $ python run-tests.py --doctest

You can run unit and doctests together at once, using $ python run-tests.py --quick.

Further checks:

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

Attention: 1 lines in your changes are missing coverage. Please review.

Comparison is base (83d32ca) 99.58% compared to head (87da691) 99.58%.
Report is 2 commits behind head on develop.

Additional details and impacted files

@@            Coverage Diff            @@
##           develop    #3198    +/-   ##
=========================================
  Coverage    99.58%   99.58%            
=========================================
  Files          254      256     +2     
  Lines        19821    19998   +177     
=========================================
+ Hits         19738    19915   +177     
  Misses          83       83            

Files	Coverage Δ
pybamm/expression_tree/averages.py	100.00% <ø> (ø)
...input/parameters/lithium_ion/Chen2020_composite.py	100.00% <ø> (ø)
...ameters/lithium_ion/Ecker2015_graphite_halfcell.py	100.00% <100.00%> (ø)
...rs/lithium_ion/OKane2022_graphite_SiOx_halfcell.py	100.00% <100.00%> (ø)
pybamm/input/parameters/lithium_ion/Xu2019.py	100.00% <ø> (ø)
...l_battery_models/lead_acid/base_lead_acid_model.py	100.00% <100.00%> (ø)
...models/full_battery_models/lithium_ion/Yang2017.py	100.00% <ø> (ø)
...ttery_models/lithium_ion/base_lithium_ion_model.py	100.00% <100.00%> (ø)
..._battery_models/lithium_ion/basic_dfn_half_cell.py	100.00% <100.00%> (+1.11%)	⬆️
...tery_models/lithium_ion/electrode_soh_half_cell.py	100.00% <100.00%> (ø)
... and 21 more

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

[brosaplanella]

Looks great, thanks Simon!

[brosaplanella]

Suggested change

	- Option `working electrode` has been replaced with `half-cell`, which can only be `true` or `false`. The positive electrode is always considered to be the working electrode. For negative half-cells, lithium metal is now considered the negative electrode and the negative electrode material to be the positive electrode. ([#3198](https://github.com/pybamm-team/PyBaMM/pull/3198))
	- If `options["half-cell"] == "false"` and either `SEI`, `SEI on cracks` or `lithium plating` are not provided as tuples, they are automatically made into tuples. This directly modifies `extra_options`, not `default_options` to ensure the other changes `default_options` still happen when required. ([#3198](https://github.com/pybamm-team/PyBaMM/pull/3198))
	- Added option to use an empirical hysteresis model for the diffusivity and exchange-current density ([#3194](https://github.com/pybamm-team/PyBaMM/pull/3194))
	- PyBaMM now has optional dependencies that can be installed with the pattern `pip install pybamm[option]` e.g. `pybamm[plot]` ([#3044](https://github.com/pybamm-team/PyBaMM/pull/3044))
	- Double-layer capacity can now be provided as a function of temperature ([#3174](https://github.com/pybamm-team/PyBaMM/pull/3174))
	- `pybamm_install_jax` is deprecated. It is now replaced with `pip install pybamm[jax]` ([#3163](https://github.com/pybamm-team/PyBaMM/pull/3163))
	- PyBaMM now has optional dependencies that can be installed with the pattern `pip install pybamm[option]` e.g. `pybamm[plot]` ([#3044](https://github.com/pybamm-team/PyBaMM/pull/3044))
	- Option `working electrode` has been replaced with `half-cell`, which can only be `true` or `false`. The positive electrode is always considered to be the working electrode. For negative half-cells, lithium metal is now considered the negative electrode and the negative electrode material to be the positive electrode. ([#3198](https://github.com/pybamm-team/PyBaMM/pull/3198))
	- If `options["half-cell"] == "false"` and either `SEI`, `SEI on cracks` or `lithium plating` are not provided as tuples, they are automatically made into tuples. This directly modifies `extra_options`, not `default_options` to ensure the other changes `default_options` still happen when required. ([#3198](https://github.com/pybamm-team/PyBaMM/pull/3198))
	- Added option to use an empirical hysteresis model for the diffusivity and exchange-current density ([#3194](https://github.com/pybamm-team/PyBaMM/pull/3194))
	- Double-layer capacity can now be provided as a function of temperature ([#3174](https://github.com/pybamm-team/PyBaMM/pull/3174))
	- `pybamm_install_jax` is deprecated. It is now replaced with `pip install pybamm[jax]` ([#3163](https://github.com/pybamm-team/PyBaMM/pull/3163))
	- PyBaMM now has optional dependencies that can be installed with the pattern `pip install pybamm[option]` e.g. `pybamm[plot]` ([#3044](https://github.com/pybamm-team/PyBaMM/pull/3044))

[valentinsulzer]

Looks good, thanks @DrSOKane !

A couple of comments:

• Is a helpful error raised if the user tries to do {"working electrode": "positive"}?
• It looks like the SEI variables now require a domain ("Negative electrode SEI thickness [m]" instead of "SEI thickness [m]"). Does that mean previous scripts with "SEI thickness [m]" will break?

[rtimms]

thanks @DrSOKane ! would be great to get this merged before the next release if you have time to respond to valentin's comments above

[valentinsulzer]

Upon further considering I think we should keep "working electrode": "positive" to avoid unnecessarily breaking people's code, and just error with "working electrode": "negative" with an error message that explains you always have to use "positive" and change the parameters. In future if we have a symmetric cell that can be "working electrode": "none"

[DrSOKane]

Hi @tinosulzer and @rtimms, I'm back from holiday and made this a priority.

All variables pertaining to the SEI, SEI on cracks and lithium plating submodels do indeed have domains now, and I've added this to the list of breaking changes.

Having thought about it, I agree that changing back to the working electrode syntax is the best way to go, so I've gone through every instance and changed it back. An OptionError is now raised if you attempt to set working electrode to be negative.

Finally, I've added an example notebook to show how to use the half-cell models.

[brosaplanella]

Happy to merge once the notebook conflicts are resolved

[brosaplanella]

@agriyakhetarpal do you know why the doc test is failing?

[agriyakhetarpal]

Yes, I think this is a bug that I have noted earlier (#3389). We should mark it at a higher priority now I guess

Edit: sorry, I read the logs too quickly. It looks like a different warning, I will debug and leave a review below.

[DrSOKane]

Yes, I think this is a bug that I have noted earlier (#3389). We should mark it at a higher priority now I guess

Edit: sorry, I read the logs too quickly. It looks like a different warning, I will debug and leave a review below.

The underline in parameter_sets.rst is to short to accommodate the name of the new parameter set, so I extended the underline. Should work now.

[brosaplanella]

Fantastic work @DrSOKane!

[DrSOKane]

Fantastic work @DrSOKane!

Thank you so much! This means a lot!