Level 1 CIF API compliance

Forum for CIF developers to define an application programming interface for CIF software.

Moderators: Brian McMahon, jcbollinger

Post Reply
jamesrhester
Posts: 39
Joined: Mon Sep 19, 2011 8:21 am

Level 1 CIF API compliance

Post by jamesrhester » Wed Jul 18, 2012 3:10 am

In the "Requirements List" thread we have a set of requirements relating to both implementation and functionality. May I suggest that we extract the three points that relate to the core functionality and agree that any library meeting those requirements is "Level 1 CIF API compliant"? This will allow us to present a list of compliant software in COMCIFS web pages as well as giving developers a clear target. It also allows us to rule a line under that particular discussion and move on to discussion of any new implementation we might want to undertake under COMCIFS auspices. NB The meaning of Level 1 would be that it is not dictionary aware - Level 2 would include dictionary functionality that we have not yet settled on.

I have reproduced the requirements I am talking about below.

The API will support inputting and parsing CIF text from external sources.
The API will support outputting logical CIF structure and content to external sinks as well-formed CIF text.
Between source, if any, and sink, if any, and in memory where applicable, the API will support all CIF-compatible inquiries and modifications of logical CIF structure and data, including, but not necessarily limited to

adding and removing data blocks
adding save frames to and removing them from data blocks
determining the presence of a data names and their contexts (whether looped; other names in the same loop) within a block or frame
adding data names to a chosen context (for example, to a particular loop) within a block or frame
removing data names and their associated data values from a block or frame
querying the data value(s) associated with a specified data name within a block or frame
replacing one or more data values associated with a specified data name within a block or frame
querying the set(s) of related data values for a chosen context within a block or frame (for example, retrieving all the values belonging to a chosen packet of a chosen loop)
replacing one or more of the data values belonging to one or more of the sets of related data values for a chosen context within a block or frame (for example, replacing selected values in a chosen packet of a chosen loop)
adding one or more sets of related data values to a chosen context within a block or frame (for example, adding a packet to a chosen loop)
removing one or more sets of related data values for a chosen context within a block or frame (for example, removing a selected packet from a chosen loop)

jcbollinger
Posts: 57
Joined: Tue Dec 20, 2011 2:41 pm

Re: Level 1 CIF API compliance

Post by jcbollinger » Thu Jul 19, 2012 10:14 pm

I think this sounds reasonable, but I want to verify that I understand the meaning and implications of "CIF API compliance". In particular, the suggested direction seems to be away from a single programmatic interface, toward recognition of multiple interfaces (and implementations) providing certifiably equivalent features. Inasmuch as we have multiple interfaces already, but not much in the way of a standard for comparing or evaluating them, I think this is a good thing.

Is there still (or was there ever, really) any interest in a specific programmatic interface, such as might be expressed in the form of function prototypes in one or more C header files, that would be designated as the CIF API? Clearly, I have not been pushing on that (or any other) front, but I guess the question is "where do we go from here?"

Also, the quoted requirements are expressed as generically as I could manage. Is it better to leave them that way, or would there be an advantage in making some of them more specific? Or perhaps an advantage in re-expressing them in terms of the CIF data model?

jamesrhester
Posts: 39
Joined: Mon Sep 19, 2011 8:21 am

Re: Level 1 CIF API compliance

Post by jamesrhester » Fri Jul 20, 2012 1:52 am

I still believe it is important to have an IUCr-supported C API, and we should continue to push forward on that front. The reasoning behind my current proposal is to formalise what we have already agreed and put it to a good use.

If we are agreed on proceeding with a 'Level 1 etc' compliance spec, I would suggest we express it in specific terms such as the following:

To obtain Level 1 CIFAPI compliance a programmer should provide both the source code to the library seeking certification and compilable test code that carries out the following actions on an arbitrary CIF file xyz:
  • Prints the value of tag '_some_dodgy_tag'
  • Prints the sum of tags '_unit_cell_a' and '_unit_cell_b'
  • Prints the sum of s.u.s for tags '_unit_cell_a' and '_unit_cell_b'
  • Prints the list of datanames occurring in the loop containing '_a_loop_tag'
  • etc....

An example input CIF and test output file are provided.


I can work up a proper draft list in this style if the rest of us think this is a good way to go. I think the datamodel should inform the result of each test, and that while we need not restrict a compliant library to e.g. always output ("?") for a missing value, it should be possible to obtain this result with appropriate flags.

jamesrhester
Posts: 39
Joined: Mon Sep 19, 2011 8:21 am

Re: Level 1 CIF API compliance

Post by jamesrhester » Mon Dec 10, 2012 11:55 pm

After some thought and discussion with Nick Spadaccini, I think it might be better to pursue developing/adopting an official CIF library, and worry about compliance specifications later.

jcbollinger
Posts: 57
Joined: Tue Dec 20, 2011 2:41 pm

Re: Level 1 CIF API compliance

Post by jcbollinger » Tue Dec 11, 2012 6:10 pm

jamesrhester wrote:After some thought and discussion with Nick Spadaccini, I think it might be better to pursue developing/adopting an official CIF library, and worry about compliance specifications later.


I think it might be easier to develop enthusiasm for such a project, but without compliance specifications, what does yet another CIF library bring to the world? Or what purpose does adopting an official one serve?

I could see developing compliance specifications side-by-side with a new library, or as an output of a careful behavioral audit of an existing library, but I don't think leaving specifications for the indefinite "later" serves a useful purpose.


John

jamesrhester
Posts: 39
Joined: Mon Sep 19, 2011 8:21 am

Re: Level 1 CIF API compliance

Post by jamesrhester » Tue Dec 11, 2012 11:03 pm

My statement was intended simply to flag that I think we should put our limited resources into producing a CIFAPI rather than fiddling with the compliance idea that I originally proposed, although I think that both are worthwhile in the long run. So there is no dispute from me regarding John's statements above.

Post Reply