feat: deprecate legacy plotter

[moe-ad]

Closes #2918.

This PR implements changes required to deprecate the legacy Plotter class. By far the major blocker that has been preventing its deprecation is the plot_contour method, which is used directly by the Field and MeshedRegion classes. The plot_contour method does too much for a single method, which unfortunately complicates things.

In summary, this PR:

• Breaks the monolithic logic in plot_contour across:
  • Smaller and more manageable module-level private functions (there is a _map_field_to_mesh function whose logic overlaps some sections of plot_contour, so I used this opportunity to refactor things).
  • Private methods in relevant classes. We can discuss whether or not these methods should be make public.
• Moves Plotter.plot_chart to a module level function (another alternative is to make it a method of DpfPlotter).
• Add deprecation warning to the Plotter class so users are informed of the eventual deprecation, and to the API documentation (on the assumption that this ships with 0.17.0).
• Add relevant tests and updates existing tests to accommodate changes made.

In detail, this PR:

• adds DpfPlotter.add_fields_container() as the new public method for plotting a FieldsContainer as a single contour.
• splits the legacy Plotter.plot_contour() workflow into smaller private helpers in plotter.py, and these private helpers are then reused when needed.
• moves field-to-mesh scattering logic into MeshedRegion._scatter_field_to_location(), and reuses that logic from vtk_helper._map_field_to_mesh().
• adds FieldsContainer._normalize_shell_layers() to contain the logic for normalizing multi-layer shell results before plotting.
• updates Field.plot(), FieldsContainer.plot(), and MeshedRegion.plot() to use DpfPlotter directly instead of relying on the legacy Plotter.
• moves chart plotting to the module-level plot_chart() function, while keeping Plotter.plot_chart() as a deprecated wrapper for compatibility.
• keeps Plotter available for now, but adds deprecation warnings and deprecation notes (to the API documentation) to guide users toward DpfPlotter.
• adds and updates tests to cover the new plotting code execution paths, shell-layer normalization, mesh scattering, chart plotting, and deprecated compatibility behavior.

End results

Plots still using former Plotter	After changes in this PR
Example 1	Example 1 Updated
Example 2 (compare several plots starting from the linked section)	Example 2 Updated

Check here for appearance of API deprecation notes.

[codecov]

Codecov Report

❌ Patch coverage is 86.44689% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.07%. Comparing base (1fc62f8) to head (9824e7c).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3184      +/-   ##
==========================================
+ Coverage   82.80%   83.07%   +0.26%     
==========================================
  Files          94       94              
  Lines       11754    11775      +21     
==========================================
+ Hits         9733     9782      +49     
+ Misses       2021     1993      -28     

[github-actions]

The documentation for this pull request will be available at https://dpf.docs.pyansys.com/pull/3184. Please allow some time for the documentation to be deployed.

[jorgepiloto]

Thanks for the refactor, @moe-ad. I noticed a behavioral regression in Plotter.plot_contour():

Plotter.__init__  still stores constructor kwargs like off_screen  and notebook. However, plot_contour() now instantiates a new  DpfPlotter from method kwargs only so constructor-level options are no longer used unless repeated per call.

Is this intended? Should we preserve legacy behavior by reusing the existing internal plotter/config from  Plotter.__init__  (or by merging stored __init__ kwargs into  plot_contour()  kwargs with call kwargs taking precedence)?

This seems important for backward compatibility during deprecation.

[moe-ad]

Thanks for the refactor, @moe-ad. I noticed a behavioral regression in Plotter.plot_contour():

Plotter.__init__  still stores constructor kwargs like off_screen  and notebook. However, plot_contour() now instantiates a new  DpfPlotter from method kwargs only so constructor-level options are no longer used unless repeated per call.

Is this intended? Should we preserve legacy behavior by reusing the existing internal plotter/config from  Plotter.__init__  (or by merging stored __init__ kwargs into  plot_contour()  kwargs with call kwargs taking precedence)?

This seems important for backward compatibility during deprecation.

Great catch! The plotter created in Plotter__init__ should be reused in plot_contour. I have added c4d256d to address that.

[PProfizi]

If you are reusing the labels from the initial FieldsContainer, then in theory you should end-up with the same number of fields, no? I am not clear on why thsi is necessary. Or did you mean to use the label_space input of the function?

[moe-ad]

This is just to create a new FieldsContainer with the same labels, otherwise line 644 would fail with DPFServerException: the query is not correctly asked i.e. your collection doesn't have any LabelSpace.

[github-actions]

Some tests with 'continue-on-error: true' have failed:

• PyDPF-Post docstring tests on ubuntu-latest

• PyDPF-Post docstring tests on windows-latest

• PyDPF-Post API tests on ubuntu-latest

• PyDPF-Post API tests on windows-latest

  Created by continue-on-error-comment