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

Adrian K. Turner akt at lanl.gov
Thu Feb 28 15:37:53 MST 2013


Thanks Doug,

I agree that using a standardized language for this is a good idea as 
well as doing validation with a schema. My vote would be for JSON but 
that's mainly because I'm more familiar with it than XML. I also like 
that JSON more clearly distinguishes between associative arrays {} and 
indexed arrays [].

Adrian

On 2/28/13 3:29 PM, Doug Jacobsen wrote:
> 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 <mailto: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
>
>
>
>
> _______________________________________________
> mpas-developers mailing list
> mpas-developers at mailman.ucar.edu
> http://mailman.ucar.edu/mailman/listinfo/mpas-developers

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mailman.ucar.edu/pipermail/mpas-developers/attachments/20130228/3c900a0a/attachment.html 


More information about the mpas-developers mailing list