Monte Carlo source updates

[hayakawa16]

We have an existing branch jr-211029-source-updates that is not associated with an issue. I'd like this issue to be the one that documents why this branch is needed.

From my recollection, these source updates were to make sure that "Lambertian" distributions were applied appropriately. We currently have "Isotropic" sources, however not an option for Lambertian distributions.
@janakarana please add to this issue if you remember more things we wanted to update.

Proposed solution: added Lambertian distribution classes for all sources that have an existing Isotropic distribution class.

[hayakawa16]

I just met with @janakarana and came to the following corrections:

1. For source types that have an existing Isotropic source class (e.g. Line, Point, etc.), add a Lambertian source class.
2. For source types that have an existing Lambertian source class (e.g. SurfaceEmittingBulkSources CylindricalFiber, Spherical, etc.), add an Isotropic source class.
3. For the "Custom..." classes which assume a Lambertian distribution, add an option to specify an Isotropic distribution. So as to not break existing code, I will create an overload for now.

Please let me know any feedback. In the meantime, I'll get started.

[janakarana]

@hayakawa16,
Following up on our meeting yesterday, I have been been thinking about current emission profiles of new LED sources. Should we modify the code to accommodate future emission profile requirements? If so, this likely means we'll also need to allow for the input of custom emission profiles.
To achieve this, we must allow users to select an emission profile: Isotropic, Lambertian, or Custom. The emission profile can be represented using either a single sphere or two hemispheres (forward and backward). Photon direction is determined by sampling the chosen emission profile. Uniform sampling can be used for the Isotropic profile, and cosine-weighted sampling can be used for the Lambertian profile. We need to determine the best way for users to input their custom emission profiles.

[hayakawa16]

@janakarana, like this feedback! On the branch, I have created a SourceAngularDistributionType that currently has Isotropic and Lambertian as options. This type will be sent into the source input definition and the code can then be expanded to handle other types of options. I think my current implementation will handle expansion okay.

I am planning to expand the code for one source type for now, LineSources, applying the 3 options listed in my post above. I am doing a bit of code cleanup and I would like to provide references in the xml comments referencing the algorithms for Isotropic and Lambertian in SourceToolbox. After I have LineSources complete, I plan to have a review of what I've done. After the review, I can update the rest of the sources in a consistent manner.

[hayakawa16]

With help from @janakarana we have determined correct way to sample Lambertian source angular distribution. See attached notes. The first page of the notes is kind of a detour because most of the descriptions out on the web have to do with Lambertian reflectance and I was interested in Lambertian source emission. The second page gets to the details of how Isotropic and Lambertian angular distributions are sampled.

notes_isotropic_vs_lambertian.pdf

[hayakawa16]

I have this crazy idea about being able to "view" source distributions. In the past, I've added Console.WriteLine code in the Source Base classes in GetNextPhoton method right before the
"photon=new Photon(finalPosition,finalDirection...);"
that outputs finalPosition.X,Y,Z and finalDirection.Ux,Uy,Uz.
Then I wrote MATLAB code to read this output and plot the source starting locations and directions (using a unit vector). It gives the user a validation that what they spelled out in the infile is actually what they had in mind.

I don't want to add Console.WriteLines to our repository code, however I'd like to achieve the end result. Any ideas on how this could be achieved?

[hayakawa16]

With @janakarana's help we have derived the equations and have formed a plan for the updates to this branch:

1. Add a method to SourceToolbox.cs that handles the generation of an nth order Lambert Source. On the attached set of notes, it shows the derivations for this nth order source with n=0 -> Isotropic, n=1 -> Lambertian, n>1 -> higher order Lambert Source (used by LED sources).
2. Add new classes to accommodate Lambert nth order sources to:
   LambertPointSource
   LambertLineSource
   LambertCircularSource
   LambertEllipticalSource
   LambertRectangularSource
3. Add unit tests to validate the results of these new classes.

Note that all Isotropic capabilities in SourceToolbox will remain as is.

Isotropic_Lambertian_Feb18_2025.pdf

[hayakawa16]

Since I am adding constructors to existing Lambertian sources with an added parameter and creating new Lambertian sources, I developed a semi-guide for ordering of parameters in a SourceInput call:

1. spatial ranges, i.e. for LambertianRectangularSourceInput: rectLengthX, rectLengthY
2. spatial descriptors, i.e. SourceProfile
3. angular ranges, i.e. polarAngleEmissionRange, azimuthalAngleEmissionRange
4. angular descriptors, i.e. Lambert order of angular distribution
5. Once the photon location and direction determined, all twist and translation actions that change this:
   a) newDirectionOfPrincipalSourceAxis
   b) translationFromOrigin
   c) beamRotationFromInwardNormal
6. initialTissueRegionIndex
   Let me know if something else makes sense.

[hayakawa16]

I'm close to creating a PR. Getting back to my idea of plotting the initial unit directionals for say 1000 photons for any given source to "view" the source distributions. I've thought of two ideas:

1. We currently have a SourceInputProvider class. This has about 8 sources defined and is called by SourceInputProvider unit tests. These two classes do not include the full list of possible source types. Side comment: I might expand this list so that most source types tested. To view the sources, we could have new way to call SourceInputProvider (much like geninfiles calls SimulationInputProvider). This would not only create a snippet of how to define the source within an infile, it would optionally go on to call CreateSource, then GetNextPhoton to obtain initial Position and Direction, and output this data for 1000 photons. I have scripts that can plot this data using MATLAB. To invoke this process we could have a) an option to MCCL, or b) a new app say Vts.MonteCarlo.SourceInputProvider.
2. The unit tests for the sources are validated by MATLAB code in matlab/test/monte_carlo. These MATLAB scripts generate the validation values for the C# unit tests. I could write a MATLAB script that calls these existing scripts to output 1000 photons Position and Direction and plot the results.

Option 2) is easier to generate. The drawbacks to 2) is that it isn't really calling the C# code, and although this code is in GitHub isn't obvious to the user to use.
Option 1) would be obvious to the user, and could be expanded to be some sort of commandline app that prompts the user for Source, Tissue, Detector inputs and generates the infile for the user, something that users have asked for.

Any thoughts? BTW this activity would be performed under another issue. Since I've immersed myself into the mechanisms of the MCCL sources during this issue, it gave me time to think about this.