Fix compset option parsing and ESMF mesh docs

CrocoDash/case.py

@@ -218,9 +218,15 @@ def init_args_check(
         """Perform sanity checks on the input arguments to ensure they are valid and consistent."""
 
         if Path(caseroot).exists() and not override:
-            raise ValueError(f"Given caseroot {caseroot} already exists!")
+            raise ValueError(
+                f"Given caseroot {caseroot} already exists! "
+                "To overwrite it, use override=True."
+            )
         if Path(inputdir).exists() and not override:
-            raise ValueError(f"Given inputdir {inputdir} already exists!")
+            raise ValueError(
+                f"Given inputdir {inputdir} already exists! "
+                "To overwrite it, use override=True."
+            )
         if not isinstance(ocn_grid, Grid):
             raise TypeError("ocn_grid must be a Grid object.")
         if not isinstance(ocn_vgrid, VGrid):
@@ -261,7 +267,11 @@ def init_args_check(
                 "ocn_grid must have a name. Please set it using the 'name' attribute."
             )
         if ocn_grid.name in cime.domains["ocnice"] and not override:
-            raise ValueError(f"ocn_grid name {ocn_grid.name} is already in use.")
+            raise ValueError(
+                f"ocn_grid name '{ocn_grid.name}' is already registered in CESM's grid config. "
+                "This happens when a previous case with this grid was deleted without using override=True. "
+                "To recreate the case, use override=True."
+            )
         if not isinstance(ninst, int):
             raise TypeError("ninst must be an integer.")
         if machine is None:
@@ -754,7 +764,7 @@ def _configure_custom_compset(self, compset_lname: str):
         # Stage: Component Physics Options (i.e., modifiers for the physics, e.g. %JRA, %MARBL-BIO, etc.)
         if Stage.active().title.startswith("Component Options"):
             for comp_class, phys in components.items():
-                opt = phys.split("%")[1] if "%" in phys else None
+                opt = "%".join(phys.split("%")[1:]) if "%" in phys else None
                 if opt is not None:
                     cvars[f"COMP_{comp_class}_OPTION"].value = opt
                 else:
@@ -763,6 +773,12 @@ def _configure_custom_compset(self, compset_lname: str):
         # Confirm successful configuration of custom component set
         assert Stage.active().title == "2. Grid"
 
+        # VCG's Z3 solver cannot handle multi-select option values (e.g., "REGIONAL%MARBL-BIO")
+        # as assignment assertions, so only the first modifier was set above. Directly assign
+        # the full correct COMPSET_LNAME now that the options stage is complete and its
+        # options assertions have been cleared.
+        cvars["COMPSET_LNAME"].value = compset_lname
+
     def _configure_custom_grid(self, atm_grid_name, rof_grid_name):
         """Assign the custom grid variables for the case."""
 

docs/source/for_users/grids.md

@@ -1,3 +1,18 @@
 # Grid Stuff (Supergrid, Bathymetry, Vgrid)
 
-In CrocoDash, the first step is grid generation. CrocoDash directly wraps, with no modifications, mom6_bathy. Please pursue the [mom6_bathy documentation](https://ncar.github.io/mom6_bathy/) for all questions. There is no extra nuance to using CrocoDash grids, the only thing you need to is import the modules through CrocoDash. 
+In CrocoDash, the first step is grid generation. CrocoDash directly wraps, with no modifications, mom6_bathy. Please pursue the [mom6_bathy documentation](https://ncar.github.io/mom6_bathy/) for all questions. There is no extra nuance to using CrocoDash grids, the only thing you need to is import the modules through CrocoDash.
+
+## Editing Topography After Case Creation
+
+If you use the `TopoEditor` (or otherwise modify the topography file) **after** creating your CESM case, be aware that:
+
+- If your edits change the **land-sea mask**, the ESMF mesh file (used by CESM for domain decomposition and remapping) must be regenerated to match.
+- If you only change depths without changing the mask, regeneration is not necessary.
+
+To regenerate the ESMF mesh from an updated `Topo` object:
+
+```python
+topo.write_esmf_mesh(path_to_esmf_mesh_file)
+```
+
+The path to the ESMF mesh file for your case is stored as `case.esmf_mesh_path` after case creation, or you can find it in the case's input directory under `ocnice/ESMF_mesh_<gridname>_<id>.nc`.