Add matplotlib energy landscape plot helper with selectable layouts Unit test included. by nfaguirrec · Pull Request #415 · SCM-NV/PLAMS

nfaguirrec · 2026-08-06T14:53:49Z

Now we can do these things :)

Also, including the molecules:

For surfaces, it also works!

…Unit test included.

Add a test for molecules and surfaces SO215, SO103

SO215, SO103

…s included SO215, SO103

SO215, SO103

dormrod

Looks very nice!

A tiny nit-pick is that it looks to me like the numbers cover some of the molecules with a white square, but this is very minor indeed ;)

Also remember to update the CHANGELOG!

dormrod · 2026-08-10T14:25:24Z

+    remove_text=True,
+    extensions=["png"],
+    style="mpl20",
+    tol=20,


These can be a bit flakey, but tol of 20 is quite high so should be ok...

I just copied it from the other tests. So far, it works. But it is a great point to keep in mind, in case at some point the tests fail

dormrod · 2026-08-10T14:27:27Z

+
+
+@requires_optional_package("matplotlib")
+def plot_energy_landscape(


Re-export in top-level plams?

https://github.com/SCM-NV/PLAMS/blob/trunk/src/scm/plams/__init__.py#L151

Well, every plot_* function in src/scm/plams/tools/plot.py has the same decorator, 10 in total. I thought it was on purpose.

$ grep -H -A1 'requires_optional_package("matplotlib")' src/scm/plams/tools/plot.py src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_band_structure( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_phonons_band_structure( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_phonons_dos( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_phonons_thermodynamic_properties( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-@requires_optional_package("ase") -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_image_grid( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_correlation( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_msd( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_work_function( -- src/scm/plams/tools/plot.py:@requires_optional_package("matplotlib") src/scm/plams/tools/plot.py-def plot_energy_landscape(

dormrod · 2026-08-10T14:28:04Z

+    connector_color: str = "black",
+    connector_linestyle: Any = (0, (4, 4)),
+    label_states: bool = True,
+    layout: str = "auto",


Can we help out the user here: Literal["auto", "dfs", "bfs", "longest_path", "force", "crossings"]?

I added this in the function's documentation:

Use "auto" to compare the available strategies and pick the one with the cleanest connector pattern.

Use "dfs" to follow one branch deeply before backtracking, which can resemble a reaction-path view.

Use "bfs" to expand level by level from one endpoint, keeping nearby states grouped together.

Use "longest_path" to place the main backbone of the network first and then attach side branches around it.

Use "force" to apply a simple force-based relaxation that spreads states while reducing visual crowding.

Use "crossings" to minimize connector crossings directly, which can help for dense networks.

dormrod · 2026-08-10T14:46:39Z

+            state_label = getattr(state, "display_id", state.id)
+            state_plot_kwargs = dict(molecule_plot_kwargs)
+            state_plot_kwargs.update(molecule_plot_kwargs_by_state.get(state_label, {}))
+            plot_molecule(state.molecule, ax=inset_ax, keep_axis=False, **state_plot_kwargs)


You might be able to use view method here instead, if you wanted AMSview style molecules instead of ASE style molecules

I have added the parameter molecule_plot_backend: Literal["view", "plot_molecule"] = "view" to the plot_energy_landscape function. Now, the user can choose which backend they prefer

By the way, I just realized that molecule_plot_backend="view"cannot be tested in CI because ams is not installed there

I also added an example examples/EnergyLandscape/EnergyLandscape.ipynb where I show how to use these new functions, including the use of view and plot_molecule

I also added this option (highlighting states):

…landscape examples and tests SO215, SO103

… landscape function SO215

SO215

SO105

nfaguirrec · 2026-08-11T17:22:40Z

Looks very nice!

A tiny nit-pick is that it looks to me like the numbers cover some of the molecules with a white square, but this is very minor indeed ;)

Also remember to update the CHANGELOG!

Thanks!
In those cases, you can use molecule_y_offset to hide the white squares :)
I already updated the CHANGELOG!

Add matplotlib energy landscape plot helper with selectable layouts. …

7ad6f20

…Unit test included.

nfaguirrec requested a review from dormrod August 6, 2026 14:53

nfaguirrec added 6 commits August 6, 2026 17:00

Removed unrelated content from the previous commit

0197649

Fixing mypy error detected in CI

daf4bbc

Add strict type annotations to energy landscape plotting (again)

d3d57a4

Add strict type annotations to energy landscape plotting (again2)

af5fefd

Add strict type annotations to energy landscape plotting (again3)

1e2fae8

Fix mypy Optional[IPython] access in CRS plotting

f893ba0

nfaguirrec changed the title ~~Add matplotlib energy landscape plot helper with selectable layouts Unit test included.~~ WIP: Add matplotlib energy landscape plot helper with selectable layouts Unit test included. Aug 6, 2026

nfaguirrec changed the title ~~WIP: Add matplotlib energy landscape plot helper with selectable layouts Unit test included.~~ Add matplotlib energy landscape plot helper with selectable layouts Unit test included. Aug 6, 2026

nfaguirrec marked this pull request as draft August 6, 2026 20:46

nfaguirrec changed the title ~~Add matplotlib energy landscape plot helper with selectable layouts Unit test included.~~ WIP: Add matplotlib energy landscape plot helper with selectable layouts Unit test included. Aug 7, 2026

nfaguirrec added 4 commits August 7, 2026 18:48

Add optional molecule rendering to energy landscape plots.

1d02c67

Add a test for molecules and surfaces SO215, SO103

Fix mypy typing for energy landscape molecule insets

0b445a6

SO215, SO103

Add state selection and reachability helpers to EnergyLandscape. Test…

520656b

…s included SO215, SO103

Fix mypy for EnergyLandscape(None) construction

7df1300

SO215, SO103

dormrod reviewed Aug 10, 2026

View reviewed changes

nfaguirrec added 7 commits August 11, 2026 15:06

Add molecule_plot_backend={"view"|"plot_molecule"} support to energy …

a3d50a9

…landscape examples and tests SO215, SO103

Improves the description of the parameter "layout" in the plot energy…

d0dcb92

… landscape function SO215

Reformat plot_energy_landscape layout docstring for Sphinx

7671f25

SO215

Reformats EnergyLandscape.py with black

9f854d2

SO215

I think that molecule_plot_backend="view" can not be testes in CI

422affa

SO215

Added the option of highlighting states

564e163

SO105

black reformatted examples/EnergyLandscape/EnergyLandscape.*

deb29e7

SO105

nfaguirrec marked this pull request as ready for review August 11, 2026 16:27

nfaguirrec changed the title ~~WIP: Add matplotlib energy landscape plot helper with selectable layouts Unit test included.~~ Add matplotlib energy landscape plot helper with selectable layouts Unit test included. Aug 11, 2026

CHANGELOG.md updated

84fea5f

Navigation Menu

Uh oh!

Add matplotlib energy landscape plot helper with selectable layouts Unit test included. - #415

Add matplotlib energy landscape plot helper with selectable layouts Unit test included.#415
nfaguirrec wants to merge 19 commits into
trunkfrom
plot_energy_landscape

nfaguirrec commented Aug 6, 2026 •

edited

Loading

Uh oh!

dormrod left a comment •

edited

Loading

Uh oh!

dormrod Aug 10, 2026 •

edited

Loading

Uh oh!

nfaguirrec Aug 11, 2026

Uh oh!

dormrod Aug 10, 2026

Uh oh!

nfaguirrec Aug 11, 2026

Uh oh!

dormrod Aug 10, 2026

Uh oh!

nfaguirrec Aug 11, 2026

Uh oh!

dormrod Aug 10, 2026

Uh oh!

nfaguirrec Aug 11, 2026

Uh oh!

nfaguirrec Aug 11, 2026

Uh oh!

nfaguirrec Aug 11, 2026

Uh oh!

nfaguirrec Aug 11, 2026

Uh oh!

nfaguirrec commented Aug 11, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants



		@requires_optional_package("matplotlib")
		def plot_energy_landscape(

Uh oh!

Conversation

nfaguirrec commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dormrod left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dormrod Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

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!

nfaguirrec commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nfaguirrec commented Aug 6, 2026 •

edited

Loading

dormrod left a comment •

edited

Loading

dormrod Aug 10, 2026 •

edited

Loading

nfaguirrec commented Aug 11, 2026 •

edited

Loading