mcx
v2024.2 (Interstellar Ion)
목차:
MCX v2024.2에는 주요 새로운 기능과 중요한 버그 수정이 모두 포함되어 있습니다. 모든 사용자에게 강력히 권장되는 업그레이드입니다.
특히 MCX v2024.2에는 세 가지 중요한 새로운 기능이 추가되었습니다.
MCX v2023에 포함된 사용자 정의 위상 함수 기능과 유사하게, 첫 번째 기능을 사용하면 이산화된 역 CDF(누적 분포 함수)를 통해 소스 방향 벡터를 기준으로 광자를 발사하기 위한 천정각 분포를 정의할 수 있습니다. . MATLAB/Octave에서는 각각 cfg.invcdf 또는 cfg.angleinvcdf 로 설정할 수 있습니다. mcxlab/examples/demo_mcxlab_phasefun.m 및 demo_mcxlab_launchangle.m 에서 즉시 사용 가능한 데모 스크립트를 제공했습니다.
두 번째 기능을 사용하면 srcpos , srcdir , srcparam1 및 srcparam2 정의할 때 사용자가 동일한 유형의 소스를 두 개 이상 지정할 수 있습니다. 각 소스는 srcpos의 4번째 요소에 의해 제어되는 독립적인 가중치를 가질 수 있습니다.
새로운 기능 외에도 광자 공유를 사용하지 않는 모든 pattern 및 pattern3d 시뮬레이션에 영향을 미치는 심각한 버그가 발견되었습니다.
#212
이 버그로 인해 이전 릴리스의 MCX/MCX-CL은 패턴 자체 대신 제곱 패턴/pattern3d 데이터를 시뮬레이션했습니다. 시뮬레이션에서 이 두 가지 소스 유형을 사용하고 광자 공유(예: 여러 패턴을 함께 시뮬레이션)를 사용하지 않는 경우 MCX/MCX-CL을 업그레이드하고 시뮬레이션을 다시 실행하십시오. 이 버그는 체적 플루언스/플럭스 출력에만 영향을 미칩니다. 확산 반사율 출력이나 바이너리 패턴에는 영향을 주지 않습니다.
또한 확산 반사율을 저장할 때 정밀도 손실과 관련된 #195의 버그 수정도 포함되어 있습니다.
여러 가지 중요한 문제(#195 및 #212)를 보고한 Haohui Zhang과 슬릿 소스 확장을 위한 패치(#214)에 기여한 Liam Keegan에게 감사의 말씀을 전하고 싶습니다. ShijieYan과 fanyuyen도 버그 수정 및 개선에 기여했습니다.
자세한 업데이트 내용은 아래 변경 로그에서 확인하실 수 있습니다.
MCX(Monte Carlo eXtreme)는 3D 이종 복합 매체를 위한 빠르고 물리적으로 정확한 광자 시뮬레이션 소프트웨어입니다. 최신 그래픽 처리 장치(GPU)의 대규모 병렬 스레드와 극도로 낮은 메모리 대기 시간을 활용함으로써 이 프로그램은 일반적으로 단일 프로세서보다 수백 배에서 천 배 빠른 속도로 몬테카를로(MC) 시뮬레이션을 수행할 수 있습니다. -스레드 CPU 기반 MC 구현.
MCX는 C 및 NVIDIA CUDA로 작성되었습니다. NVIDIA GPU에서만 실행됩니다. AMD/Intel GPU 또는 CPU에서 하드웨어 가속 MCX 시뮬레이션을 실행하려면 OpenCL로 작성된 MCX-CL(OpenCL용 MCX)을 다운로드하십시오. MCX와 MCX-CL은 호환성이 뛰어납니다.
기본 MC 알고리즘의 특성으로 인해 MCX 및 MCX-CL은 내부적으로 레이 트레이싱/레이 캐스팅 소프트웨어입니다. 컴퓨터 그래픽이나 게임 엔진에 사용되는 일반적으로 사용되는 광선 추적 라이브러리와 비교할 때 MCX-CL 및 MCX는 많은 고유한 특성을 가지고 있습니다. 가장 중요한 차이점은 MCX/MCX-CL이 물리적 법칙을 엄격하게 기반으로 한다는 것입니다. 이는 기본 복사 전달 방정식(RTE)에 대한 수치 해법이며 해당 솔루션은 광학 기기 및 실험 측정을 사용하는 많은 간행물에서 검증되었습니다. 이에 비해 대부분의 그래픽 중심 광선 추적기는 빠른 렌더링을 달성하고 정량적으로 정확한 조명 시뮬레이션 결과를 제공하기 위해 많은 근사치를 만들어야 합니다. 이로 인해 MCX/MCX-CL은 생체 광자학 연구 커뮤니티에서 참조 솔루션을 얻고 새로운 의료 영상 시스템 또는 임상 응용 분야의 개발을 안내하기 위해 광범위하게 사용되었습니다. 또한 MCX/MCX-CL은 체적 광선 추적기입니다. 복잡한 3D 영역 전체에 걸쳐 광자선을 통과하고 공간적으로 분해된 플루언스, 플럭스, 확산 반사/투과율, 에너지 침착, 부분 경로 길이 등 물리적으로 의미 있는 양을 계산합니다. 이와 대조적으로 대부분의 그래픽 광선 추적 엔진은 광선의 RGB 색상만 추적하여 평면 2D 화면에 렌더링합니다. 즉, MCX/MCX-CL은 물리적으로 정확한 3D 조명 분포를 제공하는 반면 그래픽 광선 추적기는 카메라 장면의 2D 렌더링에 중점을 둡니다. 그럼에도 불구하고 이들은 광선 행진 계산, GPU 가속, 산란/흡수 처리 등과 같은 많은 유사점을 공유합니다.
이 소프트웨어의 알고리즘은 참고문헌 [Fang2009,Yu2018,Yan2020]에 자세히 설명되어 있습니다. 주요 기능에 대한 간략한 요약은 다음과 같습니다.
이 소프트웨어는 Windows, Linux 및 Mac OS에서 사용할 수 있습니다. MCX는 C/CUDA로 작성되었으며 NVIDIA GPU가 필요합니다(ROCm을 통한 AMD/Intel CPU/GPU 지원은 아직 개발 중입니다). MCX의 보다 이식성이 뛰어난 OpenCL 구현인 MCXCL이 2012년 7월에 발표되었으며 거의 모든 NVIDIA/AMD/Intel CPU 및 GPU 모델을 지원합니다. 하드웨어가 CUDA를 지원하지 않는 경우 아래 URL에서 MCXCL을 다운로드하십시오.
https://mcx.space/wiki/index.cgi?Learn#mcxcl
이 섹션을 주의 깊게 읽어 보십시오. MCX 사용 실패의 대부분은 NVIDIA GPU 드라이버의 잘못된 설치와 관련하여 발견되었습니다.
단계별 지침을 보려면 https://mcx.space/#documentation을 찾아보세요.
MCX-CUDA의 경우 이 소프트웨어를 사용하기 위한 요구 사항은 다음과 같습니다.
NVIDIA 그래픽 드라이버가 제대로 설치되었는지 확인해야 합니다. CUDA 지원 카드 목록은 [2]에서 확인할 수 있습니다. MCX 소스 코드를 컴파일할 수 있는 가장 오래된 GPU 아키텍처는 Fermi( sm_20 )입니다. 최신 NVIDIA 카드를 사용하면 최고의 속도를 낼 수 있을 것으로 예상됩니다. 공식적으로 출시된 바이너리(mex 파일 및 pmcx 모듈 포함)는 Kepler(GTX-730, sm_35 )만큼 오래된 NVIDIA GPU에서 실행될 수 있습니다. 모든 MCX 바이너리는 재컴파일할 필요 없이 차세대 NVIDIA GPU에서 직접 실행될 수 있으므로 향후 버전과 호환됩니다.
아래 웹페이지에서는 다양한 세대의 NVIDIA GPU 간의 속도 차이를 요약했습니다.
https://mcx.space/gpubench/
대용량 시뮬레이션의 경우 시뮬레이션을 수행하려면 충분한 그래픽 메모리도 필요합니다. MC 시뮬레이션에 필요한 최소 그래픽 메모리 양은 입력 조직 데이터에 대한 Nx*Ny*Nz 바이트와 출력 플럭스/플루언스 데이터에 대한 Nx*Ny*Nz*Ng*4*2 바이트입니다. 여기서 Nx,Ny,Nz 는 조직 볼륨의 크기이고, Ng는 동시 시간 게이트의 수이고, 4는 단정밀도 부동 소수점 수의 크기이고, 2는 출력 정확도를 보장하는 데 필요한 추가 메모리입니다(#41). MCX는 하드웨어에서 배정밀도 지원을 요구하지 않습니다.
MCX는 광학 특성과 검출기 위치를 상수 메모리에 저장합니다. 일반적으로 NVIDIA GPU는 약 64kB의 상수 메모리를 제공합니다. 결과적으로 총 광학 특성 수와 검출기 수를 더한 수는 4000(4000 * 4 * 4 = 64k)을 초과할 수 없습니다.
또한 MCX는 감지된 광자 데이터를 공유 메모리 내부에 저장합니다. 이 공유 메모리의 범위는 다양한 GPU 세대에 걸쳐 스트림 프로세서당 42kB~100kB입니다. 도메인에 많은 매체 유형이 포함된 경우 공유 메모리 할당이 제한을 초과할 수 있습니다. 또한 "메모리 부족" 오류가 발생합니다.
MCX를 설치하려면 컴퓨터 아키텍처(32 또는 64비트) 및 플랫폼에 맞게 컴파일된 바이너리 실행 파일을 다운로드하고 패키지를 추출한 후 {mcx root}/bin 디렉터리에서 실행 파일을 실행해야 합니다.
Windows 사용자의 경우 GPU에 적합한 NVIDIA 드라이버를 설치했는지 확인해야 합니다. 또한 CUDA 시뮬레이션을 실행하도록 OS를 구성해야 합니다. 이를 위해서는 파일 탐색기를 사용하여 mcx/setup/win64 폴더를 열고 apply_timeout_registry_fix.bat 파일을 마우스 오른쪽 버튼으로 클릭한 후 "관리자 권한으로 실행"을 선택해야 합니다. 확인 후 메시지가 포함된 Windows 명령 창이 표시됩니다.
Patching your registry
Done
Press any key to continue ...
이 설정을 적용하려면 Windows 컴퓨터를 재부팅해야 합니다. 위 패치는 몇 초 이상 MCX 시뮬레이션을 실행할 수 있도록 드라이버 설정을 수정합니다. 그렇지 않으면 MCX를 몇 초 이상 실행하면 "unspecified error"라는 CUDA 오류가 발생합니다.
자세한 내용은 아래 링크를 참조해주세요
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
Linux를 사용하는 경우 NVIDIA GPU를 nvidia-prime 사용하는 컴퓨팅 전용으로 남겨두고 디스플레이용 Intel 통합 GPU(iGPU)를 활성화할 수 있습니다.
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
또는 이 블로그 게시물의 다른 4가지 접근 방식 중 하나를 선택하세요.
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
Intel iGPU 및 NVIDIA GPU가 포함된 하이브리드 GPU가 탑재된 노트북에서 6.5 커널이 포함된 Ubuntu Linux 22.04를 실행하려면 "NVIDIA(성능 모드)"를 선택하여 NVIDIA GPU를 기본 GPU로 사용하도록 노트북을 구성해야 합니다. NVIDIA X 서버 설정 의 PRIME 프로필 섹션에 있습니다. 당신은 또한 실행할 수 있습니다
sudo prime-select nvidia
같은 목표를 달성하기 위해. 그렇지 않으면 시뮬레이션이 몇 초 동안 실행된 후 시스템이 중단될 수 있습니다. NVIDIA GPU와 AMD iGPU를 결합한 하이브리드 GPU 노트북은 Linux를 사용하는 경우 이 문제가 없는 것 같습니다.
또한 NVIDIA 드라이버(520 이상)에는 Linux 커널 6.x(예: Ubuntu 22.04의 드라이버)에서 실행되는 알려진 결함이 있습니다. 보다
https://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153
노트북이 "성능" 모드에 있고 정지 상태에서 깨어나면 MCX 또는 모든 CUDA 프로그램이 오류와 함께 실행되지 않습니다.
MCX ERROR(-999):unknown error in unit mcx_core.cu:2523
이는 정지 후 커널 모듈 nvida-uvm 이 다시 로드되지 않기 때문입니다. MATLAB 세션이 열려 있는 경우 먼저 MATLAB을 닫고 아래 명령을 실행해야 합니다. MATLAB이 열려 있으면 rmmod: ERROR: Module nvidia_uvm is in use 가 표시됩니다.
sudo rmmod /dev/nvidia-uvm
sudo modprobe nvidia-uvm
위 명령을 실행하면 MCX가 다시 실행될 수 있습니다.
새로운 세대의 Mac 컴퓨터는 더 이상 NVIDIA 또는 AMD GPU를 지원하지 않습니다. MCX, MCX-CL의 OpenCL 버전을 다운로드하여 사용해야 합니다.
https://mcx.space/wiki/?Learn#mcxcl
시뮬레이션을 실행하기 위한 최소 입력은 구성(텍스트) 파일이며, 입력 파일에 내장 도메인 모양 설명이 포함되어 있지 않은 경우 외부 볼륨 파일( -K/--mediabyte 통해 지정된 복셀 형식의 바이너리 파일) -K/--mediabyte ). 매개변수 없이 mcx 입력하면 아래와 같이 도움말 정보와 지원되는 매개변수 목록이 인쇄됩니다.
###############################################################################
# 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
명령줄 옵션을 더 자세히 설명하기 위해 아래에서 샘플 명령을 찾을 수 있습니다.
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
위 명령은 mcx에게 GPU 스레드를 수동으로 설정하고( -A 0 ) 블록당 64개 스레드마다 16384개의 GPU 스레드( -t )를 실행하도록 요청합니다( -T ). 총 1e7 광자( -n )가 첫 번째 GPU( -G 1 )에 의해 시뮬레이션되고 두 번 반복됩니다( -r ). 즉 총 2e7 광자입니다. 미디어/소스 구성은 input.json ( -f )이라는 JSON 파일에서 읽혀지고 출력에는 세션 ID "test"( -s )로 레이블이 지정됩니다. GPU 메모리가 원하는 모든 타임 게이트를 한 번에 시뮬레이션할 수 없는 경우 시뮬레이션은 10개의 동시 타임 게이트( -g )를 실행합니다. 정의된 검출기 위치를 통과하는 광자는 나중에 크기 조정을 위해 저장됩니다( -d ). 굴절률 불일치는 미디어 경계( -b )에서 고려됩니다.
역사적으로 MCX는 tMCimg에서 사용하는 입력 파일 형식(.inp)의 확장 버전을 지원합니다. 그러나 우리는 .inp 지원을 단계적으로 중단하고 사용자가 JSON 형식(.json) 입력 파일을 채택하도록 강력히 권장합니다. 대부분의 고급 MCX 옵션은 JSON 입력 형식에서만 지원됩니다.
기존 .inp MCX 입력 파일은 다음과 같습니다.
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
산란 계수는 mus=musp/(1-g)입니다.
볼륨 파일(위 예에서는 semi60x60x60.bin )은 MCX에서 사용자 매개변수 -a 값에 따라 row-major[3] 또는 열-major의 두 가지 방법으로 읽을 수 있습니다. matlab 또는 fortran을 사용하여 볼륨 파일을 저장한 경우 바이트 순서는 열 중심이므로 -a 0 사용하거나 명령줄에서 그대로 두어야 합니다. C에서 fwrite() 사용하여 저장된 경우 순서는 행 우선이므로 -a 1 사용할 수 있습니다.
바이너리 볼륨 파일을 JSON 형식의 모양 파일로 대체할 수 있습니다. 자세한 내용은 섹션 V를 참조하세요.
타임 게이트 매개변수는 시작 시간, 종료 시간 및 시간 단계 크기(초)의 세 가지 숫자로 지정됩니다. 위의 예에서 구성은 0.1ns 분해능으로 [0 1]ns의 총 시간 창을 지정합니다. 즉, 타임 게이트의 총 개수는 10개입니다.
MCX는 GPU 메모리가 제한되어 있을 때 시뮬레이션을 실행할 수 있는 고급 옵션인 -g를 제공합니다. 동시에 시뮬레이션할 타임 게이트 수를 지정합니다. 사용자는 해당 수를 입력 파일에 지정된 총 수보다 작게 제한할 수 있으며 기본적으로 단일 시뮬레이션에서 한 번에 하나의 게이트를 실행합니다. 그러나 섹션 II의 메모리 요구 사항에 따라 충분한 메모리가 있는 경우 -g 10 사용하여 위 예의 10개 타임 게이트를 모두 동시에 시뮬레이션할 수 있습니다. 이 경우 비디오 카드에 최소 60*60이 있는지 확인해야 합니다. *60*10*5=10MB의 여유 메모리. -g 를 포함하지 않으면 MCX는 한 번에 하나의 타임 게이트만 시뮬레이션한다고 가정합니다. 입력 파일의 총 수보다 큰 타임 게이트 수를 지정하는 경우(예: -g 20 ) MCX는 10개의 타임 게이트가 완료되면 중지됩니다. 자동 조종 모드( -A )를 사용하면 타임 게이트가 자동으로 추정됩니다.
버전 0.7.9부터 MCX는 기존 tMCimg와 유사한 입력 형식 외에도 JSON 형식의 입력 파일을 허용합니다. JSON(JavaScript Object Notation)은 복잡하고 계층적인 데이터를 표현하기 위한 이식 가능하고 사람이 읽을 수 있는 "지방 없는" 텍스트 형식입니다. JSON 형식을 사용하면 입력 파일이 설명이 필요 없고 확장 가능하며 다른 응용 프로그램(예: MATLAB)과 쉽게 인터페이스할 수 있습니다.
샘플 JSON 입력 파일은 example/quicktest 폴더에서 찾을 수 있습니다. 동일한 파일 qtest.json 도 아래에 표시됩니다.
{
"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
}
]
}
}
JSON 입력 파일에는 Domain , Session , Forward 및 Optode 와 같은 여러 루트 개체가 필요합니다. Help 와 같은 다른 루트 섹션은 무시됩니다. 각 객체는 이름으로 표시된 정보를 제공하는 데이터 구조입니다. 각 개체에는 다양한 하위 필드가 포함될 수 있습니다. 동일한 수준의 필드 순서는 유연합니다. 각 필드에 대해 *.inp 입력 파일에서 언제든지 해당 필드를 찾을 수 있습니다. 예를 들어 Domain 아래의 VolumeFile 필드는 다음과 같습니다.
