Summary¶

Dataset modules contain templates for rendering reference simulation scripts for a number of different sample, source and detector configurations. The reference scripts can be rendered by invoking the appropriate functions or by running the modules. There are several parameters that can be used to control the rendering process when running the modules from a command line:

-o
Option can be used to specify a target directory for the rendered scripts and the related datasets. The current working directory is used by default. The scripts will be rendered into run subdirectory and the dataset produced by the reference simulation scripts will be saved into the data directory.
-d
Option can be used to specify a default OpenCL device that will be used to run the simulations. This value is matched against the vendor and device name (or part of it). The first available OpenCL-enabled GPU device is used by default. Note that the target OpenCL device can be also selected by setting the CL_DEVICE environment variable before running the rendered script.
-i
Option can be used to specify the index of the OpenCL device to use. This option is useful when multiple identical devices are installed. Note that the index is zero-based and defaults to 0. Note that the target OpenCL device index can be also selected by setting the CL_INDEX environment variable before running the rendered script.
-v
Flag enables verbose output.
-t
Flag performs a test run and implicitly enables verbose output. Scripts will be rendered but no files will be written to the target directory. The output will show the full paths of the generated scripts.

The following example will render all the available scripts into the current working directory and produce a verbose output:

python -m xopto.dataset.render.all -v

Details¶

The following sections provide details on different reference datasets and instructions for rendering / generating scripts that will compute these datasets. At the end of each section there is a breakdown of the directory tree and naming conventions that are used to organize the datasets.

MCML comparison datasets¶

Module xopto.dataset.render.mcml_comparison => run/mcml_comparison/

Renders scripts that will produce datasets for comparison with the MCML package. These datasets are based on Hg scattering phase function, a Line source, a Radial reflectance and transmittance detector and a FluenceRz fluence / deposition detector. The refractive index of the surrounding medium is set to 1.0. The simulation termination radius is set to 1000 mm and each simulation is run with 100 million photon packets. The optical properties of the top sample layer are sapled from $\mu_a = [0.0, 2.5, 5.0]$ cm ^-1, $\mu_s' = [5.0, 20.0, 35.0]$ cm ^-1 and $g = [0.1, 0.5, 0.9]$ .

Source, reflectance/transmittance detector and fluence/deposition detector configurations¶
	Parameter	Value	Description
`Line`			normal incidence
`Radial`	$raxis$	`Axis` (start=0, stop=0.005, n=500)	reflectance and transmittance accumulators
`FluenceRz`	$raxis$	`Axis` (start=0, stop=0.005, n=500)	radial $r$ axis
	$zaxis$	`Axis` (start=0, stop=0.005, n=500)	$z$ axis
	$mode$	‘deposition’	weight deposition mode

run/mcml_comparison/1-layer-100mm.py

A single 100 mm thick sample layer.

A single layer sample of 100 mm thickness¶
	Parameter	Value	Description
`Layer`	$d$	100 mm	thickness
	$\mu_a$	0.0, 2.5 or 5.0 cm ^-1	absorption coefficient
	$\mu_s'$	5.0, 20.0 or 35.0 cm ^-1	reduced scattering coefficient
	$n$	1.337	refractive index
	$g$	0.1, 0.5 or 0.9	`Hg` (g)

run/mcml_comparison/1-layer-1mm.py

A single 1 mm thick sample layer.

A single layer sample of 1 mm thickness¶
	Parameter	Value	Description
`Layer`	$d$	1 mm	thickness
	$\mu_a$	0.0, 2.5 or 5.0 cm ^-1	absorption coefficient
	$\mu_s'$	5.0, 20.0 or 35.0 cm ^-1	reduced scattering coefficient
	$n$	1.337	refractive index
	$g$	0.1, 0.5 or 0.9	`Hg` (g)

run/mcml_comparison/2-layer-100um-1mm.py

Two sample layers, a 0.1 mm top and a 1.0 mm bottom layer. The optical properties are varied only in the top sample layer (the refractive index is fixed to 1.462). The optical properties of the bottom sample layer are fixed to $\mu_a=0.5$ cm ^-1, $\mu_s'=20.0$ cm ^-1, $g=0.8$ and $n=1.337$ .

A 2-layer sample¶
	Parameter	Value	Description
`Layer`	$d$	0.1 mm	thickness
	$\mu_a$	0.0, 2.5 or 5.0 cm ^-1	absorption coefficient
	$\mu_s'$	5.0, 20.0 or 35.0 cm ^-1	reduced scattering coefficient
	$n$	1.462	refractive index
	$g$	0.1, 0.5 or 0.9	`Hg` (g)
`Layer`	$d$	1.0 mm	thickness
	$\mu_a$	0.5 cm ^-1	absorption coefficient
	$\mu_s'$	20 cm ^-1	reduced scattering coefficient
	$n$	1.337	refractive index
	$g$	0.8	`Hg` (g)

Dataset files

Executing the generated scripts will save the simulation results / datasets into compressed numpy data files that will be organized as follows:

data/mcml_comparison/<sample>/line/radial/hg/g-<g>/mua-<mua>-musr-<musr>-invcm.npz

The values of placeholders <> are as follows:

<sample> can take the following values:
- 1-layer-1mm A single layer 1 mm thick medium.
- 1-layer-100mm A single layer 100 mm thick medium.
- 2-layer-100um-1mm A two-layer medium with 0.1 top layer and 1 mm bottom layer
<g> is the anisotropy formatted with two decimal digits and _ as the decimal separator, e.g 0_10 for $g=0.1$ , 0_50 for $g=0.5$ or 0_90 for $g=0.9$ .
<mua> is the absorption coefficient in units of cm ^-1 with two decimal digits and _ as the decimal separator, e.g 2_50 for $\mu_a=2.5$ cm ^-1 .
<musr> is the reduced scattering coefficient in units of cm ^-1 with two decimal digits and _ as a decimal separator, e.g 20_00 for $\mu_a=20.0$ cm ^-1 .

Layered media datasets¶

Module xopto.dataset.render.mcml => run/mcml/

Renders scripts that produce datasets for the layered MC kernel. These will include a number of different source, detector and sample scattering phase function configurations. The simulation termination radius is set to 25 mm, except for the spatial frequency domain(SFD) dataset that uses a 150 mm simulation termination radius. The datasets are produced with 100 million photon packets, except for the SFD dataset and all the datasets that use an optical fiber probe with a linear layout of 6 fibers. These datasets are run with 1000 million photon packets. The optical properties of the sample are varied according to the values in the following two tables.

Absorption and reduced scattering coefficients¶
Parameter	From (cm ^-1)	To (cm ^-1)	Points
$\mu_a$	0.0	5.0	21
$\mu_s'$	5.0	35.0	21

Scattering phase functions¶
	Parameter	Values
`Hg` $(g)$	$g$	0.1, 0.3, 0.5, 0.7, 0.9
`MHg` $(g, \beta)$	$g$	0.1, 0.3, 0.5, 0.7, 0.9
	$\beta$	0.0, 0.2, 0.4, 0.6, 0.8, 1.0
`Gk` $(g, \alpha)$	$g$	0.1, 0.3, 0.5, 0.7, 0.9
	$\alpha$	-0.5, 0.0, 0.5, 1.0, 1.5
`Mie` $(n_1, n_2, d, \lambda)$	$n_1$	1.337
	$n_2$	1.462 (fused silica)
	$diameter$	0.25, 0.5, 1.0, 2.0, 4.0 μm
	$wavelength$	500 nm
`Mie` $(n_1, n_2, d, \lambda)$	$n_1$	1.337
	$n_2$	1.603 (polystyrene)
	$diameter$	0.25, 0.5, 1.0, 2.0, 4.0 μm
	$wavelength$	500 nm

The refractive index of the sample is set to 1.337.

Reference simulation scripts are rendered for the following basic sources that use a laterally uniform boundary between the sample and the surrounding medium.

Basic sources with a uniform sample-source interface and related reflectance detectors¶
Source	Parameter	Value	Reflectance detector
`Line`			`Radial` (`Axis` (start=0, stop=0.005, n=500))
`UniformBeam`	$diameter$	200 μm	`Radial` (`Axis` (start=0, stop=0.005, n=500))
`GaussianBeam`	$FWHM$	100 μm	`Radial` (`Axis` (start=0, stop=0.005, n=500))
`UniformFiber`	$dcore$	200 μm	`Radial` (`Axis` (start=0, stop=0.005, n=500), cosmin=0.98637)
	$dcladding$	220 μm
	$ncore$	1.462
	$na$	0.22

The refractive index of the surrounding medium is set to 1.0 except when using the UniformFiber source, when the refractive index of the surrounding medium follows the refractive index of the fiber core 1.462.

The reflectance of basic sources is collected with a radial detector Radial (Axis (start=0, stop=0.005, n=500)) that extends from 0 to 5 mm with 5oo concentric ring accumulators, each 5 μm wide. The acceptance angle is unlimited, except for the UniformFiber source, for which it is limited by the NA of the fiber core. The acceptance angle within the fiber core is computed as $\cos \theta = \sqrt{1 - (NA/n_{core})^2}$ .

Reference simulation scripts are also rendered for optical fiber probe sources that use a surface layout to more accurately describe the interface between the optical fiber probe tip and the sample. All the probe sources launch the photon packets with the UniformFiber source.

Optical fiber probe sources with a detailed sample-source interface and related reflectance detectors¶
Probe	Parameter	Value	Description	Reflectance detector
`SixAroundOne`	$dcore$	200 μm	six-around-one layout	`SixAroundOne`
	$dcladding$	220 μm
	$ncore$	1.462
	$na$	0.22
	$spacing$	220 μm
	$diameter$	6.0 mm
	$reflectivity$	0.6
`SixAroundOne`	$dcore$	400 μm	six-around-one layout	`SixAroundOne`
	$dcladding$	420 μm
	$ncore$	1.462
	$na$	0.22
	$spacing$	420 μm
	$diameter$	6.0 mm
	$reflectivity$	0.6
`LinearArray`	$dcore$	200 μm	linear layout of 6 fibers	`LinearArray`
	$dcladding$	220 μm
	$ncore$	1.462
	$na$	0.22
	$n$	6
	$spacing$	220 μm
	$diameter$	6.0 mm
	$reflectivity$	0.6
`LinearArray`	$dcore$	100 μm	single fiber layout	`LinearArray`
	$dcladding$	120 μm
	$ncore$	1.462
	$na$	0.22
	$n$	1
	$diameter$	6.0 mm
	$reflectivity$	0.6
`LinearArray`	$dcore$	200 μm	single fiber layout	`LinearArray`
	$dcladding$	220 μm
	$ncore$	1.462
	$na$	0.22
	$n$	1
	$diameter$	6.0 mm
	$reflectivity$	0.6
`LinearArray`	$dcore$	400 μm	single fiber layout	`LinearArray`
	$dcladding$	420 μm
	$ncore$	1.462
	$na$	0.22
	$n$	1
	$diameter$	6.0 mm
	$reflectivity$	0.6
`LinearArray`	$dcore$	800 μm	single fiber layout	`LinearArray`
	$dcladding$	820 μm
	$ncore$	1.462
	$na$	0.22
	$n$	1
	$diameter$	6.0 mm
	$reflectivity$	0.6

The reflectance of optical fiber probe sources is collected only through the individual optical fibers of the probe.

SFD source-detector arrangements

The SFD datasets are computed for two source-detector configurations and include raw reflectance and the corresponding frequency-domain reflectance, which is computed for spatial frequencies from 0.00 to 0.80 mm ^-1 in 0.01 mm ^-1 steps:

A normally incident Line source and a radial Radial (Axis (start=0, stop=0.15, n=4000, logscale=True), cosmin=0.98481) reflectance detector that uses 4000 logarithmically spaced concentric accumulators from 0 to 150 mm. The acceptance angle is limited to 10°. Hankel transform is used to compute the spatial frequency-domain reflectance. Note that this transform produces real values.
A normally incident Line source and a tilted linear detector with 20° incidence (along the $x$ axis). The accumulators of the detector extend to infinity along the positive and negative $y$ axis and follow a logarithmic spacing along the positive and negative direction of the $x$ axis SymmetricX (SymmetricAxis (center=0, range=0.15, n_half=4000, logscale=True), cosmin=0.98480). The described detector uses 8000 (4000 in each direction along the $x$ axis) logarithmically spaced accumulators from $x=-150$ to $x=150$ mm. The acceptance angle of the detector is limited to 10° around the tilted detector axis. Fourier transform is used to compute the spatial frequency-domain reflectance. Note that this transform produces complex values with amplitude and phase information.

Note that the SFD datasets are run with 1000 million photon packets and that the simulation termination radius is set to 150 mm.

Dataset files

Executing the generated scripts will save the simulation results / datasets into compressed numpy data files that will be organized as follows:

data/mcml/<sample>/<source>/<detector>/<pf>/<pf_param_1>/<pf_param_2>/mua-<mua>-musr-<musr>-invcm.npz

The values of placeholders <> are as follows:

<sample> can take the following values:
- 1-layer-semiinfinite
  A single samplelayer of infinite thickness.
<source> is the type of the photon packet source / probe used in the datasets:
- line for a infinitely narrow line source Line.
- collimated-200um for a UniformBeam with a 200 µm beam diameter.
- gaussian-fwhm-100um for a GaussianBeam with 100 µm beam FWHM.
- fiber-200um-0_22na for a UniformFiber with fiber core diameter of 200 µm and 0.22 NA.
- six-around-one-200um-0_22na for a SixAroundOne probe surface layout with a central optical fiber source UniformFiber. All optical fibers have a core diameter of 200 µm, cladding diameter of 220 µm, 0.22 NA and are tightly packed.
- six-around-one-400um-0_22na for a SixAroundOne probe surface layout with a central optical fiber source UniformFiber. All optical fibers have a core diameter of 400 µm, cladding diameter of 420 µm, 0.22 NA and are tightly packed.
- six-linear-array-200um-0_22na for a LinearArray probe surface layout with 6 tightly packed optical fibers, a leftmost source fiber (negative $x$ coordinate) UniformFiber. All optical fibers have a core diameter of 200 µm, cladding diameter of 220 µm, 0.22 NA and are tightly packed.
- single-fiber-100um-0_22na for a LinearArray probe surface layout with one central optical fiber, a fiber source UniformFiber. The optical fiber has a core diameter of 100 µm, cladding diameter of 120 µm, 0.22 NA.
- single-fiber-200um-0_22na for a LinearArray probe surface layout with one central optical fiber, a fiber source UniformFiber. The optical fiber has a core diameter of 200 µm, cladding diameter of 220 µm, 0.22 NA.
- single-fiber-400um-0_22na for a LinearArray probe surface layout with one central optical fiber, a fiber source UniformFiber. The optical fiber has a core diameter of 400 µm, cladding diameter of 420 µm, 0.22 NA.
- single-fiber-800um-0_22na for a LinearArray probe surface layout with one central optical fiber, a fiber source UniformFiber. The optical fiber has a core diameter of 800 µm, cladding diameter of 820 µm, 0.22 NA.
<detector> is the type of detector used by the datasets:
- radial for simple sources with laterally uniform source-sample boundary,
- probe for optical fiber probes with surface layout.
<pf> is the type of scattering phase function used in the datasets:

hg for Hg.

mhg for MHg.

gk for Gk.

mie-polystyrene for Mie - a water suspension of polystyrene spheres.

mie-fusedsilica for Mie - a water suspension of fused silica spheres.
pf_param_1: is the first parameter of the scattering phase function formatted with two decimal digits and using _ as the decimal separator:
- g-<g> for Hg, e.g. g-0_10 for $g=0.1$ .
- g-<g> for MHg, e.g. g-0_50 for $g=0.5$ .
- g-<g> for Gk, e.g. g-0_90 for $g=0.9$ .
- diameter-<g>um for Mie, e.g. diameter-0_25 for $d=0.25$ µm.
pf_param_2: is the second parameter of the scattering phase function formatted with two decimal digits and using _ as the decimal separator. An exception to this rule is the wavelength parameter of the Mie scattering phase function that is converted to nm and formatted as an integer. This placeholder is not used with the Hg scattering phase function.
- b-<b> for MHg, e.g. b-0_60 for $b=0.6$ .
- a-<a> for Gk, e.g. a-0_50 for $a=0.5$ .
- wavelength-<w>nm for Mie, e.g. wavelength-500nm for $wavelength=500$ nm.
<mua> is the absorption coefficient in units of cm ^-1 with two decimal digits and _ as the decimal separator, e.g 2_50 for $\mu_a=2.5$ cm ^-1.
<musr> is the reduced scattering coefficient in units of cm ^-1 with two decimal digits and _ as a decimal separator, e.g 20_00 for $\mu_a=20.0$ cm ^-1.

Voxelized media datasets¶

Module xopto.dataset.render.mcvox => run/mcvox/

Renders a dataset scripts for computing fluence / deposition datasets with the MC kernel for voxelized media. A two-layer skin model with an embedded blood vessel is used. The depth/position of the blood vessel along the $z$ axis is varied from 0.2 to 0.8 mm in steps of 0.025 mm. The refractive index of the surrounding medium is set to 1.337. The simulations are run with 1000 million photon packets.

A two-layer skin model with an embedded blood vessel¶
	Parameter	Value	Description
`Line`			normally incident
`Material`	$\mu_a$	16.5724 cm ^-1	epidermis
	$\mu_s$	375.9398 cm ^-1
	$n$	1.337
	$pf$	`Hg` (0.9)
`Material`	$\mu_a$	45.85 cm ^-1	dermis
	$\mu_s$	356.5406 cm ^-1
	$n$	1.337
	$pf$	`Hg` (0.9)
`Material`	$\mu_a$	230.5427 cm ^-1	blood vessel
	$\mu_s$	93.985 cm ^-1
	$n$	1.337
	$pf$	`Hg` (0.9)
`Fluence`	$xaxis$	`Axis` (start=-502.5e-6, stop=502.5e-6, n=201)	sample and deposition voxelization
	$yaxis$	`Axis` (start=-502.5e-6, stop=502.5e-6, n=201)
	$zaxis$	`Axis` (start=0.0, stop=0.001, n=200)
`Cartesian`	$xaxis$	`Axis` (start=-502.5e-6, stop=502.5e-6, n=201)	reflectance and transmittance detectors
	$yaxis$	`Axis` (start=-502.5e-6, stop=502.5e-6, n=201)
Blood vessel	$diameter$	200.0 μm	in dermis
	$position$	(0, 0, 0.0002-0.0008)	(x, y, z)
	$direction$	(0, 1, 0)	(x, y, z)
Epidermis	$thickness$	100 μm

Dataset files

Executing the generated scripts will save the simulation results / datasets into compressed numpy data files that will be organized as follows:

data/mcvox/fluence/2-layer-skin-<diameter>um-vessel-<depth>um-depth-deposition.npz

The values of placeholders <> are as follows:

<diameter> is the diameter of the blood vessel in units of μm, formatted as an integer value, e.g 200 for a 200 μm blood vessel.
<depth> is the $z$ coordinate (depth) of the blood vessel in units of μm, formatted as an integer value, e.g 500 for $z=500$ μm.

Sampling volume datasets¶

Module xopto.dataset.render.sv => run/sv/

Renders a reference dataset script for computing sampling-volume datasets. The sampling volume dataset is computed for a semi-infinite homogeneous medium for an optical fiber probe with two optical fibers placed at a distance of 0.5 mm. The refractive index of the surrounding medium is set to 1.0. Simulations are run in batches until 1,000,000 photon packet traces that reach the detector fiber are collected and converted to sampling volume information. The trace capacity is limited to 1000 events. The simulation termination radius is set to 25 mm.

Sampling volume for a probe with two optical fibers¶
	Parameter	Value	Description
`LinearArray`	$dcore$	200 μm	linear layout of 2 fibers
	$dcladding$	220 μm
	$ncore$	1.462
	$na$	0.22
	$spacing$	500 μm
	$n$	2
	$diameter$	6.0 mm
	$reflectivity$	0.6
`Trace`	$maxlen$	1000	packet trace configuration
`SamplingVolume`	$xaxis$	`Axis` (start=-0.00075, stop=0.00075, n=300)	sampling volume voxelization
	$yaxis$	`Axis` (start=-0.00075, stop=0.00075, n=300)
	$zaxis$	`Axis` (start=0.0, stop=0.001, n=200)
`Layer`	$\mu_a$	2.0 cm ^-1	sample layer
	$\mu_s$	500.0 cm ^-1
	$n$	1.337
	$pf$	`Hg` (0.95)

Dataset files

Executing the generated scripts will save the simulation results / datasets into compressed numpy data files that will be organized as follows:

data/mcml/1-layer-semiinfinite/sv/reflectance/fiber-200um-0_22na/sds-<sds>um/hg/g-<g>/um-mua-<mua>-musr-<musr>-invcm.npz

The values of placeholders <> are as follows:

<sds> is the distance between the centers of the source and detector fibers in units of μm, formatted as an integer value, e.g 500 for a 500 μm distance.
<g> is the anisotropy formatted with two decimal digits and _ as the decimal separator, e.g 0_15 for $g=0.15$ .
<mua> is the absorption coefficient in units of cm ^-1 with two decimal digits and _ as the decimal separator, e.g 2_50 for $\mu_a=2.5$ cm ^-1 .
<musr> is the reduced scattering coefficient in units of cm ^-1 with two decimal digits and _ as a decimal separator, e.g 20_00 for $\mu_s'=20.0$ cm ^-1.

All available datasets¶

xopto.dataset.render.all Renders all the available dataset scripts.