Documentation updates for release

[hertneky]

This PR update the documentation for the community release 10.0.12. Highlight include:

• updated instructions for building UPP (Update documentation to reflect building with hpc-stack #475)
• updates to the introduction and code overview sections
• added new unified variables table and removed app-specific tables

[hertneky]

@fossell The UG can be viewed at this link

[fossell]

@WenMeng-NOAA, @HuiyaChuang-NOAA - Tracy put together a nice table to be included in the Users Guide for upcoming releases that documents the unified model variables that go into INITPOST_NETCDF. This PR has a number of changes to the UG content, but I wanted to have you take a quick look that this new section 3.1.1. Model Forecast and the associated table of variables too. Once committed, I think this will be helpful for developers to reference, and hopefully keep up to date with it documented in one place in the repo.

[WenMeng-NOAA]

@hertneky @fossell Great job! That's what I have been looking for UPP user support. Two suggestions might be:

1. column 2: Change "UPP INITPOST Name" as "UPP Internal Name"?
2. "Model output name" stand for variable name in netcdf file?
3. Add a new column for variables from model output file "dyn(atm)" or "phy(sfc)". This could be done in the future.
   Thanks for your efforts!

[fossell]

@camshe - this PR contains updates and link to view updated documentation for the release.

[hertneky]

@WenMeng-NOAA Thanks for the review of the table. I've updated it based on your recommendations.

[HuiyaChuang-NOAA]

@WenMeng-NOAA, @HuiyaChuang-NOAA - Tracy put together a nice table to be included in the Users Guide for upcoming releases that documents the unified model variables that go into INITPOST_NETCDF. This PR has a number of changes to the UG content, but I wanted to have you take a quick look that this new section 3.1.1. Model Forecast and the associated table of variables too. Once committed, I think this will be helpful for developers to reference, and hopefully keep up to date with it documented in one place in the repo.

@hertneky @fossell
thank you for the effort. I did a quick review of document and have a few minor comments:
. Regarding the following statement under 3.1.1, I believe the current develop only supports parallel netCDF
The UPP ingests FV3 write component files in netCDF and parallel netCDF format.
. I really like the UFS variable table you made and the connection between model output and UPP output. This
will be very helpful to users. A few comments:
a) for dpres and delz, suggest describing them as layer thickness in pressure and in height respectively. As for the UPP
internal name for delz, I would just indicate "na".
b) for surface pressure, indicate it's pint(:,:,LM+1); then similarly for surface height
c) I think sh2o, smc, and stc should be labeled as 3D

[WenMeng-NOAA]

c) I think sh2o, smc, and stc should be labeled as 3D
@HuiyaChuang-NOAA The model output sha2o at 4 levels as 4 2D variables. They had the discussion of outputting as 3D variable but seems not implemented yet.

[WenMeng-NOAA]

b) for surface pressure, indicate it's pint(:,:,LM+1); then similarly for surface height
Good catching. This reminder me that we made the changes in UPP to calculate surface pressure from top to bottom with pint. So it might be better to remove the surface pressure row.

[hertneky]

@WenMeng-NOAA @HuiyaChuang-NOAA Thanks for the comments.
a. fixed both
b. removed sfc pres - thanks - I missed that it was actually computed further down
c. good point -they are 2d from the model output, but read into a 3d array in UPP. I changed to 2d>3d, but could settle on one or the other if desired.

@fossell Based on Huyia's comment about FV3 only being read in using parallel netcdf, should we remove "netcdf" option from the run_upp script?

[fossell]

@WenMeng-NOAA @HuiyaChuang-NOAA Thanks for the comments. a. fixed both b. removed sfc pres - thanks - I missed that it was actually computed further down c. good point -they are 2d from the model output, but read into a 3d array in UPP. I changed to 2d>3d, but could settle on one or the other if desired.

@fossell Based on Huyia's comment about FV3 only being read in using parallel netcdf, should we remove "netcdf" option from the run_upp script?

@hertneky - This is my misunderstanding, I apologize for that. Yes, we should additionally update the run_upp script. I'll coordinate with you and @kayeekayee to get these mods taken care of.

[fossell]

@hertneky - Good catch on the version number of seeing that there is a tag for v10.0.12 already. I had only checked release names, and failed to check the tags, that's my oversight.

@WenMeng-NOAA - We'll need to update the version number for release/public-v3 and for use when we create a upp release tag. v10.0.13 would be fine, but since 10.0.12 tag you made in March, there was also the unifying of regional and global fv3 interfaces, which could warrant a bigger version change. Thoughts?

[WenMeng-NOAA]

@fossell I would consider about v10.1.0 for release/public-v3, then hot fixes for v10.1.1, v10.1.2, ...?
For develop branch, we would bump up VERSION to 10.0.13 before 2D decomposition merging. After merging, VERSION will be 11.0.0, and 11.0.1, 11.0.2, ... for future changes until a new release branch is created?

[fossell]

@fossell I would consider about v10.1.0 for release/public-v3, then hot fixes for v10.1.1, v10.1.2, ...? For develop branch, we would bump up VERSION to 10.0.13 before 2D decomposition merging. After merging, VERSION will be 11.0.0, and 11.0.1, 11.0.2, ... for future changes until a new release branch is created?

@WenMeng-NOAA - It seems a little counterintuitive to me to have the release branch seemingly more ahead of develop, e.g. 10.1.0 > 10.0.13. But I understand the dilemma of having two branches incrementing 10.0.xx potentially at the same time. I'm not sure I have a good solution, we could bump develop to 10.2.0 to reflect the release branch breaking off of develop (and release branch would be 10.1.0 and increment from there)? But if that causes problems on your end, that's ok. We can go with your original proposal.

[WenMeng-NOAA]

@fossell I agree with your solution. The release/public-v3 bump to 10.1.0, and develop bump to 10.2.0.

[fossell]

@WenMeng-NOAA - sounds good, we'll proceed with that and I'll submit PRs for the version updates.

[fossell]

@hertneky - please note we've agreed to have release/public-v3 be version 10.1.0. You can update documentation in appropriate places accordingly. Thanks again for catching this!

[WenMeng-NOAA]

@fossell and @hertneky Thanks for working on upp version tracking.

[hertneky]

@fossell @WenMeng-NOAA I updated the inFormat throughout and the version to 10.1.0 for release/public-v3 - thanks!