mcx
v2024.2 (Interstellar Ion)
Tabla de contenido:
MCX v2024.2 contiene importantes funciones nuevas y correcciones de errores críticos. Es una actualización muy recomendada para todos los usuarios.
Específicamente, MCX v2024.2 recibió tres nuevas características importantes:
Similar a la característica de función de fase definida por el usuario incluida en MCX v2023, la primera característica permite a los usuarios definir la distribución del ángulo cenital para lanzar un fotón, en relación con el vector de dirección de origen, también a través de una CDF (función de distribución acumulativa) inversa discretizada. . En MATLAB/Octave, se pueden configurar como cfg.invcdf o cfg.angleinvcdf , respectivamente. Proporcionamos scripts de demostración listos para usar en mcxlab/examples/demo_mcxlab_phasefun.m y demo_mcxlab_launchangle.m .
La segunda característica permite a los usuarios especificar más de una fuente del mismo tipo al definir srcpos , srcdir , srcparam1 y srcparam2 . Cada fuente puede tener un peso independiente controlado por el cuarto elemento de srcpos.
Además de las nuevas funciones, se descubrió un error grave que afecta a todas las simulaciones pattern y pattern3d que no utilizan el uso compartido de fotones; consulte
#212
Debido a este error, MCX/MCX-CL en versiones anteriores ha estado simulando datos de patrón cuadrado/patrón 3d en lugar del patrón en sí. Si su simulación utiliza estos dos tipos de fuentes y no utiliza el uso compartido de fotones (es decir, simula múltiples patrones juntos), actualice su MCX/MCX-CL y vuelva a ejecutar sus simulaciones. Este error solo afecta las salidas de fluencia/flujo volumétrico; no afecta las salidas de reflectancia difusa ni los patrones binarios.
También incluye una corrección de errores del n.° 195 con respecto a la pérdida de precisión al guardar la reflectancia difusa.
Queremos agradecer a Haohui Zhang por informar una serie de problemas críticos (n.° 195 y n.° 212), y a Liam Keegan por contribuir con un parche para ampliar la fuente de la hendidura (n.° 214). ShijieYan y fanyuyen también han contribuido a corregir errores y mejorar.
Las actualizaciones detalladas se pueden encontrar en el registro de cambios a continuación.
Monte Carlo eXtreme (MCX) es un software de simulación de fotones rápido y físicamente preciso para medios complejos heterogéneos en 3D. Aprovechando los subprocesos masivamente paralelos y la latencia de memoria extremadamente baja en una unidad de procesamiento de gráficos (GPU) moderna, este programa es capaz de realizar simulaciones de Monte Carlo (MC) a una velocidad vertiginosa, generalmente de cientos a mil veces más rápida que una sola. -Implementación de MC basada en CPU con subprocesos.
MCX está escrito en C y NVIDIA CUDA. Solo se ejecutará en GPU NVIDIA. Si desea ejecutar simulaciones MCX aceleradas por hardware en GPU o CPU AMD/Intel, descargue MCX-CL (MCX para OpenCL), que está escrito en OpenCL. MCX y MCX-CL son altamente compatibles.
Debido a la naturaleza de los algoritmos MC subyacentes, MCX y MCX-CL son software de trazado/difusión de rayos ocultos. En comparación con las bibliotecas de trazado de rayos comúnmente utilizadas en gráficos por computadora o motores de juegos, MCX-CL y MCX tienen muchas características únicas. La diferencia más importante es que MCX/MCX-CL se basan rigurosamente en leyes físicas. Son solucionadores numéricos de la ecuación de transferencia radiativa (RTE) subyacente y sus soluciones han sido validadas en muchas publicaciones utilizando instrumentos ópticos y mediciones experimentales. En comparación, la mayoría de los trazadores de rayos orientados a gráficos tienen que realizar muchas aproximaciones para lograr una representación rápida y permitir proporcionar resultados de simulación de luz cuantitativamente precisos. Debido a esto, las comunidades de investigación en biofotónica han utilizado ampliamente MCX/MCX-CL para obtener soluciones de referencia y guiar el desarrollo de nuevos sistemas de imágenes médicas o aplicaciones clínicas. Además, MCX/MCX-CL son trazadores de rayos volumétricos; atraviesan rayos de fotones a lo largo de complejos dominios tridimensionales y calcula cantidades físicamente significativas, como fluencia resuelta espacialmente, flujo, reflectancia/transmitancia difusa, deposición de energía, longitudes de trayectoria parciales, entre muchas otras. Por el contrario, la mayoría de los motores de trazado de rayos gráficos solo trazan el color RGB de un rayo y lo representan en una pantalla plana 2-D. En otras palabras, MCX/MCX-CL ofrece distribuciones de luz 3D físicamente precisas, mientras que los trazadores de rayos gráficos se centran en la representación 2D de una escena en la cámara. No obstante, comparten muchas similitudes, como el cálculo de marcha de rayos, la aceleración de GPU, el manejo de dispersión/absorción, etc.
El algoritmo de este software se detalla en las Referencias [Fang2009,Yu2018,Yan2020]. Un breve resumen de las características principales incluye:
Este software se puede utilizar en Windows, Linux y Mac OS. MCX está escrito en C/CUDA y requiere GPU NVIDIA (la compatibilidad con CPU/GPU AMD/Intel a través de ROCm aún está en desarrollo). En julio de 2012 se anunció una implementación OpenCL más portátil de MCX, es decir, MCXCL, que es compatible con casi todos los modelos de CPU y GPU NVIDIA/AMD/Intel. Si su hardware no es compatible con CUDA, descargue MCXCL desde la siguiente URL:
https://mcx.space/wiki/index.cgi?Learn#mcxcl
Por favor lea esta sección atentamente. La mayoría de las fallas al usar MCX se encontraron relacionadas con la instalación incorrecta del controlador de GPU NVIDIA.
Busque https://mcx.space/#documentation para obtener instrucciones paso a paso.
Para MCX-CUDA, los requisitos para usar este software incluyen
Debe asegurarse de que su controlador de gráficos NVIDIA esté instalado correctamente. Puede encontrar una lista de tarjetas compatibles con CUDA en [2]. La arquitectura de GPU más antigua en la que se puede compilar el código fuente MCX es Fermi ( sm_20 ). Se espera que el uso de la última tarjeta NVIDIA produzca la mejor velocidad. Los binarios lanzados oficialmente (incluidos archivos mex y módulos pmcx ) pueden ejecutarse en GPU NVIDIA tan antiguas como Kepler (GTX-730, sm_35 ). Todos los archivos binarios de MCX pueden ejecutarse directamente en generaciones futuras de GPU NVIDIA sin necesidad de volver a compilarlos, por lo que son compatibles con versiones futuras.
En la siguiente página web, resumimos las diferencias de velocidad entre las diferentes generaciones de GPU NVIDIA.
https://mcx.space/gpubench/
Para simulaciones con grandes volúmenes, también se requiere suficiente memoria gráfica para realizar la simulación. La cantidad mínima de memoria gráfica requerida para una simulación MC es Nx*Ny*Nz bytes para los datos de tejido de entrada más Nx*Ny*Nz*Ng*4*2 bytes para los datos de flujo/fluencia de salida, donde Nx,Ny,Nz son las dimensiones del volumen de tejido, Ng es el número de puertas de tiempo simultáneas, 4 es el tamaño de un número de punto flotante de precisión simple, 2 es para la memoria adicional necesaria para garantizar la precisión de la salida (#41). MCX no requiere soporte de doble precisión en su hardware.
MCX almacena las propiedades ópticas y las posiciones del detector en la memoria constante. Por lo general, las GPU NVIDIA proporcionan aproximadamente 64 kB de memoria constante. Como resultado, solo podemos el número total de propiedades ópticas más el número de detectores no puede exceder 4000 (4000 * 4 * 4 = 64 k).
Además, MCX almacena los datos de los fotones detectados dentro de la memoria compartida, que también oscila entre 42 kB y 100 kB por procesador de flujo en diferentes generaciones de GPU. Si su dominio contiene muchos tipos de medios, es posible que la asignación de memoria compartida supere el límite. También recibirá un error de "memoria insuficiente".
Para instalar MCX, necesita descargar el ejecutable binario compilado para la arquitectura y plataforma de su computadora (32 o 64 bits), extraer el paquete y ejecutar el ejecutable en el directorio {mcx root}/bin .
Para los usuarios de Windows, deben asegurarse de haber instalado el controlador NVIDIA adecuado para su GPU. También debe configurar su sistema operativo para ejecutar simulaciones CUDA. Esto requiere que abra la carpeta mcx/setup/win64 usando su explorador de archivos, haga clic derecho en el archivo apply_timeout_registry_fix.bat y seleccione "Ejecutar como administrador" . Después de la confirmación, debería ver una ventana de comando de Windows con el mensaje
Patching your registry
Done
Press any key to continue ...
DEBE REINICIAR su computadora con Windows para que esta configuración sea efectiva. El parche anterior modifica la configuración del controlador para que pueda ejecutar simulaciones MCX durante más de unos pocos segundos. De lo contrario, cuando ejecute MCX durante más de unos segundos, obtendrá un error CUDA: "error no especificado".
Consulte el siguiente enlace para obtener más detalles.
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
Si usa Linux, puede habilitar la GPU integrada Intel (iGPU) para la visualización mientras deja su GPU NVIDIA dedicada a la computación usando nvidia-prime , consulte
https://forums.developer.nvidia.com/t/solved-run-cuda-on-dedicated-nvidia-gpu-when-connecting-monitors-to-intel-hd-graphics-is-this-possible/47690/ 6
o elija uno de los otros 4 enfoques en esta publicación de blog
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
Notamos que al ejecutar Ubuntu Linux 22.04 con un kernel 6.5 en una computadora portátil con una GPU híbrida con una iGPU Intel y una GPU NVIDIA, debes configurar la computadora portátil para usar la GPU NVIDIA como GPU principal eligiendo "NVIDIA (Modo de rendimiento)". en la sección Perfiles PRIME de Configuración del servidor NVIDIA X. También puedes correr
sudo prime-select nvidia
para lograr el mismo objetivo. De lo contrario, la simulación puede bloquear su sistema después de ejecutarse durante unos segundos. Una computadora portátil con GPU híbrida que combina una GPU NVIDIA con una iGPU AMD no parece tener este problema si usa Linux.
Además, el controlador NVIDIA (520 o posterior) tiene un problema conocido al ejecutarse en el kernel de Linux 6.x (como los de Ubuntu 22.04). Ver
https://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153
Cuando la computadora portátil está en el modo de "rendimiento" y se reactiva de la suspensión, MCX o cualquier programa CUDA no se ejecuta con un error
MCX ERROR(-999):unknown error in unit mcx_core.cu:2523
Esto se debe a que el módulo del kernel nvida-uvm no se puede recargar después de la suspensión. Si tenía una sesión de MATLAB abierta, primero debe cerrar MATLAB y ejecutar los siguientes comandos (si MATLAB está abierto, verá rmmod: ERROR: Module nvidia_uvm is in use )
sudo rmmod /dev/nvidia-uvm
sudo modprobe nvidia-uvm
Después del comando anterior, MCX debería poder ejecutarse nuevamente.
Las nuevas generaciones de ordenadores Mac ya no son compatibles con las GPU NVIDIA o AMD. Tendrás que usar la versión OpenCL de MCX, MCX-CL descargándola desde
https://mcx.space/wiki/?Learn#mcxcl
Para ejecutar una simulación, la entrada mínima es un archivo de configuración (texto) y, si el archivo de entrada no contiene descripciones de formas de dominio integradas, un archivo de volumen externo (un archivo binario con un formato de vóxel especificado mediante -K/--mediabyte ). Al escribir mcx sin ningún parámetro, se imprime la información de ayuda y una lista de parámetros admitidos, como se muestra a continuación:
###############################################################################
# Monte Carlo eXtreme (MCX) -- CUDA #
# Copyright (c) 2009-2024 Qianqian Fang <q.fang at neu.edu> #
# https://mcx.space/ & https://neurojson.io/ #
# #
# Computational Optics & Translational Imaging (COTI) Lab- http://fanglab.org #
# Department of Bioengineering, Northeastern University, Boston, MA, USA #
###############################################################################
# The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 #
###############################################################################
# Open-source codes and reusable scientific data are essential for research, #
# MCX proudly developed human-readable JSON-based data formats for easy reuse.#
# #
#Please visit our free scientific data sharing portal at https://neurojson.io/#
# and consider sharing your public datasets in standardized JSON/JData format #
###############################################################################
$Rev::d593a0$v2024.2 $Date::2024-03-04 00:04:10 -05$ by $Author::Qianqian Fang$
###############################################################################
usage: mcx <param1> <param2> ...
where possible parameters include (the first value in [*|*] is the default)
== Required option ==
-f config (--input) read an input file in .json or .inp format
if the string starts with '{', it is parsed as
an inline JSON input file
or
--bench ['cube60','skinvessel',..] run a buint-in benchmark specified by name
run --bench without parameter to get a list
== MC options ==
-n [0|int] (--photon) total photon number (exponential form accepted)
max accepted value:9.2234e+18 on 64bit systems
-r [1|+/-int] (--repeat) if positive, repeat by r times,total= #photon*r
if negative, divide #photon into r subsets
-b [1|0] (--reflect) 1 to reflect photons at ext. boundary;0 to exit
-B '______' (--bc) per-face boundary condition (BC), 6 letters for
/case insensitive/ bounding box faces at -x,-y,-z,+x,+y,+z axes;
overwrite -b if given.
each letter can be one of the following:
'_': undefined, fallback to -b
'r': like -b 1, Fresnel reflection BC
'a': like -b 0, total absorption BC
'm': mirror or total reflection BC
'c': cyclic BC, enter from opposite face
if input contains additional 6 letters,
the 7th-12th letters can be:
'0': do not use this face to detect photon, or
'1': use this face for photon detection (-d 1)
the order of the faces for letters 7-12 is
the same as the first 6 letters
eg: --bc ______010 saves photons exiting at y=0
-u [1.|float] (--unitinmm) defines the length unit for the grid edge
-U [1|0] (--normalize) 1 to normalize flux to unitary; 0 save raw
-E [1648335518|int|mch](--seed) set rand-number-generator seed, -1 to generate
if an mch file is followed, MCX "replays"
the detected photon; the replay mode can be used
to calculate the mua/mus Jacobian matrices
-z [0|1] (--srcfrom0) 1 volume origin is [0 0 0]; 0: origin at [1 1 1]
-k [1|0] (--voidtime) when src is outside, 1 enables timer inside void
-Y [0|int] (--replaydet) replay only the detected photons from a given
detector (det ID starts from 1), used with -E
if 0, replay all detectors and sum all Jacobians
if -1, replay all detectors and save separately
-V [0|1] (--specular) 1 source located in the background,0 inside mesh
-e [0.|float] (--minenergy) minimum energy level to trigger Russian roulette
-g [1|int] (--gategroup) number of maximum time gates per run
== GPU options ==
-L (--listgpu) print GPU information only
-t [16384|int](--thread) total thread number
-T [64|int] (--blocksize) thread number per block
-A [1|int] (--autopilot) 1 let mcx decide thread/block size, 0 use -T/-t
-G [0|int] (--gpu) specify which GPU to use, list GPU by -L; 0 auto
or
-G '1101' (--gpu) using multiple devices (1 enable, 0 disable)
-W '50,30,20' (--workload) workload for active devices; normalized by sum
-I (--printgpu) print GPU information and run program
--atomic [1|0] 1: use atomic operations to avoid thread racing
0: do not use atomic operation (not recommended)
== Input options ==
-P '{...}' (--shapes) a JSON string for additional shapes in the grid.
only the root object named 'Shapes' is parsed
and added to the existing domain defined via -f
or --bench
-j '{...}' (--json) a JSON string for modifying all input settings.
this input can be used to modify all existing
settings defined by -f or --bench
-K [1|int|str](--mediabyte) volume data format, use either a number or a str
voxel binary data layouts are shown in {...}, where [] for byte,[i:]
for 4-byte integer, [s:] for 2-byte short, [h:] for 2-byte half float,
[f:] for 4-byte float; on Little-Endian systems, least-sig. bit on left
1 or byte: 0-128 tissue labels
2 or short: 0-65535 (max to 4000) tissue labels
4 or integer: integer tissue labels
96 or asgn_float: mua/mus/g/n 4xfloat format
{[f:mua][f:mus][f:g][f:n]}
97 or svmc: split-voxel MC 8-byte format
{[n.z][n.y][n.x][p.z][p.y][p.x][upper][lower]}
98 or mixlabel: label1+label2+label1_percentage
{[label1][label2][s:0-32767 label1 percentage]}
99 or labelplus: 32bit composite voxel format
{[h:mua/mus/g/n][s:(B15-16:0/1/2/3)(label)]}
100 or muamus_float: 2x 32bit floats for mua/mus
{[f:mua][f:mus]}; g/n from medium type 1
101 or mua_float: 1 float per voxel for mua
{[f:mua]}; mus/g/n from medium type 1
102 or muamus_half: 2x 16bit float for mua/mus
{[h:mua][h:mus]}; g/n from medium type 1
103 or asgn_byte: 4x byte gray-levels for mua/s/g/n
{[mua][mus][g][n]}; 0-255 mixing prop types 1&2
104 or muamus_short: 2x short gray-levels for mua/s
{[s:mua][s:mus]}; 0-65535 mixing prop types 1&2
when formats 99 or 102 is used, the mua/mus values in the input volume
binary data must be pre-scaled by voxel size (unitinmm) if it is not 1.
pre-scaling is not needed when using these 2 formats in mcxlab/pmcx
-a [0|1] (--array) 1 for C array (row-major); 0 for Matlab array
== Output options ==
-s sessionid (--session) a string to label all output file names
-O [X|XFEJPMRL](--outputtype) X - output flux, F - fluence, E - energy deposit
/case insensitive/ J - Jacobian (replay mode), P - scattering,
event counts at each voxel (replay mode only)
M - momentum transfer; R - RF/FD Jacobian
L - total pathlength
-d [1|0-3] (--savedet) 1 to save photon info at detectors; 0 not save
2 reserved, 3 terminate simulation when detected
photon buffer is filled
-w [DP|DSPMXVW](--savedetflag)a string controlling detected photon data fields
/case insensitive/ 1 D output detector ID (1)
2 S output partial scat. even counts (#media)
4 P output partial path-lengths (#media)
8 M output momentum transfer (#media)
16 X output exit position (3)
32 V output exit direction (3)
64 W output initial weight (1)
combine multiple items by using a string, or add selected numbers together
by default, mcx only saves detector ID and partial-path data
-x [0|1] (--saveexit) 1 to save photon exit positions and directions
setting -x to 1 also implies setting '-d' to 1.
same as adding 'XV' to -w.
-X [0|1] (--saveref) 1 to save diffuse reflectance at the air-voxels
right outside of the domain; if non-zero voxels
appear at the boundary, pad 0s before using -X
-m [0|1] (--momentum) 1 to save photon momentum transfer,0 not to save.
same as adding 'M' to the -w flag
-q [0|1] (--saveseed) 1 to save photon RNG seed for replay; 0 not save
-M [0|1] (--dumpmask) 1 to dump detector volume masks; 0 do not save
-H [1000000] (--maxdetphoton) max number of detected photons
-S [1|0] (--save2pt) 1 to save the flux field; 0 do not save
-F [jnii|...](--outputformat) fluence data output format:
mc2 - MCX mc2 format (binary 32bit float)
jnii - JNIfTI format (https://neurojson.org)
bnii - Binary JNIfTI (https://neurojson.org)
nii - NIfTI format
hdr - Analyze 7.5 hdr/img format
tx3 - GL texture data for rendering (GL_RGBA32F)
the bnii/jnii formats support compression (-Z) and generate small files
load jnii (JSON) and bnii (UBJSON) files using below lightweight libs:
MATLAB/Octave: JNIfTI toolbox https://neurojson.org/download/jnifti
MATLAB/Octave: JSONLab toolbox https://neurojson.org/download/jsonlab
Python: PyJData: https://neurojson.org/download/pyjdata
JavaScript: JSData: https://neurojson.org/download/jsdata
-Z [zlib|...] (--zip) set compression method if -F jnii or --dumpjson
is used (when saving data to JSON/JNIfTI format)
0 zlib: zip format (moderate compression,fast)
1 gzip: gzip format (compatible with *.gz)
2 base64: base64 encoding with no compression
3 lzip: lzip format (high compression,very slow)
4 lzma: lzma format (high compression,very slow)
5 lz4: LZ4 format (low compression,extrem. fast)
6 lz4hc: LZ4HC format (moderate compression,fast)
--dumpjson [-,0,1,'file.json'] export all settings, including volume data using
JSON/JData (https://neurojson.org) format for
easy sharing; can be reused using -f
if followed by nothing or '-', mcx will print
the JSON to the console; write to a file if file
name is specified; by default, prints settings
after pre-processing; '--dumpjson 2' prints
raw inputs before pre-processing
== User IO options ==
-h (--help) print this message
-v (--version) print MCX revision number
-l (--log) print messages to a log file instead
-i (--interactive) interactive mode
== Debug options ==
-D [0|int] (--debug) print debug information (you can use an integer
or or a string by combining the following flags)
-D [''|RMPT] 1 R debug RNG
/case insensitive/ 2 M store photon trajectory info
4 P print progress bar
8 T save trajectory data only, disable flux/detp
combine multiple items by using a string, or add selected numbers together
== Additional options ==
--root [''|string] full path to the folder storing the input files
--gscatter [1e9|int] after a photon completes the specified number of
scattering events, mcx then ignores anisotropy g
and only performs isotropic scattering for speed
--srcid [0|-1,0,1,2,..] -1 simulate multi-source separately;0 all sources
together; a positive integer runs a single source
--internalsrc [0|1] set to 1 to skip entry search to speedup launch
--maxvoidstep [1000|int] maximum distance (in voxel unit) of a photon that
can travel before entering the domain, if
launched outside (i.e. a widefield source)
--maxjumpdebug [10000000|int] when trajectory is requested (i.e. -D M),
use this parameter to set the maximum positions
stored (default: 1e7)
== Example ==
example: (list built-in benchmarks)
mcx --bench
or (list supported GPUs on the system)
mcx -L
or (use multiple devices - 1st,2nd and 4th GPUs - together with equal load)
mcx --bench cube60b -n 1e7 -G 1101 -W 10,10,10
or (use inline domain definition)
mcx -f input.json -P '{"Shapes":[{"ZLayers":[[1,10,1],[11,30,2],[31,60,3]]}]}'
or (use inline json setting modifier)
mcx -f input.json -j '{"Optode":{"Source":{"Type":"isotropic"}}}'
or (dump simulation in a single json file)
mcx --bench cube60planar --dumpjson
Para ilustrar mejor las opciones de la línea de comando, a continuación se puede encontrar un comando de muestra
mcx -A 0 -t 16384 -T 64 -n 1e7 -G 1 -f input.json -r 2 -s test -g 10 -d 1 -w dpx -b 1
el comando anterior le pide a mcx que configure manualmente ( -A 0 ) los subprocesos de GPU y lance 16384 subprocesos de GPU ( -t ) con cada 64 subprocesos por bloque ( -T ); la primera GPU ( -G 1 ) simula un total de 1e7 fotones ( -n ) y se repite dos veces ( -r ), es decir, un total de 2e7 fotones; la configuración de medios/fuente se leerá desde un archivo JSON llamado input.json ( -f ) y la salida se etiquetará con el ID de sesión "prueba" ( -s ); la simulación ejecutará 10 puertas de tiempo simultáneas ( -g ) si la memoria de la GPU no puede simular todas las puertas de tiempo deseadas a la vez. Los fotones que pasan a través de las posiciones definidas del detector se guardan para su posterior reescalado ( -d ); La discrepancia en el índice de refracción se considera en los límites de los medios ( -b ).
Históricamente, MCX admite una versión extendida del formato de archivo de entrada (.inp) utilizado por tMCimg. Sin embargo, estamos eliminando gradualmente la compatibilidad con .inp y recomendamos encarecidamente a los usuarios que adopten archivos de entrada con formato JSON (.json). Muchas de las opciones avanzadas de MCX solo se admiten en el formato de entrada JSON.
Un archivo de entrada .inp MCX heredado tiene este aspecto:
1000000 # total photon, use -n to overwrite in the command line
29012392 # RNG seed, negative to generate, use -E to overwrite
30.0 30.0 0.0 1 # source position (in grid unit), the last num (optional) sets --srcfrom0 (-z)
0 0 1 0 # initial directional vector, 4th number is the focal-length, 0 for collimated beam, nan for isotropic
0.e+00 1.e-09 1.e-10 # time-gates(s): start, end, step
semi60x60x60.bin # volume ('unsigned char' binary format, or specified by -K/--mediabyte)
1 60 1 60 # x voxel size in mm (isotropic only), dim, start/end indices
1 60 1 60 # y voxel size, must be same as x, dim, start/end indices
1 60 1 60 # y voxel size, must be same as x, dim, start/end indices
1 # num of media
1.010101 0.01 0.005 1.37 # scat. mus (1/mm), g, mua (1/mm), n
4 1.0 # detector number and default radius (in grid unit)
30.0 20.0 0.0 2.0 # detector 1 position (real numbers in grid unit) and individual radius (optional)
30.0 40.0 0.0 # ..., if individual radius is ignored, MCX will use the default radius
20.0 30.0 0.0 #
40.0 30.0 0.0 #
pencil # source type (optional)
0 0 0 0 # parameters (4 floats) for the selected source
0 0 0 0 # additional source parameters
Tenga en cuenta que el coeficiente de dispersión mus=musp/(1-g).
MCX puede leer el archivo de volumen ( semi60x60x60.bin en el ejemplo anterior) de dos maneras: fila principal [3] o columna principal, según el valor del parámetro de usuario -a . Si el archivo de volumen se guardó usando matlab o fortran, el orden de los bytes es columna principal y debe usar -a 0 o dejarlo fuera de la línea de comando. Si se guardó usando fwrite() en C, el orden es la fila principal y puede usar -a 1 .
Puede reemplazar el archivo de volumen binario por un archivo de forma con formato JSON. Consulte la Sección V para obtener más detalles.
El parámetro de puerta de tiempo se especifica mediante tres números: hora de inicio, hora de finalización y tamaño del paso de tiempo (en segundos). En el ejemplo anterior, la configuración especifica una ventana de tiempo total de [0 1] ns, con una resolución de 0,1 ns. Eso significa que el número total de puertas de tiempo es 10.
MCX proporciona una opción avanzada, -g, para ejecutar simulaciones cuando la memoria de la GPU es limitada. Especifica cuántas puertas de tiempo se simularán simultáneamente. Es posible que los usuarios quieran limitar ese número a menos que el número total especificado en el archivo de entrada y, de forma predeterminada, ejecuta una puerta a la vez en una sola simulación. Pero si hay suficiente memoria según el requisito de memoria de la Sección II, puede simular las 10 puertas de tiempo (del ejemplo anterior) simultáneamente usando -g 10 , en cuyo caso debe asegurarse de que la tarjeta de video tenga al menos 60*60. *60*10*5=10MB de memoria libre. Si no incluye -g , MCX asumirá que desea simular solo 1 puerta de tiempo a la vez. Si especifica un número de puerta de tiempo mayor que el número total en el archivo de entrada (por ejemplo, -g 20 ) MCX se detendrá cuando se completen las 10 puertas del tiempo. Si utiliza el modo de piloto automático ( -A ), las puertas de tiempo se estiman automáticamente.
A partir de la versión 0.7.9, MCX acepta un archivo de entrada con formato JSON además del formato de entrada convencional tipo tMCimg. JSON (JavaScript Object Notation) es un formato de texto portátil, legible por humanos y "sin grasa" para representar datos complejos y jerárquicos. El uso del formato JSON hace que un archivo de entrada se explique por sí mismo, sea extensible y fácil de interactuar con otras aplicaciones (como MATLAB).
Puede encontrar un archivo de entrada JSON de muestra en la carpeta ejemplos/quicktest. El mismo archivo, qtest.json , también se muestra a continuación:
{
"Help": {
"[en]": {
"Domain::VolumeFile": "file full path to the volume description file, can be a binary or JSON file",
"Domain::Dim": "dimension of the data array stored in the volume file",
"Domain::OriginType": "similar to --srcfrom0, 1 if the origin is [0 0 0], 0 if it is [1.0,1.0,1.0]",
"Domain::LengthUnit": "define the voxel length in mm, similar to --unitinmm",
"Domain::Media": "the first medium is always assigned to voxels with a value of 0 or outside of
the volume, the second row is for medium type 1, and so on. mua and mus must
be in 1/mm unit",
"Session::Photons": "if -n is not specified in the command line, this defines the total photon number",
"Session::ID": "if -s is not specified in the command line, this defines the output file name stub",
"Forward::T0": "the start time of the simulation, in seconds",
"Forward::T1": "the end time of the simulation, in seconds",
"Forward::Dt": "the width of each time window, in seconds",
"Optode::Source::Pos": "the grid position of the source, can be non-integers, in grid unit",
"Optode::Detector::Pos": "the grid position of a detector, can be non-integers, in grid unit",
"Optode::Source::Dir": "the unitary directional vector of the photon at launch",
"Optode::Source::Type": "source types, must be one of the following:
pencil,isotropic,cone,gaussian,planar,pattern,fourier,arcsine,disk,fourierx,fourierx2d,
zgaussian,line,slit,pencilarray,pattern3d",
"Optode::Source::Param1": "source parameters, 4 floating-point numbers",
"Optode::Source::Param2": "additional source parameters, 4 floating-point numbers"
}
},
"Domain": {
"VolumeFile": "semi60x60x60.bin",
"Dim": [60,60,60],
"OriginType": 1,
"LengthUnit": 1,
"Media": [
{"mua": 0.00, "mus": 0.0, "g": 1.00, "n": 1.0},
{"mua": 0.005,"mus": 1.0, "g": 0.01, "n": 1.0}
]
},
"Session": {
"Photons": 1000000,
"RNGSeed": 29012392,
"ID": "qtest"
},
"Forward": {
"T0": 0.0e+00,
"T1": 5.0e-09,
"Dt": 5.0e-09
},
"Optode": {
"Source": {
"Pos": [29.0, 29.0, 0.0],
"Dir": [0.0, 0.0, 1.0],
"Type": "pencil",
"Param1": [0.0, 0.0, 0.0, 0.0],
"Param2": [0.0, 0.0, 0.0, 0.0]
},
"Detector": [
{
"Pos": [29.0, 19.0, 0.0],
"R": 1.0
},
{
"Pos": [29.0, 39.0, 0.0],
"R": 1.0
},
{
"Pos": [19.0, 29.0, 0.0],
"R": 1.0
},
{
"Pos": [39.0, 29.0, 0.0],
"R": 1.0
}
]
}
}
Un archivo de entrada JSON requiere varios objetos raíz, a saber, Domain , Session , Forward y Optode . Se ignorarán otras secciones raíz, como Help . Cada objeto es una estructura de datos que proporciona información indicada por su nombre. Cada objeto puede contener varios subcampos. Los órdenes de los campos en un mismo nivel son flexibles. Para cada campo, siempre puede encontrar los campos equivalentes en los archivos de entrada *.inp . Por ejemplo, el campo VolumeFile bajo Domain
