Quick list for POD developers

[bitterbark]

In order to develop a quick list for POD developers, here are my notes of the process I went through to create a POD called blocking_rneale. My suggestion is to have this checklist with links to the relevant sections in the extended documentation. Comments/edits on what I got wrong/ best practices// what is missing encouraged.

1. Where to put code/what to name things

• mkdir diagnostics/blocking_rneale , which will be the name of the pod
• copy code into above
• copy diagnostics/example/settings.jsocn to blocking_rneale
• copy diagnostics/Wheeler_Kiladis/Wheeler_Kiladis.py to blocking_rneale/blocking_rneale.py
  (example isn't good for me because it is all python. I just want to call ncl!)
• added pod to ncl-using list in src/install.py
  d.pods = ["Wheeler_Kiladis", "EOF_500hPa", "MJO_suite", "MJO_teleconnection","blocking_rneale"]
• Add pod name in input file (copy default_tests.jsonc to new file, which I called input_dani.jsonc)

2. Settings file and environment variables
   Edit the settings file with the variables to use:

• Variable name: the short-name can be whatever, will result in an env var
  setting of that followed by _var (eg varlis zg500 makes available env var: zg500_var)

• The longer "standard_name will be used to match" this up to the model variable names in the netcdf files data/fieldlist_$model.jsonc.
  eg. diagnostic/blocking_rneale/settings.jsonc
  "varlist" : {
  "zg500": {
  "standard_name" : "geopotential_height_500mb",

• If the field isn't already in data/fieldlist_$model.jsonc, add it there using the standard_name. (Note I made mine up but the important thing for the framework is that it is the same in fieldlist and settings).

• The location of model data (Note that the model input data is *re-written into the WK_DIR/freq now)
  is saved into an env var named in the pod settings file:
  "path_variable" : "WHATEVER_YOU_WANT_TO_CALL_IT",
  where what you call it is the env var used by your code
  and the framework will set this env var for you
  eg. "path_variable" : "MODEL_DATA_PATH",

• $POD_HOME env var for loading local script (only NCL)
  eg. load $POD_HOME/other_file.ncl

• list of the names of env vars that the pod can use could use clarification as to DATADIR and WK_DIR (since my WK_DIR and output dir are usually the same, I don't make a good distinction and I think I should be)
  https://mdtf-diagnostics.readthedocs.io/en/latest/sphinx/dev_guidelines.html#5.4

3. Output

• POD should write figures to these locations:

  • postscript files to: DATADIR/{model,obs}/PS
  • png (other?)files to: DATADIR/{model,obs}/
    Postscript files in the PS dir will be automatically converted to png in the dir direction above

• The POD/POD.html file needs to be edited to link to the resulting png files:
  the example html file looks for output files. Change the names in html!
  ERROR: POD blocking_neale has missing output files:
  blocking_neale/model/example_model_plot.png
  blocking_neale/obs/example_obs_plot.png

[ahmedfiaz]

Hi @bitterbark, this is a nice and concise list for newcomers. In terms of addition: a bullet 0 with Git-based workflow (fork from MDTF repo, clone to local directory, branch, push etc.) would be useful as well, since that really is the first step for POD developers.

Tagging @cmartinezvil who had some more specific feedback on this.

[wrongkindofdoctor]

@bitterbark Thanks, Dani. This is a very useful guide that will help us all to create a formal "cheat-sheet" to supplement the main documentation.

Re # 2 about modifying the fieldlist, @tsjackson-noaa has stated that updating field lists is the responsibility of the framework team, meaning that POD developers who need new variables in the field lists should submit issues requesting them. Once we add the variables and merge the updated fieldlists into the develop branch, users can pull in the updates and continue with POD development.

However, I am not opposed to developers including fieldlist modifications with POD PRs if they are comfortable doing so, and want to expedite the process, since they are required for the PODs to run to begin with.

[cmartinezvil]

Thank you Fiaz!

…

On Mon, May 24, 2021 at 2:23 PM Fiaz Ahmed ***@***.***> wrote: Hi @bitterbark <https://github.com/bitterbark>, this is a nice and concise list for newcomers. In terms of addition: a bullet 0 with Git-based workflow (fork from MDTF repo, clone to local directory, branch, push etc.) would be useful as well, since that really is the first step for POD developers. Tagging @cmartinezvil <https://github.com/cmartinezvil> who had some more specific feedback on this. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#228 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AL4TO6PFT6HNRQXRTOK2HYTTPKKSBANCNFSM45NVH2CQ> .

-- Cristian Martinez-Villalobos, PhD Postdoctoral Researcher Centro de Estudios Avanzados en Zonas Áridas http://www.ceaza.cl/team_member/dr-cristian-martinez-villalobos/ https://cristianmartinezvillalobos.com

[wrongkindofdoctor]

@bitterbark @ahmedfiaz @cmartinezvil I have submitted the draft PR #230 that includes a summary of @bitterbark's relevant suggestions. Note that some of the information is excluded such as the requirement to define a "path_variable" in the POD settings file (this is an optional setting), and the need to modify the POD list in src/install.py (POD developers should never have to modify any of the framework src files for functionality). The main docs will be updated accordingly. Feel free to leave comments in the PR discussion regarding changes or additions that you would like to include in the cheatsheet.