Critical bug fix: impact all pattern/pattern3d simulations since v2020, please update ASAP
Qianqian Fang
hi everyone,
It is embarrassing, but we have found a bug in our mcx/mcxcl
code.
As my student Shijie Yan tried to debug the issue reported by Haohui Zhang in another thread (https://groups.google.com/g/mcx-users/c/KEH754XnJdY), he discovered a serious bug in our pattern/pattern3d source code. We have documented and fixed this critical bug in the following ticket
https://github.com/fangq/mcx/issues/212
- What version was affected
we found that this bug appeared in MCX and MCXCL v2020, could be
even earlier (although Shijie believes it was not there when we
completed photon-sharing between 2019-2020)
- What type of simulations were affected
all single-pattern simulations using 'pattern' or 'pattern3d' source type (excluding multi-pattern simulations using photon-sharing) with non-binary sources have been giving incorrect volumetric outputs (fluence/flux/energy)
photon-sharing based simulations, surface diffuse-reflectance outputs and detected photon outputs were not affected. other source types (fourier etc) were not affected.
simulations using binary (0-1) single pattern/pattern3d were not affected
- What happened
our code mistakenly multiplied the photons launch weight twice when saving fluence/energy deposition. This effectively make the simulated pattern squared. In other words, if you simulate a pattern [0.1,0.2;0.5,1], mcx/mcxcl effectively simulated [0.01,0.04;0.25,1].
we discovered the same issue in Aug 2020, but was only fixed it in diffuse reflectance outputs (https://github.com/fangq/mcx/commit/c04bff5d9a81c76fde688746fbbdae1ab4be9d7a); but somehow we missed the fluence output.
- How to fix
If you happen to use non-binary single-pattern simulation in your work, please immediately update your mcx/mcxlab/mcxcl/mcxlabcl to the Github version at
https://mcx.space/nightly/github/
We sincerely apologize for the inaccurate results mcx/mcxcl produced. Please rerun your simulations and verify if your results were affected.
If you use pmcx, I have already updated pmcx to v0.2.12 after fixing this bug. Please upgrade your pmcx from pypi (https://pypi.org/project/pmcx/).
For everyone else, you are also strongly encouraged to upgrade to the Github version, and rerun your simulations to verify it is not affected. I will put together a new release in the next few days and announce it in our mailing lists - since the release of v2023, we have added user-defined photon launch angle control, mua/mus/g/n float type, and various other non-critical bug fixes. I think it is time to ship all of these features to the users.
again, we are sorry for not noticing this bug until now, let me
know if you have any specific questions or notice any other
issues.
Qianqian
PS: Haohui - a good news is that the bug you reported was also
fixed by this bug - when you had 1/2 in a pattern, effectively mcx
simulated 1/4 after squaring, thus making the total absorbed
energy more than expected. After the patch, the energy
conservation restored. Please check.
