CrocoDash.shareable package

CrocoDash.shareable package#

Submodules#

CrocoDash.shareable.apply module#

CrocoDash.shareable.bundle module#

CrocoDash.shareable.fork module#

Module contents#

shareable — case portability across user boundaries.

Built on top of recipe.py, which handles programmatic case creation from YAML. This module adds the layer for sharing a configured case with another user:

Person A (sender)
CaseBundle(caseroot)
→ identifies what makes the case non-standard beyond a plain CrocoDash setup

(SourceMods, xmlchanges, extra XML files, user_nl tweaks)

→ bundle(output_dir) packages everything into a portable folder

Person B (recipient)
ForkBundle(bundle_dir)

→ guides the user through updating paths, machine, compset, and forcings → recreates the case via recipe.py → applies the captured non-standard CESM state

The bundle folder is the artifact that crosses the user boundary. duplicate_case() is a convenience for copying a case within the same user context.

class CrocoDash.shareable.BundleDifferences(xml_files_missing_in_new: list = <factory>, user_nl_missing_params: dict = <factory>, source_mods_missing_files: list = <factory>, xmlchanges_missing: list = <factory>)#

Bases: object

Non-standard CESM state in a case beyond what recipe.py would produce.

source_mods_missing_files: list#
user_nl_missing_params: dict#
xml_files_missing_in_new: list#
xmlchanges_missing: list#
class CrocoDash.shareable.CaseBundle(caseroot)#

Bases: object

Sender-side entry point for sharing a CrocoDash case.

Reads a live case and identifies everything that makes it non-standard beyond what recipe.py would produce by default: extra XML files, user_nl tweaks, SourceMods, and xmlchanges. Packages all of it into a portable bundle folder that can be handed off to another user.

Typical usage:

bundle = CaseBundle(caseroot)
bundle.identify_non_standard_case_info(cesmroot, machine, project)
bundle_path = bundle.bundle(output_dir)
# hand bundle_path to the recipient
bundle(output_folder_location, machine=None, project=None)#

Package this case into a portable bundle folder.

Runs identify_non_standard_case_info() automatically if not already called. The bundle contains the full recipe YAML, the non-standard diff, all ocnice input files, user_nl files, replay.sh, and any SourceMods or extra XML files.

diff(other_case)#

Return a BundleDifferences of what this case has that other_case does not.

duplicate_case(new_caseroot, new_inputdir, bundle_dir=None)#
get_user_nl_value(component, param)#
identify_non_standard_case_info(cesmroot, machine, project_number)#

Diff this case against a freshly created reference case to find what’s non-standard.

Uses recipe.py to spin up a temporary reference case with the same grid, topo, vgrid, and forcing configuration (configure_only=True, so forcings are not processed). Anything in this case that the reference case lacks is captured in self.non_standard_case_info as a BundleDifferences. Called automatically by bundle() if not already run.

class CrocoDash.shareable.ForkBundle(bundle_location)#

Bases: object

Recipient-side entry point for creating a case from a bundle.

Takes a bundle folder produced by CaseBundle and recreates the case for a new user or environment. Guides the recipient through updating destination paths, machine, and optionally the compset and forcing configuration interactively. Uses recipe.py to rebuild the case from the (possibly modified) YAML, then applies any non-standard CESM state that was captured at bundle time.

Typical usage:

fork = ForkBundle(bundle_dir)
case = fork.fork(
    cesmroot="/path/to/cesm",
    machine="derecho",
    project_number="PROJ123",
    new_caseroot="/path/to/new_case",
    new_inputdir="/path/to/new_inputdir",
)
apply_copy_plan()#
fork(cesmroot, machine, project_number, new_caseroot, new_inputdir, plan=None)#

Recreate the bundled case for a new user or environment.

Guides the recipient through an interactive YAML review — prompting for destination paths, machine, project, and optionally compset and forcing date range. Offers $EDITOR for deeper changes (e.g. swapping the compset or adjusting forcing kwargs). After confirmation, creates the case via recipe.py and applies the non-standard CESM state captured at bundle time.

Parameters:

  • cesmroot (str or Path) – CESM root on the recipient’s machine.

  • machine (str) – Machine name for the new case.

  • project_number (str) – Project/account number for the new case.

  • new_caseroot (str or Path) – Destination path for the new case root.

  • new_inputdir (str or Path) – Destination path for the new input directory.

  • plan (dict, optional) – Which non-standard CESM state to transfer, keyed by "xml_files", "user_nl", "source_mods", "xmlchanges". When omitted the recipient is asked interactively for each category.

CrocoDash.shareable.apply_xmlchanges_to_case(old_caseroot, xmlchangeparams)#
CrocoDash.shareable.ask_string(prompt: str, default='') → str#
CrocoDash.shareable.ask_yes_no(prompt: str, default=True) → bool#
CrocoDash.shareable.copy_source_mods_from_case(old_caseroot, new_caseroot, short_filepaths)#
CrocoDash.shareable.copy_user_nl_params_from_case(old_caseroot, usernlparams)#
CrocoDash.shareable.copy_xml_files_from_case(old_caseroot, new_caseroot, filenames)#
CrocoDash.shareable.duplicate_case(caseroot, new_caseroot, new_inputdir, bundle_dir=None)#

Copy a CrocoDash case to a new location within the same user context.

Reads machine, project, and cesmroot from the original case’s _crocodash_state.json, identifies any non-standard CESM state, recreates the case via recipe.py, and transfers the non-standard state to the new location. Pass bundle_dir to also save a portable bundle as a side effect.

Contents