mcxlab.cpp File Reference

mex function for MCXLAB More...

#include <stdio.h>
#include <string.h>
#include <exception>
#include <math.h>
#include "mex.h"
#include "mcx_const.h"
#include "mcx_utils.h"
#include "mcx_core.h"
#include "mcx_shapes.h"

Include dependency graph for mcxlab.cpp:

Macros
#define	RAND_WORD_LEN   4
#define	GET_1ST_FIELD(x, y)   if(strcmp(name,#y)==0) {double *val=mxGetPr(item);x->y=val[0];printf("mcx.%s=%g;\n",#y,(float)(x->y));}
#define	GET_ONE_FIELD(x, y)   else GET_1ST_FIELD(x,y)
#define	GET_VEC3_FIELD(u, v)
#define	GET_VEC34_FIELD(u, v)
#define	GET_VEC4_FIELD(u, v)
#define	SET_GPU_INFO(output, id, v)   mxSetField(output,id,#v,mxCreateDoubleScalar(gpuinfo[i].v));

Typedefs
typedef mwSize	dimtype

Functions
void	mcx_set_field (const mxArray *root, const mxArray *item, int idx, Config *cfg)
	Function to parse one subfield of the input structure. More...
void	mcxlab_usage ()
	Print a brief help information if nothing is provided.
void	mexFunction (int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
	Mex function for the MCX host function for MATLAB/Octave This is the master function to interface all MCX features inside MATLAB. In MCXLAB, all inputs are read from the cfg structure, which contains all simuation parameters and data. More...
int	mcx_throw_exception (const int id, const char *msg, const char *filename, const int linenum)
	Error reporting function in the mex function, equivallent to mcx_error in binary mode. More...
void	mcx_matlab_flush ()
	Force matlab refresh the command window to print all buffered messages.

Variables
float *	detps = NULL
int	dimdetps [2] = {0, 0}
	buffer to receive data from cfg.detphotons field
int	seedbyte = 0
	dimensions of the cfg.detphotons array

Detailed Description

mex function for MCXLAB

Macro Definition Documentation

GET_1ST_FIELD

#define GET_1ST_FIELD	(		x,
			y
	)		if(strcmp(name,#y)==0) {double *val=mxGetPr(item);x->y=val[0];printf("mcx.%s=%g;\n",#y,(float)(x->y));}

Macro to read the 1st scalar cfg member

GET_ONE_FIELD

#define GET_ONE_FIELD	(		x,
			y
	)		else GET_1ST_FIELD(x,y)

Macro to read one scalar cfg member

GET_VEC34_FIELD

#define GET_VEC34_FIELD	(		u,
			v
	)

Value:

else if(strcmp(name,#v)==0) {double *val=mxGetPr(item);u->v.x=val[0];u->v.y=val[1];u->v.z=val[2];if(mxGetNumberOfElements(item)==4) u->v.w=val[3];\
        printf("mcx.%s=[%g %g %g %g];\n",#v,(float)(u->v.x),(float)(u->v.y),(float)(u->v.z),(float)(u->v.w));}

Macro to read one 3- or 4-element vector member of cfg

GET_VEC3_FIELD

#define GET_VEC3_FIELD	(		u,
			v
	)

Value:

else if(strcmp(name,#v)==0) {double *val=mxGetPr(item);u->v.x=val[0];u->v.y=val[1];u->v.z=val[2];\
        printf("mcx.%s=[%g %g %g];\n",#v,(float)(u->v.x),(float)(u->v.y),(float)(u->v.z));}

Macro to read one 3-element vector member of cfg

GET_VEC4_FIELD

#define GET_VEC4_FIELD	(		u,
			v
	)

Value:

else if(strcmp(name,#v)==0) {double *val=mxGetPr(item);u->v.x=val[0];u->v.y=val[1];u->v.z=val[2];u->v.w=val[3];\
        printf("mcx.%s=[%g %g %g %g];\n",#v,(float)(u->v.x),(float)(u->v.y),(float)(u->v.z),(float)(u->v.w));}

Macro to read one 4-element vector member of cfg

RAND_WORD_LEN

#define RAND_WORD_LEN   4

number of Words per RNG state

SET_GPU_INFO

#define SET_GPU_INFO	(		output,
			id,
			v
	)		mxSetField(output,id,#v,mxCreateDoubleScalar(gpuinfo[i].v));

Macro to output GPU parameters as field

Function Documentation

mcx_set_field()

void mcx_set_field	(	const mxArray *	root,
		const mxArray *	item,
		int	idx,
		Config *	cfg
	)

Function to parse one subfield of the input structure.

This function reads in all necessary information from the cfg input structure. it can handle single scalar inputs, short vectors (3-4 elem), strings and arrays.

Parameters

[in]	root	the cfg input data structure
[in]	item	the current element of the cfg input data structure
[in]	idx	the index of the current element (starting from 0)
[out]	cfg	the simulation configuration structure to store all input read from the parameters

float to half conversion https://stackoverflow.com/questions/3026441/float32-to-float16/5587983#5587983 https://gamedev.stackexchange.com/a/17410 (for denorms)

mcx_throw_exception()

int mcx_throw_exception	(	const int	id,
		const char *	msg,
		const char *	filename,
		const int	linenum
	)

Error reporting function in the mex function, equivallent to mcx_error in binary mode.

Parameters

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

mexFunction()

void mexFunction	(	int	nlhs,
		mxArray *	plhs[],
		int	nrhs,
		const mxArray *	prhs[]
	)

Mex function for the MCX host function for MATLAB/Octave This is the master function to interface all MCX features inside MATLAB. In MCXLAB, all inputs are read from the cfg structure, which contains all simuation parameters and data.

If no input is given for this function, it prints help information and return.

If a single string is passed, and if this string is 'gpuinfo', this function returns the list of GPUs on this host and return.

If a structure is passed to this function, a simulation will be launched.

Find out information about input and output.

how many subfield in the input cfg data structure

if input is a struct array, each element of the struct is a simulation

The function can return 1-5 outputs (i.e. the LHS)

Loop over each element of the struct if it is an array, each element is a simulation

Initialize cfg with default values first

Read each struct element from input and set value to the cfg configuration

Overwite the output flags using the number of output present

issave2pt defualt is 1, but allow users to manually disable, auto disable only if there is no output

save detected photon data to the 2nd output if present

save detected photon seeds to the 4th output if present

Validate all input fields, and warn incompatible inputs

One must define the domain and properties

One must also choose one of the GPUs

Initialize all buffers necessary to store the output variables

Start multiple threads, one thread to run portion of the simulation on one CUDA GPU, all in parallel

Enclose all simulation calls inside a try/catch construct for exception handling

Call the main simulation host function to start the simulation

If error is detected, gracefully terminate the mex and return back to MATLAB

if 5th output presents, output the photon trajectory data

if the 4th output presents, output the detected photon seeds

if the 3rd output presents, output the detector-masked medium volume, similar to the –dumpmask flag

if the 2nd output presents, output the detected photon partialpath data

if the 1st output presents, output the fluence/energy-deposit volume data

also return the run-time info in outut.runtime

return the total simulated photon number

return the total simulated energy

return the total absorbed energy

return the normalization factor

return the voxel size unitinmm

return the relative workload between multiple GPUs

return the final optical properties for polarized MCX simulation

Clear up simulation data structures by calling the destructors

Here is the call graph for this function: