documentation for user controls on logging needs updating (edited title)

[XiulinGao]

I want to turn on logging when running FATES API 37 (sci.1.80.11_api.37.0.0). Model build failed with error message indicating I have to turn on use_cn = .true. I then went to the CTSM bld folder, found that the CLMBuildNamelist.pm file is different from the earlier version that they removed use_fates condition check when set up harvest. I added that condition check back. The model was able to build and run but I don't see any logging mortality, so I suspect that logging was ever really activated. I'm wondering :

1. Why the use_fates condition check is removed on CLM side for doing harvest.
2. With the newer version, is the way we activate logging in FATES changed?

related, in FATES user guide, it's said to turn on logging we need to set the namelist parameter use_fates_logging to true, which is not correct at least up till API 31 (not sure about API 32-36). I'm wondering if the change in CLMBuildNamelist.pm is related to that the way we activate logging in fates now has changed.

[XiulinGao]

ok, after searching through CTSM code, I figured out the answer and solution. The way how we should activate logging now changed to the following:

1. set fates_harvest_mode = 'flanduse_timesiries'
2. define flanduse_timesiries file in user_nl_clm

there are also other fates harvest mode, see here for the namelist definition: https://github.com/ESCOMP/CTSM/blob/c2a8c6c0dc75a7dee3f9546a6b5d335bf1cd84a1/bld/namelist_files/namelist_definition_ctsm.xml#L772-L780

I think we need to update fates user guide regarding this change.

[rgknox]

@XiulinGao can you confirm that there the issues are not with the code itself, and that what is needed is better documentation (in the code and in the user guide)?

Or do I have that wrong?

[XiulinGao]

@rgknox you are correct. There needs a correct documentation (the current documentation is wrong not just outdated) for how we should turn on logging for the recent version of FATES and then how that is done differently for the older version in user guides (and maybe also in the code) assuming folks might be using an older version of FATES.

[glemieux]

FYI, #63 on the user's guide repo is intended to address this deficiency in the documentation. It's been low priority and on the back burner.

I'm going to transfer this issue to that repo so we can track it there.