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. The same file, onecube.json, is also shown below:

 {
    "Domain": {
	"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": {
            "Type": "pencil",
	    "Pos": [2.0, 8.0, 0.0],
	    "Dir": [0.0, 0.0, 1.0],
            "Param1": [0.0, 0.0, 0.0, 0.0],
            "Param2": [0.0, 0.0, 0.0, 0.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 "Domain", "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 "Domain" object is the same as Line#6 in onecube.inp; the "InitElem" under "Domain" 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 parameter directly in the root level. For example

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

You can even mix the alternative format with the standard format. If any input parameter has values in both formats in a single input file, the standard-formatted value has 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 have a ".json" suffix in order for MMC to recognize. If the input information is set in both command line, and input file, the command line value has higher priority (this is the same for .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.