Skip to content

MCX v2020 (Furious Fermion)
Compare
Choose a tag to compare
@fangq fangq released this 07 Sep 18:56
· 933 commits to master since this release
v2020
a6bc5a9

Download

What's New

MCX v2020 represents a new milestone towards the development of a fast,
versatile and feature-rich open-source Monte Carlo 3D photon simulator. It is
packed with numerous improvements in both functionality and stability. We want
to specifically highlight the below major additions:

  • Built-in benchmarks for easy testing and adoption by new users
  • Transition to JSON/JNIfTI input/output files for easy data sharing
  • Exporting simulation as JSON with binary volume data
  • All-in-one Windows installer for MCXStudio/MCX/MMC/MCXCL
  • Automated code building, testing and continuous integration via Travis-CI
  • CMake based compilation and Visual Studio support
  • 1.6x speedup on Pascal GPUs

A detailed list of updates is summarized below (key features marked with “*”):

  • 2020-08-20 [e8e6b58] print an explicit messgae if error 30 is found
  • 2020-08-19*[883f61b] restore windows progress bar support, disabled in @ae2d60e45
  • 2020-08-17 [c47de01] allow running testing script on machines without nvidia gpu
  • 2020-08-16 [0c25958] add more tests for various mcx options
  • 2020-08-16 [ff2f68f] add sphshell benchmark - see GPU MMC paper
  • 2020-08-15 [2afab4a] test if media prop count is less than max label
  • 2020-08-15 [2d71eb7] accept array as Domain.Media json input
  • 2020-08-15*[433df1f] accept json modifier via --json for easy testing
  • 2020-08-14 [09adbd0] support --bc or cfg.bc to set an entire bounding face as detector
  • 2020-08-11*[e095dbb] speed up by 1.6x on 1080Ti by restoring source template for pencil beam only
  • 2020-08-11 [a220cc2] autoblock size no less than 64, speed up on Turing GPU by doubling threads
  • 2020-08-04 [71d4196] fix incorrect detpt column when savedetflag/issaveexit are both set
  • 2020-08-04 [20c596a] retrieve energy tot and abs regardless of isnormalized
  • 2020-08-03*[30e01a1] add standalone script to submit to mcx speed contest
  • 2020-07-31 [d9a5953] avoid autoblock is 0 when driver fails, close #99
  • 2020-07-28 [daa9d56] fix inaccurate core count on Volta, Turing and Pascal
  • 2020-07-25 [37793ae] fix -b 0 -B rrrrrr crash, thanks to @ShijieYan
  • 2020-07-22*[f844fe8] add automated building script via travis-ci
  • 2020-07-22*[f844fe8] add automated building script via travis-ci
  • 2020-07-22*[cbf0225] add unit testing script
  • 2020-07-09 [5b038a7] add winget manifest
  • 2020-07-04*[4bda593] inno windows installer
  • 2020-07-02 [38529a7] accept -f in mcxshow and mcxviewer
  • 2020-07-02 [34ecf5f] add glscene directly to the source code
  • 2020-07-01*[f1828d3] add manpage for mcx
  • 2020-06-29 [cd4acb8] visual studio project file updated
  • 2020-06-29 [b22025d] update vs project file
  • 2020-06-28 [71bedc5] add benchmark options, add jnii/bnii output formats
  • 2020-05-02 [e7ce8f7] compiles lzma on windows, #94
  • 2020-05-02*[e56fa2b] add UBJ support, output .bnii files, close #95
  • 2020-05-01 [ed80ad5] now support lzma and lzip compression
  • 2020-05-01 [f136bc9] upgrade all built-in binary files to JData formatted JSON files #94
  • 2020-04-29 [0d9c162] save detected photon data in JSON/JData format, close #94
  • 2020-04-25 [045a3de] update json schema
  • 2020-04-25 [e8aae66] initialize gsrcpattern
  • 2020-04-23*[8086175] add built-in colini27 data,add --dumpjson, add -F jnii output format
  • 2020-04-19*[da73b8d] add mcx built in benchmarks
  • 2020-03-21*[b8fb79a] plot data in x/y/z slices,add axis labels and grid
  • 2020-03-20 [d7e6203] add axis lable and scaling to volume viewer
  • 2020-03-14*[b91dc5a] update mcxstudio gui to support gpu mmc
  • 2020-02-18*[8c37911] adding pymcx written by Maxime Baillot as submodule
  • 2020-02-08 [ba78df5] add template to disable continuous medium support, close #89
  • 2020-01-28 [b7c1982] speed up cone beam photon launch, fix accuracy, close #86
  • 2020-01-25*[984b2a0] initial support for hybrid optical properties
  • 2019-11-19 [1c07b16] scale partial-path when getting det photon time and weight, close #83
  • 2019-08-08 [0bdbef6] allow to browse file folder on windows
  • 2019-07-26*[8a341ee] update mcxstudio to add the new flags
  • 2019-07-23 [e3b53dc] add 2d sample script
  • 2019-07-22*[c4baa84] output fluence/flux in replay, backport changes from mcxcl
  • 2019-05-24 [02efc62] bug fix for continuous varying media patch

Between 2019 and 2020, four new journal papers have been published as the
result of this project. Please see the full list at
http://mcx.space/#publication

Extended output data formats

MCX may produces several output files depending user's simulation settings.
Overall, MCX produces two types of outputs, 1) data accummulated within the
3D volume of the domain (volumetric output), and 2) data stored for each detected
photon (detected photon data).

Volumetric output

By default, MCX stores a 4D array denoting the fluence-rate at each voxel in
the volume, with a dimension of NxNyNz*Ng, where Nx/Ny/Nz are the voxel dimension
of the domain, and Ng is the total number of time gates. The output data are
stored in the format of single-precision floating point numbers. One may choose
to output different physical quantities by setting the -O option. When the
flag -X/--saveref is used, the output volume may contain the total diffuse
reflectance only along the background-voxels adjacent to non-zero voxels.
A negative sign is added for the diffuse reflectance raw output to distinguish
it from the fuence data in the interior voxels.

When photon-sharing (simultaneous simulations of multiple patterns) or photon-replay
(the Jacobian of all source/detector pairs) is used, the output array may be extended
to a 5D array, with the left-most/fastest index being the number of patterns Ns (in the
case of photon-sharing) or src/det pairs (in replay), denoted as Ns.

Several data formats can be used to store the 3D/4D/5D volumetric output.

mc2 files

The .mc2 format is simply a binary dump of the entire volumetric data output,
consisted of the voxel values (single-precision floating-point) of all voxels and
time gates. The file contains a continuous buffer of a single-precision (4-byte)
5D array of dimension Ns*Nx*Ny*Nz*Ng, with the fastest index being the left-most
dimension (i.e. column-major, similar to MATLAB/FORTRAN).

To load the mc2 file, one should call loadmc2.m and must provide explicitly
the dimensions of the data. This is because mc2 file does not contain the data
dimension information.

Saving to .mc2 volumetric file is depreciated as we are transitioning towards
JNIfTI/JData formatted outputs (.jnii).

nii files

The NIfTI-1 (.nii) format is widely used in neuroimaging and MRI community to
store and exchange ND numerical arrays. It contains a 352 byte header, followed
by the raw binary stream of the output data. In the header, the data dimension
information as well as other metadata is stored.

A .nii output file can be generated by using -F nii in the command line.

The .nii file is widely supported among data processing platforms, including
MATLAB and Python. For example

jnii files

The JNIfTI format represents the next-generation scientific data storage
and exchange standard and is part of the OpenJData initiative (http://openjdata.org)
led by the MCX author Dr. Qianqian Fang. The OpenJData project aims at developing
easy-to-parse, human-readable and easy-to-reuse data storage formats based on
the ubiquitously supported JSON/binary JSON formats and portable JData data annotation
keywords. In short, .jnii file is simply a JSON file with capability of storing
binary strongly-typed data with internal compression and built in metadata.

The format standard (Draft 1) of the JNIfTI file can be found at

https://github.com/fangq/jnifti

A .jnii output file can be generated by using -F jnii in the command line.

The .jnii file can be potentially read in nearly all programming languages
because it is 100% comaptible to the JSON format. However, to properly decode
the ND array with built-in compression, one should call JData compatible
libraries, which can be found at http://openjdata.org/wiki

Specifically, to parse/save .jnii files in MATLAB, you should use

To parse/save .jnii files in Python, you should use

In Python, the volumetric data is loaded as a dict object where data['NIFTIData']
is a NumPy ndarray object storing the volumetric data.

bnii files

The binary JNIfTI file is also part of the JNIfTI specification and the OpenJData
project. In comparison to text-based JSON format, .bnii files can be much smaller
and faster to parse. The .bnii format is also defined in the BJData specification

https://github.com/fangq/bjdata

and is the binary interface to .jnii. A .bnii output file can be generated by
using -F bnii in the command line.

The .bnii file can be potentially read in nearly all programming languages
because it was based on UBJSON (Universal Binary JSON). However, to properly decode
the ND array with built-in compression, one should call JData compatible
libraries, which can be found at http://openjdata.org/wiki

Specifically, to parse/save .bnii files in MATLAB, you should use

To parse/save .bnii files in Python, you should use

In Python, the volumetric data is loaded as a dict object where data['NIFTIData']
is a NumPy ndarray object storing the volumetric data.

Detected photon data

If one defines detectors, MCX is able to store a variety of photon data when a photon
is captured by these detectors. One can selectively store various supported data fields,
including partial pathlengths, exit position and direction, by using the -w/--savedetflag
flag. The storage of detected photon information is enabled by default, and can be
disabled using the -d flag.

The detected photon data are stored in a separate file from the volumetric output.
The supported data file formats are explained below.

mch files

The .mch file, or MC history file, is stored by default, but we strongly encourage users
to adpot the newly implemented JSON/.jdat format for easy data sharing.

The .mch file contains a 256 byte binary header, followed by a 2-D numerical array
of dimensions #savedphoton * #colcount as recorded in the header.

 typedef struct MCXHistoryHeader{
	char magic[4];                 // magic bits= 'M','C','X','H'
	unsigned int  version;         // version of the mch file format 
	unsigned int  maxmedia;        // number of media in the simulation 
	unsigned int  detnum;          // number of detectors in the simulation 
	unsigned int  colcount;        // how many output files per detected photon 
	unsigned int  totalphoton;     // how many total photon simulated 
	unsigned int  detected;        // how many photons are detected (not necessarily all saved) 
	unsigned int  savedphoton;     // how many detected photons are saved in this file 
	float unitinmm;                // what is the voxel size of the simulation 
	unsigned int  seedbyte;        // how many bytes per RNG seed
        float normalizer;              // what is the normalization factor
	int respin;                    // if positive, repeat count so total photon=totalphoton*respin; if negative, total number is processed in respin subset 
	unsigned int  srcnum;          // number of sources for simultaneous pattern sources 
	unsigned int  savedetflag;     // number of sources for simultaneous pattern sources 
	int reserved[2];               // reserved fields for future extension 
 } History;

When the -q flag is set to 1, the detected photon initial seeds are also stored
following the detected photon data, consisting of a 2-D byte array of #savedphoton * #seedbyte.

To load the mch file, one should call loadmch.m in MATLAB/Octave.

Saving to .mch history file is depreciated as we are transitioning towards
JSON/JData formatted outputs (.jdat).

jdat files

When -F jnii is specified, instead of saving the detected photon into the legacy .mch format,
a .jdat file is written, which is a pure JSON file. This file contains a hierachical data
record of the following JSON structure

 {
   "MCXData": {
       "Info":{
           "Version":
	   "MediaNum":
	   "DetNum":
	   ...
	   "Media":{
	      ...
	   }
       },
       "PhotonData":{
           "detid":
	   "nscat":
	   "ppath":
	   "mom":
	   "p":
	   "v":
	   "w0":
       },
       "Trajectory":{
           "photonid":
	   "p":
	   "w0":
       },
       "Seed":[
           ...
       ]
   }
 }

where "Info" is required, and other subfields are optional depends on users' input.
Each subfield in this file may contain JData 1-D or 2-D array constructs to allow
storing binary and compressed data.

Although .jdat and .jnii have different suffix, they are both JSON/JData files and
can be opened/written by the same JData compatible libraries mentioned above, i.e.

For MATLAB

For Python

In Python, the volumetric data is loaded as a dict object where data['MCXData']['PhotonData']
stores the photon data, data['MCXData']['Trajectory'] stores the trajectory data etc.

Photon trajectory data

For debugging and plotting purposes, MCX can output photon trajectories, as polylines,
when -D M flag is attached, or mcxlab is asked for the 5th output. Such information
can be stored in one of the following formats.

mct files

By default, MCX stores the photon trajectory data in to a .mct file MC trajectory, which
uses the same binary format as .mch but renamed as .mct. This file can be loaded to
MATLAB using the same loadmch.m function.

Using .mct file is depreciated and users are encouraged to migrate to .jdat file
as described below.

jdat files

When -F jnii is used, MCX merges the trajectory data with the detected photon and
seed data and saved as a JSON-compatible .jdat file. The overall structure of the
.jdat file as well as the relevant parsers can be found in the above section.

Assets 2
Loading