Support disc sources with Lambertian direction sampling in 2D

[jolkkonen]

Summary

This change extends the existing disk source and Lambertian direction sampling to support 2D simulations, while preserving the existing 3D behaviour.

• In 3D, srctype = disk continues to sample initial photon positions uniformly over a disc.
• In 2D, srctype = disk now samples initial photon positions uniformly along a line segment centred at srcpos, with total length 2 × srcparam1.x.
• In 3D, srcdir.w = -Inf continues to use cosine-weighted (Lambertian) sampling over a hemisphere.
• In 2D, srcdir.w = -Inf now uses the corresponding cosine-weighted angular sampling over a semicircle.

Thus, the existing 3D source models are extended to their natural 2D counterparts: a disc becomes a line segment, and a hemisphere becomes a semicircle of possible unit propagation directions. No new source type is introduced.

This provides a way to model unit-strength diffuse boundary sources in 2D MCX simulations and facilitates comparisons with 2D diffusion-approximation (DA) simulations.

Validation

I compared the implementation against an independent 2D frequency-domain DA finite-element code. The boundary source in the DA model was represented by an indicator function over a boundary line segment, normalised by the segment length so that the total input flux was unity. The resulting complex photon fluence showed close agreement between MCX and the DA model in both amplitude and phase.

The modified MCX code was also successfully compiled with CUDA and tested through both the mcx executable and the pmcx Python interface.

A regression test was also added to test/testmcx.sh covering a 2D disk source with Lambertian direction sampling. The new test passes.

The full test/testmcx.sh suite was run. All tests passed except the existing colin27 volume-data JSON export check (--bench colin27 --dumpjson), which fails independently of this change.

Check List

Before you submit your pull-request, please verify and check all below items

• You have only modified the minimum number of lines that are necessary for the update; you should never add/remove white spaces to other lines that are irrelevant to the desired change.
• You have run make pretty (requires astyle in the command line) under the src/ folder and formatted your C/C++/CUDA source codes before every commit; similarly, you should run python3 -m black *.py (pip install black first) to reformat all modified Python codes, or run mh_style --fix . (pip install miss-hit first) at the top-folder to format all MATLAB scripts.
• Add sufficient in-code comments following the doxygen C format
• In addition to source code changes, you should also update the documentation (README.md, mcx_utils.c and/or mcxlab.m) if any command line flag was added or changed.

If your commits included in this PR contain changes that did not follow the above guidelines, you are strongly recommended to create a clean patch using git rebase and git cherry-pick to prevent in-compliant history from appearing in the upstream code.

Moreover, you are highly recommended to

• Add a test in the mcx/test/testmcx.sh script, following existing examples, to test the newly added feature; or add a MATLAB script under mcxlab/examples to gives examples of the desired outputs
• MCX's simulation speed is currently limited by the number of GPU registers. In your change, please consider minimizing the use of registers by reusing existing ones. CUDA compilers may not be able to optimize register counts, thus require manual optimization.
• Please create a github Issue first with detailed descriptions of the problem, testing script and proposed fixes, and link the issue with this pull-request

Please copy/paste the corresponding Issue's URL after the below dash

• Support disc sources with Lambertian direction sampling in 2D #273

[fangq]

hi @jolkkonen, mcx already supports Lambertian launch over most area sources by setting cfg.srcdir(4) to -inf, see https://github.com/fangq/mcx/blob/v2025.10/mcxlab/mcxlab.m#L80-L81

does your patch aims to the same source profile?

[jolkkonen]

Dear Dr. Fang/@fangq,

Yes, my modification is specifically for the cfg.srcdir(4) = -inf setting you referred to.

The intended source profile is the 2D analogue of the existing 3D cosine-weighted (Lambertian) profile.

My understanding is that the issue is specifically with the current implementation in 2D: the Lambertian branch uses the same 3D sampling procedure even when gcfg->is2d is set. The corresponding 2D cosine-weighted distribution requires a different angular sampling procedure, since the directions are confined to the simulation plane.

The patch adds this separate 2D sampling case under the Lambertian branch, while leaving the existing 3D Lambertian sampling unchanged.

Best regards,
Jaakko Olkkonen