[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