Definition of program options and problem domain configurations. More...

#include <stdio.h>
#include "vector_types.h"
#include "cjson/cJSON.h"

Include dependency graph for mmc_utils.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	MMC_medium
	This structure defines the optical properties for each medium. More...

struct	MMC_history
	Filer header data structure to .mch files to store detected photon data This header has a total of 256 bytes. More...

struct	MCXGPUInfo

struct	MMC_config
	This structure defines the problem settings (domain, filenames, session) More...

Macros
#define	MAX_FULL_PATH 2048
	< use multi-threading for running simulation on multiple GPUs More...

#define	MAX_PATH_LENGTH 1024

#define	MAX_SESSION_LENGTH 64

#define	MAX_CHECKPOINT 16

#define	DET_PHOTON_BUF 100000

#define	SEED_FROM_FILE -999

#define	MIN(a, b) ((a)<(b)?(a):(b))

#define	MMC_ERROR(id, msg) mcx_error(id,msg,__FILE__,__LINE__)

#define	MMC_INFO -99999

#define	MAX_DEVICE 256

#define	S_RED "\x1b[31m"

#define	S_GREEN "\x1b[32m"

#define	S_YELLOW "\x1b[33m"

#define	S_BLUE "\x1b[34m"

#define	S_MAGENTA "\x1b[35m"

#define	S_CYAN "\x1b[36m"

#define	S_BOLD "\x1b[1m"

#define	S_ITALIC "\x1b[3m"

#define	S_RESET "\x1b[0m"

#define	MMC_FPRINTF(fp, ...) fprintf(fp,__VA_ARGS__)

#define	MMCDEBUG(cfg, debugflag, outputstr)

Typedefs
typedef double	OutputType

typedef struct MMC_medium	medium

typedef struct MMC_history	history

typedef struct MCXGPUInfo	GPUInfo

typedef struct MMC_config	mcconfig

Enumerations
enum	TDebugLevel { dlMove = 1, dlTracing = 2, dlBary = 4, dlWeight = 8, dlDist = 16, dlTracingEnter = 32, dlTracingExit = 64, dlEdge = 128, dlAccum = 256, dlTime = 512, dlReflect = 1024, dlProgress = 2048, dlExit = 4096 }

enum	TRTMethod { rtPlucker, rtHavel, rtBadouel, rtBLBadouel, rtBLBadouelGrid }

enum	TMCMethod { mmMCX, mmMCML }

enum	TComputeBackend { cbSSE, cbOpenCL, cbCUDA }

enum	TSrcType { stPencil, stIsotropic, stCone, stGaussian, stPlanar, stPattern, stFourier, stArcSin, stDisk, stFourierX, stFourier2D, stZGaussian, stLine, stSlit }

enum	TOutputType { otFlux, otFluence, otEnergy, otJacobian, otWL, otWP }

enum	TOutputFormat { ofASCII, ofBin, ofNifti, ofAnalyze, ofMC2, ofTX3, ofJNifti, ofBJNifti }

enum	TOutputDomain { odMesh, odGrid }

enum	TDeviceVendor { dvUnknown, dvNVIDIA, dvAMD, dvIntel, dvIntelGPU }

enum	TMCXParent { mpStandalone, mpMATLAB }

enum	TBoundary { bcNoReflect, bcReflect, bcAbsorbExterior, bcMirror }

enum	TRayHitType { htNone, htInOut, htOutIn, htNoHitIn, htNoHitOut }

enum	TROIType { rtNone, rtEdge, rtNode, rtFace }

enum	TBJData { JDB_mixed, JDB_nulltype, JDB_noop, JDB_true, JDB_false, JDB_char, JDB_string, JDB_hp, JDB_int8, JDB_uint8, JDB_int16, JDB_int32, JDB_int64, JDB_single, JDB_double, JDB_array, JDB_object, JDB_numtypes, JDB_uint16 = 10, JDB_uint32, JDB_uint64 }

Functions
void	mcx_savedata (OutputType dat, size_t len, mcconfig cfg, int isref)
	Save volumetric output (fluence etc) to mc2 format binary file. More...

void	mcx_savenii (OutputType dat, size_t len, char name, int type32bit, int outputformatid, mcconfig *cfg)
	Save volumetric output (fluence etc) to an Nifty format binary file. More...

void	mcx_error (const int id, const char msg, const char file, const int linenum)
	Error reporting function. More...

void	mcx_loadconfig (FILE in, mcconfig cfg)
	Load user inputs from a .inp input file. More...

void	mcx_saveconfig (FILE in, mcconfig cfg)
	Save simulation settings to an inp file. More...

void	mcx_readconfig (char fname, mcconfig cfg)
	Read simulation settings from a configuration file (.inp or .json) More...

void	mcx_writeconfig (char fname, mcconfig cfg)
	Write simulation settings to an inp file. More...

void	mcx_initcfg (mcconfig *cfg)
	Initializing the simulation configuration with default values. More...

void	mcx_clearcfg (mcconfig *cfg)
	Clearing the simulation configuration data structure. More...

void	mcx_validatecfg (mcconfig *cfg)
	Validate all input fields, and warn incompatible inputs. More...

void	mcx_parsecmd (int argc, char argv[], mcconfig cfg)
	Main function to read user command line options. More...

void	mcx_usage (char exename, mcconfig cfg)
	Print MCX help information. More...

void	mcx_loadvolume (char filename, mcconfig cfg, int isbuf)

void	mcx_normalize (float field[], float scale, int fieldlen)
	Normalize the solution by multiplying a scaling factor. More...

int	mcx_readarg (int argc, char argv[], int id, void output, const char *type)
	Function to read a single parameter value followed by a command line option. More...

void	mcx_printlog (mcconfig cfg, char str)
	Print a message to the console or a log file. More...

int	mcx_remap (char *opt)
	Test if a long command line option is supported. More...

int	mcx_lookupindex (char key, const char index)
	Look up a single character in a string. More...

int	mcx_keylookup (char key, const char table[])
	Look up a string in a string list and return the index. More...

int	mcx_parsedebugopt (char *debugopt)
	Parse the debug flag in the letter format. More...

void	mcx_progressbar (float percent)
	Print a progress bar. More...

int	mcx_loadjson (cJSON root, mcconfig cfg)
	Load user inputs from a .json input file. More...

void	mcx_version (mcconfig *cfg)
	Print MCX software version. More...

int	mcx_loadfromjson (char jbuf, mcconfig cfg)
	Load a .json input file into memory. More...

void	mcx_prep (mcconfig *cfg)
	Preprocess configuration and set option dependency. More...

void	mcx_printheader (mcconfig *cfg)
	Print MCX output header. More...

void	mcx_cleargpuinfo (GPUInfo **gpuinfo)
	Reset and clear the GPU information data structure. More...

void	mcx_convertcol2row (unsigned int *vol, uint3 dim)
	Convert a column-major (MATLAB/FORTRAN) array to a row-major (C/C++) array. More...

void	mcx_convertcol2row4d (unsigned int *vol, uint4 dim)
	Convert a column-major (MATLAB/FORTRAN) array to a row-major (C/C++) array. More...

void	mcx_savejdata (char filename, mcconfig cfg)
	Save simulation settings to an inp file. More...

int	mcx_jdataencode (void vol, int ndim, uint dims, char type, int byte, int zipid, void obj, int isubj, mcconfig *cfg)
	Export an ND volumetric image to JSON/JData encoded construct. More...

int	mcx_jdatadecode (void *vol, int ndim, uint dims, int maxdim, char type, cJSON obj, mcconfig *cfg)
	Decode an ND array from JSON/JData construct and output to a volumetric array. More...

void	mcx_savejnii (OutputType vol, int ndim, uint dims, float voxelsize, char name, int isfloat, mcconfig *cfg)
	Save volumetric output (fluence etc) to a JNIfTI/JSON/JData format file. More...

void	mcx_savebnii (OutputType vol, int ndim, uint dims, float voxelsize, char name, int isfloat, mcconfig *cfg)
	Save volumetric output (fluence etc) to a binary JNIfTI/JSON/JData format file. More...

void	mcx_savejdet (float ppath, void seeds, uint count, int doappend, mcconfig *cfg)
	Save detected photon data to mch format binary file. More...

void	mcx_fflush (FILE *out)
	Flush command line output. More...

int	mexPrintf (const char *format,...)

Detailed Description

Definition of program options and problem domain configurations.

Macro Definition Documentation

◆ DET_PHOTON_BUF

#define DET_PHOTON_BUF 100000

initialize number of detected photons

◆ MAX_CHECKPOINT

#define MAX_CHECKPOINT 16

max number of photon save points

◆ MAX_FULL_PATH

#define MAX_FULL_PATH 2048

< use multi-threading for running simulation on multiple GPUs

max characters in a full file name string

◆ MAX_PATH_LENGTH

#define MAX_PATH_LENGTH 1024

max characters in a full file name string

◆ MAX_SESSION_LENGTH

#define MAX_SESSION_LENGTH 64

max session name length

◆ MIN

#define MIN	(	a,
		b
	)	((a)<(b)?(a):(b))

macro to get the min values of two numbers

◆ MMCDEBUG

#define MMCDEBUG	(	cfg,
		debugflag,
		outputstr
	)

Value:

{\
        if((cfg)->debuglevel & (debugflag)) {\
            MMC_FPRINTF outputstr ;\
            fflush((cfg)->flog);\
        }\
    }

◆ SEED_FROM_FILE

#define SEED_FROM_FILE -999

special flag indicating to load seeds from history file

Function Documentation

◆ mcx_clearcfg()

void mcx_clearcfg ( mcconfig * cfg )

Clearing the simulation configuration data structure.

Destructor of the simulation configuration, delete all dynamically allocated members

Here is the call graph for this function:

◆ mcx_cleargpuinfo()

void mcx_cleargpuinfo ( GPUInfo ** gpuinfo )

Reset and clear the GPU information data structure.

Clearing the GPU information data structure

◆ mcx_convertcol2row()

void mcx_convertcol2row	(	unsigned int **	vol,
		uint3 *	dim
	)

Convert a column-major (MATLAB/FORTRAN) array to a row-major (C/C++) array.

Parameters

[in,out]	vol	a 3D array (wrapped in 1D) to be converted
[in]	dim	the dimensions of the 3D array

◆ mcx_convertcol2row4d()

void mcx_convertcol2row4d	(	unsigned int **	vol,
		uint4 *	dim
	)

Convert a column-major (MATLAB/FORTRAN) array to a row-major (C/C++) array.

Parameters

[in,out]	vol	a 3D array (wrapped in 1D) to be converted
[in]	dim	the dimensions of the 3D array

◆ mcx_error()

void mcx_error	(	const int	id,
		const char *	msg,
		const char *	file,
		const int	linenum
	)

Error reporting function.

Parameters

[in]	id	a single integer for the types of the error
[in]	msg	the error message string
[in]	file	the unit file name where this error is raised
[in]	linenum	the line number in the file where this error is raised

Here is the call graph for this function:

◆ mcx_fflush()

void mcx_fflush ( FILE * out )

Flush command line output.

Parameters

[in] out the stream to be flushed

Here is the call graph for this function:

◆ mcx_initcfg()

void mcx_initcfg ( mcconfig * cfg )

Initializing the simulation configuration with default values.

Constructor of the simulation configuration, initializing all field to default values

◆ mcx_jdatadecode()

int mcx_jdatadecode	(	void **	vol,
		int *	ndim,
		uint *	dims,
		int	maxdim,
		char **	type,
		cJSON *	obj,
		mcconfig *	cfg
	)

Decode an ND array from JSON/JData construct and output to a volumetric array.

The JData specification defines a portable way to encode and share volumetric ND arrays and other complex data structures, such as trees, graphs and tables. This function is capable of importing any ND numerical arrays in the JData construct in to a generic array, permitting data decompression and base64 decoding.

Parameters

[in]	vol	a pointer that points to the ND array buffer
[in]	ndim	the number of dimensions
[in]	dims	an integer pointer that points to the dimensional vector
[in]	type	a string of JData data types, such as "uint8" "float32", "int32" etc
[in]	byte	number of byte per voxel
[in]	zipid	zip method: 0:zlib,1:gzip,2:base64,3:lzma,4:lzip,5:lz4,6:lz4hc
[in]	obj	a pre-created cJSON object to store the output JData fields

◆ mcx_jdataencode()

int mcx_jdataencode	(	void *	vol,
		int	ndim,
		uint *	dims,
		char *	type,
		int	byte,
		int	zipid,
		void *	obj,
		int	isubj,
		mcconfig *	cfg
	)

Export an ND volumetric image to JSON/JData encoded construct.

The JData specification defines a portable way to encode and share volumetric ND arrays and other complex data structures, such as trees, graphs and tables. This function is capable of exporting any ND numerical arrays into a JData construct, permitting data compression and base64 encoding.

Parameters

[in]	vol	a pointer that points to the ND array buffer
[in]	ndim	the number of dimensions
[in]	dims	an integer pointer that points to the dimensional vector
[in]	type	a string of JData data types, such as "uint8" "float32", "int32" etc
[in]	byte	number of byte per voxel
[in]	zipid	zip method: 0:zlib,1:gzip,2:base64,3:lzma,4:lzip,5:lz4,6:lz4hc
[in]	obj	a pre-created cJSON object to store the output JData fields

◆ mcx_keylookup()

int mcx_keylookup	(	char *	key,
		const char *	table[]
	)

Look up a string in a string list and return the index.

Parameters

[in]	key	string to be looked up
[out]	table	the dictionary where the string is searched

Returns: if found, return the index of the string in the dictionary, otherwise -1.

◆ mcx_loadconfig()

void mcx_loadconfig	(	FILE *	in,
		mcconfig *	cfg
	)

Load user inputs from a .inp input file.

This function loads user input from a simple text input format in a .inp extension

Parameters

[in]	in	file handle to the .inp file
[in]	cfg	simulation configuration

◆ mcx_loadfromjson()

int mcx_loadfromjson	(	char *	jbuf,
		mcconfig *	cfg
	)

Load a .json input file into memory.

This function loads a JSON file using cJSON

Parameters

[out]	jbuf	json data structure pointer
[in]	cfg	simulation configuration

Here is the call graph for this function:

◆ mcx_loadjson()

int mcx_loadjson	(	cJSON *	root,
		mcconfig *	cfg
	)

Load user inputs from a .json input file.

This function loads user input from a JSON format in a .json extension

Parameters

[out]	root	json data structure pointer
[in]	cfg	simulation configuration

◆ mcx_lookupindex()

int mcx_lookupindex	(	char *	key,
		const char *	index
	)

Look up a single character in a string.

Parameters

[in]	key	character to be looked up
[out]	index	the dictionary string where the char is searched

Returns: if found, return 0; otherwise, return 1

◆ mcx_normalize()

void mcx_normalize	(	float	field[],
		float	scale,
		int	fieldlen
	)

Normalize the solution by multiplying a scaling factor.

Parameters

[in,out]	field	volumetric data before normalization
[in]	scale	the scaling factor (or normalization factor) to be applied
[in]	fieldlen	the length (floating point) of elements in the volume

◆ mcx_parsecmd()

void mcx_parsecmd	(	int	argc,
		char *	argv[],
		mcconfig *	cfg
	)

Main function to read user command line options.

This function process user command line inputs and parse all short and long options.

Parameters

[in]	argc	the number of total command line parameters
[in]	argv	the pointer to all command line options
[in]	cfg	simulation configuration

Here is the call graph for this function:

◆ mcx_parsedebugopt()

int mcx_parsedebugopt ( char * debugopt )

Parse the debug flag in the letter format.

The debug flag following the -D can be either a string format, or numerical format. This function converts the string debug flags into number format

Parameters

[in] debugopt string following the -D parameter

Returns: debugflag: the numerical format of the debug flag

◆ mcx_prep()

void mcx_prep ( mcconfig * cfg )

Preprocess configuration and set option dependency.

This function preprocess the user input and set dependent flags

Parameters

[in,out] cfg simulation configuration

◆ mcx_printheader()

void mcx_printheader ( mcconfig * cfg )

Print MCX output header.

Parameters

[in] cfg simulation configuration

◆ mcx_printlog()

void mcx_printlog	(	mcconfig *	cfg,
		char *	str
	)

Print a message to the console or a log file.

Parameters

[in]	cfg	simulation configuration
[in]	str	a string to be printed

◆ mcx_progressbar()

void mcx_progressbar ( float percent )

Print a progress bar.

When -D P is specified, this function prints and update a progress bar.

Parameters

[in]	n	the number of completed photons
[in]	cfg	simulation configuration

◆ mcx_readarg()

int mcx_readarg	(	int	argc,
		char *	argv[],
		int	id,
		void *	output,
		const char *	type
	)

Function to read a single parameter value followed by a command line option.

This function reads different types of parameter values following a command line option.

Parameters

[in]	argc	the number of total command line parameters
[in]	argv	the pointer to all command line options
[in]	id	which parameter to be parsed
[out]	output	the pointer to which the parsed value to be written
[in]	type	the type of data support char, int, float, string, bytenumlist, floatlist

◆ mcx_readconfig()

void mcx_readconfig	(	char *	fname,
		mcconfig *	cfg
	)

Read simulation settings from a configuration file (.inp or .json)

Parameters

[in]	fname	the name of the input file (.inp or .json)
[in]	cfg	simulation configuration

Here is the call graph for this function:

◆ mcx_remap()

int mcx_remap ( char * opt )

Test if a long command line option is supported.

This function returns 1 if a long option is found, and 0 otherwise

Parameters

[in] opt the long command line option string

◆ mcx_savebnii()

void mcx_savebnii	(	OutputType *	vol,
		int	ndim,
		uint *	dims,
		float *	voxelsize,
		char *	name,
		int	isfloat,
		mcconfig *	cfg
	)

Save volumetric output (fluence etc) to a binary JNIfTI/JSON/JData format file.

Parameters

[in]	dat	volumetric data to be saved
[in]	len	total byte length of the data to be saved
[in]	name	output file name (will append '.nii')
[in]	type32bit	type of the data, only support 32bit per record
[in]	outputformatid	decide if save as nii or analyze format
[in]	cfg	simulation configuration

◆ mcx_saveconfig()

void mcx_saveconfig	(	FILE *	out,
		mcconfig *	cfg
	)

Save simulation settings to an inp file.

Parameters

[in]	out	handle to the output file
[in]	cfg	simulation configuration

◆ mcx_savedata()

void mcx_savedata	(	OutputType *	dat,
		size_t	len,
		mcconfig *	cfg,
		int	isref
	)

Save volumetric output (fluence etc) to mc2 format binary file.

Parameters

[in]	dat	volumetric data to be saved
[in]	len	total byte length of the data to be saved
[in]	cfg	simulation configuration

◆ mcx_savejdata()

void mcx_savejdata	(	char *	filename,
		mcconfig *	cfg
	)

Save simulation settings to an inp file.

Parameters

[in]	out	handle to the output file
[in]	cfg	simulation configuration

◆ mcx_savejdet()

void mcx_savejdet	(	float *	ppath,
		void *	seeds,
		uint	count,
		int	doappend,
		mcconfig *	cfg
	)

Save detected photon data to mch format binary file.

Parameters

[in]	ppath	buffer pointing to the detected photon data (partial path etc)
[in]	seeds	buffer pointing to the detected photon seed data
[in]	count	number of detected photons
[in]	doappend	flag if the new data is appended or write from the begining
[in]	cfg	simulation configuration

Here is the call graph for this function:

◆ mcx_savejnii()

void mcx_savejnii	(	OutputType *	vol,
		int	ndim,
		uint *	dims,
		float *	voxelsize,
		char *	name,
		int	isfloat,
		mcconfig *	cfg
	)

Save volumetric output (fluence etc) to a JNIfTI/JSON/JData format file.

Parameters

[in]	dat	volumetric data to be saved
[in]	len	total byte length of the data to be saved
[in]	name	output file name (will append '.nii')
[in]	type32bit	type of the data, only support 32bit per record
[in]	outputformatid	decide if save as nii or analyze format
[in]	cfg	simulation configuration

Here is the call graph for this function:

◆ mcx_savenii()

void mcx_savenii	(	OutputType *	dat,
		size_t	len,
		char *	name,
		int	type32bit,
		int	outputformatid,
		mcconfig *	cfg
	)

Save volumetric output (fluence etc) to an Nifty format binary file.

Parameters

[in]	dat	volumetric data to be saved
[in]	len	total byte length of the data to be saved
[in]	name	output file name (will append '.nii')
[in]	type32bit	type of the data, only support 32bit per record
[in]	outputformatid	decide if save as nii or analyze format
[in]	cfg	simulation configuration

◆ mcx_usage()

void mcx_usage	(	char *	exename,
		mcconfig *	cfg
	)

Print MCX help information.

Parameters

[in] exename path and name of the mcx executable

Here is the call graph for this function:

◆ mcx_validatecfg()

void mcx_validatecfg ( mcconfig * cfg )

Validate all input fields, and warn incompatible inputs.

Perform self-checking and raise exceptions or warnings when input error is detected

Parameters

[in,out] cfg the simulation configuration structure

◆ mcx_version()

void mcx_version ( mcconfig * cfg )

Print MCX software version.

Parameters

[in] cfg simulation configuration

◆ mcx_writeconfig()

void mcx_writeconfig	(	char *	fname,
		mcconfig *	cfg
	)

Write simulation settings to an inp file.

Parameters

[in]	fname	the name of the output file
[in]	cfg	simulation configuration

Here is the call graph for this function:

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DET_PHOTON_BUF

◆ MAX_CHECKPOINT

◆ MAX_FULL_PATH

◆ MAX_PATH_LENGTH

◆ MAX_SESSION_LENGTH

◆ MIN

◆ MMCDEBUG

◆ SEED_FROM_FILE

Function Documentation

◆ mcx_clearcfg()

◆ mcx_cleargpuinfo()

◆ mcx_convertcol2row()

◆ mcx_convertcol2row4d()

◆ mcx_error()

◆ mcx_fflush()

◆ mcx_initcfg()

◆ mcx_jdatadecode()

◆ mcx_jdataencode()

◆ mcx_keylookup()

◆ mcx_loadconfig()

◆ mcx_loadfromjson()

◆ mcx_loadjson()

◆ mcx_lookupindex()

◆ mcx_normalize()

◆ mcx_parsecmd()

◆ mcx_parsedebugopt()

◆ mcx_prep()

◆ mcx_printheader()

◆ mcx_printlog()

◆ mcx_progressbar()

◆ mcx_readarg()

◆ mcx_readconfig()

◆ mcx_remap()

◆ mcx_savebnii()

◆ mcx_saveconfig()

◆ mcx_savedata()

◆ mcx_savejdata()

◆ mcx_savejdet()

◆ mcx_savejnii()

◆ mcx_savenii()

◆ mcx_usage()

◆ mcx_validatecfg()

◆ mcx_version()

◆ mcx_writeconfig()