Cn matrix

[chrislxj]

Description of changes

1. Add matrix module for vegetation and soil C and N cycle
2. Add diagnostic variables C and N storage capacity in history files
3. Add Sparse matrix module to increase the code efficiency
4. Create spin-up switch, and be ready for matrix spin up development

Specific notes

Contributors other than yourself, if any:
Yuanyuan Huang, Zhenggang Du, Yiqi Luo

CTSM Issues Fixed (include github issue #):
Unknown

Are answers expected to change (and if so in what way)?
Answers should be generally the same but slightly changes. The slight changes of the answer is due to C pool size updating order change. Eg. Default model updates vegetation C pool size in three steps: 1) X = X + I + AphKph * X; 2) X = X + AgmKgm X; 3) X = X + AfiKfi X. The matrix model updates C pool size all at once: X = X + I + (AphKph + AgmKgm + AfiKfi) X. Because the AK*X is smaller than X by several magnitude at each time step, the difference in most cases are small.

Any User Interface Changes (namelist or namelist defaults changes)?
We added four switches:

1. use_matrixcn ! control if we use vegetation matrix to update vegetation C and N cycle
2. use_soil_matrixcn ! control if we use soil matrix to update soil C and N cycle
3. isspinup ! control if we use semi-analytical spin-up to accelerate C and N spin up. isspinup can be true only when both use_matrixcn and use_soilmatrixcn are true. This has not been tested in this version, while Zhenggang is working on it.
4. is_outmatrix ! control if we want to output diagnostic variables into history files. is_outmatrix can be true only when both use_matrixcn and use_soilmatrixcn are true.

Testing performed, if any:
(List what testing you did to show your changes worked as expected)
Scientific tests running global 4x5 resolution (f45_g37), history simulation (IHistClm50Bgc) for 150 years including 2 resubmits at every 50 years.
Results from default code (four switches .false.) and matrix code (use_matrxcn, use_soil_matrixcn and is_outmatrix are all .true., isspinup is .false.) do not show significant difference.

(This can be manual testing or running of the different test suites)
Differences between default code and matrix code are manually tested.

(Documentation on system testing is here: https://github.com/ESCOMP/ctsm/wiki/System-Testing-Guide)
We have used create_test for system testing.
(aux_clm on cheyenne for gnu/pgi and hobart for gnu/pgi/nag is the standard for tags on master)
We used create_test with aux_clm. the cime folder is detached from cime5.7.5

NOTE: Be sure to check your Coding style against the standard:
https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines

[billsacks]

Thanks a lot for this contribution.

Looking at the diffs here, it looks like something went wrong at some point in the git history, which introduced a bunch of differences that shouldn't be here. @chrislxj this isn't necessarily something that you did wrong. @ekluzek and I should sit down and try to figure it out (assuming that Erik has a decent sense of the history of this branch... I'm at a bit of a loss as to what happened here, and I think I need to talk to someone who can describe the history of this branch in git).

[ekluzek]

@chrislxj I think the important thing for you to do for us here, is to tell us what you branched this from? Assuming for example that you did the typical

git checkout -b cn-matrix

What was the that you started from?

I also realize that you might have branched from a previous branch, and if so we'll want to know about the whole history of the branching (as well as you can describe it).

We'll also be doing git log commands to figure it out as best we can.

[olyson]

I'm curious as to which files have changed that you don't think should have changed? FYI, there was an update to ctsm1.0.dev016 in November of last year.

[billsacks]

@olyson if you click on the "Files" tab, I think you'll see the issue. For example, the contents of manage_externals have been moved up to the top level here.

[ekluzek]

@olysion and @chrislxj when you look at the "files changed" in this PR there are a bunch of top level files (like the LICENSE file, and files under manic directory) that I don't think were intentionally changed. The first file that I think was intentionally changed is:

src/biogeochem/CNAnnualUpdateMod.F90

My guess is that everything before that didn't intentionally get changed.

[ekluzek]

There's also some files at the end (under under the "test/repos" directory for example) that I don't think are intentional. Everything in the middle of that I think is. There's also a list of files that are listed as "no changes" which I find odd, but I suppose that's not really a problem.

[olyson]

I wonder if my commit was the problem somehow:

chrislxj@2a29eec

For instance I see the checkout_externals file in the top directory whereas it wasn't there in the prior commit.

[olyson]

I think that in that commit I made, everything in the manage_externals directory got copied up one directory (e.g., checkout_externals). For a sub-directory that had the same name (i.e., test), everything in the manage_externals/test directory got copied into the top-level test directory. So I think that if the duplicate files were deleted things would be fixed unless there is also another problem.

[billsacks]

@olyson no, I'm pretty sure the problems existed before your merge. e.g., in chrislxj@88033e2cd (the commit on this branch before your merge).

[chrislxj]

Sorry, I missed these messages, since they sent to my gmail, which is blocked in China. Now I changed it to my Chinese email.

I have reviewed what you said.
First, the branch on the GitHub is originally migrated from svn last year (Feb, 22nd, 2018). Ben Andre helped us migrate the branch. Then we use following commands to checkout the branch, following Ben's tips:

1. Create a fork of ctsm:
2. Clone fork to the local machine:
3. Fetch the branch to the machine
   • on local dir
     • cd ctsm
   • Add Ben's fork to the clone as a 'remote'
     • git remote add bandre https://github.com/bandre-ucar/ctsm.git
   • Fetch the branches from Ben's fork:
     • git fetch bandre
   • Checkout the branch:
     • git checkout cn-matrix

Second, I may have tried to roll back some changes. But I don't remember exactly what changes and what time. Mistakes could also happen at that stages.

Third, 3 months ago, Keith updated to ctsm1.0.dev016 and pushed it to the repository.

This is the best I can remember for the one-year old repository on github. I noticed the early history Bill pointed out was from one year ago. It means those changes are most probably from Ben's help to migrate our branch from svn.

Under file_changes, I may only intentionally edit F90 files. I have no idea about those top level files.

[chrislxj]

I read the history. Could these commits be problem? (54f9823, c001ae3, 2255f78, e4af51f). I thought I was trying to keep the version up to date like what we did on svn.

[billsacks]

@chrislxj - @negin513 and I have fixed the git history issue, I think. I have created a new branch on my fork (https://github.com/billsacks/ctsm/tree/cn-matrix_v3). Negin and I created this branch by going through the history of your branch and just keeping the correct commits. The first commit on this branch is equivalent to the import from svn (note that there's only one git commit for all of the work that happened in svn, because this made the branch recreation easier), and then the other commits are what we thought were the valid git commits from your original branch.

Compared with master, this new branch only has changes in src/. It looked to me like the only intentional changes on your branch were in src/, so I think this result is correct, but please confirm this. I have diffed the src/ directory in this new branch with your original branch, and they are identical except for permissions (mode) changes that you accidentally committed on your branch.

Please proceed as follows:

First, checkout my new branch:

git remote add billsacks https://github.com/billsacks/ctsm.git
git fetch billsacks
git checkout -b cn-matrix_v3 billsacks/cn-matrix_v3

Then explore this a bit to make sure you're happy with this. For example:

git log master..cn-matrix_v3

to see the logs, or

git diff cn-matrix  cn-matrix_v3 -- src

to confirm that there are no differences in the src directory other than permissions (mode) changes.

Once you're happy with this, you can push it up to your fork. If your remote is named chrislxj, for example, you would do:

git push -u chrislxj cn-matrix_v3

Then please go to your fork on GitHub and open a new pull request from that branch into master, copying the comments that you have in your initial comment in this pull request.

Just for information: Some of the problems on your original branch were the following. I'm saying these not to be critical (I have made plenty of mistakes in git myself!), but just to help you avoid similar issues in the future:

1. There were some oddities with the initial svn import (this was a problem on our end, not yours)

2. There were some problems with the early rebases / merges on this branch (which may have been partly because of (1))

3. At some point, case directories were added. While you did remove these later, it can bloat the repository's history to have so many extra added things, even if they're removed later. For the future: it's perfectly fine to make some small changes which you revert later, but if you accidentally add a bunch of files, or even a single large file, this commit should be completely removed from history rather than simply reverted. In the future, please feel free to contact us as soon as you notice something like this, and we can help you fix it if you aren't sure how to do so. The sooner this is caught and fixed correctly, the easier it is to fix.

4. At some point, permissions (file modes) were changed on all files in src and src_clm40: all files were accidentally given execute permissions.

All of these issues have been fixed in the new branch.

[chrislxj]

Thank you Bill @billsacks and Negin @negin513 for your work. The changes should be only in src. I have checked everything, only file permission is different with the original code under src dir. Now I created another PR "Cn matrix v3" with the new code.

Sorry for the mistakes I made. I learned this time.

[billsacks]

Thanks a lot, @chrislxj , and really: don't worry about the mistakes in the original branch: we're happy to help people with git issues like this.

I'm closing this PR, since it has now been replaced by #640 .