mcx
v2024.2 (Interstellar Ion)
Table des matières :
MCX v2024.2 contient à la fois de nouvelles fonctionnalités majeures et des corrections de bogues critiques. Il s'agit d'une mise à niveau fortement recommandée pour tous les utilisateurs.
Plus précisément, MCX v2024.2 a reçu trois nouvelles fonctionnalités importantes :
Semblable à la fonctionnalité de fonction de phase définie par l'utilisateur incluse dans MCX v2023, la première fonctionnalité permet aux utilisateurs de définir la distribution de l'angle zénithal pour le lancement d'un photon, par rapport au vecteur source-direction, également via un CDF inverse discrétisé (fonction de distribution cumulative) . Dans MATLAB/Octave, ils peuvent être définis respectivement comme cfg.invcdf ou cfg.angleinvcdf . Nous avons fourni des scripts de démonstration prêts à l'emploi dans mcxlab/examples/demo_mcxlab_phasefun.m et demo_mcxlab_launchangle.m .
La deuxième fonctionnalité permet aux utilisateurs de spécifier plusieurs sources du même type lors de la définition de srcpos , srcdir , srcparam1 et srcparam2 . Chaque source peut avoir un poids indépendant contrôlé par le 4ème élément de srcpos.
Outre les nouvelles fonctionnalités, un bug grave a été découvert qui affecte toutes les simulations pattern et pattern3d qui n'utilisent pas le partage de photons, veuillez consulter
#212
En raison de ce bug, MCX/MCX-CL dans les anciennes versions simulait les données de motif carré/pattern3d au lieu du motif lui-même. Si votre simulation utilise ces deux types de sources et que vous n'utilisez pas le partage de photons (c'est-à-dire la simulation de plusieurs modèles ensemble), veuillez mettre à niveau votre MCX/MCX-CL et réexécuter vos simulations. Ce bug n'affecte que les sorties fluence/flux volumétriques ; cela n'affecte pas les sorties de réflectance diffuse ou les modèles binaires.
Il inclut également une correction de bug du #195 concernant la perte de précision lors de l'enregistrement de la réflectance diffuse.
Nous souhaitons remercier Haohui Zhang pour avoir signalé un certain nombre de problèmes critiques (#195 et #212), et Liam Keegan pour avoir contribué à un patch pour étendre la source de la fente (#214). ShijieYan et fanyuyen ont également contribué aux corrections de bugs et aux améliorations.
Les mises à jour détaillées peuvent être trouvées dans le journal des modifications ci-dessous
Monte Carlo eXtreme (MCX) est un logiciel de simulation de photons rapide et physiquement précis pour les milieux complexes hétérogènes 3D. En tirant parti des threads massivement parallèles et de la latence de mémoire extrêmement faible d'une unité de traitement graphique (GPU) moderne, ce programme est capable d'effectuer des simulations de Monte Carlo (MC) à une vitesse fulgurante, généralement des centaines à mille fois plus rapide qu'un seul. - Implémentation MC basée sur un processeur threadé.
MCX est écrit en C et NVIDIA CUDA. Il ne peut être exécuté que sur les GPU NVIDIA. Si vous souhaitez exécuter des simulations MCX accélérées par le matériel sur des GPU ou CPU AMD/Intel, veuillez télécharger MCX-CL (MCX pour OpenCL), qui est écrit en OpenCL. MCX et MCX-CL sont hautement compatibles.
En raison de la nature des algorithmes MC sous-jacents, MCX et MCX-CL sont des logiciels de traçage/casting de rayons sous le capot. Comparés aux bibliothèques de lancer de rayons couramment utilisées dans les moteurs d'infographie ou de jeux, MCX-CL et MCX présentent de nombreuses caractéristiques uniques. La différence la plus importante est que MCX/MCX-CL sont rigoureusement basés sur des lois physiques. Ce sont des solveurs numériques de l’équation de transfert radiatif (RTE) sous-jacente et leurs solutions ont été validées dans de nombreuses publications utilisant des instruments optiques et des mesures expérimentales. En comparaison, la plupart des traceurs de rayons orientés graphiques doivent faire de nombreuses approximations afin d'obtenir un rendu rapide, permettant ainsi de fournir des résultats de simulation de lumière quantitativement précis. Pour cette raison, les MCX/MCX-CL ont été largement utilisés par les communautés de recherche en biophotonique pour obtenir des solutions de référence et guider le développement de nouveaux systèmes d’imagerie médicale ou d’applications cliniques. De plus, les MCX/MCX-CL sont des traceurs de rayons volumétriques ; ils traversent les rayons photoniques à travers des domaines 3D complexes et calculent des quantités physiquement significatives telles que la fluence résolue spatialement, le flux, la réflectance/transmittance diffuse, le dépôt d'énergie, les longueurs de trajet partielles, entre autres. En revanche, la plupart des moteurs graphiques de lancer de rayons tracent uniquement la couleur RVB d'un rayon et la restituent sur un écran plat 2D. En d'autres termes, MCX/MCX-CL offre des distributions de lumière 3D physiquement précises tandis que les traceurs de rayons graphiques se concentrent sur le rendu 2D d'une scène au niveau de la caméra. Néanmoins, ils partagent de nombreuses similitudes, telles que le calcul du ray-marching, l'accélération GPU, la gestion de la diffusion/absorption, etc.
L'algorithme de ce logiciel est détaillé dans les Références [Fang2009,Yu2018,Yan2020]. Un bref résumé des principales fonctionnalités comprend :
Ce logiciel peut être utilisé sous Windows, Linux et Mac OS. MCX est écrit en C/CUDA et nécessite des GPU NVIDIA (la prise en charge des CPU/GPU AMD/Intel via ROCm est toujours en cours de développement). Une implémentation OpenCL plus portable de MCX, c'est-à-dire MCXCL, a été annoncée en juillet 2012 et prend en charge presque tous les modèles de CPU et GPU NVIDIA/AMD/Intel. Si votre matériel ne prend pas en charge CUDA, veuillez télécharger MCXCL à partir de l'URL ci-dessous :
https://mcx.space/wiki/index.cgi?Learn#mcxcl
Veuillez lire attentivement cette section. La majorité des échecs utilisant MCX étaient liés à une installation incorrecte du pilote GPU NVIDIA.
Veuillez parcourir https://mcx.space/#documentation pour obtenir des instructions étape par étape.
Pour MCX-CUDA, la configuration requise pour l'utilisation de ce logiciel inclut
Vous devez vous assurer que votre pilote graphique NVIDIA a été correctement installé. Une liste des cartes compatibles CUDA peut être trouvée sur [2]. L'architecture GPU la plus ancienne sur laquelle le code source MCX peut être compilé est Fermi ( sm_20 ). L'utilisation de la dernière carte NVIDIA devrait produire la meilleure vitesse. Les binaires officiellement publiés (y compris les fichiers mex et les modules pmcx ) peuvent fonctionner sur des GPU NVIDIA aussi anciens que Kepler (GTX-730, sm_35 ). Tous les binaires MCX peuvent fonctionner directement sur les futures générations de GPU NVIDIA sans avoir besoin d'être recompilés, donc compatibles avec les versions ultérieures.
Dans la page Web ci-dessous, nous avons résumé les différences de vitesse entre les différentes générations de GPU NVIDIA.
https://mcx.space/gpubench/
Pour les simulations avec de gros volumes, une mémoire graphique suffisante est également requise pour effectuer la simulation. La quantité minimale de mémoire graphique requise pour une simulation MC est de Nx*Ny*Nz octets pour les données tissulaires d'entrée plus Nx*Ny*Nz*Ng*4*2 octets pour les données de flux/fluence de sortie - où Nx, Ny, Nz sont les dimensions du volume tissulaire, Ng est le nombre de portes temporelles simultanées, 4 est la taille d'un nombre à virgule flottante simple précision, 2 est pour la mémoire supplémentaire nécessaire pour assurer la précision de la sortie (#41). MCX ne nécessite pas de prise en charge double précision dans votre matériel.
MCX stocke les propriétés optiques et les positions des détecteurs dans la mémoire constante. Habituellement, les GPU NVIDIA fournissent environ 64 Ko de mémoire constante. En conséquence, seul le nombre total de propriétés optiques plus le nombre de détecteurs ne peut pas dépasser 4 000 (4 000 * 4 * 4 = 64 k).
De plus, MCX stocke les données de photons détectés dans la mémoire partagée, qui varie également entre 42 Ko et 100 Ko par processeur de flux sur différentes générations de GPU. Si votre domaine contient de nombreux types de supports, il est possible que l'allocation de la mémoire partagée dépasse la limite. Vous recevrez également une erreur « mémoire insuffisante ».
Pour installer MCX, vous devez télécharger l'exécutable binaire compilé pour l'architecture de votre ordinateur (32 ou 64 bits) et votre plate-forme, extraire le package et exécuter l'exécutable sous le répertoire {mcx root}/bin .
Pour les utilisateurs Windows, vous devez vous assurer d'avoir installé le pilote NVIDIA approprié pour votre GPU. Vous devez également configurer votre système d'exploitation pour exécuter des simulations CUDA. Cela nécessite que vous ouvriez le dossier mcx/setup/win64 à l'aide de votre explorateur de fichiers, faites un clic droit sur le fichier apply_timeout_registry_fix.bat et sélectionnez « Exécuter en tant qu'administrateur » . Après confirmation, vous devriez voir une fenêtre de commande Windows avec le message
Patching your registry
Done
Press any key to continue ...
Vous DEVEZ REDÉMARRER votre ordinateur Windows pour que ce paramètre soit effectif. Le correctif ci-dessus modifie les paramètres de votre pilote afin que vous puissiez exécuter des simulations MCX pendant plus de quelques secondes. Sinon, lorsque vous exécutez MCX pendant plus de quelques secondes, vous obtiendrez une erreur CUDA : « erreur non spécifiée ».
Veuillez consulter le lien ci-dessous pour plus de détails
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
Si vous utilisez Linux, vous pouvez activer le GPU intégré Intel (iGPU) pour l'affichage tout en laissant votre GPU NVIDIA dédié à l'informatique à l'aide de nvidia-prime , voir
https://forums.developer.nvidia.com/t/solved-run-cuda-on-dedicated-nvidia-gpu-while-connecting-monitors-to-intel-hd-graphics-is-this-possible/47690/ 6
ou choisissez l'une des 4 autres approches proposées dans cet article de blog
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
Nous avons remarqué qu'en exécutant Ubuntu Linux 22.04 avec un noyau 6.5 sur un ordinateur portable doté d'un GPU hybride avec un iGPU Intel et un GPU NVIDIA, vous devez configurer l'ordinateur portable pour utiliser le GPU NVIDIA comme GPU principal en choisissant "NVIDIA (Mode Performance)". dans la section Profils PRIME des paramètres du serveur NVIDIA X. Vous pouvez également exécuter
sudo prime-select nvidia
pour atteindre le même objectif. Sinon, la simulation risque de bloquer votre système après quelques secondes d'exécution. Un ordinateur portable à GPU hybride combinant un GPU NVIDIA avec un iGPU AMD ne semble pas avoir ce problème s'il utilise Linux.
De plus, le pilote NVIDIA (520 ou plus récent) présente un problème connu fonctionnant sur le noyau Linux 6.x (comme ceux d'Ubuntu 22.04). Voir
https://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153
Lorsque l'ordinateur portable est en mode "performance" et se réveille après une suspension, MCX ou tout programme CUDA ne parvient pas à s'exécuter avec une erreur
MCX ERROR(-999):unknown error in unit mcx_core.cu:2523
Cela est dû au fait que le module du noyau nvida-uvm ne parvient pas à être rechargé après une suspension. Si vous aviez une session MATLAB ouverte, vous devez d'abord fermer MATLAB et exécuter les commandes ci-dessous (si MATLAB est ouvert, vous verrez rmmod: ERROR: Module nvidia_uvm is in use )
sudo rmmod /dev/nvidia-uvm
sudo modprobe nvidia-uvm
après la commande ci-dessus, MCX devrait pouvoir s'exécuter à nouveau.
Les nouvelles générations d'ordinateurs Mac ne prennent plus en charge les GPU NVIDIA ou AMD. vous devrez utiliser la version OpenCL de MCX, MCX-CL en la téléchargeant depuis
https://mcx.space/wiki/?Learn#mcxcl
Pour exécuter une simulation, l'entrée minimale est un fichier de configuration (texte) et, si le fichier d'entrée ne contient pas de descriptions de forme de domaine intégrées, un fichier de volume externe (un fichier binaire avec un format de voxel spécifié via -K/--mediabyte ). Taper mcx sans aucun paramètre imprime les informations d'aide et une liste des paramètres pris en charge, comme indiqué ci-dessous :
###############################################################################
# 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
Pour illustrer davantage les options de ligne de commande, vous trouverez ci-dessous un exemple de commande
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
la commande ci-dessus demande à mcx de définir manuellement ( -A 0 ) les threads GPU et de lancer 16 384 threads GPU ( -t ) tous les 64 threads par bloc ( -T ); un total de 1e7 photons ( -n ) sont simulés par le premier GPU ( -G 1 ) et répétés deux fois ( -r ) - soit un total de 2e7 photons ; la configuration média/source sera lue à partir d'un fichier JSON nommé input.json ( -f ) et la sortie sera étiquetée avec l'identifiant de session « test » ( -s ) ; la simulation exécutera 10 portes temporelles simultanées ( -g ) si la mémoire GPU ne peut pas simuler toutes les portes temporelles souhaitées à la fois. Les photons passant par les positions définies du détecteur sont enregistrés pour une mise à l'échelle ultérieure ( -d ); L'inadéquation de l'indice de réfraction est prise en compte aux limites des médias ( -b ).
Historiquement, MCX prend en charge une version étendue du format de fichier d'entrée (.inp) utilisé par tMCimg. Cependant, nous supprimons progressivement la prise en charge .inp et encourageons fortement les utilisateurs à adopter les fichiers d'entrée au format JSON (.json). La plupart des options MCX avancées ne sont prises en charge que dans le format d'entrée JSON.
Un ancien fichier d'entrée .inp MCX ressemble à ceci :
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
Notez que le coefficient de diffusion mus=musp/(1-g).
Le fichier de volume ( semi60x60x60.bin dans l'exemple ci-dessus), peut être lu de deux manières par MCX : row-major[3] ou column-major selon la valeur du paramètre utilisateur -a . Si le fichier de volume a été enregistré à l'aide de Matlab ou Fortran, l'ordre des octets est celui de la colonne principale et vous devez utiliser -a 0 ou le laisser en dehors de la ligne de commande. S'il a été enregistré à l'aide fwrite() en C, l'ordre est par ligne principale et vous pouvez soit utiliser -a 1 .
Vous pouvez remplacer le fichier de volume binaire par un fichier de forme au format JSON. Veuillez vous référer à la section V pour plus de détails.
Le paramètre de porte temporelle est spécifié par trois nombres : heure de début, heure de fin et taille du pas de temps (en secondes). Dans l'exemple ci-dessus, la configuration spécifie une fenêtre de temps totale de [0 1] ns, avec une résolution de 0,1 ns. Cela signifie que le nombre total de portes temporelles est de 10.
MCX fournit une option avancée, -g, pour exécuter des simulations lorsque la mémoire GPU est limitée. Il spécifie le nombre de portes temporelles à simuler simultanément. Les utilisateurs voudront peut-être limiter ce nombre à un nombre inférieur au nombre total spécifié dans le fichier d'entrée - et par défaut, il exécute une porte à la fois dans une seule simulation. Mais s'il y a suffisamment de mémoire en fonction des besoins en mémoire de la section II, vous pouvez simuler simultanément les 10 portes temporelles (de l'exemple ci-dessus) en utilisant -g 10 , auquel cas vous devez vous assurer que la carte vidéo dispose d'au moins 60*60. *60*10*5=10 Mo de mémoire libre. Si vous n'incluez pas le -g , MCX supposera que vous souhaitez simuler une seule porte temporelle à la fois. Si vous spécifiez un numéro de porte temporelle supérieur au nombre total dans le fichier d'entrée (par exemple, -g 20 ) MCX s'arrêtera lorsque les 10 portes temporelles seront terminées. Si vous utilisez le mode pilote automatique ( -A ), les portes horaires sont automatiquement estimées pour vous.
À partir de la version 0.7.9, MCX accepte un fichier d'entrée au format JSON en plus du format d'entrée conventionnel de type tMCimg. JSON (JavaScript Object Notation) est un format de texte portable, lisible par l'homme et « sans gras » pour représenter des données complexes et hiérarchiques. L'utilisation du format JSON rend un fichier d'entrée explicite, extensible et facile à interfacer avec d'autres applications (comme MATLAB).
Un exemple de fichier d’entrée JSON peut être trouvé dans le dossier examples/quicktest. Le même fichier, qtest.json , est également présenté ci-dessous :
{
"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 fichier d'entrée JSON nécessite plusieurs objets racine, à savoir Domain , Session , Forward et Optode . Les autres sections racine, comme Help , seront ignorées. Chaque objet est une structure de données fournissant des informations indiquées par son nom. Chaque objet peut contenir différents sous-champs. Les ordres des champs d'un même niveau sont flexibles. Pour chaque champ, vous pouvez toujours retrouver les champs équivalents dans les fichiers d'entrée *.inp . Par exemple, le champ VolumeFile sous le Domain
