Add SimBoard-compatible www inference via a new [simboard] config section

[Copilot]

Summary

Adds an opt-in [simboard] configuration section that lets zppy infer the [default] www path automatically instead of requiring users to set it explicitly. This targets SimBoard-compatible publishing, where the diagnostics archive path can be derived from Mache's web_portal.base_path.

Expected behavior:

simboard.enabled	www	Behavior
False	any	zppy does nothing SimBoard-specific.
True	empty	Infer the SimBoard archive path from mache.
True	set	Use www as the output path and do not override it. simboard.enabled still controls SimBoard-specific metadata and validation.
True	empty, but path cannot be inferred	Raise a clear configuration error.

Changes

New [simboard] config section (zppy/defaults/default.ini)

• enabled (bool, default False): opts in to SimBoard-compatible publishing.
• simulation_type (option: production | development | none, default production): selects the archive classification used when inferring www.
• [default] www no longer requires an explicit value (string(default="") instead of a bare string), since it can now be inferred.

New module zppy/simboard.py

• simboard(...): a configuration-only task hook (no HPC job), analogous to [bundle], that validates the [simboard] section has no subsections.
• simboard_enabled(config): parses enabled from bool or "true"/"false" strings (case-insensitive), raising ValueError on anything else.
• validate_simboard_config(config): rejects simulation_type = "none" whenever enabled = True.
• normalize_web_portal_base_path(...): strips whitespace and trailing slashes.
• infer_simboard_www(machine_info, config): builds <web_portal base_path>/diagnostics_archive/<simulation_type>/, raising a descriptive ValueError if Mache has no (or an empty) web_portal.base_path for the current machine.

zppy/__main__.py

• _determine_parameters now calls a new _set_default_www helper, which:
  • Always runs validate_simboard_config (so simulation_type is checked even when www is already explicitly set).
  • Leaves www untouched if already provided.
  • Otherwise requires simboard.enabled = True and infers www via infer_simboard_www; raises a clear error if www is empty and SimBoard is not enabled.
• _launch_scripts now runs the simboard config-hook bundle alongside other predefined bundles, before climo tasks.

Docs (docs/source/parameters.rst)

• Documents the two new [simboard] parameters.
• Documents the new www inference rule for the top-level www parameter, including the three failure/success cases (inferred when enabled, error when not enabled, error when Mache lacks web_portal.base_path).
• Fixes an unrelated typo (configuraiton → configuration).

Tests

• tests/test_sections.py: adds expected defaults for the new [simboard] section.
• tests/test_zppy_main.py (new): comprehensive coverage including:
  • www inference for both production and development simulation types.
  • Path normalization (trailing slash, whitespace).
  • simboard_enabled parsing across bool/string/invalid inputs.
  • Explicit www is preserved even when SimBoard is enabled.
  • Error raised when www is empty and SimBoard is disabled.
  • Error raised when simulation_type = "none" while enabled.
  • Errors raised when Mache's web_portal.base_path is missing or empty.
  • Rejection of subsections under [simboard].
  • Rejection of invalid simulation_type values via ConfigObj validation.

Behavior notes

• Backward compatible: if www is set explicitly, behavior is unchanged (aside from also validating simulation_type isn't "none" when enabled = True).
• If www is omitted and SimBoard is not enabled, zppy now raises an error (previously this was enforced structurally by the config spec requiring www).

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

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.

[tomvothecoder]

@forsyth2 Thanks for opening this PR so quickly. I replied to some of your comments above and tagged Jill for input.

[tomvothecoder]

@chengzhuzhang and @forsyth2 here is my proposed design based on the SimBoard team meeting.

Zppy diagnostic directory structure

I think zppy should publish SimBoard-compatible diagnostics under one bounded archive root:

<WEB_ROOT>/diagnostics_archive/
  production/
  development/

This gives SimBoard one narrow discovery target, avoids broad scans across unrelated web content, and keeps production and development output separated under one common root. Directory layout would be used for discovery only; provenance.settings under each diagnostic output directory would remain authoritative for classification metadata.

Zppy config

For config, I think this should be explicit and opt-in via a [simboard] section, rather than inferred from generic path-inference behavior. SimBoard publishing should depend only on simboard.enabled=True plus an empty www.

If infer_path_parameters is only being used for SimBoard publishing, I think we should remove it from this flow. It could confuse users because it combines generic path inference with SimBoard-specific behavior by inferring diagnostic archive paths using mache.

Expected behavior:

simboard.enabled	www	Behavior
False	any	zppy does nothing SimBoard-specific.
True	empty	Infer the SimBoard archive path from mache.
True	set	Use www as the output path and do not override it. simboard.enabled still controls SimBoard-specific metadata and validation.
True	empty, but path cannot be inferred	Raise a clear configuration error.

[default]
www =                         # Diagnostic web output root. If empty and simboard.enabled=True, infer a SimBoard-compatible archive path from mache.

[simboard]
enabled = False               # Opt in to SimBoard-compatible publishing behavior.
simulation_type = development # Diagnostic classification for SimBoard publishing: production | development.

Let me know what you think. We can discuss more at next week's EZ Meeting too.

[tomvothecoder]

@forsyth2 The team agreed on my design above. Happy to get your thoughts when you return from vacation.

[forsyth2]

Hi @tomvothecoder, thanks for the design.

Checking that each of my design decisions above have been addressed:

Design decision 1

# Leave blank to infer `<web_portal base_path>/simboard/<simboard_type>/`
# when `infer_path_parameters = True`
www = string(default="")

Design decision: How do we want users to specify they want to use the SimBoard paths? Is leaving www blank a sufficient method?

Addressed by:

For config, I think this should be explicit and opt-in via a [simboard] section, rather than inferred from generic path-inference behavior. SimBoard publishing should depend only on simboard.enabled=True plus an empty www.

Expected behavior:

simboard.enabled	www	Behavior
False	any	zppy does nothing SimBoard-specific.
True	empty	Infer the SimBoard archive path from mache.
True	set	Use www as the output path and do not override it. simboard.enabled still controls SimBoard-specific metadata and validation.
True	empty, but path cannot be inferred	Raise a clear configuration error.

This makes sense, but adding a new [simboard] section does complicate things a bit. Each section adds its own bash template and Python file. The cloest analog would be the [bundles] section, which like [simboard] isn't so much describing a new task as it is describing how to run other tasks.

In short, this can be implemented, but it's a little bit more overhead. It sounds like that's worth it for clarity to users though.

Design decision 2

    simboard_type = config["default"]["simboard_type"]
    web_portal_base_path = machine_info.config.get("web_portal", "base_path")
    config["default"]["www"] = (
        f"{web_portal_base_path}/simboard/{simboard_type}/"

Design decision: Is this the web portal base path we want? (Remember, the URL is deterministic based on the base path).

Addressed by:

I think zppy should publish SimBoard-compatible diagnostics under one bounded archive root:

<WEB_ROOT>/diagnostics_archive/
 production/
 development/

So, it looks like we just want to change the above to f"{web_portal_base_path}/diagnostics_archive/{simboard_type}/ and set simboard_type = option("production", "development", "none" default="production") (adding "none" for the non-simboard runs) in zppy/defaults/default.ini.

That sounds good to me; do we want to include "simboard" anywhere in the path to be explicit about the structure being for SimBoard? E.g., simboard_diagnostics_archive?

Design decision 3

For the top-level ``www`` parameter:

* If ``www`` is undefined and ``infer_path_parameters = True``, assume it is ``<web_portal base_path>/simboard/<simboard_type>/``.
* If ``www`` is undefined and ``infer_path_parameters = False``, ``zppy`` will raise an error.

Design decision: should we do the same for output?

Not addressed explicitly, but it seems like only www is needed, not output, correct?

[forsyth2]

@copilot Please implement these two additions to this PR:

1. Add a SimBoard task. The cloest analog would be the [bundles] section, which like [simboard] isn't so much describing a new task as it is describing how to run other tasks. Adding a task typically means adding a corresponding .py file and .bash template.

Expected behavior:

simboard.enabled	www	Behavior
False	any	zppy does nothing SimBoard-specific.
True	empty	Infer the SimBoard archive path from mache.
True	set	Use www as the output path and do not override it. simboard.enabled still controls SimBoard-specific metadata and validation.
True	empty, but path cannot be inferred	Raise a clear configuration error.

An example cfg:

[default]
www =                         # Diagnostic web output root. If empty and simboard.enabled=True, infer a SimBoard-compatible archive path from mache.

[simboard]
enabled = False               # Opt in to SimBoard-compatible publishing behavior.
simulation_type = development # Diagnostic classification for SimBoard publishing: production | development.

2. Change the inferred directory structure when using SimBoard

    simboard_type = config["default"]["simboard_type"]
    web_portal_base_path = machine_info.config.get("web_portal", "base_path")
    config["default"]["www"] = (
        f"{web_portal_base_path}/simboard/{simboard_type}/"

should be updated so that we get something like:

<WEB_ROOT>/diagnostics_archive/
 production/
 development/

That is, f"{web_portal_base_path}/diagnostics_archive/{simboard_type}/ and then in default.ini: simboard_type = option("production", "development", "none" default="production") (adding "none" for the non-simboard runs).

[Copilot]

@copilot Please implement these two additions to this PR:

1. Add a SimBoard task. The cloest analog would be the [bundles] section, which like [simboard] isn't so much describing a new task as ...

Addressed in 10b7f2a.

This updates the PR to use an explicit [simboard] section/task hook with enabled and simulation_type, infers empty www only when SimBoard publishing is enabled, switches the inferred archive root to diagnostics_archive/<simulation_type>/, and updates the related validation, docs, and unit coverage.

[forsyth2]

Remaining action items:

• Address Copilot's review comments
• Rebase & resolve conflicts
• Confirm completed design with Tom
• Add integration test cfg that uses SimBoard setup, and run that test cfg

[tomvothecoder]

Thanks for the updates @forsyth2.

This makes sense, but adding a new [simboard] section does complicate things a bit. Each section adds its own bash template and Python file. The cloest analog would be the [bundles] section, which like [simboard] isn't so much describing a new task as it is describing how to run other tasks.

In short, this can be implemented, but it's a little bit more overhead. It sounds like that's worth it for clarity to users though.

I agree, adding the [simboard] section is worth the clarity.

That sounds good to me; do we want to include "simboard" anywhere in the path to be explicit about the structure being for SimBoard? E.g., simboard_diagnostics_archive?

We can keep it generic since SimBoard is a consumer of the archive rather than the owner. Similarly, we'd follow the same model where E3SM simulations output performance/timing metadata to a generic performance_archive directory that PACE consumes.

Not addressed explicitly, but it seems like only www is needed, not output, correct?

I forgot to discuss this with the team. I think for now we can focus on www until somebody brings up the need to view output.

[forsyth2]

Sounds good, thanks @tomvothecoder!

[forsyth2]

It looks like the Copilot review got confused by the un-updated PR description. I've had Claude write an updated description for the PR and pasted it in above. I also included Tom's expected behavior table. Claude also suggested the new title: "Add SimBoard-compatible www inference via a new [simboard] config section".

For reference:

Pasted content

Summary

Adds an opt-in [simboard] configuration section that lets zppy infer the [default] www path automatically instead of requiring users to set it explicitly. This targets SimBoard-compatible publishing, where the diagnostics archive path can be derived from Mache's web_portal.base_path.

Expected behavior:

simboard.enabled	www	Behavior
False	any	zppy does nothing SimBoard-specific.
True	empty	Infer the SimBoard archive path from mache.
True	set	Use www as the output path and do not override it. simboard.enabled still controls SimBoard-specific metadata and validation.
True	empty, but path cannot be inferred	Raise a clear configuration error.

Changes

New [simboard] config section (zppy/defaults/default.ini)

• enabled (bool, default False): opts in to SimBoard-compatible publishing.
• simulation_type (option: production | development | none, default production): selects the archive classification used when inferring www.
• [default] www no longer requires an explicit value (string(default="") instead of a bare string), since it can now be inferred.

New module zppy/simboard.py

• simboard(...): a configuration-only task hook (no HPC job), analogous to [bundle], that validates the [simboard] section has no subsections.
• simboard_enabled(config): parses enabled from bool or "true"/"false" strings (case-insensitive), raising ValueError on anything else.
• validate_simboard_config(config): rejects simulation_type = "none" whenever enabled = True.
• normalize_web_portal_base_path(...): strips whitespace and trailing slashes.
• infer_simboard_www(machine_info, config): builds <web_portal base_path>/diagnostics_archive/<simulation_type>/, raising a descriptive ValueError if Mache has no (or an empty) web_portal.base_path for the current machine.

zppy/__main__.py

• _determine_parameters now calls a new _set_default_www helper, which:
  • Always runs validate_simboard_config (so simulation_type is checked even when www is already explicitly set).
  • Leaves www untouched if already provided.
  • Otherwise requires simboard.enabled = True and infers www via infer_simboard_www; raises a clear error if www is empty and SimBoard is not enabled.
• _launch_scripts now runs the simboard config-hook bundle alongside other predefined bundles, before climo tasks.

Docs (docs/source/parameters.rst)

• Documents the two new [simboard] parameters.
• Documents the new www inference rule for the top-level www parameter, including the three failure/success cases (inferred when enabled, error when not enabled, error when Mache lacks web_portal.base_path).
• Fixes an unrelated typo (configuraiton → configuration).

Tests

• tests/test_sections.py: adds expected defaults for the new [simboard] section.
• tests/test_zppy_main.py (new): comprehensive coverage including:
  • www inference for both production and development simulation types.
  • Path normalization (trailing slash, whitespace).
  • simboard_enabled parsing across bool/string/invalid inputs.
  • Explicit www is preserved even when SimBoard is enabled.
  • Error raised when www is empty and SimBoard is disabled.
  • Error raised when simulation_type = "none" while enabled.
  • Errors raised when Mache's web_portal.base_path is missing or empty.
  • Rejection of subsections under [simboard].
  • Rejection of invalid simulation_type values via ConfigObj validation.

Behavior notes

• Backward compatible: if www is set explicitly, behavior is unchanged (aside from also validating simulation_type isn't "none" when enabled = True).
• If www is omitted and SimBoard is not enabled, zppy now raises an error (previously this was enforced structurally by the config spec requiring www).

[forsyth2]

I've cherry-picked the commit from the accidentally-opened #844.

[forsyth2]

@tomvothecoder This PR is ready for your review. It includes the functional changes, doc updates, and test updates.

If you have enough of the SimBoard pipeline built at this point, I'd recommend testing it with a zppy dev environment built off this branch.

[tomvothecoder]

Hi @forsyth2, I appreciate you working on this. I reviewed the docs and code. My only suggestion is to make "development" the default (reasoning in PR review comment).

Afterwards, the next tasks would be:

1. @chengzhuzhang (or you) test this feature by running this zppy branch to produce sample output in the diagnostics_archive/development and diagnostics_archive/production directories -- this can be done on LCRC/Chrysalis first until NERSC/Perlmutter is back online
2. I implement and test this SimBoard issue: E3SM-Project/simboard#240
3. Merge this PR and SimBoard's PR once validation is successful.

Thanks!

[tomvothecoder]

I think the default should be "development". Accidentally placing development diagnostics under production would be more harmful than placing production diagnostics under development. Production should be an explicit designation rather than the default.

A user can later promote diagnostics to production, but this requires two separate actions: updating simulation_type in SimBoard and manually moving the diagnostic output to the corresponding location under diagnostics_archive. I recommend this information be in the zppy SimBoard docs.

[forsyth2]

@copilot Please add a commit addressing these 3 points:

1. The default simulation_type should be "development". I.e.,:

-simulation_type = option("production", "development", "none", default="production")
+simulation_type = option("production", "development", "none", default="development")

2. Please add this information to the SimBoard user docs: development is the default because "Accidentally placing development diagnostics under production would be more harmful than placing production diagnostics under development." and "A user can later promote diagnostics to production, but this requires two separate actions: updating simulation_type in SimBoard and manually moving the diagnostic output to the corresponding location under diagnostics_archive."

3. There are currently only docs on SimBoard in the user guide. Please update the dev guide as well.

[Copilot]

@copilot Please add a commit addressing these 3 points:

1. The default simulation_type should be "development". I.e.,:
   ...

Done in the latest commit:

1. Changed simulation_type default to "development" in default.ini and updated test_sections.py to match.
2. Added a "Promoting diagnostics from development to production" section to the user guide simboard.rst explaining the reasoning and the two-step promotion process.
3. Created docs/source/dev_guide/tasks/simboard.rst and registered it in the dev guide tasks index.

[forsyth2]

Copilot has addressed @tomvothecoder's comments and my request for dev-guide documentation in the latest commit.

I've tested it with:

# Copilot made changes

cd ~/ez/zppy
git status
# On branch copilot/update-default-www-and-simboard-type
# nothing to commit, working tree clean
git fetch upstream copilot/update-default-www-and-simboard-type
git reset --hard upstream/copilot/update-default-www-and-simboard-type
# HEAD is now at 41892d02 Change simulation_type default to "development"; update docs
lcrc_conda
conda activate zppy-pr841-simboard-20260724

# 1. Check pre-commit
pre-commit run --all-files

# 2. Check tests
python -m pip install .
# Unit tests:
pytest tests/test_*.py
# 84 passed in 1.30s
# SimBoard integration test:
pytest tests/integration/test_simboard_settings.py
# 4 passed in 0.24s

# 3. Check docs
cd docs
make html
cp -r _build/ /lcrc/group/e3sm/public_html/diagnostic_output/ac.forsyth2/zppy_docs_pr841_20260730
chmod -R 755 /lcrc/group/e3sm/public_html/diagnostic_output/ac.forsyth2/zppy_docs_pr841_20260730
# Visit https://web.lcrc.anl.gov/public/e3sm/diagnostic_output/ac.forsyth2/zppy_docs_pr841_20260730

There's just one clarification question for @tomvothecoder re: post-run changing from dev to prod.

[forsyth2]

This is rendered here.

[chengzhuzhang]

Tested on Chrysalis. Two things:

1. diagnostics_archive should be pre-created by a maintainer. The inferred www has no username in it, so everyone publishes to the same tree — and whoever runs zppy first creates it at mode 0755 and locks everyone else out. I've set it up on Chrysalis as group-writable + setgid, matching the parent diagnostic_output/:

BASE=/lcrc/group/e3sm/public_html/diagnostic_output/diagnostics_archive
mkdir -p "$BASE/development" "$BASE/production"
chgrp -R E3SM "$BASE"; chmod -R 2775 "$BASE"

Worth documenting that this is a one-time maintainer step.

2. Dry runs were writing to www — fixed in d0935cc. main() created <www>/<case>/ and copied provenance there before checking dry_run, so dry runs published into the shared archive. Now guarded; output is unaffected and all tests still pass.

[chengzhuzhang]

@tomvothecoder I have one test that created a dummy production run results under:/lcrc/group/e3sm/public_html/diagnostic_output/diagnostics_archive/production, let me know if this is sufficient for the simboard side test.

One enhancement I'm thinking is, we should leverage the case_group parameter from CIME, ideally if a case_group is present we should have this as a subfolder under /production. We can perhaps also infer this from a CIME file?

[chengzhuzhang]

I have confirmed that CASE_GROUP exist in env_case.xml, however never reaches provenance.*.settings, and zppy doesn't know about it either.

[chengzhuzhang]

@tomvothecoder — new commit 40ac3d1 adds case_group for SimBoard.

zppy now reads CASE_GROUP from env_case.xml into provenance and uses it as a level in the inferred path:

<web_portal_base_path>/diagnostics_archive/<simulation_type>/<case_group>/<case>/

Simulations without a CASE_GROUP publish directly under <simulation_type>/; users can set case_group in [default] instead.

There's a sample published on Chrysalis if you want to point SimBoard at something real:

/lcrc/group/e3sm/public_html/diagnostic_output/diagnostics_archive/production/
https://web.lcrc.anl.gov/public/e3sm/diagnostic_output/diagnostics_archive/production/

Currently one case (v3.LR/v3.LR.historical_0051/) with global_time_series output plus provenance.*.cfg/.settings. Note the .settings file is mode 0660, so it's readable on the filesystem but likely not over HTTP — worth checking which access path you need.

[tomvothecoder]

Thank you @chengzhuzhang. There are multiple timestamped provenance.*.cfg and provenance.*.settings in the v3.LR/v3.LR.historical_0051 directory. Does this indicate multiple zppy runs were performed on the same case, with the latest one overwriting the output of the previous one? Should we only keep one .cfg and .settings for the latest zppy run?

drwxr-sr-x 3 ac.zhang40 E3SM 4096 Aug  5 18:49 .
drwxr-sr-x 3 ac.zhang40 E3SM 4096 Aug  5 18:47 ..
drwxr-sr-x 3 ac.zhang40 E3SM 4096 Aug  5 18:49 global_time_series
-rw-r--r-- 1 ac.zhang40 E3SM 1274 Aug  5 18:47 provenance.20260805_234735_275469.cfg
-rw-rw---- 1 ac.zhang40 E3SM  229 Aug  5 18:47 provenance.20260805_234735_275469.settings
-rw-r--r-- 1 ac.zhang40 E3SM 1274 Aug  5 18:47 provenance.20260805_234749_729830.cfg
-rw-rw---- 1 ac.zhang40 E3SM  229 Aug  5 18:47 provenance.20260805_234749_729830.settings

[chengzhuzhang]

@tomvothecoder The time-stamped provenance files reflect multiple zppy runs. One common use case that cause multiple provenance file is when a simulation runner to extend the simulation end date and generate additional diagnostic figures. I was thinking about this use case as well. SimBoard should rely on the latest provenance file and, during each scan, select the most recently time-stamped file.

[tomvothecoder]

Hey @forsyth2 and @chengzhuzhang, I've identified and documented metadata/linkage issues that should be handled upstream by the model or by the case owner. I think we should limit how involved SimBoard and zppy is with correcting metadata and paths, otherwise the scope of both tools will expand too broadly.

Ryan, here is the new docs page on diagnostics that you should use to update the zppy SimBoard page in this PR. You can keep the existing technical details on zppy configuration, but might want to refer to the new troubleshooting section and information on how SimBoard handles diagnostic linkage. It aligns SimBoard guidance with zppy configuration and covers:

• configuring [simboard], simulation_type, and www -- with reference to zppy SimBoard page
• checklist before publishing to SimBoard
• publishing diagnostics and waiting for the scheduled scanner to create the case link
• development-to-production promotion -- already in zppy SimBoard page
• stable URL behavior, including what to do when output moves, is deleted, or links are missing or incorrect

[tomvothecoder]

@forsyth2 I think once you've aligned the docs this PR should be good to merge. Then I'll merge SimBoard PR #293.

[forsyth2]

I think once you've aligned the docs this PR should be good to merge

Hi @tomvothecoder, I had Claude update the zppy's user guide for SimBoard based on https://github.com/tomvothecoder/simboard/blob/diags/240-prov-scan/docs/user/diagnostics.md. I didn't change the developer guide.

Let me know if this new commit, 9f6415b, looks good to you. Thanks!

[tomvothecoder]

Hi @tomvothecoder, I had Claude update the zppy's user guide for SimBoard based on tomvothecoder/simboard@diags/240-prov-scan/docs/user/diagnostics.md. I didn't change the developer guide.

Let me know if this new commit, 9f6415b, looks good to you. Thanks!

Looks good to me. I think we can merge now. Thanks Ryan!