Critical bug fix: impact all pattern/pattern3d simulations since v2020, please update ASAP

Skip to first unread message

Qianqian Fang

Feb 27, 2024, 10:59:03 PMFeb 27

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 (, he discovered a serious bug in our pattern/pattern3d source code. We have documented and fixed this critical bug in the following ticket

- 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 (; 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

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 (

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.


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.

zhang haohui

Feb 29, 2024, 9:55:32 PMFeb 29
to mcx-users
Hello, Prof. Fang,

Thank you very much! It works well on my code now!

Best wishes

Reply all
Reply to author
0 new messages