Python script for analyzing TSH trajectories from ABIN.

[JanosJiri]

The script plots PES along the trajectory, electronic populations, total and kinetic energy from either LZSH or FSSH. All is in one plot and allows analysis of a single trajectory run.

[JanosJiri]

Hi @danielhollas, I've created a Python script which I use to analyze TSH calculations in ABIN. I thought it might be handy to attach it to ABIN as people could use it for analysis. Please, have a look and let me know if you fancy having such a script with ABIN.

[Copilot]

Pull Request Overview

This PR introduces a Python script for analyzing TSH trajectories from ABIN simulations by plotting potential energy surfaces, electronic populations, and energy data from either LZSH or FSSH runs.

• Adds a command-line interface for specifying input files and options for energy unit conversion and curve shifting.
• Implements file existence checks and plotting of trajectories and energy profiles based on generated data.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.05%. Comparing base (c83c105) to head (0d3ff08).
Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #206   +/-   ##
=======================================
  Coverage   84.05%   84.05%           
=======================================
  Files          47       47           
  Lines        6599     6599           
  Branches      764      764           
=======================================
  Hits         5547     5547           
  Misses        853      853           
  Partials      199      199           

Flag	Coverage Δ
unittests	18.41% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[danielhollas]

I thought it might be handy to attach it to ABIN as people could use it for analysis. Please, have a look and let me know if you fancy having such a script with ABIN.

Yes please! I'll have a closer look later but this looks very handy of course! 👏 😍

(I might do a quick pass over the script if you don't mind. But let me know if you prefer to iterate over review)

[JanosJiri]

Go for it, no need to iterate over review.

[danielhollas]

This is great, thanks! I made some insignificant changes and added inline metadata so that the script can be run via uv run. I have some questions / suggestions about the command line arguments.

[danielhollas]

Added via

uv add --script tsh_traj_anal.py numpy matplotlib PyQT6

[JanosJiri]

Just a question, why is PyQT6 needed here?

[danielhollas]

Good question. When using python installations from uv, the plt.show command did not work for me (no graph was interactively displayed). This is a known issue: astral-sh/uv#6893

So this is a workaround for that. It's not ideal, but I think better then potentially failing script. I'll add a comment about it.

[JanosJiri]

I modified the script according to your comments plus I added some checks for the nstates variable. Please, have a look.

[danielhollas]

Thank you for the changes! I have two questions about the energy shifting, but otherwise I am happy, this will be very useful!

I don't think we need a new top-level analysis directory at this point, so I moved it to utils/. At some point we might want to organize the utils/ directory a bit better, but not here.

[danielhollas]

This option is currently confusing to me. If I understand correctly, specifying this option actually turns off the energy shift?

What if we instead have an option that specifies the zero energy (probably in atomic units)? For example

Suggested change

	parser.add_argument(
	"-es",
	"--energy-shift",
	action="store_false",
	help="Shift curves so that the lowest state minimum has 0 energy",
	)
	parser.add_argument(
	"-ze",
	"--zero-energy",
	type=float
	default=None,
	help="Specify zero energy (in atomic units). All energy curves will be shifted with respect to this energy.",
	)

To turn off energy shifting, the user then could pass (--energy-shift 0).
And this would also allow to pass any value, which would be handy if you were analyzing multiple trajectories and wanted to have consistent E0)

[JanosJiri]

That's a good point. I added it ages ago and probably used it once in my life. Your suggestion makes complete sense.

[danielhollas]

I did not notice this before, but this looks like the E0 is taken as the minimum S0 energy across the whole trajectory? To me this is a non-obvious choice. I would expect to simply shift the energy based on S0 at t0. What do you think?

[JanosJiri]

Yep, that's also a good point. I would modify it to the minimum of PES at t0. If we have triplets in LZ, the lowest triplet could be below S0, e.g., for oxygen. But otherwise it should be the same as taking S0 energy at t0.

[JanosJiri]

I worked on the suggestions regarding the energy-shift parameter. In the end, I combined your suggestion with the original version. Currently, if you don't use --energy-shift, all the energies are shifted such that you start with the lowest state at zero energy. If you specify some value for energy shift, it will shift the original energies by the value specified. I kept it that way because if I want to look at multiple trajectories and have them all starting at the same position, I use --energy-shift. If I want to check the absolute energies, I use --energy-shift 0. And if I want to shift just one of the trajectories to see how it compares to others, I would use --energy-shift xx for the one. That's all the regimes I ever wanted to use. Let me know what you think about it.

[danielhollas]

Perfect! That's actually what I had in mind, but didn't write out clearly apparently. Thanks for bearing with me. :-)