mcx
v2024.2 (Interstellar Ion)
Inhaltsverzeichnis:
MCX v2024.2 enthält sowohl wichtige neue Funktionen als auch wichtige Fehlerbehebungen. Es handelt sich um ein dringend empfohlenes Upgrade für alle Benutzer.
Konkret erhielt MCX v2024.2 drei wichtige neue Funktionen:
Ähnlich wie die in MCX v2023 enthaltene benutzerdefinierte Phasenfunktionsfunktion ermöglicht die erste Funktion Benutzern, die Zenitwinkelverteilung für den Start eines Photons relativ zum Quellrichtungsvektor zu definieren, ebenfalls über eine diskretisierte inverse CDF (kumulative Verteilungsfunktion). . In MATLAB/Octave können sie als cfg.invcdf bzw. cfg.angleinvcdf festgelegt werden. Wir haben gebrauchsfertige Demoskripte in mcxlab/examples/demo_mcxlab_phasefun.m und demo_mcxlab_launchangle.m bereitgestellt.
Mit der zweiten Funktion können Benutzer beim Definieren von srcpos , srcdir , srcparam1 und srcparam2 mehr als eine Quelle desselben Typs angeben. Jede Quelle kann eine unabhängige Gewichtung haben, die durch das 4. Element von srcpos gesteuert wird.
Abgesehen von neuen Funktionen wurde ein schwerwiegender Fehler entdeckt, der alle pattern und pattern3d -Simulationen betrifft, die keine Photonenfreigabe verwenden, siehe
#212
Aufgrund dieses Fehlers simulierte MCX/MCX-CL in älteren Versionen quadratische Muster/Pattern3D-Daten anstelle des Musters selbst. Wenn Ihre Simulation diese beiden Quellentypen verwendet und Sie kein Photonen-Sharing verwenden (d. h. mehrere Muster gleichzeitig simulieren), aktualisieren Sie bitte Ihren MCX/MCX-CL und führen Sie Ihre Simulationen erneut aus. Dieser Fehler betrifft nur volumetrische Fluenz-/Fluss-Ausgaben; Es hat keinen Einfluss auf diffuse Reflexionsausgänge oder binäre Muster.
Es enthält außerdem einen Bugfix aus #195 hinsichtlich des Präzisionsverlusts beim Speichern der diffusen Reflexion.
Wir möchten Haohui Zhang dafür danken, dass er eine Reihe kritischer Probleme gemeldet hat (Nr. 195 und Nr. 212), und Liam Keegan dafür, dass er einen Patch zur Erweiterung der Schlitzquelle beigesteuert hat (Nr. 214). ShijieYan und fanyuyen haben ebenfalls zu den Fehlerbehebungen und Verbesserungen beigetragen.
Die detaillierten Aktualisierungen finden Sie im folgenden Änderungsprotokoll
Monte Carlo eXtreme (MCX) ist eine schnelle physikalisch genaue Photonensimulationssoftware für heterogene komplexe 3D-Medien. Durch die Ausnutzung der massiv parallelen Threads und der extrem geringen Speicherlatenz in einer modernen Grafikverarbeitungseinheit (GPU) ist dieses Programm in der Lage, Monte-Carlo-Simulationen (MC) mit rasender Geschwindigkeit durchzuführen, typischerweise hunderte bis tausende Mal schneller als eine einzelne -threaded CPU-basierte MC-Implementierung.
MCX ist in C und NVIDIA CUDA geschrieben. Es kann nur auf NVIDIA-GPUs ausgeführt werden. Wenn Sie hardwarebeschleunigte MCX-Simulationen auf AMD/Intel-GPUs oder CPUs ausführen möchten, laden Sie bitte MCX-CL (MCX für OpenCL) herunter, das in OpenCL geschrieben ist. MCX und MCX-CL sind hochkompatibel.
Aufgrund der Art der zugrunde liegenden MC-Algorithmen handelt es sich bei MCX und MCX-CL um Raytracing-/Raycasting-Software unter der Haube. Im Vergleich zu häufig verwendeten Raytracing-Bibliotheken, die in Computergrafik- oder Gaming-Engines verwendet werden, weisen MCX-CL und MCX viele einzigartige Eigenschaften auf. Der wichtigste Unterschied besteht darin, dass MCX/MCX-CL streng auf physikalischen Gesetzen basieren. Sie sind numerische Löser der zugrunde liegenden Strahlungstransfergleichung (RTE) und ihre Lösungen wurden in zahlreichen Veröffentlichungen mithilfe optischer Instrumente und experimenteller Messungen validiert. Im Vergleich dazu müssen die meisten grafikorientierten Raytracer viele Annäherungen vornehmen, um ein schnelles Rendering zu erreichen und quantitativ genaue Lichtsimulationsergebnisse zu liefern. Aus diesem Grund werden MCX/MCX-CL von biophotonischen Forschungsgemeinschaften in großem Umfang genutzt, um Referenzlösungen zu erhalten und die Entwicklung neuartiger medizinischer Bildgebungssysteme oder klinischer Anwendungen zu steuern. Darüber hinaus sind MCX/MCX-CL volumetrische Raytracer; Sie durchqueren Photonenstrahlen durch komplexe 3D-Domänen und berechnen physikalisch bedeutsame Größen wie räumlich aufgelöste Fluenz, Fluss, diffuse Reflexion/Transmission, Energiedeposition, Teilweglängen und viele andere. Im Gegensatz dazu verfolgen die meisten Grafik-Raytracing-Engines nur die RGB-Farbe eines Strahls und rendern ihn auf einem flachen 2D-Bildschirm. Mit anderen Worten: MCX/MCX-CL liefert physikalisch genaue 3D-Lichtverteilungen, während Grafik-Raytracer sich auf die 2D-Wiedergabe einer Szene vor der Kamera konzentrieren. Dennoch weisen sie viele Gemeinsamkeiten auf, wie z. B. Ray-Marching-Berechnung, GPU-Beschleunigung, Streuungs-/Absorptionshandhabung usw.
Der Algorithmus dieser Software ist in den Referenzen [Fang2009,Yu2018,Yan2020] detailliert beschrieben. Eine kurze Zusammenfassung der Hauptfunktionen umfasst:
Diese Software kann unter Windows, Linux und Mac OS verwendet werden. MCX ist in C/CUDA geschrieben und erfordert NVIDIA-GPUs (die Unterstützung für AMD/Intel-CPUs/GPUs über ROCm befindet sich noch in der Entwicklung). Eine portablere OpenCL-Implementierung von MCX, nämlich MCXCL, wurde im Juli 2012 angekündigt und unterstützt fast alle NVIDIA/AMD/Intel-CPU- und GPU-Modelle. Wenn Ihre Hardware CUDA nicht unterstützt, laden Sie MCXCL bitte von der folgenden URL herunter:
https://mcx.space/wiki/index.cgi?Learn#mcxcl
Bitte lesen Sie diesen Abschnitt sorgfältig durch. Die meisten Fehler bei der Verwendung von MCX standen im Zusammenhang mit einer fehlerhaften Installation des NVIDIA-GPU-Treibers.
Bitte durchsuchen Sie https://mcx.space/#documentation nach Schritt-für-Schritt-Anleitungen.
Für MCX-CUDA gelten folgende Voraussetzungen für die Verwendung dieser Software:
Sie müssen sicherstellen, dass Ihr NVIDIA-Grafiktreiber ordnungsgemäß installiert wurde. Eine Liste CUDA-fähiger Karten finden Sie unter [2]. Die älteste GPU-Architektur, mit der MCX-Quellcode kompiliert werden kann, ist Fermi ( sm_20 ). Mit der neuesten NVIDIA-Karte wird voraussichtlich die beste Geschwindigkeit erzielt. Die offiziell veröffentlichten Binärdateien (einschließlich MEX-Dateien und pmcx Module) können auf NVIDIA-GPUs ausgeführt werden, die so alt sind wie Kepler (GTX-730, sm_35 ). Alle MCX-Binärdateien können direkt auf zukünftigen Generationen von NVIDIA-GPUs ausgeführt werden, ohne dass eine Neukompilierung erforderlich ist, und sind daher aufwärtskompatibel.
Auf der folgenden Webseite haben wir die Geschwindigkeitsunterschiede zwischen verschiedenen Generationen von NVIDIA-GPUs zusammengefasst
https://mcx.space/gpubench/
Bei Simulationen mit großen Volumina ist außerdem ausreichend Grafikspeicher erforderlich, um die Simulation durchzuführen. Die für eine MC-Simulation erforderliche Mindestmenge an Grafikspeicher beträgt Nx*Ny*Nz Bytes für die Eingabegewebedaten plus Nx*Ny*Nz*Ng*4*2 Bytes für die Ausgabefluss-/Fluenzdaten – wobei Nx,Ny,Nz sind die Abmessungen des Gewebevolumens, Ng ist die Anzahl gleichzeitiger Zeitfenster, 4 ist die Größe einer Gleitkommazahl mit einfacher Genauigkeit, 2 ist für den zusätzlichen Speicher, der zur Gewährleistung der Ausgabegenauigkeit erforderlich ist (#41). MCX erfordert keine Unterstützung für doppelte Genauigkeit in Ihrer Hardware.
MCX speichert optische Eigenschaften und Detektorpositionen im Konstantenspeicher. Normalerweise bieten NVIDIA-GPUs etwa 64 kB konstanten Speicher. Daher können wir nur sagen, dass die Gesamtzahl der optischen Eigenschaften plus die Anzahl der Detektoren 4000 nicht überschreiten darf (4000 * 4 * 4 = 64 k).
Darüber hinaus speichert MCX erkannte Photonendaten im gemeinsamen Speicher, der über verschiedene GPU-Generationen hinweg ebenfalls zwischen 42 kB und 100 kB pro Stream-Prozessor liegt. Wenn Ihre Domain viele Medientypen enthält, ist es möglich, dass die Belegung des gemeinsam genutzten Speichers das Limit überschreitet. Sie erhalten außerdem die Fehlermeldung „Nicht genügend Speicher“.
Um MCX zu installieren, müssen Sie die für Ihre Computerarchitektur (32 oder 64 Bit) und Plattform kompilierte binäre ausführbare Datei herunterladen, das Paket extrahieren und die ausführbare Datei im Verzeichnis {mcx root}/bin ausführen.
Für Windows-Benutzer müssen Sie sicherstellen, dass Sie den entsprechenden NVIDIA-Treiber für Ihre GPU installiert haben. Sie sollten Ihr Betriebssystem auch für die Ausführung von CUDA-Simulationen konfigurieren. Dazu müssen Sie den Ordner mcx/setup/win64 mit Ihrem Datei-Explorer öffnen, mit der rechten Maustaste auf die Datei apply_timeout_registry_fix.bat klicken und „Als Administrator ausführen“ auswählen. Nach der Bestätigung sollte ein Windows-Befehlsfenster mit einer Meldung angezeigt werden
Patching your registry
Done
Press any key to continue ...
Sie MÜSSEN Ihren Windows-Computer neu starten, damit diese Einstellung wirksam wird. Der obige Patch ändert Ihre Treibereinstellungen, sodass Sie MCX-Simulationen länger als ein paar Sekunden ausführen können. Andernfalls erhalten Sie einen CUDA-Fehler: „Unspecified error“, wenn Sie MCX länger als ein paar Sekunden ausführen.
Weitere Informationen finden Sie unter dem folgenden Link
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
Wenn Sie Linux verwenden, können Sie die integrierte Intel-GPU (iGPU) für die Anzeige aktivieren, während Ihre NVIDIA-GPU für die Datenverarbeitung mit nvidia-prime reserviert bleibt, siehe
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
oder wählen Sie einen der 4 anderen Ansätze in diesem Blogbeitrag
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
Wir haben festgestellt, dass Sie beim Ausführen von Ubuntu Linux 22.04 mit einem 6.5-Kernel auf einem Laptop mit einer Hybrid-GPU mit einer Intel iGPU und einer NVIDIA-GPU den Laptop so konfigurieren müssen, dass er die NVIDIA-GPU als primäre GPU verwendet, indem Sie „NVIDIA (Leistungsmodus)“ auswählen. im Abschnitt PRIME-Profile der NVIDIA X-Server-Einstellungen . Sie können auch laufen
sudo prime-select nvidia
das gleiche Ziel zu erreichen. Andernfalls kann es sein, dass die Simulation Ihr System nach einigen Sekunden blockiert. Bei einem Hybrid-GPU-Laptop, der eine NVIDIA-GPU mit einer AMD-iGPU kombiniert, scheint dieses Problem unter Linux nicht aufzutreten.
Darüber hinaus weist der NVIDIA-Treiber (520 oder neuer) einen bekannten Fehler auf, der auf dem Linux-Kernel 6.x läuft (z. B. in Ubuntu 22.04). Sehen
https://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153
Wenn sich der Laptop im „Leistungsmodus“ befindet und aus dem Ruhezustand aufwacht, kann MCX oder ein beliebiges CUDA-Programm mit einem Fehler nicht ausgeführt werden
MCX ERROR(-999):unknown error in unit mcx_core.cu:2523
Dies liegt daran, dass das Kernelmodul nvida-uvm nach dem Anhalten nicht neu geladen werden kann. Wenn Sie eine offene MATLAB-Sitzung hatten, müssen Sie MATLAB zuerst schließen und die folgenden Befehle ausführen (wenn MATLAB geöffnet ist, wird rmmod: ERROR: Module nvidia_uvm is in use angezeigt).
sudo rmmod /dev/nvidia-uvm
sudo modprobe nvidia-uvm
Nach dem obigen Befehl sollte MCX wieder ausgeführt werden können.
Neue Generationen von Mac-Computern unterstützen keine NVIDIA- oder AMD-GPUs mehr. Sie müssen die OpenCL-Version von MCX, MCX-CL, verwenden, indem Sie sie von herunterladen
https://mcx.space/wiki/?Learn#mcxcl
Um eine Simulation auszuführen, ist die Mindesteingabe eine Konfigurationsdatei (Textdatei) und, wenn die Eingabedatei keine integrierten Domänenformbeschreibungen enthält, eine externe Volumendatei (eine Binärdatei mit einem angegebenen Voxelformat über -K/--mediabyte ). Wenn Sie mcx ohne Parameter eingeben, werden die Hilfeinformationen und eine Liste der unterstützten Parameter gedruckt, wie unten gezeigt:
###############################################################################
# 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
Um die Befehlszeilenoptionen weiter zu veranschaulichen, finden Sie unten einen Beispielbefehl
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
Der obige Befehl fordert mcx auf, GPU-Threads manuell festzulegen ( -A 0 ) und 16384 GPU-Threads ( -t ) mit jeweils 64 Threads pro Block ( -T ) zu starten. insgesamt 1e7 Photonen ( -n ) werden von der ersten GPU ( -G 1 ) simuliert und zweimal wiederholt ( -r ) – also insgesamt 2e7 Photonen; Die Medien-/Quellenkonfiguration wird aus einer JSON-Datei mit dem Namen input.json ( -f ) gelesen und die Ausgabe wird mit der Sitzungs-ID „test“ ( -s ) gekennzeichnet. Die Simulation führt 10 Zeitfenster gleichzeitig aus ( -g ), wenn der GPU-Speicher nicht alle gewünschten Zeitfenster gleichzeitig simulieren kann. Photonen, die die definierten Detektorpositionen passieren, werden für eine spätere Neuskalierung gespeichert ( -d ); Die Nichtübereinstimmung des Brechungsindex wird an den Mediengrenzen berücksichtigt ( -b ).
Historisch gesehen unterstützt MCX eine erweiterte Version des von tMCimg verwendeten Eingabedateiformats (.inp). Wir lassen jedoch die .inp-Unterstützung auslaufen und empfehlen Benutzern dringend, JSON-formatierte (.json) Eingabedateien zu verwenden. Viele der erweiterten MCX-Optionen werden nur im JSON-Eingabeformat unterstützt.
Eine ältere .inp-MCX-Eingabedatei sieht folgendermaßen aus:
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
Beachten Sie, dass der Streukoeffizient mus=musp/(1-g) ist.
Die Volume-Datei ( semi60x60x60.bin im obigen Beispiel) kann von MCX auf zwei Arten gelesen werden: zeilenmajor[3] oder spaltenmajor, abhängig vom Wert des Benutzerparameters -a . Wenn die Volume-Datei mit Matlab oder Fortran gespeichert wurde, ist die Bytereihenfolge spaltenorientiert und Sie sollten -a 0 verwenden oder es in der Befehlszeile weglassen. Wenn es mit fwrite() in C gespeichert wurde, ist die Reihenfolge zeilenweise und Sie können entweder -a 1 verwenden.
Sie können die binäre Volume-Datei durch eine JSON-formatierte Shape-Datei ersetzen. Weitere Informationen finden Sie in Abschnitt V.
Der Zeitfensterparameter wird durch drei Zahlen angegeben: Startzeit, Endzeit und Zeitschrittgröße (in Sekunden). Im obigen Beispiel gibt die Konfiguration ein Gesamtzeitfenster von [0 1] ns mit einer Auflösung von 0,1 ns an. Das bedeutet, dass die Gesamtzahl der Zeitfenster 10 beträgt.
MCX bietet eine erweiterte Option, -g, um Simulationen auszuführen, wenn der GPU-Speicher begrenzt ist. Es gibt an, wie viele Zeitfenster gleichzeitig simuliert werden sollen. Benutzer möchten diese Anzahl möglicherweise auf weniger als die in der Eingabedatei angegebene Gesamtzahl begrenzen – und standardmäßig wird in einer einzelnen Simulation jeweils ein Gate ausgeführt. Wenn jedoch basierend auf dem Speicherbedarf in Abschnitt II genügend Speicher vorhanden ist, können Sie alle 10 Zeitfenster (aus dem obigen Beispiel) gleichzeitig simulieren, indem Sie -g 10 verwenden. In diesem Fall müssen Sie sicherstellen, dass die Grafikkarte über mindestens 60*60 verfügt *60*10*5=10 MB freier Speicher. Wenn Sie -g nicht angeben, geht MCX davon aus, dass Sie jeweils nur ein Zeitfenster simulieren möchten. Wenn Sie eine Zeitfensternummer angeben, die größer als die Gesamtzahl in der Eingabedatei ist (z. B. -g 20 ) MCX stoppt, wenn die 10 Zeitfenster abgelaufen sind. Wenn Sie den Autopilot-Modus ( -A ) verwenden, werden die Zeitfenster automatisch für Sie geschätzt.
Ab Version 0.7.9 akzeptiert MCX zusätzlich zum herkömmlichen tMCimg-ähnlichen Eingabeformat auch eine JSON-formatierte Eingabedatei. JSON (JavaScript Object Notation) ist ein portables, für Menschen lesbares und „fettfreies“ Textformat zur Darstellung komplexer und hierarchischer Daten. Durch die Verwendung des JSON-Formats ist eine Eingabedatei selbsterklärend, erweiterbar und lässt sich leicht mit anderen Anwendungen (wie MATLAB) verbinden.
Eine Beispiel-JSON-Eingabedatei finden Sie im Ordner „examples/quicktest“. Die gleiche Datei, qtest.json , wird auch unten angezeigt:
{
"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
}
]
}
}
Eine JSON-Eingabedatei erfordert mehrere Stammobjekte, nämlich Domain , Session , Forward und Optode . Andere Stammabschnitte wie Help werden ignoriert. Jedes Objekt ist eine Datenstruktur, die Informationen bereitstellt, die durch ihren Namen angegeben werden. Jedes Objekt kann verschiedene Unterfelder enthalten. Die Reihenfolge der Felder auf derselben Ebene ist flexibel. Für jedes Feld finden Sie immer die entsprechenden Felder in den *.inp Eingabedateien. Zum Beispiel das Feld VolumeFile unter der Domain
