mcx
v2024.2 (Interstellar Ion)
Daftar Isi:
MCX v2024.2 berisi fitur baru utama dan perbaikan bug penting. Ini adalah peningkatan yang sangat disarankan untuk semua pengguna.
Secara khusus, MCX v2024.2 menerima tiga fitur baru yang penting:
Mirip dengan fitur fungsi fase yang ditentukan pengguna yang disertakan dalam MCX v2023, fitur pertama memungkinkan pengguna menentukan distribusi sudut puncak untuk meluncurkan foton, relatif terhadap vektor arah sumber, juga melalui CDF invers terdiskritisasi (fungsi distribusi kumulatif) . Di MATLAB/Oktaf, masing-masing dapat disetel sebagai cfg.invcdf atau cfg.angleinvcdf . Kami menyediakan skrip demo siap pakai di mcxlab/examples/demo_mcxlab_phasefun.m dan demo_mcxlab_launchangle.m .
Fitur kedua memungkinkan pengguna untuk menentukan lebih dari satu sumber dengan tipe yang sama ketika mendefinisikan srcpos , srcdir , srcparam1 dan srcparam2 . Setiap sumber dapat memiliki bobot independen yang dikontrol oleh elemen ke-4 dari srcpos.
Selain fitur baru, ditemukan bug parah yang memengaruhi semua simulasi pattern dan pattern3d yang tidak menggunakan berbagi foton, silakan lihat
#212
Karena bug ini, MCX/MCX-CL di rilis lama telah mensimulasikan data pola kuadrat/pattern3d, bukan pola itu sendiri. Jika simulasi Anda menggunakan dua jenis sumber ini dan Anda tidak menggunakan berbagi foton (yaitu mensimulasikan beberapa pola secara bersamaan), harap tingkatkan MCX/MCX-CL Anda dan jalankan kembali simulasi Anda. Bug ini hanya mempengaruhi keluaran fluks/fluks volumetrik; itu tidak mempengaruhi keluaran reflektansi difus atau pola biner.
Ini juga mencakup perbaikan bug dari #195 mengenai hilangnya presisi saat menyimpan reflektansi difus.
Kami ingin berterima kasih kepada Haohui Zhang karena melaporkan sejumlah masalah kritis (#195 dan #212), Liam Keegan karena menyumbangkan tambalan untuk memperluas sumber celah (#214). ShijieYan dan fanyuyen juga berkontribusi pada perbaikan bug dan peningkatan.
Pembaruan terperinci dapat ditemukan di log perubahan di bawah
Monte Carlo eXtreme (MCX) adalah perangkat lunak simulasi foton yang cepat dan akurat secara fisik untuk media kompleks heterogen 3D. Dengan memanfaatkan thread paralel yang sangat besar dan latensi memori yang sangat rendah dalam unit pemrosesan grafis (GPU) modern, program ini mampu melakukan simulasi Monte Carlo (MC) dengan kecepatan sangat tinggi, biasanya ratusan hingga seribu kali lebih cepat daripada simulasi tunggal. -implementasi MC berbasis CPU berulir.
MCX ditulis dalam C dan NVIDIA CUDA. Itu hanya dapat dijalankan pada GPU NVIDIA. Jika Anda ingin menjalankan simulasi MCX dengan akselerasi perangkat keras pada GPU atau CPU AMD/Intel, silakan unduh MCX-CL (MCX untuk OpenCL), yang ditulis dalam OpenCL. MCX dan MCX-CL sangat kompatibel.
Karena sifat dari algoritma MC yang mendasarinya, MCX dan MCX-CL adalah perangkat lunak ray-tracing/ray-casting yang tersembunyi. Dibandingkan dengan perpustakaan ray-tracing yang umum digunakan dalam grafis komputer atau mesin game, MCX-CL dan MCX memiliki banyak karakteristik unik. Perbedaan yang paling penting adalah MCX/MCX-CL didasarkan pada hukum fisika. Mereka adalah pemecah numerik persamaan transfer radiasi (RTE) yang mendasarinya dan solusinya telah divalidasi di banyak publikasi menggunakan instrumen optik dan pengukuran eksperimental. Sebagai perbandingan, sebagian besar pelacak sinar berorientasi grafis harus membuat banyak perkiraan untuk mencapai rendering yang cepat, sehingga dapat memberikan hasil simulasi cahaya yang akurat secara kuantitatif. Oleh karena itu, MCX/MCX-CL telah banyak digunakan oleh komunitas riset biofotonik untuk mendapatkan solusi referensi dan memandu pengembangan sistem pencitraan medis baru atau aplikasi klinis. Selain itu, MCX/MCX-CL adalah pelacak sinar volumetrik; mereka melintasi sinar foton di seluruh domain 3-D yang kompleks dan menghitung kuantitas yang bermakna secara fisik seperti fluks yang diselesaikan secara spasial, fluks, reflektansi/transmitansi difus, pengendapan energi, panjang jalur parsial, dan banyak lainnya. Sebaliknya, sebagian besar mesin ray-tracing grafis hanya menelusuri warna RGB dari sebuah sinar dan merendernya pada layar 2-D datar. Dengan kata lain, MCX/MCX-CL memberikan distribusi cahaya 3-D yang akurat secara fisik sementara ray-tracer grafis fokus pada rendering 2-D suatu pemandangan di kamera. Meskipun demikian, keduanya memiliki banyak kesamaan, seperti komputasi ray-marching, akselerasi GPU, penanganan hamburan/penyerapan, dll.
Algoritma perangkat lunak ini dirinci dalam Referensi [Fang2009,Yu2018,Yan2020]. Ringkasan singkat dari fitur-fitur utama meliputi:
Software ini dapat digunakan pada Windows, Linux dan Mac OS. MCX ditulis dalam C/CUDA dan memerlukan GPU NVIDIA (dukungan untuk CPU/GPU AMD/Intel melalui ROCm masih dalam pengembangan). Implementasi OpenCL MCX yang lebih portabel, yaitu MCXCL, diumumkan pada Juli 2012 dan mendukung hampir semua model CPU dan GPU NVIDIA/AMD/Intel. Jika perangkat keras Anda tidak mendukung CUDA, silakan unduh MCXCL dari URL di bawah ini:
https://mcx.space/wiki/index.cgi?Learn#mcxcl
Harap baca bagian ini dengan cermat. Mayoritas kegagalan menggunakan MCX ditemukan terkait dengan kesalahan instalasi driver GPU NVIDIA.
Silakan telusuri https://mcx.space/#documentation untuk petunjuk langkah demi langkah.
Untuk MCX-CUDA, persyaratan untuk menggunakan software ini antara lain
Anda harus memastikan bahwa driver grafis NVIDIA Anda telah diinstal dengan benar. Daftar kartu berkemampuan CUDA dapat ditemukan di [2]. Arsitektur GPU tertua yang dapat dikompilasi kode sumber MCX adalah Fermi ( sm_20 ). Menggunakan kartu NVIDIA terbaru diharapkan dapat menghasilkan kecepatan terbaik. Biner yang dirilis secara resmi (termasuk file mex dan modul pmcx ) dapat berjalan pada GPU NVIDIA setua Kepler (GTX-730, sm_35 ). Semua biner MCX dapat berjalan langsung pada GPU NVIDIA generasi mendatang tanpa perlu dikompilasi ulang, sehingga kompatibel ke depan.
Di halaman web di bawah ini, kami merangkum perbedaan kecepatan antara berbagai generasi GPU NVIDIA
https://mcx.space/gpubench/
Untuk simulasi dengan volume besar, memori grafis yang cukup juga diperlukan untuk melakukan simulasi. Jumlah minimum memori grafis yang diperlukan untuk simulasi MC adalah Nx*Ny*Nz byte untuk data jaringan masukan ditambah Nx*Ny*Nz*Ng*4*2 byte untuk data fluks/fluks keluaran - di mana Nx,Ny,Nz adalah dimensi volume jaringan, Ng adalah jumlah gerbang waktu secara bersamaan, 4 adalah ukuran bilangan floating-point presisi tunggal, 2 adalah memori ekstra yang diperlukan untuk memastikan keakuratan keluaran (#41). MCX tidak memerlukan dukungan presisi ganda di perangkat keras Anda.
MCX menyimpan properti optik dan posisi detektor dalam memori konstan. Biasanya, GPU NVIDIA menyediakan memori konstan sekitar 64 kB. Akibatnya, kita hanya dapat jumlah total sifat optik ditambah jumlah detektor tidak boleh melebihi 4000 (4000 * 4 * 4 = 64 k).
Selain itu, MCX menyimpan data foton yang terdeteksi di dalam memori bersama, yang juga berkisar antara 42 kB hingga 100 kB per stream processor di berbagai generasi GPU. Jika domain Anda berisi banyak tipe media, kemungkinan alokasi memori bersama bisa melebihi batas. Anda juga akan menerima kesalahan "kehabisan memori".
Untuk menginstal MCX, Anda perlu mengunduh biner yang dapat dieksekusi yang dikompilasi untuk arsitektur komputer Anda (32 atau 64bit) dan platform, mengekstrak paket dan menjalankan yang dapat dieksekusi di bawah direktori {mcx root}/bin .
Untuk pengguna Windows, Anda harus memastikan Anda telah menginstal driver NVIDIA yang sesuai untuk GPU Anda. Anda juga harus mengkonfigurasi OS Anda untuk menjalankan simulasi CUDA. Ini mengharuskan Anda untuk membuka folder mcx/setup/win64 menggunakan file explorer Anda, klik kanan pada file apply_timeout_registry_fix.bat dan pilih “Run as administrator” . Setelah konfirmasi, Anda akan melihat jendela perintah windows dengan pesan
Patching your registry
Done
Press any key to continue ...
Anda HARUS REBOOT komputer Windows Anda agar pengaturan ini efektif. Patch di atas mengubah pengaturan driver Anda sehingga Anda dapat menjalankan simulasi MCX lebih dari beberapa detik. Jika tidak, saat menjalankan MCX selama lebih dari beberapa detik, Anda akan mendapatkan kesalahan CUDA: “kesalahan tidak ditentukan”.
Silakan lihat tautan di bawah untuk detailnya
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
Jika Anda menggunakan Linux, Anda dapat mengaktifkan GPU terintegrasi Intel (iGPU) untuk tampilan sambil membiarkan GPU NVIDIA Anda didedikasikan untuk komputasi menggunakan nvidia-prime , lihat
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
atau pilih salah satu dari 4 pendekatan lain dalam postingan blog ini
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
Kami memperhatikan bahwa menjalankan Ubuntu Linux 22.04 dengan kernel 6.5 pada laptop dengan GPU hybrid dengan Intel iGPU dan GPU NVIDIA, Anda harus mengkonfigurasi laptop untuk menggunakan GPU NVIDIA sebagai GPU utama dengan memilih "NVIDIA (Mode Kinerja)" di bagian Profil PRIME Pengaturan Server NVIDIA X. Anda juga bisa lari
sudo prime-select nvidia
untuk mencapai tujuan yang sama. Jika tidak, simulasi mungkin membuat sistem Anda terhenti setelah dijalankan selama beberapa detik. Laptop GPU hybrid yang memadukan GPU NVIDIA dengan AMD iGPU sepertinya tidak mengalami masalah ini jika menggunakan Linux.
Selain itu, driver NVIDIA (520 atau lebih baru) memiliki kesalahan umum yang berjalan pada kernel Linux 6.x (seperti yang ada di Ubuntu 22.04). Melihat
https://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153
Ketika laptop dalam mode "kinerja" dan bangun dari suspensi, MCX atau program CUDA apa pun gagal dijalankan karena kesalahan
MCX ERROR(-999):unknown error in unit mcx_core.cu:2523
Ini karena modul kernel nvida-uvm gagal dimuat ulang setelah ditangguhkan. Jika Anda memiliki sesi MATLAB terbuka, Anda harus menutup MATLAB terlebih dahulu, dan menjalankan perintah di bawah ini (jika MATLAB terbuka, Anda akan melihat rmmod: ERROR: Module nvidia_uvm is in use )
sudo rmmod /dev/nvidia-uvm
sudo modprobe nvidia-uvm
setelah perintah di atas, MCX seharusnya bisa berjalan kembali.
Komputer Mac generasi baru tidak lagi mendukung GPU NVIDIA atau AMD. Anda harus menggunakan MCX versi OpenCL, MCX-CL dengan mengunduhnya dari
https://mcx.space/wiki/?Learn#mcxcl
Untuk menjalankan simulasi, input minimum adalah file konfigurasi (teks), dan, jika file input tidak berisi deskripsi bentuk domain bawaan, file volume eksternal (file biner dengan format voxel tertentu melalui -K/--mediabyte ). Mengetik mcx tanpa parameter apa pun akan mencetak informasi bantuan dan daftar parameter yang didukung, seperti yang ditunjukkan di bawah ini:
###############################################################################
# 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
Untuk mengilustrasikan lebih lanjut opsi baris perintah, di bawah ini kita dapat menemukan contoh perintah
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
perintah di atas meminta mcx untuk secara manual ( -A 0 ) mengatur thread GPU, dan meluncurkan 16384 thread GPU ( -t ) dengan setiap 64 thread dalam satu blok ( -T ); total 1e7 foton ( -n ) disimulasikan oleh GPU pertama ( -G 1 ) dan diulang dua kali ( -r ) - yaitu total 2e7 foton; konfigurasi media/sumber akan dibaca dari file JSON bernama input.json ( -f ) dan outputnya akan diberi label dengan id sesi “test” ( -s ); simulasi akan menjalankan 10 gerbang waktu secara bersamaan ( -g ) jika memori GPU tidak dapat mensimulasikan semua gerbang waktu yang diinginkan sekaligus. Foton yang melewati posisi detektor yang ditentukan disimpan untuk diubah skalanya nanti ( -d ); ketidakcocokan indeks bias dianggap pada batas media ( -b ).
Secara historis, MCX mendukung versi diperpanjang dari format file input (.inp) yang digunakan oleh tMCimg. Namun, kami menghentikan dukungan .inp secara bertahap dan sangat menganjurkan pengguna untuk mengadopsi file input berformat JSON (.json). Banyak opsi MCX tingkat lanjut hanya didukung dalam format masukan JSON.
File masukan .inp MCX lama terlihat seperti ini:
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
Perhatikan bahwa koefisien hamburan mus=musp/(1-g).
File volume ( semi60x60x60.bin pada contoh di atas), dapat dibaca dengan dua cara oleh MCX: row-major[3] atau Column-major bergantung pada nilai parameter pengguna -a . Jika file volume disimpan menggunakan matlab atau fortran, urutan byte adalah kolom-mayor, dan Anda harus menggunakan -a 0 atau mengabaikannya dari baris perintah. Jika disimpan menggunakan fwrite() di C, urutannya adalah baris-mayor, dan Anda dapat menggunakan -a 1 .
Anda dapat mengganti file volume biner dengan file bentuk berformat JSON. Silakan merujuk ke Bagian V untuk rinciannya.
Parameter gerbang waktu ditentukan oleh tiga angka: waktu mulai, waktu berakhir, dan ukuran langkah waktu (dalam detik). Dalam contoh di atas, konfigurasi menentukan jendela waktu total [0 1] ns, dengan resolusi 0,1 ns. Itu berarti jumlah gerbang waktu adalah 10.
MCX menyediakan opsi lanjutan, -g, untuk menjalankan simulasi ketika memori GPU terbatas. Ini menentukan berapa banyak gerbang waktu yang akan disimulasikan secara bersamaan. Pengguna mungkin ingin membatasi jumlah tersebut hingga kurang dari jumlah total yang ditentukan dalam file input - dan secara default ini menjalankan satu gerbang pada satu waktu dalam satu simulasi. Namun jika terdapat cukup memori berdasarkan kebutuhan memori di Bagian II, Anda dapat mensimulasikan 10 gerbang waktu (dari contoh di atas) secara bersamaan dengan menggunakan -g 10 dalam hal ini Anda harus memastikan kartu video memiliki setidaknya 60*60 *60*10*5=10 MB memori bebas. Jika Anda tidak menyertakan -g , MCX akan menganggap Anda hanya ingin menyimulasikan 1 gerbang waktu dalam satu waktu.. Jika Anda menentukan jumlah gerbang waktu yang lebih besar dari jumlah total dalam file masukan, (misal, -g 20 ) MCX akan berhenti ketika 10 gerbang waktu selesai. Jika Anda menggunakan mode autopilot ( -A ), maka gerbang waktu diperkirakan secara otomatis untuk Anda.
Mulai dari versi 0.7.9, MCX menerima file masukan berformat JSON selain format masukan konvensional seperti tMCimg. JSON (JavaScript Object Notation) adalah format teks portabel, dapat dibaca manusia, dan “bebas lemak” untuk mewakili data yang kompleks dan hierarkis. Penggunaan format JSON membuat file input menjadi cukup jelas, dapat diperluas, dan mudah dihubungkan dengan aplikasi lain (seperti MATLAB).
Contoh file input JSON dapat ditemukan di folder contoh/tercepat. File yang sama, qtest.json , juga ditampilkan di bawah:
{
"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
}
]
}
}
File input JSON memerlukan beberapa objek root, yaitu Domain , Session , Forward dan Optode . Bagian root lainnya, seperti Help , akan diabaikan. Setiap objek adalah struktur data yang memberikan informasi yang ditunjukkan dengan namanya. Setiap objek dapat berisi berbagai sub-bidang. Urutan bidang di tingkat yang sama bersifat fleksibel. Untuk setiap kolom, Anda selalu dapat menemukan kolom yang setara di file masukan *.inp . Misalnya, bidang VolumeFile di bawah Domain
