[forward] add pmcxcl and user-defined input

[fangq]

@avolu and @emiddell, I took a look at the pmcx integration and did some tweaking, summarized below

• I added pmcxcl (https://pypi.org/project/pmcxcl/) as an optional alternative to pmcx, can be able via input flag. pmcxcl can run on the CPU as well as on GPU, as long as the OpenCL runtime is installed.
• positional parameters are allowed to compute_fluence_mcx() so that users can overwrite the default cfg settings at runtime, for example compute_fluence_mcx(nphoton=1e3, gpuid=2, tend=10e-9, tstep=10e-9, cuda=True)
• absorbed nphoton to the positional parameters **kwargs
• deleted seed setting - because if you randomize the seed, the result is not repeatable anymore, if you don't set it, mcx will set a default seed
• deleted the following line - I don't think it is needed (the output is already set to fluence, and the normalization is already applied): fangq@97e41cf#diff-c3cc59e68697af1f05a58f6208b1201c8e3a1d572d3b67b13f1017a23eb0ccd0L682

I tried to test this on my laptop, but it only has an intel gpu, pmcxcl seems to run but I need more test back home.

I am wondering if you use any formatter for the code styles, such as black or blue? I am happy to reformat my patch.

[fangq]

converting to draft for now. will do some test on CPU and GPU backend before removing the draft state.

[emiddell]

Hi @fangq, thank your for the patch. It is very much appreciated.

Regarding the normalization: we followed here the implementation in AtlasViewer, which applied this normalizatoin although cfg.outputtype is set to 'fluence'. If this is already done in mcx, we'll should ask for change in AtlasViewer, too.

We use ruff for code formatting. It gets its configuration from the pyproject.toml.

[fangq]

interesting, thanks for the link to the AtlasViewer code - looks like @dboas made the commit.

when cfg.outputtype='fluence', the normalizer (result["stat"]["normalizer"]) returned by mcxlab was computed here, which has the below form

scale = (cfg->tstep * cfg->unitinmm) / (cfg->energytot * Vvox * cfg->tstep) 
      = 1 / ( nphoton * cfg->unitinmm^2 )

this multiplicative scaling factor converts the raw energy-deposition in each voxel (unitless or J) to fluence as a result of a unitary source - so that the output unit is (1/mm^2) , which matches that of fluence.

when you set cfg.outputtype='flux' which is default, then, scale = 1 / ( nphoton * cfg->unitinmm^2 * cfg->tstep ), this makes the output fluence-rate, which has a unit of 1/(mm^2*s)

@dboas, let's redo the conversion between mcx and tMCimg and figure out the right scalar - I was under the impression that it should not need any additional scaling factor if tMCimg solutions are normalized to produce the "Green's function" as mcx does.

because the initial version of mcx also uses the tMCimg's way to deposit energy (in 2010ish, it has shifted to depositing energy-loss instead of current weight), if tMCimg's raw output were normalized according to the Eq 1 in the mcx paper, then, it should produce the Green's function of fluence-rate, and match that of the 'flux' output of mcxlab