A simple json format for storing and exchanging code calculation and experimental results
Wim Haeck, USDOE National Nuclear Security Administration (NNSA) · 2019
Calculation codes and code systems give their results in a plethora of different formats and/or files. For instance, MCNP gives a user the MCNP specific output file, the mctal file, the ptrac file, etc. while PARTISN has a PARTISN specific output file and a number of binary files with various kinds of information about the calculation. However, the results we are interested in are always the same. These can be single values such as the effective multiplication factor keff or the effective delayed neutron fraction βeff. It can be histogram data (such as particle spectra, reaction rates, sensitivity profiles, etc.) or even pointwise data (for example the nuclide composition as a function of time, etc.). It is also worthwhile to note that this would also apply to experimental data that we may wish to compare with as well. Calculation and experimental results can basically be split into two components: attributes (or metadata) and the actual result itself. Attributes represent information about the result that are not necessarily required for its’ interpretation but that are still good to have. Often, these attributes are what we will want to filter results on. This means that these attributes are often the answer to specific questions we may have about the result. The following is a non exhaustive list of such basic questions: what type of result is it: e.g. the effective multiplication factor keff, the effective delayed neutron fraction βeff, etc.; which case does it relate to: e.g. a specific ICSBEP case such as PU-MET-FAST-001-001; which code and version produced this result: e.g. MCNP 6.2, etc.; which nuclear data library was used to obtain the result: e.g. ENDF/B-VIII.0 or JEFF 3.3; which nuclide and reaction does it apply to (for reaction rates and sensitivity profiles); which volume in the geometry was it calculated in? The second component of the calculation or experimental result is the actual numerical data of the result. It is this data that we want to compare, exchange, plot, interpret, etc. It consists of values with optional uncertainties and units. It also includes the underlying structure (if any structure is required to interpret the result). Depending on the type of result, it may be a single value (e.g. the effective multiplication factor), an array of values (e.g. a reaction rate or particle spectrum) or even a multidimensional array. In order to exchange results between different organisations, for instance for benchmarking, people often resort to spreadsheets or custom text files that need to be filled out. While this approach works well if little information is to be exchanged, it can become cumbersome when dealing with large amounts of data (like for instance particle spectra for thousands of cases). In addition, such an approach does not always capture the metadata we may be interested in to allow for automated processing of these files. The purpose of this report is to propose a standardised json structure to store any type of result and present an associated python interface to interact with these results directly. For such a structure to be useful, it must fulfill a specific set of functional requirements that we try to meet with this proposal. The format must allow for the calculation result to stand by itself. This means that we should not have to look in multiple places to be able to understand it. For example, if the result relates to a particle spectrum, the group structure in which the result is given should be stored with it. The format should be code agnostic. This means that we do not need to know where it came from to understand it. The format should be result type agnostic. This means that the format must be generic enough so that we can even use it for results we have not thought of yet. The format should be relatively easy to interact with through different scripting or programming languages (i.e. the machine interface) while still providing a clean structure that can be used directly by any human.