clarify expanded shortwave radiation band descriptions

[eclare108213]

Copied and slightly edited from E3SM-Project#42 (comment)

      fswthrun_uvrdr, & !   > 700nm vis uvr dir sw radiation through ice bot (W/m**2)
      fswthrun_uvrdf, & !   > 700nm vis uvr dif sw radiation through ice bot (W/m**2)
      fswthrun_pardr, & ! 400-700nm vis par dir sw radiation through ice bot (W/m**2)
      fswthrun_pardf, & ! 400-700nm vis par dif sw radiation through ice bot (W/m**2)

@proteanplanet
The abbreviated commenting of fswthrun_uvrdr, fswthrun_uvrdf, fswthrun_pardr, and fswthrun_pardf needs to be expanded here. ">700nm vis uvr" appears to be an oxymoron, and I could not find a clear language explanation of "400-700nm vis par".

@eclare108213
The expanded definitions are in the documentation, https://cice-consortium-icepack.readthedocs.io/en/main/appendices/icepack_index.html

fswthru_pardf | visible photosynthetically active shortwave diffuse radiation 400-700nm penetrating to ocean
fswthru_pardr | visible photosynthetically active shortwave direct radiation 400-700nm penetrating to ocean
fswthru_uvrdf | visible ultraviolet shortwave diffuse radiation > 700nm penetrating to ocean 
fswthru_uvrdr | visible ultraviolet shortwave direct radiation > 700nm penetrating to ocean

These changes came in with #518, where the PR header info says

Add 4 new shortwave terms, uvrdr, uvrdf, pardr, pardf to the coupling. These terms represent a breakdown of the direct and diffuse visible shortwave terms into two components, par = photosynthetical active radiation (400-700nm) and uvr = rest of the visible shortwave term (>700nm). The current visible shortwave is exactly represented by these two components. Includes adding atm forcing and terms associated with radiation passthru to the ocean.

So it sounds like uvr is the part of the visible spectrum that is not par... but the word 'ultraviolet' does not make sense with 'visible', I agree. Perhaps these would be better described something like "red side" and "blue side" of the visible spectrum?

@zhaobin74, please clarify what you mean by "vis uvr" and "vis par". Thank you.

[zhaobin74]

@eclare108213, sorry for the mistakes in the description. I think the uvr is indeed ultraviolet band and par is 400-700nm. The vis is misleading. Please correct them by removing references to vis.

[eclare108213]

Following up on @zhaobin74's question in #549 about whether specific values need to be stated in the code:

There are assumptions in icepack's shortwave code (delta Eddington especially) about the wavelength bands, e.g.

! Divides solar spectrum into 3 intervals: 0.2-0.7, 0.7-1.19, and
! 1.19-5.0 micro-meters. The latter two are added (using an assumed
! partition of incident shortwave in the 0.7-5.0 micro-meter band between
! the 0.7-1.19 and 1.19-5.0 micro-meter band) to give the final output
! of 0.2-0.7 visible and 0.7-5.0 near-infrared albedos and fluxes.

The important value in the dEdd context is 700 nm, and the comments generally indicate < 700 nm as 'visible' and > 700 nm as 'infrared'. Now, as noted in #518, the < 700 nm band can be divided into PAR (400-700 nm) and ultraviolet (< 400 nm) for the GEOS model. The comments in the code stating 'visible ... < 700 nm' imply a lower bound and so may be even more confusing with a uv band now available for special cases.

[zhaobin74]

Following up on @zhaobin74's question in #549 about whether specific values need to be stated in the code:

There are assumptions in icepack's shortwave code (delta Eddington especially) about the wavelength bands, e.g.

! Divides solar spectrum into 3 intervals: 0.2-0.7, 0.7-1.19, and
! 1.19-5.0 micro-meters. The latter two are added (using an assumed
! partition of incident shortwave in the 0.7-5.0 micro-meter band between
! the 0.7-1.19 and 1.19-5.0 micro-meter band) to give the final output
! of 0.2-0.7 visible and 0.7-5.0 near-infrared albedos and fluxes.

The important value in the dEdd context is 700 nm, and the comments generally indicate < 700 nm as 'visible' and > 700 nm as 'infrared'. Now, as noted in #518, the < 700 nm band can be divided into PAR (400-700 nm) and ultraviolet (< 400 nm) for the GEOS model. The comments in the code stating 'visible ... < 700 nm' imply a lower bound and so may be even more confusing with a uv band now available for special cases.

@eclare108213, it looks like the visible (0.2-0.7) reference already exists in CICE code? So the only confusion part is the uv band (0.2-0.4) is counted as visible which is counterintuitive. Maybe a cleaning up in DEdd is also warranted?

[eclare108213]

@eclare108213, it looks like the visible (0.2-0.7) reference already exists in CICE code? So the only confusion part is the uv band (0.2-0.4) is counted as visible which is counterintuitive. Maybe a cleaning up in DEdd is also warranted?

Yes. This is made even more confusing because dEdd generally computes in 3 bands as stated above in the code comments, and now for snow there's an option for 5 bands. The two bands broadly labeled 'visible' and 'infrared' are (or were originally) for input fields. I'm thinking we need a new section in the documentation that distinguishes the input forcing from the bands used in the rest of the calculation and also explains the band breakdown for various options. I will not try to do that in the current PR and will leave this issue open for further work.

[eclare108213]

I made a stab at it, without getting into the weeds. How does this look? (in icepack documentation)

Two methods for computing albedo and shortwave fluxes are available, the
"CCSM3" method and a multiple scattering radiative transfer scheme that
uses a Delta-Eddington approach. Shortwave forcing input is generally
divided into two wavelength bands (< 700 nm, visible and below) and
(> 700 nm, infrared), with an additional capability to accept
shortwave divided into ultraviolet (< 400 nm) and visible /
photosynthetically active (400 - 700 nm) bands.
Radiation calculations may occur in the original two bands
or for up to five bands, as described below.

[zhaobin74]

I made a stab at it, without getting into the weeds. How does this look? (in icepack documentation)

Two methods for computing albedo and shortwave fluxes are available, the
"CCSM3" method and a multiple scattering radiative transfer scheme that
uses a Delta-Eddington approach. Shortwave forcing input is generally
divided into two wavelength bands (< 700 nm, visible and below) and
(> 700 nm, infrared), with an additional capability to accept
shortwave divided into ultraviolet (< 400 nm) and visible /
photosynthetically active (400 - 700 nm) bands.
Radiation calculations may occur in the original two bands
or for up to five bands, as described below.

@eclare108213, I think this looks great. Thanks.