pmcx 0.4.2__py3-none-any.whl

pmcx/__init__.py

@@ -0,0 +1,69 @@
+# Copyright (c) 2022-2023 Matin Raayai Ardakani <raayaiardakani.m at northeastern.edu>. All rights reserved.
+# Copyright (c) 2022-2023 Qianqian Fang <q.fang at neu.edu>. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""PMCX - Python bindings for Monte Carlo eXtreme photon transport simulator
+
+Example usage:
+
+# To list available GPUs
+import pmcx
+pmcx.gpuinfo()
+
+# To run a simulation
+res = pmcx.run(nphoton=1000000, vol=np.ones([60, 60, 60], dtype='uint8'),
+               tstart=0, tend=5e-9, tstep=5e-9, srcpos=[30,30,0],
+               srcdir=[0,0,1], prop=np.array([[0, 0, 1, 1], [0.005, 1, 0.01, 1.37]]))
+"""
+
+try:
+    from _pmcx import gpuinfo, run, version
+except ImportError:  # pragma: no cover
+    print("the pmcx binary extension (_pmcx) is not compiled! please compile first")
+
+from .utils import (
+    detweight,
+    cwdref,
+    meanpath,
+    meanscat,
+    dettpsf,
+    dettime,
+    tddiffusion,
+    getdistance,
+    detphoton,
+    mcxlab,
+)
+
+# from .files import loadmc2, loadmch, load, save
+from .bench import bench
+
+__version__ = "0.4.2"
+
+__all__ = (
+    "gpuinfo",
+    "run",
+    "version",
+    "bench",
+    "detweight",
+    "cwdref",
+    "meanpath",
+    "meanscat",
+    "dettpsf",
+    "dettime",
+    "tddiffusion",
+    "getdistance",
+    "detphoton",
+    "mcxlab",
+)

pmcx/bench.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2022-2023 Matin Raayai Ardakani <raayaiardakani.m at northeastern.edu>. All rights reserved.
+# Copyright (c) 2022-2023 Qianqian Fang <q.fang at neu.edu>. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Built-in benchmark configurations"""
+
+import numpy as np
+import copy
+
+bench = {}
+bench["cube60"] = {
+    "nphoton": 1000000,
+    "vol": np.ones([60, 60, 60], dtype="uint8"),
+    "tstart": 0,
+    "tend": 5e-9,
+    "tstep": 5e-9,
+    "srcpos": [29, 29, 0],
+    "srcdir": [0, 0, 1],
+    "prop": [[0, 0, 1, 1], [0.005, 1, 0.01, 1.37], [0.002, 5, 0.9, 1]],
+    "isreflect": 0,
+    "seed": 1648335518,
+    "session": "cube60",
+    "detpos": [[29, 19, 0, 1], [29, 39, 0, 1], [19, 29, 0, 1], [39, 29, 0, 1]],
+    "issrcfrom0": 1,
+}
+
+bench["cube60b"] = copy.deepcopy(bench["cube60"])
+bench["cube60b"]["isreflect"] = 1
+
+bench["cube60planar"] = copy.deepcopy(bench["cube60b"])
+bench["cube60planar"]["srctype"] = "planar"
+bench["cube60planar"]["srcpos"] = [10, 10, -10]
+bench["cube60planar"]["srcparam1"] = [40, 0, 0, 0]
+bench["cube60planar"]["srcparam2"] = [0, 40, 0, 0]

pmcx/utils.py

@@ -0,0 +1,683 @@
+# Copyright (c) 2023 Kuznetsov Ilya
+# Copyright (c) 2023 Qianqian Fang (q.fang <at> neu.edu)
+# Copyright (c) 2023 Fan-Yu (Ivy) Yen (yen.f at northeastern.edu)
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+"""Utilities for processing MCX input and output data"""
+
+import numpy as np
+import re
+import sys
+
+# sys.path.insert(0, '../../src/build/')
+
+import pmcx
+
+
+def cwdref(detp, cfg):
+    """
+    Compute CW diffuse reflectance from MC detected photon profiles.
+
+    (Python code was adapted from mcxcwdref.m MATLAB function, ported by Kuznetsov Ilya)
+
+    input:
+        detp: profiles of detected photons
+        cfg:  a dictionary. Each element of cfg defines
+              the parameters associated with a MC simulation.
+
+    output:
+        dref: CW diffuse reflectance at detectors
+
+    this file is part of Monte Carlo eXtreme (MCX)
+    License: GPLv3, see https://mcx.space for details
+    see Yao2018
+    """
+
+    unitinmm = 1
+    if "unitinmm" in cfg:
+        unitinmm = cfg["unitinmm"]
+
+    det_weight = detweight(detp, cfg["prop"])
+    detnum = len(np.unique(detp["detid"]))
+    detweightsum = np.zeros(detnum)
+
+    for i in range(len(detp["detid"])):
+        index = int(detp["detid"][i]) - 1
+        detweightsum[index] += det_weight[i]
+
+    area = np.pi * (cfg["detpos"][:, 3] * unitinmm) ** 2
+    dref = detweightsum / area / cfg["nphoton"]
+
+    return dref
+
+
+# ---------------------------------------------
+def meanpath(detp, prop=None):
+    """
+    Calculate the average pathlengths for each tissue type for a given source-detector pair
+
+    (Python code was adapted from mcxmeanpath.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        detp: the 2nd output from mcxlab. detp can be either a struct or an array (detp.data)
+        prop: optical property list, as defined in the cfg.prop field of mcxlab's input
+
+    output:
+        avgpath: the average pathlength for each tissue type
+    """
+    if "unitinmm" in detp:
+        unitinmm = detp["unitinmm"]
+    else:
+        unitinmm = 1
+
+    if prop is None:
+        if "prop" in detp:
+            prop = detp["prop"]
+        else:
+            raise ValueError('Must provide input "prop"')
+
+    detw = detweight(detp, prop)
+    avgpath = np.sum(
+        detp["ppath"] * unitinmm * np.tile(detw, (detp["ppath"].shape[1], 1)).T, 0
+    ) / np.sum(detw)
+
+    return avgpath
+
+
+def detweight(detp, prop=None, unitinmm=None):
+    """
+    Recalculate the detected photon weight using partial path data and
+    optical properties (for perturbation Monte Carlo or detector readings)
+
+    (Python code was adapted from mcxdetweight.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        detp: the 2nd output from mcxlab. detp must be a dict.
+        prop: optical property list, as defined in the cfg.prop field of mcxlab's input.
+        unitinmm: voxel edge-length in mm, should use cfg.unitinmm used to generate detp;
+              if ignored, assume to be 1 (mm)
+
+    output:
+        detw: re-caculated detected photon weight based on the partial path data and optical property table
+    """
+    if prop is None:
+        if "prop" in detp:
+            prop = detp["prop"]
+        else:
+            raise ValueError('Must provide input "prop"')
+
+    medianum = np.array(prop).shape[0]
+    if medianum <= 1:
+        raise ValueError("Empty property list")
+
+    if unitinmm is None:
+        if "unitinmm" in detp:
+            unitinmm = detp["unitinmm"]
+        else:
+            unitinmm = 1
+
+    if isinstance(detp, dict):
+        if "w0" not in detp:
+            detw = np.ones(detp["ppath"].shape[0])
+        else:
+            detw = detp["w0"]
+
+        for i in range(medianum - 1):
+            detw = detw * np.exp(-prop[i + 1, 0] * detp["ppath"][:, i] * unitinmm)
+    else:
+        raise ValueError('The first input must be a dict with a key named "ppath"')
+
+    return detw
+
+
+def meanscat(detp, prop):
+    """
+    Calculate the average scattering event counts for each tissue type for a given source-detector pair
+
+    (Python code was adapted from mcxmeanscat.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        detp: the 2nd output from mcxlab. detp can be either a struct or an array (detp.data)
+        prop: optical property list, as defined in the cfg.prop field of mcxlab's input
+
+    output:
+        avgnscat: the average scattering event count for each tissue type
+
+    Python code was ported from mcxmeanpath.m MATLAB function by Fan-Yu Yen
+    """
+    detw = detweight(detp, prop)
+    avgnscat = np.sum(
+        np.array(detp["nscat"], dtype=float) * detw[:, np.newaxis]
+    ) / np.sum(detw)
+
+    return avgnscat
+
+
+def dettpsf(detp, detnum, prop, time):
+    """
+    Calculate the temporal point spread function curve of a specified detector
+    given the partial path data, optical properties, and distribution of time bins
+
+    (Python code was adapted from mcxdettpsf.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        detp: the 2nd output from mcxlab. detp must be a struct with detid and ppath subfields
+        detnum: specified detector number
+        prop: optical property list, as defined in the cfg.prop field of mcxlab's input
+        time: distribution of time bins, a 1*3 vector [tstart tend tstep]
+              could be defined different from in the cfg of mcxlab's input
+    output:
+        tpsf: caculated temporal point spread function curve of the specified detector
+    """
+    detp = detp.copy()
+
+    # select the photon data of the specified detector
+    detp["ppath"] = detp["ppath"][detp["detid"] == detnum, :]
+    detp["detid"] = detp["detid"][detp["detid"] == detnum]
+
+    # calculate the detected photon weight and arrival time
+    replayweight = detweight(detp, prop)
+    replaytime = dettime(detp, prop)
+
+    # define temporal point spread function vector
+    nTG = int(np.round((time[1] - time[0]) / time[2]))
+    tpsf = np.zeros((nTG, 1))
+
+    # calculate the time bin, make sure not to exceed the boundary
+    ntg = np.ceil((replaytime - time[0]) / time[2])
+    ntg[ntg < 1] = 1
+    ntg[ntg > nTG] = nTG
+
+    ntg = ntg.astype(int)
+    ntg = ntg[0]
+
+    # add each photon weight to corresponding time bin
+    for i in range(len(replayweight)):
+        tpsf[ntg[i] - 1] = tpsf[ntg[i] - 1] + replayweight[i]
+
+    return tpsf
+
+
+def dettime(detp, prop=None, unitinmm=None):
+    """
+    Recalculate the detected photon time using partial path data and
+    optical properties (for perturbation Monte Carlo or detector readings)
+
+    (Python code was adapted from mcxdettime.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        detp: the 2nd output from mcxlab. detp must be a struct
+        prop: optical property list, as defined in the cfg.prop field of mcxlab's input
+        unitinmm: voxel edge-length in mm, should use cfg.unitinmm used to generate detp;
+              if ignored, assume to be 1 (mm)
+
+    output:
+        dett: re-caculated detected photon time based on the partial path data and optical property table
+    """
+    R_C0 = 3.335640951981520e-12  # inverse of light speed in vacuum
+    if unitinmm is None:
+        if "unitinmm" in detp:
+            unitinmm = detp["unitinmm"]
+        else:
+            unitinmm = 1
+
+    if prop is None:
+        if "prop" in detp:
+            prop = detp["prop"]
+        else:
+            raise ValueError('must provide input "prop"')
+
+    medianum = prop.shape[0]
+    if medianum <= 1:
+        raise ValueError("empty property list")
+
+    if isinstance(detp, dict):
+        dett = np.zeros((1, detp["ppath"].shape[0]))
+        for i in range(medianum - 1):
+            dett = dett + prop[i + 1, 3] * detp["ppath"][:, i] * R_C0 * unitinmm
+    else:
+        raise ValueError(
+            'the first input must be a struct with a subfield named "ppath"'
+        )
+    return dett
+
+
+def tddiffusion(mua, musp, v, Reff, srcpos, detpos, t):
+    """
+    Semi-infinite medium analytical solution to diffusion model
+
+    (Python code was adapted from tddiffusion.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        mua:   the absorption coefficients in 1/mm
+        musp:  the reduced scattering coefficients in 1/mm
+        v:     the speed of light
+        Reff:  the effective reflection coeff.
+        srcpos:array for the source positions (x,y,z)
+        detpos:array for the detector positions (x,y,z)
+        t:     a list of time in s at which to evaluate the
+             analytical diffusion solution
+
+    output:
+        Phi:  the output fluence for all time points
+    """
+    srcpos = np.atleast_2d(srcpos)
+    detpos = np.atleast_2d(detpos)
+
+    D = 1 / (3 * (mua + musp))
+    zb = (1 + Reff) / (1 - Reff) * 2 * D
+
+    z0 = 1 / (musp + mua)
+    r = getdistance(
+        np.concatenate((srcpos[:, 0:2].flatten(), srcpos[:, 2].flatten() + z0)), detpos
+    )
+    r2 = getdistance(
+        np.concatenate(
+            (srcpos[:, 0:2].flatten(), srcpos[:, 2].flatten() - z0 - 2 * zb)
+        ),
+        detpos,
+    )
+
+    s = 4 * D * v * t
+
+    # unit of phi:  1/(mm^2*s)
+    Phi = (
+        v
+        / ((s * np.pi) ** (3 / 2))
+        * np.exp(-mua * v * t)
+        * (np.exp(-(r**2) / s) - np.exp(-(r2**2) / s))
+    )
+
+    return Phi
+
+
+def getdistance(srcpos, detpos):
+    """
+    Compute the source/detector separation from the positions
+
+    (Python code was adapted from getdistance.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        srcpos:array for the source positions (x,y,z)
+        detpos:array for the detector positions (x,y,z)
+
+    output:
+        separation:  the distance matrix between all combinations
+              of sources and detectors. separation has the number
+              of source rows, and number of detector of columns.
+    """
+    srcpos = np.atleast_2d(srcpos)
+    detpos = np.atleast_2d(detpos)
+
+    srcnum = len(srcpos[:, 0])
+    detnum = len(detpos[:, 0])
+
+    separation = np.zeros((detnum, srcnum))
+
+    for s in range(srcnum):
+        for r in range(detnum):
+            separation[r, s] = np.linalg.norm(srcpos[s, :] - detpos[r, :])
+    return separation
+
+
+def detphoton(detp, medianum, savedetflag, issaveref=None, srcnum=None):
+    """
+    Separating combined detected photon data into easy-to-read structure based on
+    user-specified detected photon output format ("savedetflag")
+
+    (Python code was adapted from mcxdetphoton.m MATLAB function, ported by Fan-Yu Yen)
+
+    input:
+        detp: a 2-D array defining the combined detected photon data, usually
+              detp.data, where detp is the 2nd output from mcxlab
+        medianum: the total number of non-zero tissue types (row number of cfg.prop minus 1)
+        savedetflag: the cfg.savedetflag string, containing letters 'dspmxvwi' denoting different
+              output data fields, please see mcxlab's help
+        issaveref: the cfg.issaveref flag, 1 for saving diffuse reflectance, 0 not to save
+        srcnum: the cfg.srcnum flag, denoting the number of source patterns in the photon-sharing mode
+
+    output:
+        newdetp: re-organized detected photon data as a dict; the mapping of the fields are
+                 newdetp['detid']: the ID(>0) of the detector that captures the photon (1)
+                 newdetp['nscat']: cummulative scattering event counts in each medium (#medium)
+                 newdetp['ppath']: cummulative path lengths in each medium, i.e. partial pathlength (#medium)
+                      one need to multiply cfg.unitinmm with ppath to convert it to mm.
+                 newdetp['mom']: cummulative cos_theta for momentum transfer in each medium (#medium)
+                 newdetp['p'] or ['v']: exit position and direction, when cfg.issaveexit=1 (3)
+                 newdetp['w0']: photon initial weight at launch time (3)
+                 newdetp['s']: exit Stokes parameters for polarized photon (4)
+                 newdetp['srcid']: the ID of the source when multiple sources are defined (1)
+    """
+    newdetp = {}
+    c0 = 0
+    length = 0
+
+    if re.search("[dD]", savedetflag):
+        if issaveref is not None and issaveref > 1:
+            newdetp["w0"] = detp[0, :].transpose()
+        else:
+            newdetp["detid"] = detp[0, :].astype(int).transpose()
+            if np.any(newdetp["detid"] > 65535):
+                newdetp["srcid"] = np.right_shift(newdetp["detid"], 16, dtype=np.int32)
+                newdetp["detid"] = np.bitwise_and(
+                    newdetp["detid"], 0xFFFF, dtype=np.int32
+                )
+        c0 = 1
+
+    length = medianum
+    if re.search("[sS]", savedetflag):
+        newdetp["nscat"] = detp[c0 : c0 + length, :].astype(int).transpose()
+        c0 = c0 + length
+
+    if re.search("[pP]", savedetflag):
+        newdetp["ppath"] = detp[c0 : c0 + length, :].transpose()
+        c0 = c0 + length
+
+    if re.search("[mM]", savedetflag):
+        newdetp["mom"] = detp[c0 : c0 + length, :].transpose()
+        c0 = c0 + length
+
+    length = 3
+    if re.search("[xX]", savedetflag):
+        newdetp["p"] = detp[c0 : c0 + length, :].transpose()
+        c0 = c0 + length
+
+    if re.search("[vV]", savedetflag):
+        newdetp["v"] = detp[c0 : c0 + length, :].transpose()
+        c0 = c0 + length
+
+    if re.search("[wW]", savedetflag):
+        length = 1
+        newdetp["w0"] = detp[c0 : c0 + length, :].transpose()
+        if srcnum is not None and srcnum > 1:
+            newdetp["w0"] = newdetp["w0"].view("uint32")
+        c0 = c0 + length
+
+    if re.search("[iI]", savedetflag):
+        length = 4
+        newdetp["s"] = detp[c0 : c0 + length, :].transpose()
+        c0 = c0 + length
+
+    return newdetp
+
+
+def mcxlab(*args):
+    """
+    Python wrapper of mcxlab - please see the help information of mcxlab.m for details
+
+    (Python code was adapted from mcxlab.m MATLAB function, ported by Fan-Yu Yen)
+
+    Format:
+       res = mcxlab(cfg);
+          or
+       res = mcxlab(cfg, option);
+
+    Input:
+       cfg: a dictionary defining the parameters associated with a simulation.
+            if cfg='gpuinfo': return the supported GPUs and their parameters,
+            if cfg='version': return the version of MCXLAB as a string,
+       option: (optional), options is a string, specifying additional options
+            option='opencl':  force using mcxcl.mex* instead of mcx.mex* on NVIDIA/AMD/Intel hardware
+            option='cuda':    force using mcx.mex* instead of mcxcl.mex* on NVIDIA GPUs
+
+       if one defines USE_MCXCL=1 in as Python global variable, all following
+       pmcx.mcxlab calls will use _pmcxcl (OpenCL version of mcx); by setting option='cuda',
+       one can force pmcx.mcxlab to use _pmcx (CUDA version). Similarly, if
+       USE_MCXCL=0, all pmcx.mcxlab calls will use _pmcx by default, unless
+       one sets option='opencl'.
+
+    Output:
+         res: a dictionary containing the following subfields
+             res['flux'] is a 4D array with
+                    dimensions specified by [size(vol) total-time-gates].
+                    The content of the array is the normalized fluence at
+                    each voxel of each time-gate.
+
+                    when cfg.debuglevel contains 'T', fluence(i).data stores trajectory
+                    output, see below
+             res['dref'] is a 4D array with the same dimension as fluence(i).data
+                    if cfg.issaveref is set to 1, containing only non-zero values in the
+                    layer of voxels immediately next to the non-zero voxels in cfg.vol,
+                    storing the normalized total diffuse reflectance (summation of the weights
+                    of all escaped photon to the background regardless of their direction);
+                    it is an empty array [] when if cfg.issaveref is 0.
+             res['stat'] is a structure storing additional information, including
+                    runtime: total simulation run-time in millisecond
+                    nphoton: total simulated photon number
+                    energytot: total initial weight/energy of all launched photons
+                    energyabs: total absorbed weight/energy of all photons
+                    normalizer: normalization factor
+                    unitinmm: same as cfg.unitinmm, voxel edge-length in mm
+
+             res['detp']: res['detp'] is a directionary object including the following field
+                   res['detp']['detid']: the ID(>0) of the detector that captures the photon
+                   res['detp']['nscat']: cummulative scattering event counts in each medium
+                   res['detp']['ppath']: cummulative path lengths in each medium (partial pathlength)
+                        one need to multiply cfg.unitinmm with ppath to convert it to mm.
+                   res['detp']['mom']: cummulative cos_theta for momentum transfer in each medium
+                   res['detp']['p'] or ['v']: exit position and direction, when cfg.issaveexit=1
+                   res['detp']['nscat']: photon initial weight at launch time
+                   res['detp']['s']: exit Stokes parameters for polarized photon
+                   res['detp']['prop']: optical properties, a copy of cfg.prop
+                   res['detp']['data']: a concatenated and transposed array in the order of
+                        [detid nscat ppath mom p v w0]'
+
+                   if returned by pmcx.run, res['det'] is a 2D numpy array in a format as
+                   res['detp']['data'] described above
+
+             res['vol']: (optional) a numpy array storing a preprocessed volume.
+                   Each volume is a 3D int32 array.
+             res['seeds']: (optional), if give, mcxlab returns the seeds, in the form of
+                   a byte array (uint8) for each detected photon. The column number
+                   of seed equals that of res['detp'].
+             res['traj']: if given, mcxlab returns the trajectory data for
+                   each simulated photon. The output has 6 rows, the meanings are
+                      res['traj']['id']:    1:    index of the photon packet
+                      res['traj']['pos']: 2-4:    x/y/z/ of each trajectory position
+                                            5:    current photon packet weight
+                                            6:    reserved
+               By default, mcxlab only records the first 1e7 positions along all
+               simulated photons; change cfg['maxjumpdebug'] to define a different limit.
+    """
+    try:
+        defaultocl = eval("USE_MCXCL", globals())
+    except:
+        defaultocl = 0
+
+    useopencl = defaultocl
+
+    if len(args) == 1 and isinstance(args[0], str):
+        if args[0] == "gpuinfo":
+            varargout = pmcx.gpuinfo()
+            return varargout
+        elif args[0] == "version":
+            varargout = pmcx.version()
+            return varargout
+
+    if len(args) == 2 and isinstance(args[1], str):
+        if args[1] == "preview":
+            varargout = mcxpreview(args[0])
+            return varargout
+        elif args[1] == "opencl":
+            useopencl = 1
+
+    if isinstance(args[0], dict):
+        castlist = [
+            "srcpattern",
+            "srcpos",
+            "detpos",
+            "prop",
+            "workload",
+            "srcdir",
+            "srciquv",
+        ]
+        for j in range(len(castlist)):
+            if castlist[j] in args[0]:
+                args[0][castlist[j]] = np.double(args[0][castlist[j]])
+
+        if "vol" in args[0] and np.ndim(args[0]["vol"]) == 4:
+            if (
+                isinstance(args[0]["vol"], np.float32)
+                or isinstance(args[0]["vol"], np.float64)
+            ) and "unitinmm" in args[0]:
+                args[0]["vol"] = args[0]["vol"] * args[0]["unitinmm"]
+
+        if "tstart" not in args[0]:
+            args[0]["tstart"] = 0
+
+        if "tend" not in args[0]:
+            raise ValueError(
+                "you must define cfg.tend for the maximum time-of-flight of a photon in seconds"
+            )
+
+        if "tstep" not in args[0]:
+            args[0]["tsetp"] = args[0]["tend"]
+
+        if "srcpos" not in args[0]:
+            raise ValueError(
+                "you must define cfg.srcpos to define the x/y/z position of the source in voxel unit"
+            )
+
+        if "detphotons" in args[0] and isinstance(args[0]["detphotons"], dict):
+            if "data" in args[0]["detphotons"]:
+                args[0]["detphotons"] = args[0]["dephotons"]["data"]
+            else:
+                fulldetdata = ["detid", "nscat", "ppath", "mom", "p", "v", "w0"]
+                detfields = [x in args[0]["detphotons"] for x in fulldetdata]
+                detdata = []
+                for j in range(len(detfields)):
+                    if detfields[j]:
+                        val = np.array(
+                            args[0]["detphotons"][fulldetdata[j]], dtype=np.float32
+                        )
+                        detdata.append(
+                            np.reshape(
+                                val, np.shape(args[0]["detphotons"][fulldetdata[j]])
+                            )
+                        )
+                args[0]["detphotons"] = detdata.transpose()
+                args[0]["savedetflag"] = "dspmxvw"
+                args[0]["savedetflag"][detfields == 0] = []
+
+    if useopencl == 0:
+        varargout = pmcx.run(args[0])
+    else:
+        try:
+            import pmcxcl
+
+            varargout = pmcxcl.run(args[0])
+        except ImportError:
+            raise ImportError(
+                'To call OpenCL based MCX, one must first run "pip install pmcxcl" to install pmcxcl'
+            )
+
+    if len(args) == 0:
+        return
+
+    cfg = args[0]
+
+    if not isinstance(cfg, str):
+        if "srcnum" in cfg and cfg["srcnum"] > 1:
+            dim = varargout["flux"].shape
+            varargout["flux"] = varargout["flux"].reshape(
+                [cfg["srcnum"], int(dim[0] / cfg["srcnum"]), *dim[1:]]
+            )
+            varargout["flux"] = np.transpose(
+                varargout["flux"], [i for i in range(1, len(dim) + 1)] + [0]
+            )
+            if "dref" in varargout and varargout["dref"] is not None:
+                varargout["dref"] = varargout["dref"].reshape(
+                    [cfg["srcnum"], int(dim[0] / cfg["srcnum"]), *dim[1:]]
+                )
+                varargout["dref"] = np.transpose(
+                    varargout["dref"], [i for i in range(1, len(dim) + 1)] + [0]
+                )
+
+    if "detp" in varargout:
+        #         for i in range(len(varargout.keys())): #for i in range(varargout[1]):
+        if ("savedetflag" not in cfg) or (
+            ("savedetflag" in cfg) and (not cfg["savedetflag"])
+        ):
+            cfg["savedetflag"] = "DP"
+
+        if "issaveexit" in cfg and cfg["issaveexit"]:
+            cfg["savedetflag"] += "XV"
+
+        if "ismomentum" in cfg and cfg["ismomentum"]:
+            cfg["savedetflag"] += "M"
+
+        if "polprop" in cfg and cfg["polprop"]:
+            cfg["savedetflag"] += "PVWI"
+        else:
+            cfg["savedetflag"] = (
+                cfg["savedetflag"].replace("I", "").replace("i", "")
+            )  # cfg(i).savedetflag(regexp(cfg(i).savedetflag,'[Ii]'))=[];
+
+        if np.ndim(cfg["vol"]) == 4 and np.shape(cfg["vol"])[0] != 8:
+            cfg["savedetflag"] = ""
+            if (
+                isinstance(cfg["vol"], float) or isinstance(cfg["vol"], double)
+            ) and "unitinmm" in cfg:  # if((isa(cfg(i).vol,'single') || isa(cfg(i).vol,'double')) && isfield(cfg(i),'unitinmm'))
+                cfg["vol"] = cfg["vol"] * cfg["unitinmm"]
+
+        if "issaveexit" not in cfg or cfg["issaveexit"] != 2:
+            medianum = np.shape(cfg["prop"])[0] - 1
+            detp = varargout["detp"]  # detp = varargout[1]['data']
+            #             if not detp:
+            #                 continue
+
+            if "polprop" in cfg and cfg["polprop"]:
+                medianum = np.shape(cfg["polprop"])[0]
+
+            flags = [cfg["savedetflag"]]
+
+            if "issaveref" in cfg:
+                flags.append(cfg["issaveref"])
+
+            if "srcnum" in cfg:
+                flags.append(cfg["srcnum"])
+
+            newdetp = detphoton(
+                detp, medianum, *flags
+            )  # newdetp=mcxdetphoton(detp,medianum,flags{:});
+            newdetp["prop"] = cfg["prop"]
+
+            if "polprop" in cfg and cfg["polprop"] and "prop" in varargout:
+                newdetp["prop"][1:] = np.transpose(varargout["prop"][:, 1:])
+
+            if "unitinmm" in cfg:
+                newdetp["unitinmm"] = cfg["unitinmm"]
+
+            newdetp["data"] = detp
+            newdetpstruct = newdetp
+        else:
+            newdetpstruct = varargout["detp"]
+
+        if "newdetpstruct" in locals():
+            varargout["detp"] = newdetpstruct  # varargout = newdetpstruct
+
+    if "traj" in varargout:
+        data = varargout["traj"]
+        if len(data):
+            traj = {}
+            traj["pos"] = np.transpose(data[1:4, :])
+            traj["id"] = np.frombuffer(data[0, :].tobytes(), dtype=np.uint32)
+            traj["id"], idx = np.sort(traj["id"]), np.argsort(traj["id"])
+            traj["pos"] = traj["pos"][idx, :]
+            traj["data"] = np.vstack([np.single(traj["id"]), data[1:, idx]])
+            varargout["traj"] = traj
+
+    return varargout

pmcx-0.4.2.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: pmcx
+Version: 0.4.2
+Summary: Python bindings for Monte Carlo eXtreme photon transport simulator
+Home-page: https://github.com/fangq/mcx
+Download-URL: https://mcx.space
+Author: Matin Raayai Ardakani, Qianqian Fang, Fan-Yu Yen
+Author-email: raayaiardakani.m@northeastern.edu, q.fang@neu.edu, yen.f@northeastern.edu
+Maintainer: Qianqian Fang
+License: GPLv3+
+Keywords: Monte Carlo simulation,Biophotonics,Ray-tracing,Rendering,GPU,Modeling,Biomedical Optics,Tissue Optics,Simulator,Optics,NVIDIA,CUDA
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires: numpy
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: maintainer
+Dynamic: requires
+Dynamic: requires-python
+Dynamic: summary
+
+![](https://mcx.space/img/mcx_wiki_banner.png)
+
+# PMCX - Python bindings for Monte Carlo eXtreme photon transport simulator
+
+- Copyright: (C) Matin Raayai Ardakani (2022-2023) <raayaiardakani.m at northeastern.edu>, Qianqian Fang (2019-2025) <q.fang at neu.edu>, Fan-Yu Yen (2023-2024) <yen.f at northeastern.edu>
+- License: GNU Public License V3 or later
+- Version: 0.4.2
+- URL: https://pypi.org/project/pmcx/
+- Github: https://github.com/fangq/mcx
+
+![Linux Python Module](https://github.com/fangq/mcx/actions/workflows/build_linux_manywheel.yml/badge.svg)\
+![MacOS Python Module](https://github.com/fangq/mcx/actions/workflows/build_macos_wheel.yml/badge.svg)\
+![Windows Python Module](https://github.com/fangq/mcx/actions/workflows/build_windows_wheel.yml/badge.svg)
+
+This module provides a Python binding for Monte Carlo eXtreme (MCX).
+For other binaries, including the standalone executable and the MATLAB bindings, see [our website](http://mcx.space).
+
+Monte Carlo eXtreme (MCX) is a fast photon transport simulation software for 3D 
+heterogeneous turbid media. By taking advantage of the massively parallel 
+threads and extremely low memory latency in a modern graphics processing unit 
+(GPU), MCX is capable of performing Monte Carlo (MC) photon simulations at a 
+blazing speed, typically hundreds to a thousand times faster than a fully 
+optimized CPU-based MC implementation.
+
+## How to Install
+
+* PIP: ```pip install pmcx``` see https://pypi.org/project/pmcx/
+
+## Runtime Dependencies
+* **NVIDIA GPU Driver**: A CUDA-capable NVIDIA GPU and driver is required to run MCX. An up-to-date driver is recommended.
+The binary wheel distributed over pip runs on NVIDIA drivers with CUDA 10.1 support on Windows, CUDA 9.2 support on Linux, and
+CUDA 10.2 support on macOS, respectively. For more details on driver versions and their CUDA support, see the 
+[CUDA Release Notes](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html). 
+To download the latest driver for your system, see the 
+[NVIDIA Driver Download Page](https://www.nvidia.com/download/index.aspx).
+**You shouldn't need to have CUDA toolkit installed**. MCX is built with the static CUDA runtime library. 
+* **Python**: Python 3.6 and newer is required. **Python 2 is not supported**.
+* **numpy**: Used to pass/receive volumetric information to/from pmcx. To install, use either conda or pip 
+package managers: `pip install numpy` or `conda install numpy`
+* (optional) **jdata**: Only needed to read/write JNIfTI output files. To install, use pip: `pip install jdata` 
+on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter 
+using apt-get: `sudo apt-get install python3-jdata`. See https://pypi.org/project/jdata/ for more details. 
+* (optional) **bjdata**: Only needed to read/write BJData/UBJSON files. To install, run `pip install bjdata` 
+on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter 
+using apt-get: `sudo apt-get install python3-bjdata`. See https://pypi.org/project/bjdata/ for more details. 
+* (optional) **matplotlib**: For plotting the results. To install, run either `pip install matplotlib` or
+`conda install matplotlib`
+
+## Build Instructions
+
+### Build Dependencies
+* **Operating System**: Windows and Linux are fully supported; For building MCX on macOS, OSX 10.13 (High Sierra) and 
+older are highly recommended since 10.13 was the last version of macOS with NVIDIA CUDA support, and matching the CUDA 
+compiler version with the C/C++ compiler shipped with Xcode is easier. Newer macOS versions can be used for building MCX, 
+but need to have System Integrity Protection disabled prior to installing the CUDA toolkit due to the NVIDIA installer copying
+its payload under the ```/Developer``` directory under root.
+* **NVIDIA CUDA Toolkit**: CUDA 7.5 or newer is required. On macOS, 10.2 is the last available CUDA version.
+For details on how to install CUDA, see the [CUDA Download Page](https://developer.nvidia.com/cuda-downloads). 
+The NVIDIA GPU driver of the target system must support the selected CUDA toolkit.
+* **Python Interpreter**: Python 3.6 or above. The ```pip``` Python package manager and the ```wheel``` package (available
+  via ```pip```) are not required but recommended.
+* **C/C++ Compiler**: CUDA Toolkit supports only the following compilers:
+  * GNU GCC for Linux-based distributions.
+  * Microsoft Visual Studio C/C++ Compiler for Windows.
+  * Apple Clang for macOS, available via Xcode. The last Xcode version supported by CUDA 10.2 is 10.3. If using an OSX 
+  version higher than 10.15 it can be downloaded and installed from [Apple's Developer Website](https://developer.apple.com/download/) 
+  with an Apple ID. After installation, select the proper Xcode version from the commandline, and set the ```SDKROOT```
+  environment variable:
+    ```zsh
+    sudo xcode-select -s /Applications/Xcode_10.3.app/Contents/Developer/
+    export SDKROOT=/Applications/Xcode_10.3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
+    ```
+  
+  Refer to each OS's online documentations for more in-depth information on how to install these compilers.
+  Note that the version of the C/C++ compiler used must be supported by the CUDA toolkit version. If not, compilation
+  will fail with an error notifying you of this problem. See the [CUDA Installation Guides](https://developer.nvidia.com/cuda-toolkit-archive)
+  for more details.
+* **OpenMP**: The installed C/C++ Compiler should have support for [OpenMP](https://www.openmp.org/). 
+  GCC and Microsoft Visual Studio compiler support OpenMP out of the box. Apple Clang, however, requires manual 
+  installation of OpenMP libraries for Apple Clang. The easiest way to do this is via the [Brew](https://brew.sh/) package
+  manager, preferably after selecting the correct Xcode version:
+  ```zsh
+    brew install libomp
+    brew link --force libomp
+  ```
+
+* **CMake**: CMake version 3.15 and later is required. Refer to the [CMake website](https://cmake.org/download/) for more information on how to download.
+  CMake is also widely available on package managers across all operating systems.
+  Additionally, on Windows, make sure **Visual Studio's C++ CMake tools for Windows** is also installed by selecting its option
+  during installation.
+
+### Build Steps
+1. Ensure that ```cmake```, ```nvcc``` (NVIDIA CUDA Compiler) and the C/C++ compiler are all located over your ```PATH```.
+This can be queried via ```echo $env:PATH``` on Windows or ```echo $PATH``` on Linux. If not, locate them and add their folder to the ```PATH```.
+
+2. Clone the repository and switch to the ```pmcx/``` folder:
+    ```bash
+        git clone --recursive https://github.com/fangq/mcx.git
+        cd mcx/pmcx
+    ```
+
+3. One can run `python3 setup.py install` or `python3 -m pip install .` to both locally build and install the module
+
+4. If one only wants to locally build the module, one should run `python3 -m pip wheel .`
+
+5. If the binary module is successfully built locally, you should see a binary wheel file `pmcx-X.X.X-cpXX-cpXX-*.whl`
+stored inside the `mcx/pmcx` folder. You can install this wheel package using `python3 -m pip install --force-reinstall pmcx-*.whl`
+to force installing this locally compiled `pmcx` module and overwrite any previously installed versions.
+
+
+## How to use
+
+The PMCX module is easy to use. You can use the `pmcx.gpuinfo()` function to first verify
+if you have NVIDIA/CUDA compatible GPUs installed; if there are NVIDIA GPUs detected,
+you can then call the `run()` function to launch a photon simulation.
+
+A simulation can be defined conveniently in two approaches - a one-liner and a two-liner:
+
+* For the one-liner, one simply pass on each MCX simulation setting as positional
+argument. The supported setting names are compatible to nearly all the input fields
+for the MATLAB version of MCX - [MCXLAB](https://github.com/fangq/mcx/blob/master/mcxlab/mcxlab.m))
+
+```python3
+import pmcx
+import numpy as np
+import matplotlib.pyplot as plt
+
+res = pmcx.run(nphoton=1000000, vol=np.ones([60, 60, 60], dtype='uint8'), tstart=0, tend=5e-9, 
+               tstep=5e-9, srcpos=[30,30,0], srcdir=[0,0,1], prop=np.array([[0, 0, 1, 1], [0.005, 1, 0.01, 1.37]]))
+res['flux'].shape
+
+plt.imshow(np.log10(res['flux'][30,:, :]))
+plt.show()
+```
+
+* Alternatively, one can also define a Python dict object containing each setting
+as a key, and pass on the dict object to `pmcx.run()`, or preferably, `pmcx.mcxlab()`
+
+```python3
+import pmcx
+import numpy as np
+cfg = {'nphoton': 1000000, 'vol':np.ones([60,60,60],dtype='uint8'), 'tstart':0, 'tend':5e-9, 'tstep':5e-9,
+       'srcpos': [30,30,0], 'srcdir':[0,0,1], 'prop':[[0,0,1,1],[0.005,1,0.01,1.37]]}
+res = pmcx.run(cfg)      # pmcx.run returns detected photon data as a concatenated 2D array res['detp'], same for res['traj']
+# or alternatively/preferably
+res = pmcx.mcxlab(cfg)   # pmcx.mcxlab calls pmcx.run, and postprocess res['detp'] and res['traj'] raw data into dict form
+```

pmcx-0.4.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+pmcx/__init__.py,sha256=2uQQ2eIXRBB8cKX8QQBbl4fdxR8OCnO47SdOZq6ZX8Y,1898
+pmcx/bench.py,sha256=sFe2MprqqAx7HdUB_wgz8wMc6SsQcJrERrUe6fa5BdM,1691
+pmcx/utils.py,sha256=qiarJdO-aVCHEvui7HAXnXvI0EUQYllocBF9A8dacpw,25781
+pmcx-0.4.2.dist-info/METADATA,sha256=sdTGxQRM2p1H4xPZo0cFlZDTluSulI4SEX1ovqbqkFE,10460
+pmcx-0.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pmcx-0.4.2.dist-info/top_level.txt,sha256=Mzy152LlBPhQQ2nJ5TTpjuqQeZwfKz5gPXtj-YuU4yw,5
+pmcx-0.4.2.dist-info/RECORD,,

pmcx-0.4.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pmcx-0.4.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+pmcx