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.
بصرف النظر عن الميزات الجديدة، تم اكتشاف خطأ خطير يؤثر على جميع عمليات محاكاة pattern والأنماط pattern3d التي لا تستخدم مشاركة الفوتون، يرجى الاطلاع على
#212
وبسبب هذا الخطأ، كان MCX/MCX-CL في الإصدارات الأقدم يحاكي بيانات النمط/النمط التربيعي ثلاثي الأبعاد بدلاً من النمط نفسه. إذا كانت المحاكاة الخاصة بك تستخدم هذين النوعين من المصادر ولا تستخدم مشاركة الفوتون (أي محاكاة أنماط متعددة معًا)، فيرجى ترقية MCX/MCX-CL وإعادة تشغيل عمليات المحاكاة الخاصة بك. يؤثر هذا الخطأ فقط على مخرجات التدفق/التدفق الحجمي؛ ولا يؤثر على مخرجات الانعكاس المنتشرة أو الأنماط الثنائية.
ويتضمن أيضًا إصلاحًا للأخطاء من رقم 195 فيما يتعلق بفقد الدقة عند حفظ الانعكاس المنتشر.
نريد أن نشكر Haohui Zhang على الإبلاغ عن عدد من المشكلات الحرجة (#195 و#212)، وLiam Keegan لمساهمته في تصحيح لتوسيع مصدر الشق (#214). ساهم ShijieYan وfanyuyen أيضًا في إصلاحات الأخطاء والتحسينات.
يمكن العثور على التحديثات التفصيلية في سجل التغيير أدناه
يعد برنامج Monte Carlo eXtreme (MCX) برنامجًا سريعًا ودقيقًا لمحاكاة الفوتون للوسائط المعقدة غير المتجانسة ثلاثية الأبعاد. من خلال الاستفادة من الخيوط المتوازية بشكل كبير وزمن الوصول المنخفض للغاية للذاكرة في وحدة معالجة الرسومات الحديثة (GPU)، فإن هذا البرنامج قادر على إجراء عمليات محاكاة مونت كارلو (MC) بسرعة مذهلة، وعادةً ما تكون أسرع بمئات إلى آلاف المرات من محاكاة واحدة. - تنفيذ MC القائم على وحدة المعالجة المركزية (CPU).
تمت كتابة MCX بلغة C وNVIDIA CUDA. يتم تنفيذه فقط على وحدات معالجة الرسومات NVIDIA. إذا كنت تريد تشغيل عمليات محاكاة MCX المسرَّعة بالأجهزة على وحدات معالجة الرسومات أو وحدات المعالجة المركزية AMD/Intel، فيرجى تنزيل MCX-CL (MCX for OpenCL)، المكتوب بلغة OpenCL. MCX وMCX-CL متوافقان للغاية.
نظرًا لطبيعة خوارزميات MC الأساسية، فإن MCX وMCX-CL هما برنامجان لتتبع الشعاع/صب الشعاع تحت الغطاء. بالمقارنة مع مكتبات تتبع الأشعة الشائعة المستخدمة في رسومات الكمبيوتر أو محركات الألعاب، تتمتع MCX-CL وMCX بالعديد من الخصائص الفريدة. الفرق الأكثر أهمية هو أن MCX/MCX-CL تعتمد بشكل صارم على القوانين الفيزيائية. إنهم عبارة عن حلول رقمية لمعادلة النقل الإشعاعي الأساسية (RTE) وقد تم التحقق من صحة حلولهم عبر العديد من المنشورات باستخدام الأدوات البصرية والقياسات التجريبية. بالمقارنة، يتعين على معظم أجهزة تتبع الشعاع الموجهة للرسومات إجراء العديد من التقديرات التقريبية من أجل تحقيق عرض سريع، وتمكين تقديم نتائج محاكاة ضوئية دقيقة من الناحية الكمية. ولهذا السبب، تم استخدام MCX/MCX-CL على نطاق واسع من قبل مجتمعات أبحاث الضوئيات الحيوية للحصول على حلول مرجعية وتوجيه تطوير أنظمة التصوير الطبي الجديدة أو التطبيقات السريرية. بالإضافة إلى ذلك، فإن MCX/MCX-CL عبارة عن أجهزة تتبع شعاع حجمية؛ إنهم يجتازون أشعة الفوتون عبر مجالات ثلاثية الأبعاد معقدة ويحسبون كميات ذات معنى ماديًا مثل التدفق المكاني، والتدفق، والانعكاس/النفاذية المنتشرة، وترسب الطاقة، وأطوال المسارات الجزئية، من بين أشياء أخرى كثيرة. في المقابل، فإن معظم محركات تتبع الشعاع الرسومية تقوم فقط بتتبع لون RGB للشعاع وعرضه على شاشة مسطحة ثنائية الأبعاد. بمعنى آخر، يوفر MCX/MCX-CL توزيعات ضوئية ثلاثية الأبعاد دقيقة فعليًا بينما تركز أجهزة تتبع الأشعة الرسومية على العرض ثنائي الأبعاد للمشهد في الكاميرا. ومع ذلك، فإنها تشترك في العديد من أوجه التشابه، مثل حساب مسيرة الشعاع، وتسريع وحدة معالجة الرسومات، ومعالجة التشتت/الامتصاص وما إلى ذلك.
تم تفصيل خوارزمية هذا البرنامج في المراجع [Fang2009، Yu2018، Yan2020]. يتضمن ملخص قصير للميزات الرئيسية ما يلي:
يمكن استخدام هذا البرنامج على أنظمة التشغيل Windows وLinux وMac OS. تمت كتابة MCX بلغة C/CUDA ويتطلب وحدات معالجة الرسومات NVIDIA (لا يزال دعم وحدات المعالجة المركزية AMD/Intel/وحدات معالجة الرسومات عبر ROCm قيد التطوير). تم الإعلان عن تنفيذ OpenCL أكثر قابلية للحمل لـ MCX، أي MCXCL، في يوليو 2012 ويدعم تقريبًا جميع نماذج 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 القديمة مثل Kepler (GTX-730, sm_35 ). يمكن تشغيل جميع ثنائيات MCX مباشرة على الأجيال القادمة من وحدات معالجة الرسومات NVIDIA دون الحاجة إلى إعادة ترجمتها، وبالتالي فهي متوافقة مع الإصدارات المستقبلية.
في صفحة الويب أدناه، قمنا بتلخيص اختلافات السرعة بين الأجيال المختلفة لوحدات معالجة الرسومات NVIDIA
https://mcx.space/gpubench/
بالنسبة لعمليات المحاكاة ذات الأحجام الكبيرة، يلزم وجود ذاكرة رسومات كافية أيضًا لإجراء المحاكاة. الحد الأدنى من ذاكرة الرسومات المطلوبة لمحاكاة MC هو Nx*Ny*Nz بايت لبيانات الأنسجة المدخلة بالإضافة إلى Nx*Ny*Nz*Ng*4*2 بايت لبيانات التدفق/التدفق الناتج - حيث Nx,Ny,Nz هي أبعاد حجم الأنسجة، Ng هو عدد البوابات الزمنية المتزامنة، 4 هو حجم رقم الفاصلة العائمة ذو الدقة الواحدة، 2 للذاكرة الإضافية اللازمة لضمان دقة الإخراج (#41). لا يتطلب MCX دعمًا مزدوج الدقة في أجهزتك.
يقوم MCX بتخزين الخصائص البصرية ومواقع الكاشف في الذاكرة الثابتة. عادةً ما توفر وحدات معالجة الرسومات NVIDIA حوالي 64 كيلو بايت من الذاكرة الثابتة. ونتيجة لذلك لا نستطيع إلا أن يكون العدد الإجمالي للخصائص الضوئية بالإضافة إلى عدد الكاشفات لا يمكن أن يتجاوز 4000 (4000 * 4 * 4 = 64 ك).
بالإضافة إلى ذلك، يقوم MCX بتخزين بيانات الفوتون المكتشفة داخل الذاكرة المشتركة، والتي تتراوح أيضًا بين 42 كيلو بايت إلى 100 كيلو بايت لكل معالج تيار عبر أجيال GPU المختلفة. إذا كان المجال الخاص بك يحتوي على العديد من أنواع الوسائط، فمن الممكن أن يتجاوز تخصيص الذاكرة المشتركة الحد الأقصى. ستتلقى أيضًا خطأ "نفاد الذاكرة".
لتثبيت MCX، تحتاج إلى تنزيل الملف الثنائي القابل للتنفيذ الذي تم تجميعه لبنية الكمبيوتر لديك (32 أو 64 بت) والنظام الأساسي، واستخراج الحزمة وتشغيل الملف القابل للتنفيذ ضمن دليل {mcx root}/bin .
بالنسبة لمستخدمي Windows، يجب عليك التأكد من تثبيت برنامج تشغيل NVIDIA المناسب لوحدة معالجة الرسومات الخاصة بك. يجب عليك أيضًا تكوين نظام التشغيل لديك لتشغيل عمليات محاكاة CUDA. يتطلب هذا منك فتح المجلد mcx/setup/win64 باستخدام مستكشف الملفات، ثم النقر بزر الماوس الأيمن على ملف apply_timeout_registry_fix.bat وتحديد "تشغيل كمسؤول" . بعد التأكيد، يجب أن تشاهد نافذة أوامر 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 (iGPU) للعرض مع ترك وحدة معالجة الرسومات NVIDIA الخاصة بك مخصصة للحوسبة باستخدام 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
أو اختر أحد الأساليب الأربعة الأخرى في منشور المدونة هذا
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
لاحظنا أنه عند تشغيل Ubuntu Linux 22.04 بنواة 6.5 على جهاز كمبيوتر محمول مزود بوحدة معالجة رسومات هجينة مع Intel iGPU ووحدة معالجة الرسومات NVIDIA، يجب عليك تكوين الكمبيوتر المحمول لاستخدام وحدة معالجة الرسومات NVIDIA كوحدة معالجة الرسومات الأساسية عن طريق اختيار "NVIDIA (وضع الأداء)" في قسم ملفات تعريف PRIME في إعدادات خادم NVIDIA X. يمكنك أيضًا الركض
sudo prime-select nvidia
لتحقيق نفس الهدف. وإلا، فقد تؤدي المحاكاة إلى تعليق نظامك بعد تشغيله لبضع ثوانٍ. لا يبدو أن الكمبيوتر المحمول المختلط المزود بوحدة معالجة الرسومات (GPU) الذي يجمع بين وحدة معالجة الرسومات NVIDIA ووحدة معالجة الرسوميات AMD iGPU يواجه هذه المشكلة في حالة استخدام Linux.
بالإضافة إلى ذلك، يحتوي برنامج تشغيل NVIDIA (الإصدار 520 أو الأحدث) على خلل معروف يعمل على Linux kernel 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
وذلك بسبب فشل إعادة تحميل وحدة kernel 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. سيتعين عليك استخدام إصدار OpenCL من MCX، MCX-CL عن طريق تنزيله من
https://mcx.space/wiki/?Learn#mcxcl
لتشغيل محاكاة، الحد الأدنى للإدخال هو ملف تكوين (نص)، وإذا كان ملف الإدخال لا يحتوي على أوصاف شكل مجال مضمنة، فإن ملف حجم خارجي (ملف ثنائي بتنسيق فوكسل محدد عبر -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 ) وتشغيل 16384 سلسلة عمليات GPU ( -t ) مع كل 64 سلسلة ترابط في كتلة ( -T ); تمت محاكاة إجمالي 1e7 فوتونات ( -n ) بواسطة وحدة معالجة الرسومات الأولى ( -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. يرجى الرجوع إلى القسم الخامس للحصول على التفاصيل.
يتم تحديد معلمة بوابة الوقت بثلاثة أرقام: وقت البدء ووقت الانتهاء وحجم خطوة الوقت (بالثواني). في المثال أعلاه، يحدد التكوين نافذة زمنية إجمالية تبلغ [0 1] ns، بدقة تبلغ 0.1 ns. وهذا يعني أن إجمالي عدد البوابات الزمنية هو 10.
يوفر MCX خيارًا متقدمًا، -g، لتشغيل عمليات المحاكاة عندما تكون ذاكرة وحدة معالجة الرسومات محدودة. وهو يحدد عدد البوابات الزمنية التي سيتم محاكاتها بشكل متزامن. قد يرغب المستخدمون في تحديد هذا العدد إلى أقل من العدد الإجمالي المحدد في ملف الإدخال - وبشكل افتراضي يتم تشغيل بوابة واحدة في كل مرة في محاكاة واحدة. ولكن إذا كانت هناك ذاكرة كافية بناءً على متطلبات الذاكرة في القسم الثاني، فيمكنك محاكاة جميع البوابات الزمنية العشرة (من المثال أعلاه) بشكل متزامن باستخدام -g 10 وفي هذه الحالة عليك التأكد من أن بطاقة الفيديو تحتوي على 60*60 على الأقل *60*10*5=10 ميجابايت من الذاكرة الحرة. إذا لم تقم بتضمين -g ، فسوف يفترض MCX أنك تريد محاكاة بوابة زمنية واحدة فقط في كل مرة.. إذا قمت بتحديد رقم بوابة زمنية أكبر من العدد الإجمالي في ملف الإدخال، (على سبيل المثال، -g 20 ) سوف تتوقف MCX عند اكتمال البوابات الزمنية العشرة. إذا كنت تستخدم وضع الطيار الآلي ( -A )، فسيتم تقدير بوابات الوقت تلقائيًا لك.
بدءًا من الإصدار 0.7.9، يقبل MCX ملف إدخال بتنسيق JSON بالإضافة إلى تنسيق الإدخال التقليدي الذي يشبه tMCimg. JSON (JavaScript Object Notation) هو تنسيق نصي محمول يمكن قراءته و"خالي من الدهون" لتمثيل البيانات المعقدة والهرمية. يؤدي استخدام تنسيق 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
