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 input parameters have 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 an .inp file. For example:

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

The input file must has a ".json" suffix in order for MMC to recognize. If the input information is set in both the command line, and the input file, the command line values has higher priority (this is the same for .inp and .json 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.