JSON-formatted input files for MMC

Starting from version 0.9, MMC accepts a JSON-formatted input file in addition to the conventional tMCimg-like input format. JSON (JavaScript Object Notation) is a portable, human-readable and "fat-free" text format to represent complex and hierarchical data. Using the JSON format makes a input file self-explanatory, extensible and easy-to-interface with other applications (like MATLAB).

A sample JSON input file can be found under the examples/onecube folder. This file, onecube.json, is also shown below:

 {
    "Mesh": {
	"MeshID": "onecube",
	"InitElem": 3
    },
    "Session": {
	"Photons":  100,
	"Seed":     17182818,
	"ID":       "onecube"
    },
    "Forward": {
	"T0": 0.0e+00,
	"T1": 5.0e-09,
	"Dt": 5.0e-10
    },
    "Optode": {
	"Source": {
	    "Pos": [2.0, 8.0, 0.0],
	    "Dir": [0.0, 0.0, 1.0]
	},
	"Detector": [
	    {
		"Pos": [2.0, 6.0, 0.0],
		"R": 1.0
	    },
            {
                "Pos": [2.0, 4.0, 0.0],
                "R": 1.0
            },
            {
                "Pos": [2.0, 2.0, 0.0],
                "R": 1.0
            }
	]
    }
 }

A JSON input file requires 4 root objects, namely "Mesh", "Session", "Forward" and "Optode". Each object is a data structure providing information as indicated by its name. Each object can contain various sub-fields. The orders of the fields in the same level are flexible. For each field, you can always find the equivalent fields in the *.inp input files. For example, The "MeshID" field under the "Mesh" object is the same as Line#6 in onecube.inp; the "InitElem" under "Mesh" is the same as Line#7; the "Forward.T0" is the same as the first number in Line#5, etc.

An MMC JSON input file must be a valid JSON text file. You can validate your input file by running a JSON validator, for example http://jsonlint.com/ You should always use "..." to quote a "name" and separate parallel items by ",".

MMC accepts an alternative form of JSON input, but using it is not recommended. In the alternative format, you can use

 "rootobj_name.field_name": value 

to represent any specific parameter in the root level. For example

 {
    "Mesh.MeshID": "onecube",
    "Session.ID": "onecube",
    ...
 }

You can even mix this format with the standard format. If any of the input parameters has both formats in a single input file, the standard-formatted values have higher priority.

To invoke the JSON-formatted input file in your simulations, you can use the "-f" command line option with MMC, just like using a .inp file. For example:

  ../../src/bin/mmc -n 20 -f onecube.json -s onecubejson -D M

The input file must have a ".json" suffix in order for MMC to recognize it. If the input information is set in both the command-line, and the input file, the command line values take priority (this rule also applies to .inp input files). For example, when using "-n 20", the value set in "Session"/"Photons" is overwritten to 20; when using "-s onecubejson", the "Session"/"ID" value is modified. If your JSON input file is invalid, MMC will quit and point out where it expects you to double check.