Add `F.plot(...)` for one-line PyVista field visualization by Copilot · Pull Request #1176 · festim-dev/FESTIM

Copilot · 2026-06-23T12:28:04Z

Description

Summary

This PR adds a lightweight plotting API for species fields so users can generate PyVista visuals in one line, including multi-species and subdomain-aware cases.

API surface
- Added public F.plot(...) entrypoint (src/festim/plot.py, exported via src/festim/__init__.py).
Core behavior
- Supports single species and list input (auto subplot layout).
- Supports subdomain=... for mixed-domain/discontinuous workflows.
- Supports filename=... for screenshot output and show_edges=True shortcut.
- Forwards extra mesh args via **kwargs to plotter.add_mesh(...).
Robustness
- Clear errors for invalid field types, missing post-processing solutions, and missing optional pyvista dependency.
Tests
- Added focused unit tests in test/test_plot.py covering API behavior, edge cases, and error paths.

Related Issues

Handled by automatic issue linking in the PR system.

Motivation and Context

Plotting fields with PyVista currently requires repetitive boilerplate (vtk_mesh, grid wiring, plotter setup). This change introduces a small wrapper to make field visualization immediate while preserving control through optional arguments.

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

None.

Screenshots/Examples

import festim as F

H = F.Species("H")
D = F.Species("D")

F.plot(H)                              # default quick view
F.plot(H, subdomain=vol1)              # mixed-domain: specific subdomain
F.plot([H, D], show_edges=True)        # automatic subplots
F.plot(H, filename="concentration.png")  # save screenshot

Additional Notes

This PR keeps scope intentionally narrow: one public plotting helper plus focused tests around that API surface.

codecov · 2026-06-23T12:32:34Z

Codecov Report

❌ Patch coverage is 89.65517% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.68%. Comparing base (9a6407b) to head (4a4d206).

Files with missing lines	Patch %	Lines
src/festim/plotting.py	89.47%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1176      +/-   ##
==========================================
- Coverage   94.76%   94.68%   -0.09%     
==========================================
  Files          46       47       +1     
  Lines        3534     3592      +58     
==========================================
+ Hits         3349     3401      +52     
- Misses        185      191       +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.

RemDelaporteMathurin · 2026-06-24T13:39:04Z

@ck768 @jhdark @hhy2022 would one of you mind having a look at these modifications?

jhdark · 2026-07-07T13:30:48Z

+    try:
+        import pyvista
+    except ImportError as import_error:
+        raise ImportError(
+            "pyvista is required for plotting. Install it with `pip install pyvista`."
+        ) from import_error


We're already importing pyvista in the conda env; maybe we could just make it a requirement in the pyproject.toml as well, and add it to the festim-feedstock conda recipe too?

which conda env? as in it's a dependency inthe FESTIM conda-forge recipe?

jhdark · 2026-07-07T13:36:07Z

+    else:
+        if field.post_processing_solution is not None:
+            raise ValueError(
+                "Problem seems to be HydrogenTransportProblem but a subdomain"
+                " was provided."
+            )
+    if not field.subdomain_to_post_processing_solution:
+        raise ValueError(
+            f"Species {field.name} has no subdomain post-processing solutions."
+        )
+    if subdomain not in field.subdomain_to_post_processing_solution:
+        raise ValueError(
+            f"Species {field.name} has no post-processing solution on subdomain "
+            f"{subdomain}."
+        )


We could write some quick, simple tests to make sure these get raised, and that errors are not raised beforehand elsewhere

jhdark · 2026-07-07T13:36:43Z

+    return field.subdomain_to_post_processing_solution[subdomain]
+
+
+def _make_ugrid(solution, pyvista_module, name="c"):


Even its a hidden method, could use some doc strings

jhdark · 2026-07-07T13:36:49Z

+    raise TypeError("field must be of type festim.Species or a list of festim.Species")
+
+
+def _get_solution(field: Species, subdomain=None):


Doc strings

jhdark · 2026-07-07T13:36:56Z

+DEFAULT_TITLE_FONT_SIZE = 12
+
+
+def _normalize_fields(field: Species | list[Species]) -> list[Species]:


Doc strings

jhdark

Just some minor changes from me

jhdark · 2026-07-07T13:37:35Z

+
+from festim.species import Species
+
+DEFAULT_TITLE_FONT_SIZE = 12


This is only used in one place, dont think its needed

I would keep it here as 1. we may use it in other places 2. it helps keep the "config" variables easily accessible

Co-authored-by: James Dark <65899899+jhdark@users.noreply.github.com>

Initial plan

3de4700

Copilot AI assigned Copilot and RemDelaporteMathurin Jun 23, 2026

Copilot started work on behalf of RemDelaporteMathurin June 23, 2026 12:28 View session

Copilot AI added 6 commits June 23, 2026 12:33

feat: add pyvista plotting helper for species fields

aad93d5

chore: address validation feedback for plotting helper

845ebec

refactor: replace plotting magic numbers with constants

43290d3

test: improve plot wrapper assertions and kwargs coverage

e2dae12

chore: polish plot helper and test naming

fe4aa80

test: cover plot edge cases and defaults

f67490f

Copilot AI changed the title ~~[WIP] Add basic functionality for plotting fields with pyvista~~ Add F.plot(...) for one-line PyVista field visualization Jun 23, 2026

Copilot AI requested a review from RemDelaporteMathurin June 23, 2026 12:40

Copilot finished work on behalf of RemDelaporteMathurin June 23, 2026 12:40

RemDelaporteMathurin added 11 commits June 23, 2026 08:50

fixed shape

a9add94

handle all subdomains

9b8fc60

split coloubars

4e7154c

plotting instead of plot

ee4aaaa

fixed init

62f7305

rewrote tests

e790063

added pyvista to test

89b1c29

install via conda

86e3d20

added plotter close

d7f28b6

more closes

8e62a7b

added headless display action

6d011f9

RemDelaporteMathurin marked this pull request as ready for review June 24, 2026 13:03

RemDelaporteMathurin approved these changes Jun 24, 2026

View reviewed changes

increase coverage

a8d1069

RemDelaporteMathurin approved these changes Jun 24, 2026

View reviewed changes

RemDelaporteMathurin requested a review from jhdark June 24, 2026 13:38

RemDelaporteMathurin requested review from ck768 and hhy2022 June 24, 2026 13:38

RemDelaporteMathurin added 3 commits June 24, 2026 10:03

Merge branch 'main' into copilot/basic-functionality-plotting-fields

2438b41

Merge branch 'main' into copilot/basic-functionality-plotting-fields

85a0e26

Merge branch 'main' into copilot/basic-functionality-plotting-fields

4a4d206

jhdark reviewed Jul 7, 2026

View reviewed changes

jhdark requested changes Jul 7, 2026

View reviewed changes

Apply suggestions from code review

fa67d58

Co-authored-by: James Dark <65899899+jhdark@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add `F.plot(...)` for one-line PyVista field visualization#1176

Add `F.plot(...)` for one-line PyVista field visualization#1176
RemDelaporteMathurin with Copilot wants to merge 23 commits into
mainfrom
copilot/basic-functionality-plotting-fields

Copilot AI commented Jun 23, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

RemDelaporteMathurin commented Jun 24, 2026

Uh oh!

jhdark Jul 7, 2026

Uh oh!

RemDelaporteMathurin Jul 7, 2026

Uh oh!

Uh oh!

jhdark Jul 7, 2026

Uh oh!

jhdark Jul 7, 2026

Uh oh!

jhdark Jul 7, 2026

Uh oh!

jhdark Jul 7, 2026

Uh oh!

jhdark left a comment

Uh oh!

jhdark Jul 7, 2026

Uh oh!

RemDelaporteMathurin Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		return field.subdomain_to_post_processing_solution[subdomain]


		def _make_ugrid(solution, pyvista_module, name="c"):

		raise TypeError("field must be of type festim.Species or a list of festim.Species")


		def _get_solution(field: Species, subdomain=None):

		DEFAULT_TITLE_FONT_SIZE = 12


		def _normalize_fields(field: Species \| list[Species]) -> list[Species]:


		from festim.species import Species

		DEFAULT_TITLE_FONT_SIZE = 12

Uh oh!

Conversation

Copilot AI commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary

Related Issues

Motivation and Context

Type of Change

Testing

Code Quality Checklist

Documentation

Breaking Changes

Screenshots/Examples

Additional Notes

Uh oh!

codecov Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

RemDelaporteMathurin commented Jun 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhdark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jun 23, 2026 •

edited

Loading

codecov Bot commented Jun 23, 2026 •

edited

Loading