[Feature]: add water and energy budget plots

[chengzhuzhang]

How will this affect the next version number?

New feature (increment MINOR version)

Is your feature request related to a problem?

As a part of code review, it requires a water and energy budget check. We can use zppy/zppy-interfaces to parse log files and create time-series plots for water and energy conservation.

There still work needs to be done from component level (i.e. land energy budget) from a comprehensive conservation check, but we can start with prototyping with visualizing cpl log file.

Describe the solution you'd like

We will model after the python scripts created by @golaz that reads from ascii coupler tables from cpl.log.*.gz and and create html page that include the budget plots.

Describe alternatives you've considered

No response

Additional context

No response

[forsyth2]

Thanks @chengzhuzhang. Is this asking for a new plotting package or to add plots to an existing package? It sounds like the former, in which case, we can add this as a new entry point for zppy-interfaces.

Can you provide the paths to the Python scripts so I can take a look?

[chengzhuzhang]

Thanks, Ryan. I have assigned Claude code to work on this. Since this is a small script, the recommendation is to add directly to zppy to avoid maintenance overhead. I will tag you once there is a workable version.

[forsyth2]

add directly to zppy to avoid maintenance overhead.

Ok, so something like tc_analysis, which just uses a bash script? It's important then that dependencies are kept to an absolute minimum, since these ad-hoc scripts don't have corresponding dev environments built around them (i.e., to use for environment_commands). If that begins to grow, I would recommend switching over to zppy-interfaces.

[chengzhuzhang]

Thanks for the suggestion, it makes great sense, although it's currently a small script, but we will potentially add more functionalities and grow it bigger. Which means we will have one PR for zppy-interfaces include the CLI version of budget analysis, and another PR for zppy to call it.

[forsyth2]

Yes that sounds good, thanks. I do have a couple more questions, which may be answered once I see Claude's implementation/PR.

1. Is there context for why this should be a new plotting feature (rather than integrating it as a new set in e3sm_diags for example)? I just want to confirm the implementation is sufficiently distinct to warrant that.
2. Re: "requires a water and energy budget check" & "create time-series plots for water and energy conservation" -- are these the same task or 2 distinct tasks? That is, should the output consist of both a "yes/no this run of the model conserved energy/water" and a plot of relevant values? Or is the conservation check to be done by humans looking at the generated plot?

[chengzhuzhang]

1. The draft for zppy-interfaces is up (Add E3SM Budget Analysis CLI Tool zppy-interfaces#47). This new set parses and visualize log files, is a relatively independent. zppy-interfaces
   seems to be a good fit to host it.
2. The conservation plots from post-processing will require experts in the loop to check, just as for instance the use of those global time-series plots.

[forsyth2]

@chengzhuzhang Ok sounds good, and thanks for working on E3SM-Project/zppy-interfaces#47 & #776. Are they ready for review? They're still marked as drafts. I can also add the unit/integration tests if you'd like.

There still work needs to be done from component level (i.e. land energy budget) from a comprehensive conservation check, but we can start with prototyping with visualizing cpl log file.

Is the intention for that work to be done as a later pull request or to be included in these?

[chengzhuzhang]

I will further testing this with some recent cpl log files. Let's keep it as draft for now.
Would be nice to finalize and merge for the next zppy release for unified.