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 แต่ละแหล่งสามารถควบคุมน้ำหนักได้อย่างอิสระโดยองค์ประกอบที่ 4 ของ srcpos
นอกเหนือจากคุณสมบัติใหม่แล้ว ยังมีการค้นพบข้อบกพร่องร้ายแรงที่ส่งผลต่อการจำลอง pattern และ pattern3d ทั้งหมดที่ไม่ใช้การแบ่งปันโฟตอน โปรดดู
#212
เนื่องจากจุดบกพร่องนี้ MCX/MCX-CL ในรุ่นเก่าจึงได้จำลองข้อมูลรูปแบบกำลังสอง/รูปแบบ 3 มิติ แทนที่จะเป็นรูปแบบนั้นเอง หากการจำลองของคุณใช้แหล่งที่มาทั้งสองประเภทนี้ และคุณไม่ได้ใช้การแบ่งปันโฟตอน (เช่น การจำลองหลายรูปแบบร่วมกัน) โปรดอัปเกรด MCX/MCX-CL ของคุณแล้วรันการจำลองของคุณอีกครั้ง จุดบกพร่องนี้ส่งผลต่อเอาต์พุตปริมาตร/ฟลักซ์ตามปริมาตรเท่านั้น ไม่ส่งผลต่อเอาท์พุตการสะท้อนแสงแบบกระจายหรือรูปแบบไบนารี
นอกจากนี้ยังมีการแก้ไขข้อบกพร่องจาก #195 เกี่ยวกับการสูญเสียความแม่นยำเมื่อบันทึกการสะท้อนแบบกระจาย
เราขอขอบคุณ Haohui Zhang สำหรับการรายงานปัญหาสำคัญหลายประการ (#195 และ #212) Liam Keegan ที่ร่วมสนับสนุนแพตช์เพื่อขยายแหล่งที่มาของ slit (#214) ShijieYan และ fanyuyen ยังมีส่วนร่วมในการแก้ไขข้อบกพร่องและปรับปรุงอีกด้วย
การอัปเดตโดยละเอียดสามารถพบได้ในบันทึกการเปลี่ยนแปลงด้านล่าง
Monte Carlo eXtreme (MCX) เป็นซอฟต์แวร์จำลองโฟตอนที่มีความแม่นยำทางกายภาพที่รวดเร็วสำหรับสื่อ 3 มิติที่ซับซ้อนต่างกัน ด้วยการใช้ประโยชน์จากเธรดแบบขนานขนาดใหญ่และเวลาแฝงของหน่วยความจำที่ต่ำมากในหน่วยประมวลผลกราฟิกสมัยใหม่ (GPU) โปรแกรมนี้จึงสามารถทำการจำลองมอนติคาร์โล (MC) ได้ด้วยความเร็วที่เห็นได้ชัด ซึ่งโดยทั่วไปจะเร็วกว่าหลายร้อยถึงพันเท่า - การใช้งาน MC ที่ใช้ CPU แบบเธรด
MCX เขียนด้วยภาษา C และ NVIDIA CUDA ใช้งานได้กับ NVIDIA GPU เท่านั้น หากคุณต้องการรันการจำลอง MCX ที่เร่งด้วยฮาร์ดแวร์บน AMD/Intel GPU หรือ CPU โปรดดาวน์โหลด MCX-CL (MCX สำหรับ OpenCL) ซึ่งเขียนใน OpenCL MCX และ MCX-CL มีความเข้ากันได้สูง
เนื่องจากธรรมชาติของอัลกอริธึม MC พื้นฐาน MCX และ MCX-CL จึงเป็นซอฟต์แวร์ Ray Tracing/Ray Casting ที่อยู่ภายใต้การควบคุม เมื่อเปรียบเทียบกับไลบรารี Ray Tracing ทั่วไปที่ใช้ในคอมพิวเตอร์กราฟิกหรือเอ็นจิ้นเกม MCX-CL และ MCX มีลักษณะเฉพาะหลายประการ ความแตกต่างที่สำคัญที่สุดคือ MCX/MCX-CL เป็นไปตามกฎหมายทางกายภาพอย่างเข้มงวด พวกมันคือตัวแก้ปัญหาเชิงตัวเลขของสมการการถ่ายโอนการแผ่รังสี (RTE) ที่สำคัญ และสารละลายของพวกมันได้รับการตรวจสอบความถูกต้องในสิ่งพิมพ์หลายฉบับโดยใช้เครื่องมือทางแสงและการวัดเชิงทดลอง ในการเปรียบเทียบ เครื่องติดตามรังสีที่มุ่งเน้นกราฟิกส่วนใหญ่จะต้องทำการประมาณค่าต่างๆ มากมายเพื่อให้ได้การเรนเดอร์ที่รวดเร็ว จึงสามารถให้ผลลัพธ์การจำลองแสงที่แม่นยำในเชิงปริมาณได้ ด้วยเหตุนี้ MCX/MCX-CL จึงถูกนำมาใช้อย่างกว้างขวางในชุมชนการวิจัยด้านชีวโฟโตนิกส์ เพื่อให้ได้โซลูชันอ้างอิงและเป็นแนวทางในการพัฒนาระบบการถ่ายภาพทางการแพทย์แบบใหม่หรือการใช้งานทางคลินิก นอกจากนี้ MCX/MCX-CL ยังเป็นเครื่องติดตามรังสีเชิงปริมาตร พวกมันสำรวจรังสีโฟตอนทั่วทั้งโดเมน 3 มิติที่ซับซ้อน และคำนวณปริมาณที่มีความหมายทางกายภาพ เช่น ฟลูเอนซ์ที่ได้รับการแก้ไขเชิงพื้นที่ ฟลักซ์ การสะท้อน/การส่งผ่านแบบกระจาย การสะสมพลังงาน ความยาวเส้นทางบางส่วน และอื่นๆ อีกมากมาย ในทางตรงกันข้าม กลไกการติดตามรังสีของกราฟิกส่วนใหญ่จะติดตามเฉพาะสี RGB ของรังสีแล้วเรนเดอร์บนหน้าจอ 2 มิติแบบแบน กล่าวอีกนัยหนึ่ง MCX/MCX-CL ให้การกระจายแสง 3 มิติที่แม่นยำทางกายภาพ ในขณะที่เรย์เทรเซอร์กราฟิกมุ่งเน้นไปที่การเรนเดอร์ฉาก 2 มิติที่กล้อง อย่างไรก็ตาม พวกเขามีความคล้ายคลึงกันหลายประการ เช่น การคำนวณ ray-marching, การเร่งความเร็วของ GPU, การจัดการการกระเจิง/การดูดซึม เป็นต้น
อัลกอริธึมของซอฟต์แวร์นี้มีรายละเอียดอยู่ในข้อมูลอ้างอิง [Fang2009,Yu2018,Yan2020] สรุปคุณสมบัติหลักโดยย่อประกอบด้วย:
ซอฟต์แวร์นี้สามารถใช้ได้กับ Windows, Linux และ Mac OS MCX เขียนด้วยภาษา C/CUDA และต้องใช้ NVIDIA GPUs (การรองรับ AMD/Intel CPUs/GPUs ผ่าน ROCm ยังอยู่ระหว่างการพัฒนา) มีการประกาศการใช้งาน OpenCL แบบพกพามากขึ้นของ MCX เช่น MCXCL เมื่อเดือนกรกฎาคม 2555 และรองรับ NVIDIA/AMD/Intel CPU และ GPU เกือบทั้งหมด หากฮาร์ดแวร์ของคุณไม่รองรับ CUDA โปรดดาวน์โหลด MCXCL จาก URL ด้านล่าง:
https://mcx.space/wiki/index.cgi?Learn#mcxcl
โปรดอ่านส่วนนี้อย่างละเอียด พบความล้มเหลวส่วนใหญ่ในการใช้ MCX เกี่ยวข้องกับการติดตั้งไดรเวอร์ NVIDIA GPU ที่ไม่ถูกต้อง
โปรดเรียกดู https://mcx.space/#documentation เพื่อดูคำแนะนำทีละขั้นตอน
สำหรับ MCX-CUDA ข้อกำหนดในการใช้ซอฟต์แวร์นี้ประกอบด้วย
คุณต้องตรวจสอบให้แน่ใจว่าไดรเวอร์กราฟิก NVIDIA ของคุณได้รับการติดตั้งอย่างถูกต้อง รายชื่อการ์ดที่รองรับ CUDA สามารถดูได้ที่ [2] สถาปัตยกรรม GPU ที่เก่าแก่ที่สุดที่สามารถคอมไพล์ซอร์สโค้ด MCX ได้คือ Fermi ( sm_20 ) การใช้การ์ด NVIDIA รุ่นล่าสุดคาดว่าจะสร้างความเร็วที่ดีที่สุด ไบนารีที่เปิดตัวอย่างเป็นทางการ (รวมถึงไฟล์ mex และโมดูล pmcx ) สามารถทำงานบน NVIDIA GPU ที่เก่าเท่ากับ Kepler (GTX-730, sm_35 ) ไบนารี 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 จะให้หน่วยความจำคงที่ประมาณ 64 kB เป็นผลให้เราทำได้เฉพาะจำนวนคุณสมบัติทางแสงทั้งหมดบวกจำนวนเครื่องตรวจจับต้องไม่เกิน 4,000 (4,000 * 4 * 4 = 64 k)
นอกจากนี้ MCX ยังจัดเก็บข้อมูลโฟตอนที่ตรวจพบภายในหน่วยความจำที่ใช้ร่วมกัน ซึ่งมีช่วงระหว่าง 42 kB ถึง 100 kB ต่อโปรเซสเซอร์สตรีมใน GPU รุ่นต่างๆ หากโดเมนของคุณมีสื่อหลายประเภท อาจเป็นไปได้ว่าการจัดสรรหน่วยความจำที่ใช้ร่วมกันอาจเกินขีดจำกัด คุณยังจะได้รับข้อผิดพลาด "หน่วยความจำไม่เพียงพอ"
ในการติดตั้ง MCX คุณจะต้องดาวน์โหลดไฟล์ปฏิบัติการแบบไบนารีที่คอมไพล์สำหรับสถาปัตยกรรมคอมพิวเตอร์ (32 หรือ 64 บิต) และแพลตฟอร์มของคุณ จากนั้นแตกแพ็คเกจและเรียกใช้ไฟล์ปฏิบัติการภายใต้ไดเร็กทอรี {mcx root}/bin
สำหรับผู้ใช้ Windows คุณต้องตรวจสอบให้แน่ใจว่าคุณได้ติดตั้งไดรเวอร์ NVIDIA ที่เหมาะสมสำหรับ GPU ของคุณ คุณควรกำหนดค่าระบบปฏิบัติการของคุณให้รันการจำลอง CUDA ด้วย สิ่งนี้ต้องการให้คุณเปิดโฟลเดอร์ mcx/setup/win64 โดยใช้ file explorer ของคุณ คลิกขวาที่ไฟล์ apply_timeout_registry_fix.bat และเลือก “Run as administrator” หลังจากการยืนยัน คุณจะเห็นหน้าต่างคำสั่ง windows พร้อมข้อความ
Patching your registry
Done
Press any key to continue ...
คุณต้องรีบูตคอมพิวเตอร์ Windows ของคุณเพื่อให้การตั้งค่านี้มีประสิทธิภาพ แพตช์ด้านบนจะปรับเปลี่ยนการตั้งค่าไดรเวอร์ของคุณ เพื่อให้คุณสามารถรันการจำลอง MCX ได้นานกว่าสองสามวินาที มิฉะนั้น เมื่อเรียกใช้ MCX นานกว่าสองสามวินาที คุณจะได้รับข้อผิดพลาด CUDA: “ข้อผิดพลาดที่ไม่ระบุ”
โปรดดูลิงค์ด้านล่างเพื่อดูรายละเอียด
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
หากคุณใช้ Linux คุณสามารถเปิดใช้งาน Intel integrated GPU (iGPU) สำหรับการแสดงผลในขณะที่ปล่อยให้ NVIDIA GPU ของคุณใช้สำหรับการประมวลผลโดยใช้ nvidia-prime โดยเฉพาะ ดู
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
เราสังเกตเห็นว่าการใช้ Ubuntu Linux 22.04 พร้อมเคอร์เนล 6.5 บนแล็ปท็อปที่มี GPU ไฮบริดที่มี Intel iGPU และ NVIDIA GPU คุณต้องกำหนดค่าแล็ปท็อปให้ใช้ NVIDIA GPU เป็น GPU หลักโดยเลือก "NVIDIA (โหมดประสิทธิภาพ)" ในส่วนโปรไฟล์ PRIME ของ การตั้งค่าเซิร์ฟเวอร์ NVIDIA X คุณยังสามารถวิ่งได้
sudo prime-select nvidia
เพื่อให้บรรลุเป้าหมายเดียวกัน มิฉะนั้น การจำลองอาจทำให้ระบบของคุณหยุดทำงานหลังจากทำงานไปไม่กี่วินาที แล็ปท็อป GPU แบบไฮบริดที่รวม NVIDIA GPU กับ AMD iGPU ดูเหมือนจะไม่มีปัญหานี้หากใช้ 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
ในการรันการจำลอง อินพุตขั้นต่ำคือไฟล์การกำหนดค่า (ข้อความ) และหากไฟล์อินพุตไม่มีคำอธิบายรูปร่างโดเมนในตัว ไฟล์โวลุ่มภายนอก (ไฟล์ไบนารีที่มีรูปแบบ voxel ที่ระบุผ่าน -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 ) และเปิดใช้งานเธรด GPU 16384 ตัว ( -t ) โดยทุกๆ 64 เธรดต่อบล็อก ( -T ); โฟตอนทั้งหมด 1e7 ( -n ) ถูกจำลองโดย GPU ตัวแรก ( -G 1 ) และทำซ้ำสองครั้ง ( -r ) - เช่นโฟตอนทั้งหมด 2e7; การกำหนดค่าสื่อ/แหล่งที่มาจะถูกอ่านจากไฟล์ JSON ชื่อ input.json ( -f ) และเอาต์พุตจะมีป้ายกำกับด้วยรหัสเซสชัน “test” ( -s ) การจำลองจะทำงาน 10 ประตูเวลาพร้อมกัน ( -g ) หากหน่วยความจำ GPU ไม่สามารถจำลองประตูเวลาที่ต้องการทั้งหมดในคราวเดียว โฟตอนที่ผ่านตำแหน่งเครื่องตรวจจับที่กำหนดไว้จะถูกบันทึกไว้เพื่อปรับขนาดใหม่ในภายหลัง ( -d ); ดัชนีการหักเหของแสงไม่ตรงกันจะถือว่าอยู่ที่ขอบเขตของสื่อ ( -b )
ในอดีต MCX รองรับเวอร์ชันขยายของรูปแบบไฟล์อินพุต (.inp) ที่ใช้โดย tMCimg อย่างไรก็ตาม เรากำลังยุติการสนับสนุน .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: row-major[3] หรือ column-major ขึ้นอยู่กับค่าของพารามิเตอร์ผู้ใช้ -a หากไฟล์โวลุ่มถูกบันทึกโดยใช้ Matlab หรือ Fortran ลำดับไบต์จะเป็นคอลัมน์หลัก และคุณควรใช้ -a 0 หรือปล่อยไว้นอกบรรทัดคำสั่ง หากบันทึกโดยใช้ fwrite() ใน C ลำดับจะเป็นแถวหลัก และคุณสามารถใช้ -a 1 ได้
คุณสามารถแทนที่ไฟล์โวลุ่มไบนารีด้วยไฟล์รูปร่างที่จัดรูปแบบ JSON โปรดดูส่วนที่ V สำหรับรายละเอียด
พารามิเตอร์ประตูเวลาระบุด้วยตัวเลขสามตัว: เวลาเริ่มต้น เวลาสิ้นสุด และขนาดขั้นตอนเวลา (เป็นวินาที) ในตัวอย่างข้างต้น การกำหนดค่าระบุกรอบเวลารวมเป็น [0 1] ns โดยมีความละเอียด 0.1 ns นั่นหมายถึงจำนวนประตูเวลาทั้งหมดคือ 10
MCX มีตัวเลือกขั้นสูง -g เพื่อรันการจำลองเมื่อหน่วยความจำ GPU มีจำกัด ระบุจำนวนประตูเวลาที่จะจำลองพร้อมกัน ผู้ใช้อาจต้องการจำกัดจำนวนนั้นให้น้อยกว่าจำนวนทั้งหมดที่ระบุในไฟล์อินพุต และตามค่าเริ่มต้น ระบบจะรันทีละเกตในการจำลองเดียว แต่หากมีหน่วยความจำเพียงพอตามความต้องการหน่วยความจำในส่วนที่ 2 คุณสามารถจำลองไทม์เกตทั้งหมด 10 ไทม์เกต (จากตัวอย่างด้านบน) พร้อมๆ กันได้โดยใช้ -g 10 ซึ่งในกรณีนี้คุณต้องแน่ใจว่าการ์ดแสดงผลมีขนาดอย่างน้อย 60*60 *60*10*5=หน่วยความจำว่าง 10MB หากคุณไม่รวม -g ไว้ MCX จะถือว่าคุณต้องการจำลองเกตเวลาเพียง 1 ครั้งในแต่ละครั้ง .. หากคุณระบุหมายเลขประตูเวลามากกว่าจำนวนทั้งหมดในไฟล์อินพุต (เช่น -g 20 ) MCX จะหยุดเมื่อประตูเวลา 10 ประตูเสร็จสมบูรณ์ หากคุณใช้โหมดอัตโนมัติ ( -A ) ประตูเวลาจะถูกประมาณโดยอัตโนมัติสำหรับคุณ
ตั้งแต่เวอร์ชัน 0.7.9 เป็นต้นไป MCX ยอมรับไฟล์อินพุตในรูปแบบ JSON นอกเหนือจากรูปแบบอินพุตที่คล้ายกับ tMCimg ทั่วไป JSON (สัญลักษณ์วัตถุ JavaScript) เป็นรูปแบบข้อความแบบพกพาที่มนุษย์อ่านได้ และ "ปราศจากไขมัน" เพื่อแสดงข้อมูลที่ซับซ้อนและเป็นลำดับชั้น การใช้รูปแบบ JSON ทำให้ไฟล์อินพุตอธิบายได้ในตัว ขยายได้ และเชื่อมต่อกับแอปพลิเคชันอื่นๆ ได้ง่าย (เช่น MATLAB)
คุณสามารถดูไฟล์อินพุต JSON ตัวอย่างได้ภายใต้โฟลเดอร์ตัวอย่าง/การทดสอบด่วน ไฟล์เดียวกัน 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 ได้เสมอ ตัวอย่างเช่น ช่อง VolumeFile ใต้ Domain
