Determine how to handle user_nl_cism for multiple ice sheets

[billsacks]

I can see three options for supporting multiple ice sheets in user_nl_cism, and would like feedback on which method people prefer:

(1) Have multiple user_nl_cism files, like user_nl_cism_gris, user_nl_cism_ais, etc.

This feels relatively easy to use for the user. However, it would require changing some of the cime scripting to be aware of the multiple ice sheets. I think the relevant cime code is pretty limited, but this might be hard to do in a way that keeps cime compatible with e3sm and other modeling systems and keeps it easy to introduce new ice sheets (Laurentide, etc.) without changing cime.

I'd say on this: If people strongly prefer this approach, I can give some thought to how to implement it without tying cime too tightly with CISM, but if other alternatives seem about as good, then maybe we should drop this one to avoid the need for these cime changes.

(2) Have a single user_nl_cism file, with sections for the different ice sheets

I'm imagining something like:

[gris]
foo = value1
bar = value2

[ais]
foo = value3
baz = value4

possibly with an extra section for [all] that would apply to all ice sheets. We could then have a little code in CISM's python scripting that separates this file into temporary files for each ice sheet (containing that ice sheet's section and anything in the [all] section), with a check to confirm that nothing appears before the first section.

It would be easy to have the original user_nl_cism file that is staged in your case directory already have the necessary sections for all possible ice sheets (though I think it would be hard to make it smart enough to have only the section headings for the ice sheets you're running with – that gets back to the need to change cime). i.e., you would start with a file like:

[all]
! Settings that apply to all ice sheets go here

[gris]
! Settings that apply to Greenland (if present) go here

[ais]
! Settings that apply to Antarctica (if present) go here

A possible downside of this approach is that, if user_nl_cism gets long, I could see the potential for accidentally adding a setting in the wrong section.

(3) Have a single user_nl_cism file, with prefixes for each ice sheet.

I'm imagining something like:

gris: foo = value1
gris: bar = value2

ais: foo = value3
ais: baz = value4

The order wouldn't matter here: you could interleave gris and ais settings. As with (2), we could also support 'all'.

This requires more typing for the user than the other approaches, and it seems slightly less intuitive: they'd need to read a bit of documentation. But that documentation can appear in comments at the top of the file. An advantage relative to (2) is that it feels harder to make a mistake with this approach.

@whlipscomb @mvertens @gunterl @Katetc Do you have preferences between these, or ideas for a different approach?

[billsacks]

A variation on (2) and (3) is: Any variable that appears before the first ice sheet-specific section (for (2)) or without a prefix (for (3)) applies to all ice sheets. The advantages of this is that it is backwards compatible with existing user_nl_cism files and it keeps things simple for cases with a single ice sheet. A disadvantage is that it may be more error-prone: a user may accidentally have some setting apply to all ice sheets when they mean for it to just apply to one.

Another possibility would be to allow that usage when running with a single ice sheet, but not when running with multiple ice sheets. This avoids the above disadvantage, but results in some inconsistency between the single and multiple ice sheet cases that may be a bit confusing for users: sometimes it seems best to be consistent, even if that means that things are a little more complicated in the simple case.

[whlipscomb]

@billsacks - Thanks for thoughtfully laying out the possibilities. I'm leaning toward (2) with your suggested variation, that any variables appearing before the first ice-sheet-specific section will apply to all ice sheets. After that, there would be headings for each supported ice sheet: [gris], [ais], etc., under which users could add ice-sheet-specific settings under each heading. I like that this approach would be backward-compatible and would allow all changes to go in one namelist file.

Happy holidays!

[billsacks]

I just talked to @mvertens about this and she agrees with @whlipscomb 's comment above. (If it weren't for the backwards compatibility piece, she would prefer the explicit [all], but she likes the idea of keeping this backwards compatible.)

[billsacks]

Closing this discussion issue; opening an issue to actually do the work: https://github.com/ESMCI/cime/issues/3999

[jedwards4b]

I don't see the difficulty with (1) - most of the changes would be in the cism buildnml file and not in cime.

[whlipscomb]

One issue is that we'll eventually want to support multiple paleo ice sheets: Laurentide, Eurasian, Fennoscandian, and so on. In addition to Greenland (gris) and Antarctica (ais), we'd have to carry around other usernl* files for ice sheets that are irrelevant to most people running the model.

[billsacks]

To avoid having two separate threads, let's move this discussion to https://github.com/ESMCI/cime/issues/3999 so it gets more attention from CIME folks who may want to weigh in.

[billsacks]

For anyone interested in this issue: please see my latest comment in the CIME issue, https://github.com/ESMCI/cime/issues/3999#issuecomment-861902486, where I propose option (1) (following @jedwards4b 's suggestion) after all, if people are happy with that.