Remove "v5" references in doc

[duvivier]

@JFLemieux73 found a few places in the documentation where we reference Version 5 or V5. We need to search through and find anywhere else. Known issues in:

https://cice-consortium-cice.readthedocs.io/en/master/user_guide/ug_implementation.html#restart-files

https://cice-consortium-cice.readthedocs.io/en/master/user_guide/ug_troubleshooting.html#restarttrouble

[eclare108213]

We are still using the v5 restart files, so some references might be okay.

[duvivier]

Yes, but we need to go through carefully and be sure. And in some places, we can probably modify the wording to say "for CICE version 5 and later" or something like that to be inclusive of this release.

[eclare108213]

I've read through the first couple of sections (pdf). There is a lot of duplication with the Icepack docs, and I think we should just refer to the Icepack docs - see notes below. I remember now that we didn't finish that job when we released Icepack! We should also compare the Icepack and CICE namelist input and find the variables that are different, so we can highlight them in the CICE documentation. This is a partial list of suggested changes - I'll work on the implementation section next.

boldface means do this for Icepack documentation too

It looks like many of the code variables are not in the correct font. Should we fix them or use some other font, or not use a special font for them at all? Some are italic, which is wrong. See the last paragraph of section 1.1. We use math font (looks like italic to me) for mathematical symbols, italic for subroutine names, and typewritten for variable names in the code, including namelist flags. This seems to be messed up throughout the documentation.

fix all links to oceans11.lanl.gov

contents: make section 2.2 title ‘sea ice model components’ sections 4.2, 4.3, 4.5 remove ‘Implementation’

section 1.1 second paragraph, “… along with snowfall and melt ponds; …” add space after period: “… strain. External…” and let’s change that sentence: “When coupled with other earth system model components, routines external to the CICE model prepare and execute data exchanges with an external “flux coupler.” “

remove sections 1.2.1 and 1.2.2, but make sure the info is included somewhere else in the docs. Let's rewrite section 1.2.2 and move it to section 1.1:

The standard standalone CICE test configuration uses a 3 degree grid with atmospheric data from 1997, available as detailed on the wiki. A 1 degree configuration and data are also available, along with some idealized problems. The data files are designed only for testing the code, not for use in production runs or as observational data. Please do not publish results based on these data sets.

The CICE model can run serially or in parallel, and the CICE software package includes tests for various configurations. MPI is used for message passing between processors, and OpenMP threading is available.

section 1.3 Did we remove the first sentence, "This model release is CICE version 6.0.0.alpha." ?

section 1.3.1 replace with updated info (I will provide a summary, and let’s link to the release info for these lists)

section 1.4 I think we should remove all of the individuals' names, and say "Special thanks are due to participants from these institutions and many other who contributed to previous versions of CICE or Icepack."

section 1.5 remove the hyphen from the last sentence

section 1.6 (do this also for both CICE and Icepack everywhere in wikis, code, etc) replace "Los Alamos National Security" with "Triad National Security" and change the contract number to 89233218CNA000001

section 2.1 - Dave, Tony, Andrew, others with knowledge of the coupling please read and correct this as needed. Remove /bf from 'to' in table 1 A quick comparison of table 1 in Icepack and CICE docs - I think only Delta H_o is different. Maybe we should add that to the Icepack table and refer the CICE documentation to it, rather than duplicating the table in both places?

remove the last paragraph of the section 2.1 intro

section 2.1.1, 2.1.2 remove these sections and refer to Icepack, but make sure that the stand-alone forcing information (around eqns 2.8-2.10) is kept somewhere. We also need to keep the paragraph around eqn 2.11 in the CICE doc.

After equation 2.8, make a new paragraph starting at "The downwelling longwave formula of [62] is also available in function longwave_parkinson_washington:"

At the end of the previous paragraph, add "The merged ice-ocean temperature in this formula creates a feedback between longwave radiation and sea ice surface temperature which is unrealistic, resulting in erroneous model sensitivities to radiative changes, e.g. other emissivity values, when run in stand-alone model. Athough our stand-alone test configurations are useful for model development purposes, we strongly recommend that scientific conclusions be drawn using the model only when coupled with other earth system components."

remove 2.1.3

section 2.2 - keep the first 2 paragraphs and the rest of the section after table 2, starting with “In addition to the fractional ice area…”, refer to Icepack for ice thickness distribution details.

Let’s keep all of the 2.2.1 intro, and refer to Icepack for “Tracers that depend on other tracers” and following text. Remove all of the subsections, starting with “Ice age”

section 2.2.2, 2.2.3 - keep!

2.2.4 remove this entire section We need to make sure that there’s a note in the horizontal transport section saying that the ridging mechanism is used to clean up the ice thickness distribution after horizontal transport.

[eclare108213]

Icepack needs a ‘citing the code’ section as in the CICE documentation (1.5)

2.2 instead of ‘model components’ maybe make sections for momentum, stress and horizontal transport

section 4 remove ‘implementation’ from the section titles

I didn’t read sections 3 very carefully, since it looks like they’ve been kept up to date with changes in the scripts, etc., and I didn't get very far into section 4 tonight.

The font convention is very inconsistent in these sections, especially \bf

comp_ice still appears in a number of places and needs to be changed to whatever is appropriate, probably either cice.settings or ice_in?

Also, we should capitalize Icepack whenever we refer to the software package or its modules, but in the code, directory and filenames with 'icepack' are not capitalized.

section 3.1 second paragraph - I think the link should be to Icepack, not CICE

section 3.1.1 - change icepack to cice

section 3.1.2, 3rd paragraph:
remove “, including that used for the column configuration” change “These are binary unformatted, direct access files produced on an SGI (Big Endian). If you are using an incompatible (Little Endian) architecture, choose rectangular instead of displaced_pole in ice_in, or follow procedures as for conejo (⟨OS⟩.⟨SITE⟩.⟨machine⟩ = Linux.LANL.conejo). There are versions of the gx3 grid files available.” to “These are binary unformatted, direct access, Big Endian files.”

Replace the Bio-grid and Column configurations sections with:

Vertical grids

The sea ice physics described in a single column or grid cell is contained in the Icepack submodule, which can be run independently of the CICE model. Icepack includes a vertical grid for the physics and a “bio-grid” for biogeochemistry, described in [section 3.1.2 of the Icepack documentation]. History variables available for column output are ice and snow temperature, Tinz and Tsnz. These variables also include thickness category as a fourth dimension.

In the Performance subsection: “Timings illustrates the CICE version 5 computational expense …”

section 3.1.3 correct spelling: routiines

section 3.1.4 Change “As discussed in section Mechanical redistribution and [51]” to “As discussed in [51]”

section 3.1.5, first paragraph: “… depending on the output file format chosen in ice_in. The netCDF history files are…” (It looks like the special LaTeX command to typeset ‘netCDF’ isn’t working in the paragraph and elsewhere in the docs, e.g. the ‘restart files’ subsection and section 3.5.2.)

remove “With this release,” at the beginning of the second paragraph.

Last paragraph, change “In this version of CICE,” to “Beginning with CICE v6.0,”

second to last paragraph of section 3.1.5: Change the first sentence to “Two restart files are included with the CICE v5 and v6 code distributions, for the gx3 and gx1 grids. They were created using the default v5 model configuration (settings as in comp_ice and ice_in), but initialized with no ice.”

Remove the last paragraph of section 3.1.5

I didn’t check section 3.2 carefully against a test code setup

In the first bullet after “Some hints:”, remove “tracer numbers or”

This doesn’t make sense - please correct: “The version should be some like n.m.p.string.”

First line under Examples at the end of section 3.2.1, change tense to “configuration”

section 3.3 remove /bf from “The testing scripts support several features” in the first bullet, add space in test)or

Section 3.3.3 first paragraph, capitalize Consortium (2nd instance) and remove the 3rd instance. Add to the end of this paragraph: “This can be accomplished by posted the full results to the wiki, or by copying the testing summary to the PR comments.”

section 3.3.5 This says that the timeseries.csh script works for CICE, but it refers to the Icepack diagnostic files rather than CICE’s. We need to check that it works and correct the text here appropriately.

There’s a quotation mark imbalance in the namelist table around solve_zsal

I think the bgc tuning parameter table should be removed from CICE and a reference to Icepack added. There are a lot of other Icepack parameters in this table. Maybe we should make a list of Icepack parameters (everything that has init/query/write status), refer the user to Icepack docs for those, and keep just the CICE-specific ones here???

section 3.5.2 regarding restarting from v4.1 restart files, I’d keep the paragraph that begins “Provided that the same number of ice layers…” and delete the following bullets. The final sentence could be “To convert a v4.1 restart file, consult section *** in the CICE v5 documentation [link].” Probably the driver has changed…

@apcraig, do we still have an option to set MPI barriers? See the second paragraph of section 3.5.3. We need to change comp_ice here to something else… cice.settings?

Section 3.5.6, second paragraph - @dbailey10 is this still true in the code? “With the Delta-Eddington parameterization, the albedo depends on the cosine of the zenith angle (cos 𝜙, coszen) and is zero if the sun is below the horizon (cos 𝜙 < 0). Therefore time-averaged albedo fields would be low if a diurnal solar cycle is used, because zero values would be included in the average for half of each 24-hour period. To rectify this, a separate counter is used for the averaging that is incremented only when cos 𝜙 > 0. The albedos will still be zero in the dark, polar winter hemisphere.”

section 4.1, second bullet, change ‘so’ to ‘no’. In the next sentence: “CICE must call into Icepack using…”

Section 4.2.2 spell Dynamic instead of Dyamic change “and before” to “and earlier” change “and above” to “and later versions”

more later…

[duvivier]

@eclare108213 I have worked through the first set of comments. Below are any comments or questions I had. If I did not comment, it just means I completed that task as requested. Here is the current read the docs build with those changes: https://cice.readthedocs.io/en/latest/index.html

One major thing to mention. At a number of places I removed the sections you suggested and referenced the Icepack documentation, including a link to the read-the-docs section of the master documentation. I'm not a huge fan of this because if we change something in the Icepack documentation structure, etc. it will all break. Because they are separate documents it isn't possible to have internal links. Alternately, I could link to the "release" version of Icepack once we release that before CICE. However, I will still need to go in manually and change each one of those links. Please let me know what you think about what I have and we can modify from there.

It looks like many of the code variables are not in the correct font. Should we fix them or use some other font, or not use a special font for them at all? Some are italic, which is wrong. See the last paragraph of section 1.1. We use math font (looks like italic to me) for mathematical symbols, italic for subroutine names, and typewritten for variable names in the code, including namelist flags. This seems to be messed up throughout the documentation.

I will try to hit this again at the end of everything

fix all links to oceans11.lanl.gov

I only found this one place (user's guide) and have fixed it. Please let me know if you see elsewhere (grep is not picking up any other instances).

remove sections 1.2.1 and 1.2.2, but make sure the info is included somewhere else in the docs.

Most of the info about the scripts/porting was already in the user guide/ug_running.rst documentation, so I've removed section 1.2.1.

section 1.3.1 replace with updated info (I will provide a summary, and let’s link to the release info for these lists)

I'm waiting on the updated info from you to add here. We do run into a catch 22 though where if we wanted to provide a link to the release docs and such, we don't have a link yet. and once we create the tag/release we'd have to additionally update the documentation to add the link. Maybe I can think of how to do this or we just generally link to the tags and notes?

section 1.4 I think we should remove all of the individuals' names, and say "Special thanks are due to participants from these institutions and many other who contributed to previous versions of CICE or Icepack."

Please check how I worded this section.

section 1.6 (do this also for both CICE and Icepack everywhere in wikis, code, etc) replace "Los Alamos National Security" with "Triad National Security" and change the contract number to 89233218CNA000001

I have fixed this in the documentation. It is not referenced anywhere in the Wikis. However, we should update the follow file in the repo: https://github.com/CICE-Consortium/CICE/blob/master/LICENSE.pdf

section 2.1 - Dave, Tony, Andrew, others with knowledge of the coupling please read and correct this as needed.

@dabail10 @apcraig @proteanplanet , if you have comments add them in this thread. I've addressed Elizabeth's specific comments.

A quick comparison of table 1 in Icepack and CICE docs - I think only Delta H_o is different. Maybe we should add that to the Icepack table and refer the CICE documentation to it, rather than duplicating the table in both places? section 2.1.1, 2.1.2 remove these sections and refer to Icepack, but make sure that the stand-alone forcing information (around eqns 2.8-2.10) is kept somewhere. We also need to keep the paragraph around eqn 2.11 in the CICE doc.

Check how I have referenced the Icepack documentation and see if it's to your liking.

section 2.2 - keep the first 2 paragraphs and the rest of the section after table 2, starting with “In addition to the fractional ice area…”, refer to Icepack for ice thickness distribution details.

Check that I removed the correct parts.

Let’s keep all of the 2.2.1 intro, and refer to Icepack for “Tracers that depend on other tracers” and following text. Remove all of the subsections, starting with “Ice age”

Check that I did this right.

2.2.4 remove this entire section We need to make sure that there’s a note in the horizontal transport section saying that the ridging mechanism is used to clean up the ice thickness distribution after horizontal transport.

I moved the entire Mechanical redistribution section to be a subsection under horizontal transport. However, I think we want to cut it, but I wasn't sure precisely how much or what should be cut.

[eclare108213]

Let's make this the intro section 1.1, and remove section 1.3 completely:

CICE is a computationally efficient model for simulating the growth, melting, and movement of polar sea ice. Designed as one component of coupled atmosphere-ocean-land-ice global climate models, today’s CICE model is the outcome of more than two decades of effort led by scientists at Los Alamos National Laboratory. The current version of the model has been enhanced greatly through collaborations with members of the community.

CICE has several interacting components: a model of ice dynamics, which predicts the velocity field of the ice pack based on a model of the material strength of the ice; a transport model that describes advection of the areal concentration, ice volumes and other state variables; and a vertical physics package, called “Icepack”, which includes mechanical, thermodynamic, and biogeochemical models to compute thickness changes and the internal evolution of the hydrological ice-brine ecosystem. When coupled with other earth system model components, routines external to the CICE model prepare and execute data exchanges with an external “flux coupler”.

Icepack is implemented in CICE as a git submodule, and it is documented at https://cice-consortium-icepack.readthedocs.io/en/master/intro/about.html. This document describes the remainder of the CICE model. The code is available from https://github.com/CICE-Consortium/CICE.

The standard standalone CICE test configuration uses a 3 degree grid with atmospheric data from 1997, available as detailed on the GitHub wiki. A 1 degree configuration and data are also available, along with some idealized configurations. The data files are designed only for testing the code, not for use in production runs or as observational data. Please do not publish results based on these data sets.

The CICE model can run serially or in parallel, and the CICE software package includes tests for various configurations. MPI is used for message passing between processors, and OpenMP threading is available.

This document uses the following text conventions: Variable names used in the code are typewritten. Subroutine names are given in italic. File and directory names are in boldface. A comprehensive Index of primary variables and parameters, including glossary of symbols with many of their values, appears at the end of this guide.

Please cite any use of the CICE code. More information can be found at Citing the CICE code. [link this as it is]

[eclare108213]

Re linking to Icepack documentation, maybe the best thing to do is keep it at a high level and not try to link to particular sections. I think it would work well to just link to the major chapters (science guide, user guide), which would bring up the detailed outlines.

section 1.4: remove the colon after "the" and it'll be perfect.

However, we should update the follow file in the repo: https://github.com/CICE-Consortium/CICE/blob/master/LICENSE.pdf

good catch! I'll make a note to fix that for both repos.

section 2.2.4: we do want to cut this completely -- now remove the new section 2.2.2.5. Mechanical redistribution is part of Icepack. At the end of section 2.2.2, add this sentence:

After the transport calculation, the sum of ice and open water areas within a grid cell may not add up to 1. The mechanical deformation parameterization in Icepack [link] corrects this issue by ridging the ice and creating open water such that the ice and open water areas again add up to 1.

[eclare108213]

In section 2.1, I'd collect the various sentences referencing the Icepack documentation into one statement at the end of the section, and just ref the science guide:

Please see the Icepack documentation for additional information about atmospheric and oceanic forcing and other data exchanged between the flux coupler and the sea ice model.

and similarly for section 2.2 and elsewhere. E.g. at the end of section 2.2.1 I don't think you need the list of links.

[duvivier]

Re linking to Icepack documentation, maybe the best thing to do is keep it at a high level and not try to link to particular sections. I think it would work well to just link to the major chapters (science guide, user guide), which would bring up the detailed outlines.

Do you think we should link to the "master" version of the icepack documentation? Or a particular version?

[duvivier]

Items still needing to change, based on the above lists. Otherwise I think we're in pretty good shape. Here is the latest rtd html and pdf: https://cice.readthedocs.io/en/latest/index.html https://media.readthedocs.org/pdf/cice/latest/cice.pdf

Remaining items

It looks like many of the code variables are not in the correct font. Should we fix them or use some other font, or not use a special font for them at all? Some are italic, which is wrong. See the last paragraph of section 1.1. We use math font (looks like italic to me) for mathematical symbols, italic for subroutine names, and typewritten for variable names in the code, including namelist flags. This seems to be messed up throughout the documentation.

I found a few instances where the font looked okay in the html but not pdf. I think I will try to do this at the very end.

2.2 instead of ‘model components’ maybe make sections for momentum, stress and horizontal transport

I'm not sure I understand what you mean here

comp_ice still appears in a number of places and needs to be changed to whatever is appropriate, probably either cice.settings or ice_in?

I still need to do this, it's just not always consistently used in the text (e.g. comp_ice vs. comp_ice) and I will look more tomorrow.

History variables available for column output are ice and snow temperature, Tinz and Tsnz

Isn't salinz also a variable? I added it in the text.

section 3.1.5, first paragraph: “… depending on the output file format chosen in ice_in. The netCDF history files are…” (It looks like the special LaTeX command to typeset ‘netCDF’ isn’t working in the paragraph and elsewhere in the docs, e.g. the ‘restart files’ subsection and section 3.5.2.)

Again, I didn't see this as an issue. Maybe just a PDF thing vs. html? I'll look more tomorrow.

This doesn’t make sense - please correct: “The version should be some like n.m.p.string.”

@apcraig, can you clarify in section 3.2?

section 3.3 remove /bf from “The testing scripts support several features”

This is definitely an issue in the PDF only and is fine in HTML. Not sure why...

There are a lot of other Icepack parameters in this table. Maybe we should make a list of Icepack parameters (everything that has init/query/write status), refer the user to Icepack docs for those, and keep just the CICE-specific ones here???

I don't want to remove all of these since you can also modify them when running CICE. I'm not sure the best way forward. Maybe just an asterix or other identifier if they're common in both documentation?

@apcraig, do we still have an option to set MPI barriers? See the second paragraph of section 3.5.3. We need to change comp_ice here to something else… cice.settings?

@apcraig your input is needed here

Section 3.5.6, second paragraph - @dbailey10 is this still true in the code? “With the Delta-Eddington parameterization, the albedo depends on the cosine of the zenith angle (cos 𝜙, coszen) and is zero if the sun is below the horizon (cos 𝜙 < 0). Therefore time-averaged albedo fields would be low if a diurnal solar cycle is used, because zero values would be included in the average for half of each 24-hour period. To rectify this, a separate counter is used for the averaging that is incremented only when cos 𝜙 > 0. The albedos will still be zero in the dark, polar winter hemisphere.”

@dabail10 your input is needed here

[eclare108213]

Looks like you're linking to the Icepack documentation master. I think that's the best thing to do. There is a link to the Git workflow doc on googledocs, which needs to be changed to the wiki (section 1.2).

For section 2.2, I was thinking of removing the "model components" header and raising the sections up a level, so their titles would appear in the outline here: https://cice.readthedocs.io/en/latest/index.html

Isn't salinz also a variable? I added it in the text.

You're right, there is a vertical salinity variable, but I think it is Sinz.

Don't spend too much time trying to figure out why the pdf formatting is different from the html. I expect that most people will use the html.

I don't want to remove all of these since you can also modify them when running CICE. I'm not sure the best way forward. Maybe just an asterix or other identifier if they're common in both documentation?

Yes, some of them might have different options available in Icepack and CICE. It makes sense to include them in the CICE table with an asterisk that says for further information about these flags and the processes (functionality?) they represent, see Icepack.

Thanks @duvivier !

[duvivier]

@eclare108213 I'm ready for the next read through. @dabail10 @apcraig, your feedback would be appreciated as well if you have tie to look over the documentation as a whole or just the particular sections I list below. I've also updated the Icepack documentation and have a PR waiting on that. Latest CICE rtd: https://cice.readthedocs.io/en/latest/index.html https://media.readthedocs.org/pdf/cice/latest/cice.pdf Latest Icepack rtd (which the CICE doc references): https://icepack.readthedocs.io/en/latest/index.html https://media.readthedocs.org/pdf/icepack/latest/icepack.pdf

In particular things to check:

• I have changed all the comp_ice and run_ice references I found to cice.settings and cice.run. These were all in the user's guide. Please let me know if you see more issues.
• I've added Tinz and Tsnz to the cice index and added Sinz to the possible column output.
• Section 3.2 --> still needs testing and @apcraig 's input on the one particular part.
• Section 3.3.5 --> still needs testing of timeseries.csh
• Section 3.4 I added asterix to signify if the variables are also in icepack. Double check this please.
• Section 3.5 I modified the albedo discussion to reference Icepack and updated the Icepack documentation. @apcraig needs to weigh in on the MPI question still.

[eclare108213]

Section 3.3.5 needs to be changed to refer to CICE files instead of Icepack. @mattdturner tested the script, which worked for him, but it didn't work for me just now, so I've asked him to take a look.

[duvivier]

Most things have been resolved by PR #256 . Some minor modifications will likely need to be made in the user's guide section (e.g. sections 3.2, 3.3 and 3.3.5 in particular).

[duvivier]

I think we've solved most of these. The final things are new and we have an email chain about it. So I'm closing this issue.