Agenda

1. Ensuring the API is general-purpose

   Proposal: the API should not be tied to a particular xml parser, or even to xml. We may wish to start by defining a low-level interface for accessing data from any hierarchical data structure, i.e. XML, JSON, HDF, etc.

   The low-level API would need to define an 'element' or 'node' class corresponding to each level in the hierarchy. Each node needs a way to access its node name, attributes, child nodes (including searching for child nodes by name or by attribute value), and text / data content.

   Caleb has some more specific proposals for that low-level API, will go over those in detail.

2. Establish some API design standards

   Proposals: use camelCase names, Capitalize first letter of class names, lowercase first letter of method names, use prefix 'a_' for method arguments and 'm_' for class members

3. Initial API design should provide enough methods to open a GNDS file, find a desired reaction and extract the cross section. Once we are happy with that, expand to other types of data.

Meetings notes

Slides from the telecon are available here

Had some audio problems with webex. M. Paris was able to view webex but didn't get audio.

Starting with the assumption that first implementation will be in C++. This choice will impact API design.

1. Start by making a low-level API to abstract away file details, so that higher-level stuff isn't tied to a particular type of file (XML, HDF5, etc).

   • General agreement that this is a good idea
   • Also agreement that this low-level API should have an 'empty node' concept. In other words, if higher-level requests a child node that does not exist, return an empty node rather than throwing an exception
   • Some discussion about how to handle data nodes. In XML, these contain a string representation of a list of (usually) float64 values. However, they could also contain a list of ints, float32s, etc. Caleb's initial proposal had a 'getData' method that returns a vector of numbers, but since the number type could vary we probably need more specific methods like getFloat64Data(), getInt32Data(), etc.
   • Caleb also proposed a getString() method that would return a string representation of the data. This is easy when starting with xml, but when starting from binary storage like HDF5 this requires generating the string representation. K. Tada asks what precision to use when generating that string? We also discussed whether this method is really necessary

     After conference I (Caleb) thought more about that question: I think the answer is yes, to support reading in from HDF5 and writing out to ascii representation like XML

   • When low-level API opens a new file, should it try to auto-detect file type, or does the user need to specify? Preference for now is that the user must specify, may later decide to try supporting autodetect.

2. Establish some naming conventions and guidelines for API design.

   • One of the proposals was to use standard prefixes for certain types of variable, for instance 'a_' for method arguments and 'm_' for class members. There was some confusion about that, Caleb has expanded the example in the slides to illustrate why this may be helpful.

3. Starting to fill out initial API details.

   • Some discussion about whether everything needs to be constructed at once vs. using lazy evaluation and only reading in data when needed. However, we decided that decision is better left as an implementation detail, not spelled out in the API
   • One discussion item that came up several times: how should we handle case where a container can hold more than one class? For example the crossSection component in GNDS can contain at least 4 different forms: XYs1d (single interpolation region), regions1d (multiple interpolation regions), resonancesWithBackground and reference (contains a link to another cross section). Does the crossSection class (in the API) need specific getXYs1d, getRegions1d, etc. methods?

     Hoping that Doro and Bret can join for the next meeting to explain how they are handling this question.

   • The example slides suggested using a generic PhysicalQuantity class for things like temperature. Fausto suggests that we have more specific classes.

Attendees

• C.M. Mattoon (LLNL)
• F. Malvagi (CEA Saclay)
• D.A. Brown (BNL)
• K. Tada (JAEA)
• M. Paris (LANL)

Assignments

• Caleb to organize next meeting, likely the week of July 17 or 24 (will send out Doodle poll for best day).
• Also work on moving API thoughts from slides to more formal document.
• If possible, will have Bret, Doro and others show how they are starting to handle GNDS data at the next meeting.