[mpas-developers] DESIGN DOCUMENTS: Field Statistics, Run-time I/O, Auto-Documentation

Doug Jacobsen jacobsen.douglas at gmail.com
Thu Feb 28 15:29:27 MST 2013


Hi again everyone,

To try and help fuel the discussion about the format of Registry, I've
decided to try and mock up two versions of Registry. There is the current
proposal in the design document for XML, but I slightly modified it in a
way that makes it more closely mirror whats currently in the code. Another
developer here recommended I look at JSON as well, so I put together an
example of the same XML Registry, but in the JSON format.

These are not complete versions of what they would look like in the end,
but I tried to give examples of at least everything I wanted to have in the
file in the end. Please take a bit and download the two files. You can open
them up in your favorite editor and look around to see if you like or
dislike either of them.

One thing to note, I'm not super familiar with JSON so some of the
formatting might be incorrect in the version I sent you. So there might be
some small errors, but I think largely it's correct.

Some small notes:
One fairly large benefit to using either of these two formats is that we
can define a JSON or XML schema and do validation checks on our Registry
file prior to using it.
One fairly large negative to the JSON format is that you can't write
comments. The only want to write comments is to define an unused key:value
pair that is your comment.

Again, any questions or comments are appreciated.

Thanks,
Doug


On Tue, Feb 26, 2013 at 10:43 AM, Doug Jacobsen
<jacobsen.douglas at gmail.com>wrote:

> Hello Everyone,
>
> There are two design documents attached (and also recently committed to
> the repo). I put two in this email because on of them requires the other,
> and provides something to consider in the first.
>
> First, is the run-time I/O document that also includes auto-documentation.
> This requires some rather significant modifications to Registry, with the
> end goal being a verbose format for Registry that allows documentation of
> fields, namelists, and dimensions to be written into the Registry file. I
> have provided an XML proposal for Registry conversion in this document, but
> this could be a different format. This format will also be used to enforce
> CF compliance in our output files (writing out field level attributes and
> what-not).
>
> This document also includes description (although rough currently) of an
> auto-documentation parser script. Currently I have a script written in
> python that parses Registry and an additional documentation file (as a
> test) that generates tables and sections that will be included in our users
> guide.
>
> One of the main short term benefits of this project is that it allows ease
> of documentation. However the second benefit is the creation of a run-time
> I/O layer. This allows the creation of streams at compile time, and the
> modification of what fields are in each stream at run-time. This makes use
> of another namelist file (described in the document) to make configuration
> easy.
>
> Second, is the field statistics module design document. This provides a
> description of a generic module that can be used to compute time averages
> and field moments. Time averages and moments of fields can be specified at
> run-time, with the implementation of the run-time I/O layer.
>
> Both of these projects are rather large, and some of our documentation
> requires the first project. My hope is to begin to work on this project
> within the next few weeks so I would like to get at least the first
> document solidified sooner rather than later.
>
> So, please let me know if you have any questions of comments. Especially
> regarding the format of Registry.
>
> Thanks!
> Doug
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mailman.ucar.edu/pipermail/mpas-developers/attachments/20130228/ce768247/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Registry.xml
Type: text/xml
Size: 1179 bytes
Desc: not available
Url : http://mailman.ucar.edu/pipermail/mpas-developers/attachments/20130228/ce768247/attachment-0001.xml 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Registry.json
Type: application/json
Size: 1409 bytes
Desc: not available
Url : http://mailman.ucar.edu/pipermail/mpas-developers/attachments/20130228/ce768247/attachment-0001.bin 


More information about the mpas-developers mailing list