CCSM Software Engineering Working Group Meeting Summary

February 27, 2001 at Oak Ridge, TN

 

 

Focus: Software-Related Documents

 

The following is a summary of the CCSM Software Engineering Working Group Meeting (CCSM SEWG). It contains: 1) an overview of the purpose and results of the meeting; 2) a description of some of the tools and guidelines that were mentioned, including URLs; 3) a list of short-term action items.

 

1. Overview

 

URLs for the tools discussed at the meeting are included later in this document.  Currently software documents for the CCSM project are being generated in a variety of formats (LaTeX, Word, html, DocBook), document content is inconsistent (e.g., "design document" can mean very different things), and auto-documentation tools are rarely used. Documents are not that easy to generate, locate, or browse. The point of this SEWG meeting was to come up with a strategy to use documents more effectively and generate them more efficiently. We proposed general guidelines for any documents related to CCSM software. We also proposed a set of basic documents and outlined their applicability and content. The documents and guidelines that were presented at the meeting are described at:

http://www.ccsm.ucar.edu/working_groups/Software/dev_guide/doc.03.html

The guidelines were accepted with the caveat that some meeting participants wanted to try out the proposed LaTeX-based tools for document generation before committing to a strategy. Comments on these tools or on other aspects of the meeting can be sent to the ccsm-sewg@ucar.edu mailing list or posted on the SEWG discussion forum:

 

http://www.ccsm.ucar.edu/cgi-bin/csm/BBS/bbs_forum.cgi?forum=software

 

We agreed to hold a "barn raising" before the Sixth Annual CCSM Workshop in June, in which a handful of people will instrument the atmospheric model using the ProTeX auto-documentation tool. If this goes well, there was interest in instrumenting the other components in the CCSM as well. We will create and circulate templates and examples for the documents proposed and for module headers. We may explore creating a position in NCAR's Climate and Global Dynamics Division that would include assisting with documents and maintaining the CCSM website.

 

There were some questions about what the priorities should be in creating some of these software documents. Participants considered defining requirements and architecture for the whole model and large model components important, since this helps to communicate major design decisions. Documenting common utilities was also considered a priority.

 

2. Guidelines and tools

 

One of the proposed guidelines is that documents be written in LaTeX, since:

- it is a system many people are already familiar with,

- it produces reasonable print and web documentation using latex2html,

- there is a GUI interface option via the LyX tool, and

- it is compatible with ProTeX, a F90/C auto-documentation tool.

 

Links to the latex2html, ProTeX, and LyX tools are included here:

ProTeX: http://dao.gsfc.nasa.gov/software/protex/

 (File List: protex v2.0) 
LyX:  http://www.lyx.org/

 latex2html
http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html

 

Some participants were curious about documentation produced using latex2html. Here are some examples:

NWChem:  http://www.emsl.pnl.gov:2080/docs/nwchem/doc/user/index.html
(thanks to David Bernholdt)

MOM:  http://www.gfdl.gov/~smg/MOM/MOM_manual.html

3. Action items

1) Try out and comment on tools (if interested, within next two weeks); 2) Create templates and examples for proposed documents (DeLuca/Kauffman with CCSM-programmers, next two weeks); 3) Set date for "barn raising" to instrument atmospheric model and coupler (before June); 4) Explore adding additional staff to assist with and organize documents, help to maintain website (ongoing).

 

4. Participants:

 

Jim Rosinski/NCAR

Brian Eaton/NCAR

Cecelia DeLuca/NCAR

Byron Boville/NCAR

Dave Williamson/NCAR

Tony Craig/NCAR

Tom Bettge/NCAR

Brian Kauffman/NCAR

Rob Jacobs/ANL

Jay Larson/ANL

Art Mirin/LLNL

Doug Rotman/LLNL

John Taylor/LLNL

David Bernholdt/ORNL

John Drake/ORNL

David Erickson/ORNL

Pat Worley/ORNL

Bob Malone/LANL

Phil Jones/LANL

Chris Ding/LBL

Will Sawyer/NASA

 

ANL - Argonne National Laboratory

LANL - Los Alamos National Laboratory

ORNL - Oak Ridge National Laboratory

LLNL - Lawrence Livermore National Laboratory

LBL - Lawrence Berkeley Laboratory

NCAR - National Center for Atmospheric Research

NASA - National Aeronautics and Space Administration