xopto.mcbase.mctrace module

class Filter(x: Optional[tuple] = None, y: Optional[tuple] = None, z: Optional[tuple] = None, pz: Optional[tuple] = None, r: Optional[tuple] = None, dir: Optional[tuple] = None, pl: Optional[tuple] = None)[source]

Bases: object

Trace filter constructor. Creates a filter of traced photon packets according to the final position of the photon packet. Set the unused filter parameters to None - default value. Filters are connected through a logical and.

Parameters

  • x ((float, float) or ((float, float), (float, float), ...)) – Final x coordinate of the photon packet must be within the specified interval including the boundaries (xmin, xmax). Multiple intervals can be specified as a list or tuple of intervals.

  • y ((float, float) or ((float, float), (float, float), ...)) – Final y coordinate of the photon packet must be within the specified interval including the boundaries (ymin, ymax). Multiple intervals can be specified as a list or tuple of intervals.

  • z ((float, float) or ((float, float), (float, float), ...)) – Final z coordinate of the photon packet must be within the specified interval including the boundaries (zmin, zmax). Multiple intervals can be specified as a list or tuple of intervals.

  • pz ((float, float)) – Final z component of the photon packet propagation direction must be within the specified interval. Note that the z component of the propagation direction of photon packets terminated at the top sample boundary is negative!. Multiple intervals can be specified as a list or tuple of intervals.

  • dir ((float, float, (float, float, float))) – The cosine of the angle between the given direction and the final direction of the photon packet must be within the specified interval (cosmin, cosmax, (px, py, pz)). Multiple filters can be specified as a list or tuple.

  • r ((float, float, (float, float)) or ((float, float, (float, float)), ...)) – Final r=sqrt((x-xo)**2 + (y - yo)**2) coordinate of the photon packet must be within the specified radius (rmin, rmax). The radius is calculated with respect to the given origin (x0, y0). Multiple filters can be specified as a list or tuple of (rmin, rmax, (x0, y0)).

  • pl ((float, float) or ((float, float), (float, float), ...)) – Final optical path length traveled by the photon packet must be within the specified interval including the boundaries (plmin, plmax). Multiple intervals can be specified as a list or tuple of intervals.

property dir: tuple

Filter of the propagation direction as (cosmin, cosmax, (px, py, pz)).

classmethod fromdict(data: dict) → xopto.mcbase.mctrace.Filter[source]

Create a Filter instance from a dictionary.

Parameters

data (dict) – Dictionary created by the Filter.todict() method.

property pl: tuple

Filter of the optical pathlength as ((pl_min, pl_max), …).

property pz: tuple

Filter of the z component of the propagation direction as (pz_min, pz_max).

property r: tuple

Filter of r=sqrt(x*x + y*y) as ((r_min, r_max, (x_origin, y_origin)), …).

todict() → dict[source]

Save the filter configuration to a dictionary.

Returns

data – Filter configuration as a dictionary.

Return type

dict

property x: tuple

Filter of the x coordinate as ((x_min, x_max), …).

property y: tuple

Filter of the y coordinate as ((y_min, y_max), …).

property z: tuple

Filter of the z coordinate as ((z_min, z_max), …).

TRACE_EVENT_ABSORPTION = 16

Trace all packet absorption events.

TRACE_EVENT_ALL = -1

Trace all events.

TRACE_EVENT_BOUNDARY_HIT = 4

Trace all geometry boundary hit events.

TRACE_EVENT_ESCAPE = 128

Trace events that are triggered by packet escaping/leaving the simulation domain.

TRACE_EVENT_LAUNCH = 8

Trace all packet launch events.

TRACE_EVENT_REFLECTION = 1

Trace all packet reflection events at geometry boundaries.

TRACE_EVENT_REFRACTION = 2

Trace all packet refraction events at geometry boundaries.

TRACE_EVENT_SCATTERING = 32

Trace all packet scattering events.

TRACE_EVENT_TERMINATION = 64

Trace all packet termination events.

class Trace(maxlen: int = 500, options: int = 7, filter: Optional[xopto.mcbase.mctrace.Filter] = None, event_mask: Optional[int] = None, plon: bool = True)[source]

Bases: xopto.mcbase.mcobject.McObject

Photon packet trace interface.

Photon packet trace object constructor.

Parameters

  • maxlen (int or Trace) –

    Maximum number of trace entries (events) per photon packet. If maxlen is an instance of Trace, a new copy of the trace object is created. Each trace entry is composed of seven fields that describe the state of the photon packet at the time of the event:

    ’x’ - x coordinate of the photon packet

    ’y’ - y coordinate of the photon packet

    ’z’ - z coordinate of the photon packet

    ’px’ - x component of the photon packet propagation direction

    ’py’ - y component of the photon packet propagation direction

    ’pz’ - z component of the photon packet propagation direction

    ’w’ - photon packet weight

    ’pl’ - photon path length

  • options (int) –

    Trace options must be formed by combining (logical or) the following flags:

    TRACE_START - trace the initial photon packet state

    TRACE_END - trace the final/terminal photon packet state

    TRACE_ALL - trace all (scattering/absorption and boundary transition) events

  • filter (Filter) – Filter trace results according to the supplied filter. A filter class needs to define a __call__ method that returns a new Trace instance with filtered events. See the Filter class for details and example.

  • event_mask (int) –

    A mask of event flags that are recorded/traced in the MC kernel. If None, all events are traced and event tracking is disabled (default). Note that event tracking comes with some performance cost. All events should be traced when computing the sampling volume! The following events can be used with the event mask:

    • TRACE_EVENT_LAUNCH, tracing all packet launch events

    • TRACE_EVENT_ABSORPTION, tracing all packet absorption events

    • TRACE_EVENT_SCATTERING, tracing all packet scattering events

    • TRACE_EVENT_BOUNDARY_HIT, tracing all geometry boundary interactions

    • TRACE_EVENT_REFLECTION, tracing all packet reflection events at geometrical boundaries

    • TRACE_EVENT_REFRACTION, tracing all packet refraction events at geometrical boundaries

    • TRACE_EVENT_TERMINATION, tracing packet termination

    • TRACE_EVENT_ESCAPE, packet escapes the simulation domain

  • plon (bool) – Turn on/off tracking of the optical pathlength. If set to nonzero, the simulator option MC_TRACK_OPTICAL_PATHLENGTH will be set turning on the tracking of optical pathlength.

Note

The value of maxlen parameter is automatically adjusted to:

  1. 1 - if only the TRACE_START or TRACE_END option flags are set,

  2. 2 - if the TRACE_START and the TRACE_END option flags are set,

  3. left unchanged if the TRACE_ALL option flag is set.

Use the update method to convert raw simulation output buffer into a numpy structured array with items ‘x’, ‘y’, ‘z’, ‘px’, ‘py’, ‘pz’, and ‘w’. The array shape is (nphotons, length). To access the trace of first photon packet use obj.data[0]

The number of valid trace entries for each photon packet can be obtained by obj.n (e.g. obj.n[0] for the first photon packet).

TRACE_ALL = 7
TRACE_END = 2
TRACE_ENTRY_LEN = 8
TRACE_EVENT_ABSORPTION = 16
TRACE_EVENT_ALL = -1
TRACE_EVENT_BOUNDARY_HIT = 4
TRACE_EVENT_ESCAPE = 128
TRACE_EVENT_LAUNCH = 8
TRACE_EVENT_REFLECTION = 1
TRACE_EVENT_REFRACTION = 2
TRACE_EVENT_SCATTERING = 32
TRACE_EVENT_TERMINATION = 64
TRACE_NONE = 0
TRACE_START = 1
apply_filter()[source]
static cl_declaration(mc: xopto.mcbase.mcobject.McObject) → str[source]

Structure that defines the trace in the Monte Carlo simulator.

static cl_implementation(mc: xopto.mcbase.mcobject.McObject) → str[source]

Implementation of the trace in the Monte Carlo simulator.

cl_options(mc: xopto.mcbase.mcobject.McObject) → List[Tuple[str, str]][source]
cl_pack(mc: xopto.mcbase.mcobject.McObject, target: Optional[xopto.cl.cltypes.Structure] = None, nphotons: Optional[int] = None) → xopto.cl.cltypes.Structure[source]

Fills the ctypes structure (target) with the data required by the Monte Carlo simulator. See the Trace.cl_type class for a detailed list of fields.

Parameters

  • mc (mcobject.McObject) – Monte Carlo simulator instance.

  • target (cltypes.Structure) – Ctypes structure that is filled with the source data.

  • nphotons (int) – The number of photon packets that will be run by the simulator.

Returns

target – Filled ctypes structure received as an input argument or a new instance if the input argument target is None.

Return type

cltypes.Structure

static cl_type(mc: xopto.mcbase.mcobject.McObject) → xopto.cl.cltypes.Structure[source]

Structure that is passed to the Monte carlo simulator kernel.

Parameters

mc (McObject) – A Monte Carlo simulator instance.

Returns

struct – A structure type that represents a trace in the Monte Carlo kernel.

The returned structure type implements the following fields:

  • max_events: mc_int_t

    Maximum number of trace events per photon packet.

  • data_buffer_offset: mc_size_t

    Offset of the first element of the trace data buffer.

  • count_buffer_offset: mc_size_t

    Offset of the first element of the trace event counter buffer.

Return type

cltypes.Structure

property data: numpy.ndarray

Trace data.

data_to_cl(mc: xopto.mcbase.mcobject.McObject) → numpy.ndarray[source]

Prepare the trace data array for upload to the OpenCL kernel.

Parameters

mc (mcobject.McObject) – Simulator instance that will use the data.

Returns

cl_data – Flat numpy data array of basic type ready for transfer to the OpenCL device.

Return type

np.ndarray

property dropped: int

The number of photon packets that matched the filter, but were dropped due to exceeding the maximum trace length.

dtype(mc: xopto.mcbase.mcobject.McObject) → numpy.dtype[source]

Return a structure numpy data type that represents the trace data.

Parameters

mc (mcobject.McObject) – Instance of the Monte Carlo simulator which will be used with this trace object.

property event_mask: int

Mask of traced events.

property filter: xopto.mcbase.mctrace.Filter

Trace filter.

float_len(nphotons: int) → int[source]

Number of float values required to save trace data for the given number of photon packets.

Parameters

nphotons (int) – Number of photon packets to trace

classmethod fromdict(data: dict) → xopto.mcbase.mctrace.Trace[source]

Create a Trace instance from a dictionary.

Parameters

data (dict) – Dictionary created by the Trace.todict() method.

property maxlen: int

Maximum trace length.

property n: int

Number of trace events for each photon packet.

n_to_cl(mc: xopto.mcbase.mcobject.McObject) → numpy.ndarray[source]

Prepare the array with number of events per photon packet for upload to the OpenCL kernel.

Parameters

mc (mcobject.McObject) – Simulator instance that will use the data.

Returns

cl_data – Flat numpy data array of basic type ready for transfer to the OpenCL device.

Return type

np.ndarray

np_buffer(mc: xopto.mcbase.mcobject.McObject, allocation: xopto.mcbase.mcutil.buffer.BufferAllocation, nphotons=None, **kwargs) → numpy.ndarray[source]

Efficient numpy buffer allocation that can be used to directly download data to the Trace object.

Parameters

  • mc (mcobject.McObject) – Simulator instance that produced the results.

  • allocation – Buffer allocation made by the Trace.cl_pack() method.

  • nphotons (int) – The number of photon packets traced by the simulation.

Returns

np_buffer – A numpy buffer that can be used to directly download the data (no copy is required in the Trace.update_data() method).

Return type

np.ndarray

property nphotons

Number of photon packets in the trace.

property options: int

Compile time trace options.

property overflow: numpy.ndarray

Binary mask of photon packets that have overflowed the trace

property plon: bool

State of the optical pathlength tracking.

plot(inds: numpy.ndarray = None, view='3d', show: bool = True, ax: matplotlib.axes.Axes = None)[source]

Plots the paths of photon packets.

Parameters

  • inds (np.ndarray) – A vector of indices or a logical mask for selecting the photon packet. If a logical mask, the shape of the mask should be (num_packets).

  • view (str) –

    A string that specifies the plot view:

    • ’xy’ - projection into the x-y plane.

    • ’xy’ - projection into the x-z plane.

    • ’xy’ - projection into the y-z plane.

    • ’3d’ - 3D plot (default).

  • show (bool) – If True, show the plot.

  • ax (matplotlib.axes.Axes) – A 3D matplotlib axis that will be used to plot the traces or None to create a new figure.

property terminal: numpy.ndarray

Terminal/final state of the photon packets.

todict() → dict[source]

Save the trace configuration without the accumulator data to a dictionary.

Returns

data – Trace configuration as a dictionary.

Return type

dict

update(obj: xopto.mcbase.mctrace.Trace)[source]

Update the trace with data from the given trace object.

Parameters

obj (Trace) – Update the trace of this instance with the data from Trace instance obj.

update_data(mc: xopto.mcbase.mcobject.McObject, data: Dict[numpy.dtype, List[numpy.ndarray]], nphotons: int, **kwargs)[source]

Update the content of raw data accumulators with simulation results.

Parameters

  • mc (mcobject.McObject) – Simulator instance that produced the data.

  • data (Dict[np.dtype, List[np.ndarray]]) – Dict of allocated buffers (this implementation uses only one integer and one floating point buffer).

  • nphotons (int) – Number of photon packets used in the simulations.

  • kwargs (dict) – Additional keyword arguments not used by this implementation.