search

CABLE-LSM / CABLE

Home to the CABLE land surface model and its documentation
https://cable.readthedocs.io/en/latest/
Other
8 stars 4 forks source link

USER guide namelist descriptions #143

Open har917 opened 11 months ago

har917 commented 11 months ago

It is good that User guide has an overview of the various namelist options and their meanings - however one big list is not that useful. Could we reorder/split things up so it's easier to determine

tammasloughran commented 11 months ago

Yep, I had thought of doing something about this as I was working on the tables, but just focused on getting "some" documentation for everything, at least to start with. Therefore, there is no special order or organisation yet.

Regarding the optional vs. mandatory namelist variables: if a variable has a default value then it is optional. There are many that are uninitialised, which would potentially cause an error if they are left that way. Someone will have to track down and check each uninitialised namelist variable to find out if it is optional or not. Some are mandatory depending on the configuration. e.g. casafile namelist variables would not be needed when not runnning with CASA. How can this be made clear?

Regarding I/O: it's a good category to group together. the filename%, output%, casafile%, and gswpfile% are obvious ones. But there are some directories in the cable_user% namelist variables that are not so obvious.

Regarding science options: maybe the namelist variables relating to certain subcomponents of cable could be grouped together first, then specific science options?

It's not clear to me what the purpose of the cable_user type is (or kbl_user_switches). It just seems like a random collection of namelist variables. Maybe someone could explain this and document it at the next docathon? https://cable.readthedocs.io/en/latest/api/type/kbl_user_switches.html

ccarouge commented 10 months ago

It's not clear to me what the purpose of the cable_user type is (or kbl_user_switches). It just seems like a random collection of namelist variables. @tammasloughran from my understanding, I think you have got it right. I don't say it was the original intent though but I would say that is the current status.

ccarouge commented 10 months ago

@har917 I agree some ordering is in order. But as @tammasloughran pointed out, finding mutually exclusive categories is going to be tricky. First, I wouldn't put a required/optional category. But for each category, the required options should be listed first and then the optional.

Also, Jhan and I have often say we would like to split the namelist into several namelists. We're just not yet sure which namelists. I would suggest the categorisation we choose here would then be used to create several namelists. For example, we could have a CASA category.

JhanSrbinovsky commented 10 months ago

It's not clear to me what the purpose of the cable_user type is (or kbl_user_switches). It just seems like a random collection of namelist variables.

This is almost a legacy thing now. Originally, post ACCESS1.3, the merger of YP's v Eva's version of CABLE, I had runtime switches in place where we could use either cable_user=YP or able_user=Eva, and/or a series of switches for either. When we released CABLE2.0 we told people to put new things in on a switch. "How do I do that?" Would be the next question, so the answer became - just follow/add onto kbl_user. It was never intended to remain for this long, but there is only one of me. Since then we have started JAC, CMIP6, pushed SLI etc. Lauren left, Eva retired. Bernard retired, but he only ever helped YP really. He certainly didn't touch ACCESS - except the forcing thing. I organised getting the forcing, he put it into offline. Not that I have the time, but I still think we are in a much better position to re-visit this issue now. Especially now that we have ready access/understanding/experience with JULES standalone.

har917 commented 10 months ago

This all comes back to the broader question of 'what do we want the structure of CABLE to look like?'

cable_user is a useful method of passing all the various user switches around the code in one TYPE (rather than lots of USE statements or subroutine arguments) - but it isn't how JULES (and hence JAC) would need them to be managed.

I never really understood why we needed cable_user and kbl_user (and the other similar duplications) though.

JhanSrbinovsky commented 10 months ago

cable_user is an instantiation of TYPE kbl_user. My preference would be to have something like JULES does. That was always our intention BUT the reality was a little different. Imposing rules for developers to follow is difficult - thankfully it is gradually changing with the younger co-hort.

The Community aspect of C(omnnunity)ABLE has been .....challenging. Users/developers are still not using VCS as intended. It is hard enough to get them to commit, let alone merge etc, let alone push something back to the trunk, let alone jump through hoops to get there. Just look at what we have out there already POP, GW, SLI - branched from the trunk 5+ years ago, and operated independently ever since. The only reason SLI ever got to the trunk was I worked w Vanessa on a short term project to do just that. YP refused to join in until last year, and now he's gone. SLI was convoluted by not simply being a checkout from the trunk, but along the way Vanessa copied/pasted work from YP, ESM, etc. This is also what YP's code did. Sometimes he got the mods from Bernard or Chris who had subsequently got them into the trunk. So this messed everything up.

I can understand completely. Back in the day when I had a research career, each one of my papers mapped onto a model that I had written. I got points for the paper not the software elegance of the model, or prettiness of the code. Ideally there needs to be some sort of reward for community development, or even admonition for non-compliance. In my honours research we submitted a paper and the first response from the reviewer was why haven't you used the latest version of the model?