Recommendations for input file format for science applications

Question

Assuming that a program is written in either C, C++, Fortran or python, what do you think is the best format for the input file given that users could be relatively diverse, i.e. not familiar with the source code? My current interest is a thermodynanic property tool but the discussion could be more general. Here is what I think are the main options:

• dumb ASCII file

  VARIABLE_NAME
  300
  OTHER_VARIABLE
  101325
  STRING_ARRAY
  N2 O2
  

• more involved ASCII file: some custom delimiters to better handle array inputs for example. Essentially you are trying to be smart about your data and have a custom parser that is more flexible than the one for the dumb ASCII

• JSON

• xml

Anything else you would recommend? A lot of tools choose route #2 but I really don't like it, you often end up with weird non-standard syntax that are more confusing than helping.

Answer 1

I would perhaps argue that the main virtue of XML is the ease with which one can write a parser, rather than the ease with which you can write an actual XML document. JSON seems a slightly better alternative to my mind. Both have the advantage of being standards to some degree, meaning people won't have to learn whichever arcane syntax your program of choice has adopted.

You mentioned Python, and I would argue that a simple Python file will easily be as, or more, accessible than a text file with a custom syntax. People will need to learn a new syntax anyway, which is unlikely to be less complicated than "entry level" python.

In my experience, input files often end up with some sort of macro capability anyway, which accidentally becomes Turing-complete. In this case, it would be much better to have a "proper" language, with all that entails.

Take the problem of defining geometry in Monte Carlo particle transport codes, such as FLUKA or Geant4. While many such codes use a custom syntax (your case 2), a full scripting language allows you to use loops and conditionals, allowing you to define the geometry in a fraction of the time.

Other alternatives to Python would be Lua, which is used heavily in the games industry, Julia or even Javascript (it's sub-par handling of numbers aside).

Answer 2

I disagree with the "make it as easy as possible" answers to this question.

Options 1 and 2 lock you into something you will have a hard time changing later on. For example, you will find that if your number of parameters grows, you will want to put them into sections and subsections because that makes it simpler to organize. But your syntax doesn't allow this. This is why Microsoft Windows configuration files have these weird [section] markers -- but they neither really help to clarify sections (because there is no 'end-section' marker) nor do they allow nesting. In other words, Windows configuration files are a great example of "well, dang, shoulda thought of that some more up front". (Of course, that's sort of a running theme with many Microsoft features.)

So, don't do it, you will regret having gone this way and keep inventing strange workarounds to do things you wish you had considered beforehand.

Option 4, on the other hand, is great if you have a machine write the file, but not if a human is doing it. People have tried writing scientific software where the input files are created by hand and have XML format -- I've been on the board of an organization that did that, and it was a complete disaster because people rebelled: XML is simply not readable nor writable for humans.

That only leaves you with option 3. Whether you choose JSON or something that is easier on the eye but has otherwise the same expressiveness does not matter that much. But it should be human readable, human writable, and have some sort of syntax. It should also be pretty self-explanatory what an input file wants to say, which is neither true for your option 1 nor 4. Finally, it should be relatively straightforward to implement in your code, which calls for something for which there already is a parser.

Answer 3

Don't ignore HDF5 which is designed for scientific datasets and has bindings for all the languages you mention, more besides. It's widely used and there are tools for poking around inside files without programming. If you want to (though I don't know why you would) you can even dump an HDF5 file into XML.

It's primary purpose may be for large datasets but it can cope with very small ones too. Indeed one reason you should consider it is precisely because you can store the parameters and other bits of job setup in the same file as the input and output datasets.

Answer 4

This answer is like LKlevin's but too long to add as a comment.

If it's OK for input file to not allow fully general (turing complete?) instructions then I'd use json.

If you want to allow the user to specify turing complete instructions in a setting that is tightly controlled by your software then I'd use lua.

If you want to let the user do anything in their input file (downloading stuff from the internet, reading files, hacking the execution sandbox, hacking the host computer) then let them use python.

Answer 5

I can recommend based on my personal experience. I had to do a similar task of parsing an input file in a cross-platform C++ program. I needed something simple and most of all something that could be swiftly implemented, so I went with choice #1 (ASCII), because the input data was relatively plain and simple.

However, i think that the size and complexity of your input on one hand, and the language you're using on the other hand, should be considered. If a complex input file is needed, choices #3 and #4 are better, nonethless I am not sure which format has a better parsing speed, easier to implement ...

Another choice is the YAML format which is simple and human readable. If your project uses python, then the PyYAML binding is the way to go.

Answer 6

Use the dumbest format that suits your needs. Make it ASCII-based if you can. Make it inflexible and as easy to parse as possible because there are better things to do with your life than writing input parsers. That means eschewing JSON and XML and S-expressions and any sort of hierarchy that the code itself will have to strip away. Look at the DIMACS formats, rather than XML and JSON, for inspiration and try to make something even easier.

To reiterate, your job is probably not to build parsers for complicated input formats. It's to solve a real problem based on whatever input you're given.

Answer 7

The best solution I think is a combination of @lklevin's and @wolfgang-bangerth answers.

First, make sure to have a clean API. This means have one function/class which takes all the needed parameters. Then, if your program is written in a language where string/data manipulation would require some amount of code (i.e. Fortran, C, C++ etc.), wrap it in a dynamic language (python, ruby, lua, perl etc.), and use a standard format (ini, json, xml).

This means if you really need to have some kind of Turing complete input format its easy to add, and if the format you choose is not suitable any more, then you can change easily without affecting the main code.

The worst thing would be some unique format, as if you end up needing to generate (or read using a different program) the format (say as the output of another program), then you'll (or someone else who is trying to use your work) have to work out how to write your new format.