Need CCPP scheme description metadata

[nusbaume]

As CCPP-ized physics and chemistry schemes are shared amongst host models, it may become important to include additional metadata somewhere in the scheme comments that can help users know the current development state and provenance of the scheme itself. So far we have come up with the following list of information that would be good to have for each scheme, if possible:

• The institution/lab that provided the scheme.
• A scheme reference URL (e.g. a DOI to a paper, or a URL to website documentation).
• A scheme description summary (e.g. a few sentences on what the scheme is doing and/or what is for).
• The last modification date.
• Contact person (e.g. name and email).

This is in no way an exhaustive list, and we can always separate "mandatory" versus "encouraged" metadata. If anyone has additional description metadata they would like to add, or have strong feelings on what should be required versus just recommended, then please feel free to add a comment here.

Hopefully this issue will be closed once all of the schemes that currently exist in this repo have been updated with at least the minimum set of description metadata that folks have decided should be mandatory.

[nusbaume]

Additional thoughts from the CAM-SIMA meeting this week:

• Would be good to have multiple points of contact (e.g. primary and secondary person), to protect against folks leaving the lab or field.
• Would be good to emphasize that DOIs, specifically for scientific documentation, are better than just a URL to a website (although that is better than nothing).
• It probably makes more sense for this info to live in the metadata files somewhere, as opposed to the source code itself. This might be particularly helpful if the framework starts doing its own documentation generation. However, will need to check with NOAA first.
• It would be beneficial to have a Github Action that either checks against the last modified date, or updates the date itself. That way we can prevent the last modified date info from going stale.
• Along with the date action, it might also be beneificial to have a "broken links" check that lets us know when a scheme description URL no longer works, and needs to be updated.

Finally, additional discussion from this meeting can be found here: https://docs.google.com/document/d/12LYYg05tlvrcSmQv6WZ-7a7jB598ekaY0d-j2WAJlTI/edit

[gold2718]

I think NOAA has all the metadata in the code, or at least documentation. For instance picking a random file from the CCPP Physics repo):

!> \ingroup NoahMP_LSM
!! \brief This subroutine is the main CCPP entry point for the NoahMP LSM.
!! \section arg_table_noahmpdrv_run Argument Table
!! \htmlinclude noahmpdrv_run.html
!!
!! \section general_noahmpdrv NoahMP Driver General Algorithm
!!  @{
!!    - Initialize CCPP error handling variables.
!!    - Set a flag to only continue with each grid cell if the fraction of land is non-zero.
...

[nusbaume]

Thanks @gold2718! Ligia pointed me to the official CCPP scheme documentation rules here:

https://ccpp-techdoc.readthedocs.io/en/latest/CompliantPhysicsParams.html#scientific-documentation-rules

It looks like, as you pointed out, that all of the metadata is within the source code itself, and uses doxygen. So for now we should probably adopt the same rules for our own schemes.

[mwaxmonsky]

In reference to the DOI/URL links to the source material, the NCAR library has resources available to generate DOI links to source material under certain constraints: https://library.ucar.edu/research/data-management/DOIs

I am not sure of the process but we can look into having the library generate DOI links for us if possible.

There is also the NCAR archives which archive NCAR owned domains so if a paper/poster/source document is internal, it should be pretty easy to get it added to the archives.

Lastly there is the OpenSky (https://opensky.ucar.edu/about) which lists preservation as a service it offers:

Preservation. OpenSky ensures long-term access to conference materials, reports, and other documents.

I'm not sure how feasible it would be but worst case scenario, it would be ideal if we could request the original authors of non-tracked materials if they could upload the material to OpenSky or similar service or we ask for their permission to do it on their behalf but I feel like this is going to be a much smaller use case in the grand scheme of things as most source material should be tracked by other services (journals, Zenodo, etc.).