Add a table of physical constants to the user guide

[rkutteh]

CABLE

Description

Added a table of physical constants and a table of mathematical constants to the user guide. Additional tables of constants can be added following the same pattern.

Fixed missing/incorrect units in code and documentation.

It might be a good time at this stage to decide on the numerical value to use for the ice density: 910 from cable_soilparm.nml OR 921 from cable_phys_constants_mod.F90 ? Interestingly another well known code uses 917.

• New or updated documentation

---

📚 Documentation preview 📚: https://cable--326.org.readthedocs.build/en/326/

[ccarouge]

Not approving to prevent accidental merge until we settle on the density of ice value.

[ccarouge]

@har917 For the density of ice, should we take advantage of this PR to settle on one value? Here is what we have so far:

Source	Value	Comment
cable_soilparm.nml	910	Usually not used in offline but used in JaC
cable_phys_constants_mod.F90	921	Used for freeze/melt water balance calculations
UM value	917	Is used in ACCESS

Looking at Wikipedia, 917 kg/m3 is the closest value to the density of ice. And since we are going to use this value in ACCESS, it seems a good value to settle on.

One issue we have with offline CABLE is that the soil properties are given in the gridinfo file and their correctness depends on the file creator's checking. But we can at least make sure the values we provide in the code and the example namelist are agreed on.

[har917]

It would be a good idea I think - but I have no particular preference either way (as long as it's reasonable - there's a whole stack of processes that can cause variations to that value, what we need is consistency through the code base).

To add to the confusion - SLI uses 920. (GW seems to inherit the cable_phys_constants_mod value which is a relief).

On the ancillary issue - we are reading in soil type. Can't we - as part of @rkutteh issue - say 'where a land point has been determined to be of ice soil type - then set all the soil parameters to be that of ice as per the constants module'?

[ccarouge]

@har917 If you don't mind about the value, I would move to 917.

Can't we - as part of @rkutteh issue - say 'where a land point has been determined to be of ice soil type - then set all the soil parameters to be that of ice as per the constants module'?

Yes we can add that to #280

Can we deal with SLI later? It's already introducing its own set of numbers and there is more than the ice density that is different there.

[har917]

Can we deal with SLI later?

Absolutely yes - I only went there as I wanted to check on the other soil models (SLI and GW). Ensuring consistency with SLI constants will come up earlier than I suspect you think - since it's part of BIOS,

[rkutteh]

@har917 If you don't mind about the value, I would move to 917.

Can't we - as part of @rkutteh issue - say 'where a land point has been determined to be of ice soil type - then set all the soil parameters to be that of ice as per the constants module'?

That's what we have already put in there, as in:

         soil%rhosoil(k) = density_ice  
         soil%css(k) =     csice        

where density_ice and csice are from cable_phys_constants_mod.F90

@ccarouge @har917 are you happy then if I go ahead and set density_ice = 917 in cable_phys_constants_mod.F90 and soilin%rhosoil to 917 for 'Permanent ice' in cable_soilparm.nml ?

We need to be careful also about adjusting the numerical values of parameters like cs_rho_ice ! heat capacity * density ice

[ccarouge]

@rkutteh

That's what we have already put in there

No, it isn't. This only sets the values for "new" icy soils. The idea would be if the soil type is given as ice in one of the input file, then overwrite the associated parameter values read in the file with the ones in the physical constants. All of them, not just the new ones we create with the check on the veg type.

[ccarouge]

@rkutteh Please go ahead and update the density and cs_rho_ice values.

[rkutteh]

@rkutteh

That's what we have already put in there

No, it isn't. This only sets the values for "new" icy soils. The idea would be if the soil type is given as ice in one of the input file, then overwrite the associated parameter values read in the file with the ones in the physical constants. All of them, not just the new ones we create with the check on the veg type.

OK, that's easy...

[ccarouge]

@rkutteh Can you update the values here about ice density and specific heat for ice according to #332. Then, ask for review again.

[rkutteh]

@ccarouge The pull request #332 for setting the ice density and specific heat has been merged, so I am asking for another review for the present pull.

[ccarouge]

This is all good.

Testing

Using benchcab, we see identical results for both the fluxsite tests and the spatial configuration with this branch and the main branch. This seems to indicate no to minimal impact on the CABLE results in general.

[ccarouge]

The CI is failing because of a known issue. Let's wait a few days to see if this gets resolved before merging.