Add E3SM Budget Analysis CLI Tool

[chengzhuzhang]

Summary

Adds zi-budget-analysis CLI tool for analyzing water and energy conservation from E3SM coupler log files, designed to be called by zppy's new budget task. This tool is based on the script Chris Golaz (@golaz) originally created.

Key Changes

• New package: zppy_interfaces/budget_analysis/ with modular architecture
• CLI entry point: zi-budget-analysis command registered in pyproject.toml
• Parser module: parser.py - Extracts budget data from E3SM coupler logs (cpl.log.*.gz)
• Plotting module: plotting.py - Generates interactive Bokeh HTML plots and PNG fallbacks
• Main CLI: main.py - Command-line interface with argparse

Features

• Data extraction: Parses E3SM coupler budget tables from compressed log files
• Interactive visualization: Bokeh-based HTML plots showing cumulative budget trends
• Fallback plots: matplotlib PNG generation when Bokeh fails
• ASCII summaries: Tabular budget data for numerical analysis
• Flexible input: Configurable budget types (water, heat) and year ranges

CLI Interface

zi-budget-analysis --log_path /lcrc/group/e3sm2/ac.jwolfe/E3SMv3_dev/20251107.v3.HR.piControl-Spinup/archive/logs --start_year 114 --end_year 206 --output_dir /lcrc/group/e3sm/public_html/diagnostic_output/ac.zhang40/zppy_dev  

Dependencies

• Adds bokeh and matplotlib to project dependencies
• Uses existing numpy, xarray ecosystem for data handling

Integration

Designed as external tool for zppy budget task, following zppy-interfaces pattern of providing specialized CLI tools
that zppy orchestrates through batch job templates.

Issue resolution:

• Closes #<ISSUE_NUMBER_HERE>

Select one: This pull request is...

• a bug fix: increment the patch version
• a small improvement: increment the minor version
• a new feature: increment the minor version
• an incompatible (non-backwards compatible) API change: increment the major version

Please fill out either the "Small Change" or "Big Change" section (the latter includes the numbered subsections), and delete the other.

Small Change

• To merge, I will use "Squash and merge". That is, this change should be a single commit.
• Logic: I have visually inspected the entire pull request myself.
• Pre-commit checks: All the pre-commits checks have passed.

Big Change

• To merge, I will use "Create a merge commit". That is, this change is large enough to require multiple units of work (i.e., it should be multiple commits).

1. Does this do what we want it to do?

Required:

• Product Management: I have confirmed with the stakeholders that the objectives above are correct and complete.
• Testing: I have considered likely and/or severe edge cases and have included them in testing.

2. Are the implementation details accurate & efficient?

Required:

• Logic: I have visually inspected the entire pull request myself.
• Logic: I have left GitHub comments highlighting important pieces of code logic. I have had these code blocks reviewed by at least one other team member.

If applicable:

• Dependencies: This pull request introduces a new dependency. I have discussed this requirement with at least one other team member. The dependency is noted in zppy-interfaces/conda, not just an import statement.

3. Is this well documented?

Required:

• Documentation: by looking at the docs, a new user could easily understand the functionality introduced by this pull request.

4. Is this code clean?

Required:

• Readability: The code is as simple as possible and well-commented, such that a new team member could understand what's happening.
• Pre-commit checks: All the pre-commits checks have passed.

If applicable:

• Software architecture: I have discussed relevant trade-offs in design decisions with at least one other team member. It is unlikely that this pull request will increase tech debt.

[rljacob]

If you're also adding an agent help file in this PR, I suggest you follow what I did for E3SM. E3SM-Project/E3SM#8083. AGENTS.md is the standard.

[chengzhuzhang]

Thanks, @rljacob. Does this change 4d9becd look okay?

[forsyth2]

@chengzhuzhang The addition of AGENTS.md should absolutely be a distinct PR, not included as part of this PR.

[chengzhuzhang]

@forsyth2 This is needed to keep work on this PR using CLAUDE efficiently.
This is still a Draft. thanks!