Bringing CABLE standalone and CABLE in JULES into parity

[Whyborn]

There have been a number of changes to the CABLE files both here and in JULES in recent times. These need to be brought into parity before CABLE can be introduced as a library to UM13/JULES builds.

My conclusions after inspecting the differences between the respective code bases:

1. The files in JULES/src/cable_science should be updated with the files from this repository.
2. The rest of the files relating to initialisation and control should be set to the JULES versions i.e take the files from the JULES versions control/cable, control/casa, initialisation/cable and initialisation/casa, with potentially some exceptions:

• The CABLE version of control/cable/util/init/cbl_um_init_soilsnow.F90 contains a call to initialise_wetfac that doesn't exist in the JULES version- is this an intentional removal?
• The CABLE version of control/CABLE/CM3/cbl_cbm_mod.F90 includes some trad_corr correction factor which is applied to rad%trad in both the explicit and implicit routines, which doesn't exist in the JULES version. Is this correction important?

I didn't find any other scientifically meaningful differences. We will have to bring in the new Australian trees, but I don't understand what on earth is going on in coupled/AM3/control/cable/shared/cable_surface_types_mod.F90, nor why the PFT parameters are set up as in initialisation/cable_pft_params.F90 and not as namelist input.

I'm not sure who's most likely to know about the scientific differences @JhanSrbinovsky @har917?

[JhanSrbinovsky]

I have to rush for school drop off and then an appt- but I will try to follow this up later. From memory in AM3 - surface_types definitely are reading a namelist (thru rose-app.conf). PFT params may be read from cable_pft_params, I can remember if I ever got around to making this a namelist in AM3. In every other instance tho, I've set it up hard-wired in a file like this and they later become the default values until over-written. We could (perhaps should) initialize them as NaN and let the namelist give them a value.

[har917]

@Whyborn Quick response:

• the call to initialize_wetfac needs checking. It will relate to whether or not %wetfac is in the restart - so may even need to be inside a IF cable_runtime%ESM15 condition*.
• rad%trad definitely needed and AM3 should be the truth.

• ps I'm not sure how rigorously we're going to enforce backwards compatibility here - it could end up being awkward given the differences in what's in, what's not the different code bases.

[Whyborn]

I'm fairly sure we removed the cable_runtime%ESM15 condition from the code? And given this code would only be included in a future AM3 library build, we can just keep/remove the code depending on whether it's necessary for AM3.

And on the rad%trad- both versions of the code have this, but the CABLE version adds this trad_corr offset- see this in cbm_expl and this in cbm_impl. The JULES version does not have this trad_corr at all.

[JhanSrbinovsky]

Sorry - forgot about getting back to this. As above - param values are read thru file. I implemented the read thru namelist in ESM1.6 and offline (I think) but haven't here yet it seems. (Odd because I remember using the namelist written by rose-cylc as the namelist input to offline.) The cbm issue is troublesome. Since CMIP5 the version of cbm had to deviate from that offline uses. After CMIP6 and ENDGAME there was an additional explicit/implicit dependence. The within timestep model driver became very spaghettified. With ESM1.6 development happening as well I was stumbling on all the IF( conditions) and what was being reset through a timetep etc - trying to read through what was happening when. So I separated them. Going forward if we are to have separate expl/impl SUBRs or even UM specific versions - they probably don't need to be reconciled (OR even in) the CABLE:main repo. If we pull it altogether into one cbm it's going to be spaghetti again. It depends on the concensus I guess.

%wetfac is in the restart.

UM7:

atmosphere/land_surface/cable/cable_explicit_driver.F90:   cable_runtime%esm15= .TRUE.

so it is switched to true on the explicit pathway BUT doesn't seem to be switched off again. A worry, to be sure, but I think it is safe as roughness is only called on the explicit pathway here (and no L_new_soil_roughness)

science/roughness/cable_roughness.F90:IF(cable_runtime%um_radiation .OR. cable_runtime%esm15                         &

condition to execute LAI_eff and compute effective LAI remaining due to snow coverage (%vlaiw). Always runs for offline. In UM7.3 when esm15 switch is true - which it is on explicit step. BUT it is all wrong anyway, um_radiation is never true in roughness anyway. AM3 does need this on radiation step AND it is called directly from cable_land_albedo - so it is done. As it is %vlaiw is constant through a timestep, using the snow from the beginning of the step. Same as the other two. roughness isn't called in implicit im pretty sure, BUT there is a chance of calling it from canopy if the "new"_soil_roughness model is triggered - So maybe we can get rid of all of them?

science/soilsnow/cbl_surfbv.F90:    IF( .NOT. cable_runtime%UM  .OR. cable_runtime%esm15 ) THEN

sets the glacier model. Should be in the namelist anyway - kinda trivial. Lucky for the preceding oversight andNOT turning off the esm15 switch in explicit or this would not be triggered. NB - this was (esm15) in general a switch implemented to highlight the points in the code that marked where ESM1.5 behavior deviated unless esm15 = .TRUE. - but I do recall in this case there was a more dire situation here when ESM1.6 used another nglacier=?? To late to be testing this I suspect.

[JhanSrbinovsky]

BTW - AM3 needs to be updated from CABLE:main. There might be some AM3 developments we want to keep but I think all the esm15 switches in AM3 are meaningless? cos they are never true anyway

[Whyborn]

So the gist is that all the CABLE code within the JULES repo should be updated with the code from CABLE repo? Even the code in shared/AM3? There were a fair few updates to the JULES versions of the "infrastructure" code (control and initialisation) which looked important- addition of CNP working variables, soil respiration.

[har917]

@ccarouge @Whyborn @JhanSrbinovsky - short answer is that I suspect that most of the science differences should i) be checked and then (mostly) ii) CABLE repo versions adopted. The technical/infrastructure stuff should likely come from the NRI-JULES/AM3 repo since that had moved on to (hopefully) facilitate the CNP variables.

On this - can we be clear what the NRI-JULES repo is (at least in discussions). I keep getting confused as to what we're comparing to what (I think this issue is around the differences between the current NRI repo of JULES from which we build AM3, and the MAIN branch of CABLE-LSM/CABLE)

Equally - as part of this issue and probably next year - I think we should design/agree on the longer term structure of the CABLE-JULES connections. We haven't really discussed this since the 'panic' around code removal from MOSRS back in September. Particular questions:

• relationship with MOSRS-JULES - so what needs to be on the MOSRS-JULES repo? what form (do we need stubs etc.)? Both for the i/o routine but also the science interface layer.
• long term vision for i/o (notably input) - namelists, pft_loopuk.csv, relationship with the gridinfo file, modifications to UM/JULES diagnostic routines, STASH MASTER.
• obvious special cases where the connections need to be deeper (aerosols, orographic drag, dust, chemistry, deposition, rivers)
• link between the NRI-JULES repo, CABLE library and the build/run environment (for both general users [though possibly not that important since hopefully they'll use version controlled, pre-built exe's] and developers)

We may also need to think through what further changes need to go onto the MOSRS-JULES repo and on what timeline (and any rose-stem stuff to go with it).

[JhanSrbinovsky]

probably from cbm down into CABLE should be from the CABLE:main repo. There could be, but I cant think of any (especially not any that haven't already been dealt with), some updates that were made on the AM3 side. cbm up into JULES, what is in AM3 should be the ones to use. IDK how any others would be made whilst outside of AM3. The updates to allow for running AM3+CNP - these may not have gone back to the CABLE repo. The main part of it were from ages ago and so they are BUT prior to the workshop/creating the poster - there may have been some tweaks and I done remember back porting them to CABLE:main.

The science_cable/ directory is straight out of CABLE:main (well from xxx months ago anyway). We still have the same mapping in place where for e.g. util/ (in CABLE:main) maps onto util/cable/ (in NRI-JULES) etc

[Whyborn]

On this - can we be clear what the NRI-JULES repo is (at least in discussions). I keep getting confused as to what we're comparing to what (I think this issue is around the differences between the current NRI repo of JULES from which we build AM3, and the MAIN branch of CABLE-LSM/CABLE)

Whenever I mention the JULES repo, I mean the ACCESS-NRI/JULES repository, and CABLE is this repo CABLE-LSM/CABLE.

short answer is that I suspect that most of the science differences should i) be c. hecked and then (mostly) ii) CABLE repo versions adopted. The technical/infrastructure stuff should likely come from the NRI-JULES/AM3 repo since that had moved on to (hopefully) facilitate the CNP variables.

This is what I thought would be the case. There are just a couple of instances where the infrastructure code has additions in the CABLE repository and not the JULES repository that look important.

As for the longer term strategy, I'm not sure. I don't think the current structure of JULES is very conducive to a clean integration of CABLE. I know the JULES design doc says the intention was to keep the science modular to allow for simple substitution, but looking at the JULES code, I don't think they were very successful in that goal, especially when running with the UM.

[Whyborn]

The science_cable/ directory is straight out of CABLE:main (well from xxx months ago anyway). We still have the same mapping in place where for e.g. util/ (in CABLE:main) maps onto util/cable/ (in NRI-JULES) etc

None of the the ESM1.6 developments have made it in yet (at least on the default AM3-dev branch).

[JhanSrbinovsky]

Nah, but they are in main - so they should be picked up now right?

[Whyborn]

We don't use CABLE as a library for AM3 yet, just the code that's in the the ACCESS-NRI/JULES repository

[ccarouge]

It might also be useful to check when the files were last updated in each repository. For the most recent file, checking the history of changes might show if the divergent version in the other repository (either JULES or CABLE) is in fact an older version. And checking the history of the files would point us to the PR and issues and hence the reasoning for the change if we need it.

[JhanSrbinovsky]

I did keep them in sync for a while but I gave up somewhere along the way as ESM1.6 took precedence

We don't use CABLE as a library for AM3 yet, just the code that's in the the ACCESS-NRI/JULES repository

Yeah I know not yet - I mean after they're in sync.

[Whyborn]

Yea, but I want to sync the CABLE and JULES repos first so I have something that should be bitwise compatible to compare against when I try to bring in the library.