Open billsacks opened 6 years ago
@whlipscomb @gunterl I have added chapter assignments in the comment above. (Bill L: no need to deal with this right now - just within the next few weeks.)
@billsacks, Thanks for putting together this outline. I'll work on this after the code is frozen and the draft paper is done. (It's going to be a busy month.)
@gunterl and @whlipscomb - Okay, I have done the initial reorganization of the documentation that @gunterl and I came up with (sorry this has taken me a while to complete!). I have created a branch in this repo named doc_work where we can continue to work on this documentation. My plan is that we can then merge this branch to both master and the release branch. (I have done an initial merge of this branch to both master and release just now.)
The build of the documentation is here:
https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/index.html
There are instructions on how to build the documentation on the doc_work branch, under doc/README.md (I'm not sure all of these instructions are correct and up-to-date, though: I copied some of them from an older wiki page). If you don't want to struggle with the documentation build, don't worry about it for now: I can do the build periodically. Note that you can view a sort-of-pretty version of the documentation in the github view of an rst page, e.g., https://github.com/ESCOMP/cism-wrapper/blob/doc_work/doc/source/ice-sheets-in-clm.rst
@whlipscomb you had a lot of good information in the quick start section (at least, I think you're the one who wrote that) - generally describing how to use CESM. However, some of it is out of date. Rather than trying to update all of it, I'm just removing it for now, pointing people to existing documentation. (I'll push these changes up soon.)
I wanted to give you a heads-up about this in case you want to reinstate any of that.
@billsacks, Thanks for the heads-up. I doubt I'll have time to update this section before the release. Maybe @gunterl and I can reinstate an updated version of the section at a later date.
@gunterl - for now I am completely removing the section on "simulating the Greenland ice sheet". We had talked about moving it to the "quick start" section (now called "Running and modifying the CESM land ice component", but it feels very out of place there). I'm not sure this section is necessary, but if you want it, you can dig up the original version from an earlier commit.
@whlipscomb and @gunterl I am making some progress on what I view as the most critical sections that were assigned to me - see checklist above. The main piece that's done now is the new section 2, "Running and modifying the CESM land ice component". I have also added an appendix on adding a new CISM grid, because this mostly consisted of moving information off of the wiki into this documentation. The one additional piece I want to do before leaving tomorrow morning is to fix the documentation of TG compsets. If I don't finish it then, it will be a high priority for me at the end of next week.
Again, see the doc_work branch in this repository, as well as https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/ for the current build. Feel free to modify as you see fit.
Hi @billsacks,
Thanks for working on this. I will be make progress on my part this week.
On Sun, Jun 3, 2018 at 10:54 AM, Bill Sacks notifications@github.com wrote:
@whlipscomb https://github.com/whlipscomb and @gunterl https://github.com/gunterl I am making some progress on what I view as the most critical sections that were assigned to me - see checklist above. The main piece that's done now is the new section 2, "Running and modifying the CESM land ice component". I have also added an appendix on adding a new CISM grid, because this mostly consisted of moving information off of the wiki into this documentation. The one additional piece I want to do before leaving tomorrow morning is to fix the documentation of TG compsets. If I don't finish it then, it will be a high priority for me at the end of next week.
Again, see the doc_work branch in this repository, as well as https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/ for the current build. Feel free to modify as you see fit.
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/ESCOMP/cism-wrapper/issues/12#issuecomment-394175497, or mute the thread https://github.com/notifications/unsubscribe-auth/AH0K-PnErm7T3bwxgOm5XJ5nJ0HTaLnKks5t5BTfgaJpZM4T1HtT .
I am partially done the section on T/TG compsets (section 3): I have gone over subsections 1, 2 and 4 here. I just need to rewrite subsection 3 (creating and running with your own forcing data).
@whlipscomb and @gunterl - I don't think I'll get any more chance to work on this before leaving on vacation through Thursday, so here's a summary of where things stand: I've been working on the doc_work branch in this repository. The latest build is here: https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/ . I am finished drafts of the following sections:
(2) Running and modifying the CESM land ice component
(3) Running the standalone ice sheet model within CESM: T compsets
Finished drafts of 3.1, 3.2, 3.4
Still need to rewrite 3.3
(6) Controlling output from CISM and CLM
I'd be happy to get your reviews or edits of those sections.
When I return, my highest priority will be rewriting section 3.3. Beyond that, I need to do a lot of work on section 5 (Ice sheets in the Community Land Model, and glacier-land coupling) to bring it up to date with the latest capabilities. That probably won't be done in time for the release (unless the release is delayed) so my plan is to temporarily remove that page (and any other incorrect pages) from the index until they're corrected, so people won't stumble across grossly incorrect information.
@billsacks, thank you so much for the great progress.
On Mon, Jun 4, 2018 at 8:41 AM, Bill Sacks notifications@github.com wrote:
@whlipscomb https://github.com/whlipscomb and @gunterl https://github.com/gunterl - I don't think I'll get any more chance to work on this before leaving on vacation through Thursday, so here's a summary of where things stand: I've been working on the doc_work branch in this repository. The latest build is here: https://escomp.github.io/cism- docs/cism-in-cesm/doc_work/html/ . I am finished drafts of the following sections:
-
Running and modifying the CESM land ice component
Running the standalone ice sheet model within CESM: T compsets
Finished drafts of 3.1, 3.2, 3.4
Still need to rewrite 3.3
- Controlling output from CISM and CLM
I'd be happy to get your reviews or edits of those sections.
When I return, my highest priority will be rewriting section 3.3. Beyond that, I need to do a lot of work on section 5 (Ice sheets in the Community Land Model, and glacier-land coupling) to bring it up to date with the latest capabilities. That probably won't be done in time for the release (unless the release is delayed) so my plan is to temporarily remove that page (and any other incorrect pages) from the index until they're corrected, so people won't stumble across grossly incorrect information.
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/ESCOMP/cism-wrapper/issues/12#issuecomment-394379146, or mute the thread https://github.com/notifications/unsubscribe-auth/AH0K-K-eh4-gw47Yvf44UPa0WbSZTMzRks5t5UcbgaJpZM4T1HtT .
@whlipscomb here are the sections I envision writing (roughly) for chapter 5:
Different ways CISM can be coupled
(This will discuss one-way vs. two-way coupling.)
Brief overview of CLM-CISM coupling
(This will include a brief, conceptual overview, including things like: CLM sends SMB, which can trigger a change between glacier and non-glacier in CISM, then CISM dictates new glacier cover. In particular: CLM never generates a change between glacier and non-glacier itself.)
Fields sent from CISM to CLM
Fields sent from CLM to CISM
Other fields sent from CISM
(this will cover the runoff fields)
Remapping fields from CLM to CISM
Remapping fields from CISM to CLM
CLM's possible glacier behaviors
(This refers to the different glacier regions and their different possible behaviors. This doesn't completely fit with the topic of CLM-CISM coupling, but I'd like to include documentation of this. It's possible that this would just point to the CLM tech note or user's guide.)
In addition, at least some of the existing sections in ice-sheets-in-clm.rst
should probably be kept, though maybe in abbreviated form.
Maybe we really need two sections:
"Ice sheets in CLM" - will include some of the existing information from ice-sheets-in-clm.rst
that is CLM-centric, plus the above section on CLM's possible glacier behaviors
CISM-CLM coupling
I'm open to any thoughts you have on the best way to organize this material.
I have (finally) merged the doc_work branch to both master and the release branch. I haven't done any work on it lately, but I couldn't remember why I hadn't merged it long ago, so decided it was probably time to merge it, partly to facilitate some other documentation changes needed soon.
Alice Bertini showed me the nice marbl docs: https://marbl-ecosys.github.io/versions/latest/ , with particular reference to how they do the pull-down for the versions. I took a quick stab at trying to get that working here:
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 6f1740d..8c85cc6 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -88,13 +88,16 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'bizstyle'
+import sphinx_rtd_theme
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
-# html_theme_options = {}
+html_theme_options = {}
+html_theme_options['versions'] = {'latest': '../master', 'cesm2.0': '../release-cesm2.0'}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
But that is apparently not enough (the build generates WARNING: unsupported theme option 'versions' given
, and doesn't result in the version pull-down). Digging a bit more, it looks like we might need the js file from https://github.com/marbl-ecosys/MARBL/commit/ddd346f138b62c8415a0671f59777897ca956c99 . Since I don't understand that, I'm not prepared to bring it in yet. Also, I don't like that (apparently) every branch needs to have a hard-coded list of versions... does that imply that, if you add a version, all branches need to change? I'm going to wait for Alice to look at this and possibly come up with an improvement.
@whlipscomb @gunterl - I am done the pieces that I was assigned. See the checklist at the top of this issue for the remaining needs.
A few notes about my recent changes:
I'm not adding any documentation on the algorithm that does the remapping from cism to clm, because there isn't much I can think to say about this.
I deleted the old ice-sheets-in-clm.rst
: Everything in here was either already documented elsewhere (mainly in the CLM tech note), no longer relevant, or not important enough to be worth the time to rework.
I have added a note about the need to set restart = 0 for the case that Laura ran into August, 2018 (in https://escomp.github.io/cism-docs/cism-in-cesm/versions/master/html/running-and-modifying.html#special-considerations-for-hybrid-cases). I'd welcome any explanation you'd like to add about that (I don't completely understand the need for restart = 0
, including when it's needed or why).
This issue documents things needed for the cism-in-cesm documentation for the cesm2 release.
[x] Rewrite chapter 1 (introduction) - Gunter (with help from Bill L, Bill S)
[x] Chapter 2 (quick start) - Bill S
[x] New chapter on developing and modifying CISM
[x] Add a section on grids (rewritten from the section in the current chapter 4) - Bill S (with help from others)
[x] Chapter 3 (TG compsets) - Bill S
[ ] Chapter 4 (the dynamic ice sheet model) - Gunter
[x] Chapter 5 (ice sheets in the community land model, and coupling) - Bill L with help from Bill S
[x] Chapter 6 (FAQ) - cut this for now; can add things back in later as needed (note that they'll need documentation for the new code)
[x] New chapter on controlling output from cism and clm
[x] Chapter 7 (acknowledgements) - Bill L
[ ] Chapter 8 (references) - Gunter and Bill L
Other things we want to mention somewhere: