{"action":"created","issue":{"url":"https://api.github.com/repos/StrikeNP/trac_test/issues/695","repository_url":"https://api.github.com/repos/StrikeNP/trac_test","labels_url":"https://api.github.com/repos/StrikeNP/trac_test/issues/695/labels{/name}","comments_url":"https://api.github.com/repos/StrikeNP/trac_test/issues/695/comments","events_url":"https://api.github.com/repos/StrikeNP/trac_test/issues/695/events","html_url":"https://github.com/StrikeNP/trac_test/issues/695","id":330468160,"node_id":"MDU6SXNzdWUzMzA0NjgxNjA=","number":695,"title":"Brian's Tracifesto on glorious hydrometeor and PDF notation and naming conventions (Trac #695)","user":{"login":"StrikeNP","id":2577059,"node_id":"MDQ6VXNlcjI1NzcwNTk=","avatar_url":"https://avatars0.githubusercontent.com/u/2577059?v=4","gravatar_id":"","url":"https://api.github.com/users/StrikeNP","html_url":"https://github.com/StrikeNP","followers_url":"https://api.github.com/users/StrikeNP/followers","following_url":"https://api.github.com/users/StrikeNP/following{/other_user}","gists_url":"https://api.github.com/users/StrikeNP/gists{/gist_id}","starred_url":"https://api.github.com/users/StrikeNP/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/StrikeNP/subscriptions","organizations_url":"https://api.github.com/users/StrikeNP/orgs","repos_url":"https://api.github.com/users/StrikeNP/repos","events_url":"https://api.github.com/users/StrikeNP/events{/privacy}","received_events_url":"https://api.github.com/users/StrikeNP/received_events","type":"User","site_admin":false},"labels":[{"id":958019852,"node_id":"MDU6TGFiZWw5NTgwMTk4NTI=","url":"https://api.github.com/repos/StrikeNP/trac_test/labels/Migrated%20from%20Trac","name":"Migrated from Trac","color":"FFFFFF","default":false},{"id":958174284,"node_id":"MDU6TGFiZWw5NTgxNzQyODQ=","url":"https://api.github.com/repos/StrikeNP/trac_test/labels/betlej@uwm.edu","name":"betlej@uwm.edu","color":"FFFFFF","default":false},{"id":958042830,"node_id":"MDU6TGFiZWw5NTgwNDI4MzA=","url":"https://api.github.com/repos/StrikeNP/trac_test/labels/clubb_src","name":"clubb_src","color":"FFFFFF","default":false},{"id":958042692,"node_id":"MDU6TGFiZWw5NTgwNDI2OTI=","url":"https://api.github.com/repos/StrikeNP/trac_test/labels/task","name":"task","color":"FFFFFF","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":53,"created_at":"2018-06-07T23:18:12Z","updated_at":"2018-06-09T23:39:46Z","closed_at":null,"author_association":"OWNER","body":"In advance of the software engineering meetings, I would like to issue my Tracifesto -- that's Trac manifesto -- describing goals and aims for hydrometeor/PDF variable naming conventions.  I have a lot of things to write, so I wanted to put all this stuff somewhere.\n\nI hereby propose that all hydrometeor species variables be named with two letters universally.  The first letter denotes the type of quantity -- either mixing ratio, r, or concentration, N.  The second letter denotes the precipitation type -- r for rain, i for ice, s for snow, or g for graupel.  All in all, the following arise:\n\nrr -- rain water mixing ratio\nNr -- rain drop concentration\nri -- ice mixing ratio\nNi -- ice crystal concentration\nrs -- snow mixing ratio\nNs -- snow flake concentration\nrg -- graupel mixing ratio\nNg -- graupel concentration\n\nThe advantages of this system far, far outweight the disadvantages.  I will list those advantages now:\n\n1)  The notation used in this system is an exact match to the notation used in the math found in documentation and papers (in the math, the first letter, r or N, is standard size, and the second letter, which denotes precipitation type, is a subscript).  This makes it very easy for anyone to compare between a written math equation and the code.  This aids in debugging (determining the accuracy of the code when compared to the equation) and in the understandability of the code.\n\n2)  Issues have been made in the past about searchability of variable names.  At this point, I would like to make a statement about this naming convention and searchability -- the above variable names are not used completely by themselves in the code (for example, not as rr + ri + rs, etc.).  Rather, they are usually used as part of a larger variable name that indicates the type of quantity they are in the PDF.  In the context of the math found in the documentation and papers, the two-letter hydrometeor notation is a subscript.  For example, mu_rr_1 or sigma_Nr_2.  THESE VARIABLE NAMES ARE VERY UNIQUE AND SEARCHABLE.\n\n\n... but Brian, what about the overall means of hydrometeor variables ... those names would be only three characters each ... Nim, rsm, rgm, Ngm, etc.?\n\n\nTwo points about those:\n\na)  These variables, even at only three characters, would still be highly searchable.  After searching the code myself, I found that out of rrm, Nrm, rim, Nim, rsm, Nsm, rgm, and Ngm, the only variable that produces any searchability concerns at all is rim, which brings up every instances of the FORTRAN command \"trim\".  However, ...\n\nb)  These variables are ported around through most of CLUBB as part of the hydromet array.  They are referenced by array indices -- the ii... set of indices.  (As an aside, what does ```ii``` stand for -- integer index?  Regardless, it is a great notation for an index.)\n\nWith this proposed naming convention, the hydrometeor set of indices would be iirr, iiNr, iiri, iiNi, iirs, iiNs, iirg, and iiNg.  The associated names in the PDF set of indices would be iiPDF_rr, iiPDF_Nr, iiPDF_ri, iiPDF_ni, iiPDF_rs, iiPDF_Ns, iiPDF_rg, and iiPDF_Ng.  Again, each and every one of these names -- both hydrometeor indices and PDF indices -- are unique and searchable.\n\n\nThe bottom line of all of item (2) is that this naming convention will not produce searchability concerns.  I want to put that to rest right now.\n\n\n\nI also have numerous points to make about excessive length when using \"drawn-out\" variable names -- rgraupel instead of rg, etc.\n\n3)  Excessively long, drawn-out variable names are gangly and clumsy when trying to use them in a sizable math equation.  Excessively long names work against easily-discernable and eye-pleasing formatting of equations in the code.  I extremely dislike that.\n\n4)  A variable name and its description are listed together on a single line in the variable declaration section of any subroutine or function.  Both the variable names and the description must fit within a finite amount of characters on any given line.  Extremely long, drawn-out variable names make that more difficult, especially when there are two hydrometeors in a variable name (in a correlation or covariance) for the excessively long, drawn-out names of both hydrometeors are found in both the variable name and in the description.\n\n5)  Despite my best efforts, some variable names need to be long even before the hydrometeor notation is added to it.  For example, the namelist variables that denoted variance-over-mean-squared values, rgraupelp2_on_rgraupelm2_cloud, etc., needed to be changed because the variance-over-mean-squared values are now in-precip, in-component values with the introduction of the new PDF, and the \"p2\" and \"m\" variable names denote overall variances and means, respectively.  I needed to change these namelist variables to ```_sigma2_on_mu2_ip_cloud``` and ```_sigma2_on_mu2_ip_below```.  When I tried to use ```rgraupelm_sigma2_on_mu2_ip_cloud```, etc., I found it was over the FORTRAN character limit.  I needed to use ```rg_sigma2_on_mu2_ip_cloud``` to fit within the character limit, which is long and disgusting enough as it is.\n\n6)  GrADS Plotting.  Regardless of the length of the statistical output variable name, the full thing is written to the netCDF output file or the GrADS control output (*.ctl) file.  However, when a GrADS output file is opened in GrADS, only the first 15 characters of the stat variable name can be referenced.  For example, the variable ```CRIKEY_HES_A_NAUGHTY_ONE``` would be found if you opened the GrADS ```*.ctl``` file with ```less```, but when you actually open the file in GrADS, only ```CRIKEY_HES_A_NA``` would be found -- and the GrADS prompt will only respond to that many characters.\n\nHow is this an issue?  Well, first let's look at stats output using the glorious method of notating hydrometeors:\n\n\n```text\nsigma_rg_1_n\nsigma_rg_2_n\ncorr_rgNg_1_n\ncorr_rgNg_2_n\n```\n\nThe sigma terms come in at 12 characters and the correlations come in at 13 characters.  Now let's look at the same stats output using puke-and-vomit notation:\n\n\n```text\nsigma_rgraupel_1_n\nsigma_rgraupel_2_n\ncorr_rgraupelNgraupel_1_n\ncorr_rgraupelNgraupel_2_n\n```\n\nThe sigma terms comes in at a horrid 18 characters and the correlations come in at a disgusting 25 characters.  Worse, lets look at what it looks like in GrADS:\n\n\n```text\nsigma_rgraupel_\nsigma_rgraupel_\ncorr_rgraupelNg\ncorr_rgraupelNg\n```\n\nBoth stats are exactly the same for both sigma terms and corr terms!  This is a recipe for disaster.\n\n7)  Excessively-long hydrometeor variable names are a result of commie filth!\n\n\n\nNow, the issue has been brought up about saturation mixing ratio because we will be using rs for snow mixing ratio.  We should use ```rsat``` or ```r_sat``` for saturation mixing ratio to alleviate any confusion.\n\n\nNow, that leaves us with two poorly-named variables in CLUBB's PDF.  These names were not originally thought of by us, but rather by some guy named Mellor.  These variables are s and t.  These two variables are the coordinates used after the PDF of rt and theta-l are transformed into s and t coordinates.  However, there are a number of problems with Mellor's notation.  Number one, t is used in meteorology to denote time.  It is simply what meteorologists think of when they see the variable t.  The other issue that has been brought up is that Mellor's s should be renamed to distinguish it from snow.\n\nI also have a problem with ```s_mellor``` and ```t_mellor```.  That problem is that the s and t that we are using in CLUBB are not s and t from Mellor!  The equations used in the PDF transformation in Mellor are not the ones used in CLUBB.  You could not look at Mellor (1977) and find those equations in CLUBB code.  Rather, the equations in CLUBB are from the improved form of the PDF transformation listed in Larson et al. 2001.\n\nSo, after all of this, we are left with the current code with s and t notation and variables like:\n\n```corr_st_1```\n\n(Is this variable ready for canonization?)\n\nNor do we want the excessively long, gangly, and incorrectly-named ```s_mellor``` and ```t_mellor``` used everywhere.\n\nI have a much better solution that satisfies all our concerns -- the Greek letter solution.\n\nThe PDF transformation from rt and theta-l coordinates would be written in something like chi and eta coordinates, where chi and eta would replace s and t, respectively.  This satisfies many issues -- (1) the symbols chi and eta can be used in the documentation and math and also in the code.  The math will match the code.  (2) there will be absolutely no problem searching the variable names chi and eta.  (3)  They are not excessively long, gangly, and nasty.  They will not mess with the formatting in equations in the code.  They will not take up too much line space in variable lists.  They will not violate the GrADS character limit.  (4)  They do not conflict with any other CLUBB variable.\n\n\nAttachments:\n\n\nMigrated from http://carson.math.uwm.edu/trac/clubb/ticket/695\n```json\n{\n    \"status\": \"closed\", \n    \"changetime\": \"2014-08-28T17:28:25\", \n    \"description\": \"In advance of the software engineering meetings, I would like to issue my Tracifesto -- that's Trac manifesto -- describing goals and aims for hydrometeor/PDF variable naming conventions.  I have a lot of things to write, so I wanted to put all this stuff somewhere.\\n\\nI hereby propose that all hydrometeor species variables be named with two letters universally.  The first letter denotes the type of quantity -- either mixing ratio, r, or concentration, N.  The second letter denotes the precipitation type -- r for rain, i for ice, s for snow, or g for graupel.  All in all, the following arise:\\n\\nrr -- rain water mixing ratio\\nNr -- rain drop concentration\\nri -- ice mixing ratio\\nNi -- ice crystal concentration\\nrs -- snow mixing ratio\\nNs -- snow flake concentration\\nrg -- graupel mixing ratio\\nNg -- graupel concentration\\n\\nThe advantages of this system far, far outweight the disadvantages.  I will list those advantages now:\\n\\n1)  The notation used in this system is an exact match to the notation used in the math found in documentation and papers (in the math, the first letter, r or N, is standard size, and the second letter, which denotes precipitation type, is a subscript).  This makes it very easy for anyone to compare between a written math equation and the code.  This aids in debugging (determining the accuracy of the code when compared to the equation) and in the understandability of the code.\\n\\n2)  Issues have been made in the past about searchability of variable names.  At this point, I would like to make a statement about this naming convention and searchability -- the above variable names are not used completely by themselves in the code (for example, not as rr + ri + rs, etc.).  Rather, they are usually used as part of a larger variable name that indicates the type of quantity they are in the PDF.  In the context of the math found in the documentation and papers, the two-letter hydrometeor notation is a subscript.  For example, mu_rr_1 or sigma_Nr_2.  THESE VARIABLE NAMES ARE VERY UNIQUE AND SEARCHABLE.\\n\\n\\n... but Brian, what about the overall means of hydrometeor variables ... those names would be only three characters each ... Nim, rsm, rgm, Ngm, etc.?\\n\\n\\nTwo points about those:\\n\\na)  These variables, even at only three characters, would still be highly searchable.  After searching the code myself, I found that out of rrm, Nrm, rim, Nim, rsm, Nsm, rgm, and Ngm, the only variable that produces any searchability concerns at all is rim, which brings up every instances of the FORTRAN command \\\"trim\\\".  However, ...\\n\\nb)  These variables are ported around through most of CLUBB as part of the hydromet array.  They are referenced by array indices -- the ii... set of indices.  (As an aside, what does {{{ii}}} stand for -- integer index?  Regardless, it is a great notation for an index.)\\n\\nWith this proposed naming convention, the hydrometeor set of indices would be iirr, iiNr, iiri, iiNi, iirs, iiNs, iirg, and iiNg.  The associated names in the PDF set of indices would be iiPDF_rr, iiPDF_Nr, iiPDF_ri, iiPDF_ni, iiPDF_rs, iiPDF_Ns, iiPDF_rg, and iiPDF_Ng.  Again, each and every one of these names -- both hydrometeor indices and PDF indices -- are unique and searchable.\\n\\n\\nThe bottom line of all of item (2) is that this naming convention will not produce searchability concerns.  I want to put that to rest right now.\\n\\n\\n\\nI also have numerous points to make about excessive length when using \\\"drawn-out\\\" variable names -- rgraupel instead of rg, etc.\\n\\n3)  Excessively long, drawn-out variable names are gangly and clumsy when trying to use them in a sizable math equation.  Excessively long names work against easily-discernable and eye-pleasing formatting of equations in the code.  I extremely dislike that.\\n\\n4)  A variable name and its description are listed together on a single line in the variable declaration section of any subroutine or function.  Both the variable names and the description must fit within a finite amount of characters on any given line.  Extremely long, drawn-out variable names make that more difficult, especially when there are two hydrometeors in a variable name (in a correlation or covariance) for the excessively long, drawn-out names of both hydrometeors are found in both the variable name and in the description.\\n\\n5)  Despite my best efforts, some variable names need to be long even before the hydrometeor notation is added to it.  For example, the namelist variables that denoted variance-over-mean-squared values, rgraupelp2_on_rgraupelm2_cloud, etc., needed to be changed because the variance-over-mean-squared values are now in-precip, in-component values with the introduction of the new PDF, and the \\\"p2\\\" and \\\"m\\\" variable names denote overall variances and means, respectively.  I needed to change these namelist variables to {{{_sigma2_on_mu2_ip_cloud}}} and {{{_sigma2_on_mu2_ip_below}}}.  When I tried to use {{{rgraupelm_sigma2_on_mu2_ip_cloud}}}, etc., I found it was over the FORTRAN character limit.  I needed to use {{{rg_sigma2_on_mu2_ip_cloud}}} to fit within the character limit, which is long and disgusting enough as it is.\\n\\n6)  GrADS Plotting.  Regardless of the length of the statistical output variable name, the full thing is written to the netCDF output file or the GrADS control output (*.ctl) file.  However, when a GrADS output file is opened in GrADS, only the first 15 characters of the stat variable name can be referenced.  For example, the variable {{{CRIKEY_HES_A_NAUGHTY_ONE}}} would be found if you opened the GrADS {{{*.ctl}}} file with {{{less}}}, but when you actually open the file in GrADS, only {{{CRIKEY_HES_A_NA}}} would be found -- and the GrADS prompt will only respond to that many characters.\\n\\nHow is this an issue?  Well, first let's look at stats output using the glorious method of notating hydrometeors:\\n\\n{{{\\nsigma_rg_1_n\\nsigma_rg_2_n\\ncorr_rgNg_1_n\\ncorr_rgNg_2_n\\n}}}\\n\\nThe sigma terms come in at 12 characters and the correlations come in at 13 characters.  Now let's look at the same stats output using puke-and-vomit notation:\\n\\n{{{\\nsigma_rgraupel_1_n\\nsigma_rgraupel_2_n\\ncorr_rgraupelNgraupel_1_n\\ncorr_rgraupelNgraupel_2_n\\n}}}\\n\\nThe sigma terms comes in at a horrid 18 characters and the correlations come in at a disgusting 25 characters.  Worse, lets look at what it looks like in GrADS:\\n\\n{{{\\nsigma_rgraupel_\\nsigma_rgraupel_\\ncorr_rgraupelNg\\ncorr_rgraupelNg\\n}}}\\n\\nBoth stats are exactly the same for both sigma terms and corr terms!  This is a recipe for disaster.\\n\\n7)  Excessively-long hydrometeor variable names are a result of commie filth!\\n\\n\\n\\nNow, the issue has been brought up about saturation mixing ratio because we will be using rs for snow mixing ratio.  We should use {{{rsat}}} or {{{r_sat}}} for saturation mixing ratio to alleviate any confusion.\\n\\n\\nNow, that leaves us with two poorly-named variables in CLUBB's PDF.  These names were not originally thought of by us, but rather by some guy named Mellor.  These variables are s and t.  These two variables are the coordinates used after the PDF of rt and theta-l are transformed into s and t coordinates.  However, there are a number of problems with Mellor's notation.  Number one, t is used in meteorology to denote time.  It is simply what meteorologists think of when they see the variable t.  The other issue that has been brought up is that Mellor's s should be renamed to distinguish it from snow.\\n\\nI also have a problem with {{{s_mellor}}} and {{{t_mellor}}}.  That problem is that the s and t that we are using in CLUBB are not s and t from Mellor!  The equations used in the PDF transformation in Mellor are not the ones used in CLUBB.  You could not look at Mellor (1977) and find those equations in CLUBB code.  Rather, the equations in CLUBB are from the improved form of the PDF transformation listed in Larson et al. 2001.\\n\\nSo, after all of this, we are left with the current code with s and t notation and variables like:\\n\\n{{{corr_st_1}}}\\n\\n(Is this variable ready for canonization?)\\n\\nNor do we want the excessively long, gangly, and incorrectly-named {{{s_mellor}}} and {{{t_mellor}}} used everywhere.\\n\\nI have a much better solution that satisfies all our concerns -- the Greek letter solution.\\n\\nThe PDF transformation from rt and theta-l coordinates would be written in something like chi and eta coordinates, where chi and eta would replace s and t, respectively.  This satisfies many issues -- (1) the symbols chi and eta can be used in the documentation and math and also in the code.  The math will match the code.  (2) there will be absolutely no problem searching the variable names chi and eta.  (3)  They are not excessively long, gangly, and nasty.  They will not mess with the formatting in equations in the code.  They will not take up too much line space in variable lists.  They will not violate the GrADS character limit.  (4)  They do not conflict with any other CLUBB variable.\\n\", \n    \"reporter\": \"bmg2@uwm.edu\", \n    \"cc\": \"vlarson@uwm.edu\", \n    \"resolution\": \"Verified by V. Larson\", \n    \"_ts\": \"1409246905370877\", \n    \"component\": \"clubb_src\", \n    \"summary\": \"Brian's Tracifesto on glorious hydrometeor and PDF notation and naming conventions\", \n    \"priority\": \"major\", \n    \"keywords\": \"hydrometeor PDF notation\", \n    \"time\": \"2014-06-10T05:28:38\", \n    \"milestone\": \"\", \n    \"owner\": \"betlej@uwm.edu\", \n    \"type\": \"task\"\n}\n```\n"},"comment":{"url":"https://api.github.com/repos/StrikeNP/trac_test/issues/comments/396006495","html_url":"https://github.com/StrikeNP/trac_test/issues/695#issuecomment-396006495","issue_url":"https://api.github.com/repos/StrikeNP/trac_test/issues/695","id":396006495,"node_id":"MDEyOklzc3VlQ29tbWVudDM5NjAwNjQ5NQ==","user":{"login":"StrikeNP","id":2577059,"node_id":"MDQ6VXNlcjI1NzcwNTk=","avatar_url":"https://avatars0.githubusercontent.com/u/2577059?v=4","gravatar_id":"","url":"https://api.github.com/users/StrikeNP","html_url":"https://github.com/StrikeNP","followers_url":"https://api.github.com/users/StrikeNP/followers","following_url":"https://api.github.com/users/StrikeNP/following{/other_user}","gists_url":"https://api.github.com/users/StrikeNP/gists{/gist_id}","starred_url":"https://api.github.com/users/StrikeNP/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/StrikeNP/subscriptions","organizations_url":"https://api.github.com/users/StrikeNP/orgs","repos_url":"https://api.github.com/users/StrikeNP/repos","events_url":"https://api.github.com/users/StrikeNP/events{/privacy}","received_events_url":"https://api.github.com/users/StrikeNP/received_events","type":"User","site_admin":false},"created_at":"2018-06-09T23:39:46Z","updated_at":"2018-06-09T23:39:46Z","author_association":"OWNER","body":"Trac update at 2014/07/15 at 23:19\n\nbmg2@uwm.edu commented:\n\nCommit comment from clubb:r7074:\n\nI updated KK_upscaled_means.F90 to use chi instead of s in correlation names and\nin descriptions.  I also updated all the correlation variables to place an\nunderscore \"_\" between the two variables involved in the correlation.\n\nThe GrADS output file results from this revision are an exact match to the GrADS\noutput file results from the previous revision for all cases.\n\nObligatory Larson Group Internal Trac System Reference: https://github.com/larson-group/clubb/issues/695.\n\n\n\n"}}
{"actor":{"display_login":"StrikeNP"}}