-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.txt
1705 lines (1473 loc) · 91.1 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---------------------------------------------------------------------
= Monte Carlo eXtreme (MCX) =
CUDA Edition
---------------------------------------------------------------------
*Author: Qianqian Fang <q.fang at neu.edu>
*License: GNU General Public License version 3 (GPLv3)
*Version: 2.0 (v2023, Heroic Hadron)
*Website: http://mcx.space
---------------------------------------------------------------------
Table of Content:
<toc>
---------------------------------------------------------------------
== # What's New ==
MCX v2023 is a milestone release since v2020 released 3 years ago. It contains all
the new features introduced in the two previous unofficial releases, v2022.10 and v2021.2,
along with extensive continuous integration (CI) development and numerous bug fixes.
Specifically, MCX v2023 officially ships a major new feature - split-voxel MC (SVMC),
published in Biomedical Optics Express by Shijie Yan and Qianqian Fang, see
[https://www.osapublishing.org/boe/abstract.cfm?uri=boe-11-11-6262 Yan2020] for details.
Shortly, SVMC provides a level of accuracy close to mesh-based MC (MMC) in modeling
curved boundaries but it is 4x to 6x faster than MMC. Several demo scripts of SVMC
can be found in the MCXLAB package under examples/demo_svmc_*. In addition, MCX v2023
supports '''GPU-based polarized light simulation''', see our JBO paper
[https://doi.org/10.1117/1.JBO.27.8.083015 Yan2022]. Moreover, an '''"RF replay"'''
algorithm was implemented by Pauliina Hirvi et al. to create frequency-domain (RF)
Jacobians for both amplitude and phase components. Please read the details in
[Hirvi2023](https://iopscience.iop.org/article/10.1088/1361-6560/acd48c). This release
also includes both the web-client and server scripts for MCX Cloud - an in-browser MC
simulator as we reported in [https://doi.org/10.1117/1.JBO.27.8.083008 Fang2022]. Lastly, MCX
v2023 provides an official Python mcx module ('''pmcx''') to run stream-lined MCX simulations
in Python, offering mcxlab-like interface.
Starting in MCX v2023, we have completed the migration from MCX-specific binary output
formats (.mc2/.mch) to human-readable, extensible and future-proof JSON-based portable
data formats defined by the [NeuroJSON](https://neurojson.org) project. The NeuroJSON
project aims at simplify scientific data exchange using portable data formats that are
readable, searchable, shareable, can be readily validated and served in the web and cloud.
The NeuroJSON project is also led by MCX's author, Dr. Qianqian Fang, funded by the
US NIH U24-NS124027 grant.
As a result of this migration, the MCX executable's default output formats are now
`.jnii` for volumetric output data, and `.jdat` for detected photon/trajectory data.
Both data formats are JSON compatible. Details on how to read/write these data files
can be found below.
In summary, v2023 is packed with exciting updates, including
* Introduced Split voxel MC (SVMC) to accurately model curved boundaries
* GPU polarized light modeling (Stokes) with 900x speedup
- RF replay to build frequency-domain Jacobians for amplitude and phase
* Web-based MCX Cloud platform including web-client and server scripts
* pymcx - an mcxlab-like Python module for running MCX simulations in Python
* Added Debian/Ubuntu packages for easy installation
* Added a unified command line interface, photon, to call mcx/mcxcl/mmc
* Fine-tuned Windows installer
* Extensively developed Github Action for automated building and packaging of mcx
* Adopted standardized NeuroJSON JNIfTI and JData formats to ease data exchange
A detailed list of updates is summarized below (key features marked with “*”):
Updates since v2022.10:
* 2023-08-07 [ac893cd] * mcxplotvol: allow keeping x/y/z slice when switching between 4th dimension
* 2023-08-07 [9aaba97] fix photon sharing 0 output issue in negative patterns
* 2023-08-05 [da0beda] padding -0 instead of 0 when saving dref with mua_float medium
* 2023-08-04 [82367f0] simplify dref/flux separation
* 2023-08-04 [97fff3e] update zmatlib, use miniz, drop zlib for easy deployment
* 2023-08-03 [4fbb4d6] bump pmcx version to 0.0.14
* 2023-08-03 [aaedf35] handle mirror bc in the reflection code
* 2023-08-03 [198cd34] * initial support of negative source and negative-patterns some test still fails, but feature is mostly working, need more work
* 2023-07-27 [081c382] parse outputtype in json2mcx
* 2023-07-21 [87167cb] simplify mua->0 approximation, drop high order term, #164
* 2023-07-21 [f063fd6] disable macos runner, macos no longer supports CUDA see https://github.com/actions/runner-images/discussions/7838
* 2023-07-21 [3067a26] fix incorrect handling of near-zero mus, fix #174, fix test
* 2023-06-30 [ac06b05] CI: compress with upx on Linux
* 2023-06-29 [527a5cc] add header, format with black, update action runners, #172
* 2023-05-21 [540931d] * support trajectory-only mode with debuglevel=T
* 2023-05-20 [0100212] * mcxplotphotons: plotting photon tracks with patch and show weights
* 2023-05-20 [615af1b] avoid recursion and segfault when resetting device
* 2023-05-16 [c327541] add demo to build RF Jacobians using replay, by Pauliina Hirvi
* 2023-05-05 [bd44f65] reformat pmcx python units with black
* 2023-05-05 [c12310b] added cwdref function to compute CW diffuse reflectance
* 2023-05-05 [0bd643e] added detweight function (using only numpy) to the utils.py in pmcx
* 2023-05-04 [31c0fa3] fix incorrect stat.unitinmm output
* 2023-04-29 [0c6b358] use svg vector graphs in mcxlab tutorial
* 2023-04-29 [bed8f08] Update plots with GPU runtime outputs
* 2023-04-29 [688ac78] Support mcxlabcl for non-GPU runtime on colab, add srctype tutorial
* 2023-04-28 [4f53e12] add examples on getting trajectory data
* 2023-04-27 [f271501] Update mcxlab jupyter notebook based tutorial
* 2023-04-27 [be5a420] * add jupyter-notebook based mcxlab tutorial
* 2023-04-26 [eb68720] make static linking default on Windows
* 2023-04-25 [e315dfe] fix incorrect comment regarding gaussian src, fix #165
* 2023-04-16 [b78c4e3] fix inaccurate output unit for energy output time
* 2023-04-15 [2fd3594] accept jobs submitted from https://mcx.space/cloud
* 2023-04-15 [7515611] * fix mcxcloud job max duration bug, kill runtime>1min
* 2023-04-13 [70b3b5e] Add photon replay demo codes for pmcx in jupyter notebook
* 2023-04-13 [855aa40] pmcx: support photon replay, accept detphotons input
* 2023-04-13 [8a49fe3] switch from cmake back to Makefile
* 2023-04-01 [c2591aa] ask cmake to create Makefile
* 2023-03-22 [67d1128] add pmcx jupyter notebook tutorial
* 2023-03-22 [291adf5] allow mus=0, avoid unnecessary casting of scalars to double
* 2023-03-17 [3a4f7ed] fix fluence for mua -> 0
* 2023-03-15 [46b4311] remove explicit dependency to GLScene in mcxstudio
* 2023-03-10 [193158c] make volume rendering window available on main gui
* 2023-03-10 [2d09e54] allow Open project dialog to also load nii and jnii files for rendering
* 2023-03-09 [63a626d] fix progress bar stalling when setting cfg.issavedet to 3
* 2023-03-08 [8cab50f] add descriptions on how to start mcxstudio on an Mac, fix #162
* 2023-03-08 [da49503] allow early termination if -d 3 or cfg.issavedet=3 is set
* 2023-03-04 [5d4d3c6] transition from openjdata.org to neurojson.org, fix #161
* 2023-03-02 [3c29fa5] * mcxstudioL: loading and rendering jnifti based volume file
* 2023-03-01 [b99f9a9] mcxstudioL: loading portable JSON/JNIFTI based MCX output data files
* 2023-02-09 [32e3aef] fix RF replay in mcx binary, allow tweaking replay Jacobian for Born approx
* 2023-02-05 [9abd3f3] * adding additional native python pmcx functions
* 2023-02-05 [63b80f4] add missing pmcx file
* 2023-02-05 [e77ff2f] allow pmcx to use mixed binary extension and native function
* 2023-02-01 [d9b2f2b] * fix unmatched unit for RF replay, thanks to Pauliina Hirvi
* 2023-02-01 [ce2a65c] add the l/length option in help info
* 2023-02-01 [e67feed] support outputtype=length/l for saving total path lengths per voxel
* 2023-01-25 [4344574] fix windows compilation error
* 2023-01-25 [a7ce222] permit 3D plotting of DMMC output double-precision nii files
* 2023-01-22 [cdabf68] automatically replace RCS keywords in pmcx action
* 2023-01-22 [e527f4b] fix incomplete handling bc and isreflect setting combinations, fix #160
* 2023-01-20 [daa1dea] use standard CFLAGS and CPPFLAGS in compilation, remove --std99 error for g++
* 2023-01-11 [def38f6] Merge pull request #159 from matinraayai/master
* 2023-01-11 [e077f86] Bump pmcx version to 0.0.7.
* 2023-01-10 [7af2ea2] bump pmcx version to 0.0.6
* 2023-01-10 [820ce88] build macos binary wheels
* 2023-01-09 [4f969d1] Removed the macOS builder VM.
* 2023-01-09 [dd47cda] Updated README.md for pmcx.
* 2023-01-09 [82ef430] Final version.
* 2022-12-08 [eb9322f] Added Windows Wheel building job + fixed compilation errors for windows.
* 2022-11-18 [d5a9beb] Update build_linux_manywheel.yml
* 2022-11-18 [816c55f] Added Github workflow.
* 2022-10-15 [084ffc1] update cmake file and remove zmat from pymcx and mex
* 2022-10-14 [04000e2] remove zmatlib and ubj as dependency to mex and oct
* 2022-10-14 [d033520] fix negative respin number bug
* 2022-10-13 [ec4a29d] update version strings
* 2022-10-13 [a3fe4ce] remove warning on replay output
* 2022-10-10 [660dd31] update three.js to r145, fix volume render, fix thumbnail
Updates since v2021.2:
* 2022-10-08 [eaedca7] update installer to 2022.10
* 2022-10-08 [c31a0e2] update mcx version number to v2022.10
* 2022-10-05 [dc42951] prevent nan where log(rand) is calculated
* 2022-10-05 [63ffc1e] fix nan in detected photon data when using hyperboloid src, see https://groups.google.com/g/mcx-users/c/vyfHbzEO-0M/m/JzlpEZ3TBwAJ
* 2022-09-07 [e281f3e] allow to preview continuously varying medium (4D cfg.vol)
* 2022-08-19 [10330ef] fix windows compilation error
* 2022-08-17 [bbb4425] prevent zero-valued mus creating nan, #133
* 2022-08-12 [51f42f5] fix mcxlab log printing caused by commit f3beb75a
* 2022-08-12 [7058785] Lambertian launch for all focusable sources when focal-length is -inf
* 2022-07-28 [6d64c0b] fix incorrect flag for skipvoid
* 2022-06-27 [3d4fb26] partially fix rf replay
* 2022-06-04 [8af3631] fix line source
* 2022-05-22 [149b1ef] make code compile on windows
* 2022-05-20 [e87bb49] use consistent file naming convention, remove outdated units
* 2022-05-20 [45d84d3] complete reformat source code using astyle, always run make pretty before committing
* 2022-05-20 [aff8ff0] add source code formatting option
* 2022-05-20 [f3beb75] use MATLAB_MEX_FILE to determine container environment
* 2022-05-18 [1295024] fix incorrect trajectory id, fix #147
* 2022-05-18 [ccd2deb] fix macro condition
* 2022-05-18 [6f4ee88] use MCX_CONTAINER and env macros to replace extra PYMCX_CONTAINER
* 2022-05-16 [6fa1580] avoid using clear all and ~ in return value
* 2022-05-16 [21f9bd7] merge changes with @ShijieYan's svmc fix
* 2022-05-16 [8b2740f] debugging svmc crashes
* 2022-05-16 [7582a6e] fix svmc issue after patch f8da832f11b751c07d33c77dd7d428a2c75a888b
* 2022-05-15 [188ac2a] Added Pybind11's license info to README.md.
* 2022-05-15 [86529cf] Added PYMCX_CONTAINER compilation macro. Added support for extracting MCX_ERRORs like Mex + author fix.
* 2022-05-15 [b58ad88] Renamed gpu_info to gpuinfo for consistency.
* 2022-05-15 [0582974] changed issaveref to accept ints.
* 2022-05-15 [1cf1b3b] Added py::value_error handling + additional error checking for volume assurance.
* 2022-05-15 [7df8938] Added better + more informative exception handling for pymcx.
* 2022-05-15 [6a741e8] Changed reinterpret_casts to direct object construction + added the stat dict to the output dict + defined PYBIND11_DETAILED_ERROR_MESSAGES for easier debugging.
* 2022-05-15 [e4547ba] add pybind11 as submodule to build pymcx
* 2022-05-13 [f8da832] fix cyclic bc demo and srctype demo error, svmc still not working
* 2022-05-13 [4bd3974] report register counts on sm_60 using nvcc --ptxas-options=-v
* 2022-05-13 [e8f6a2d] fix cfg.unitinmm does not exist error
* 2022-05-13 [447975f] complete dda ray-marching, cube60 benchmark gain 40% speed, others are similar
* 2022-05-12 [b873f90] add integer voxel indices to avoid nextafter
* 2022-05-11 [32d46cd] merge additional updates from mcxcl version of json2mcx, #139
* 2022-05-11 [3d6d7df] fix bugs in json2mcx, #139
* 2022-05-08 [3b1c320] Removed nlhs argument left from Matlab.
* 2022-05-08 [61cc994] Fixed issue with std::cout and std::cerr flush.
* 2022-05-06 [d9793e9] Added working setup.py.
* 2022-05-03 [a3e47c8] Minor fix.
* 2022-05-02 [c9bedd6] Moved validate_config.
* 2022-05-02 [5427ece] Working prototype with different volume configs.
* 2022-05-02 [739b7ea] Moved some stuff to interface-common.cpp.
* 2022-05-02 [d852a87] Minor bug fixes.
* 2022-05-01 [f4cd3c3] Added kwargs version of mcx.
* 2022-05-01 [baa5fdd] Skeleton is done.
* 2022-04-24 [e919716] Prints GPU info.
* 2022-04-23 [0c7b6a7] Working interface and CMakeLists.txt file.
* 2022-04-19 [c710c3c] update ubj parser, update jnifti metadata
* 2022-04-15 [4033c54] mcxlab bug fix: digimouse atlas voxel size is 0.2mm, not 0.8mm
* 2022-04-15 [9b17eee] critical bug fix: digimouse atlas voxel size is 0.2mm, not 0.8mm
* 2022-03-31 [df6c311] Add viewing axis selection
* 2022-03-25 [04f1565] Add optimized isosurface rendering; add the ability to view cross-sectional slices of geometry
* 2022-03-23 [200decb] Remove testing files
* 2022-03-23 [e434553] Remove unnecessary variable
* 2022-03-22 [ebd5bee] update ubj to support BJData Draft 2, add JNIfTI _DataInfo_, fix #142
* 2022-03-21 [6de0855] Enable event-based repainting; re-add shader refinement, remove animation frame bugs; remove unnecessary shader branches and discards
* 2022-03-19 [7ef65a8] Added event-based repainting; shader optimizations
* 2022-03-05 [a93f6fa] save user info in local storage to avoid retyping
* 2022-03-05 [34d9afa] fix SaveDataFlag invisible bug
* 2022-02-18 [f051314] add missing voxel unit
* 2022-02-03 [23bf5b2] lowering default photon number so it can be launched on most gpus
* 2022-01-31 [220d9c2] fix incorrect type for gsmatrix
* 2022-01-31 [28e20d6] fix windows vs warning
* 2022-01-29 [6a9ad2f] update mcx_utils to use the Mie interface
* 2022-01-29 [13679e9] fix compilation issue of mcx_mie.cpp using MSVC, close #138
* 2022-01-28 [d7daf57] manually resolve complaint in CUDA 9
* 2022-01-28 [e99edb2] update .travis.yml
* 2022-01-28 [533c8ce] manually add mcx_mie in Makefile
* 2022-01-28 [e56b5cb] improve complex arithmetic compatablity with MSVC
* 2022-01-27 [a0ed0e7] add Mie function modules into cmake
* 2022-01-27 [c350c67] seperate Mie scattering functions from mcx_utils.h
* 2022-01-27 [0d51bb7] add missing i detflag in command line
* 2022-01-27 [9b74e4b] fix: add save detector flag for Stokes vectors
* 2022-01-26 [077060a] use static_cast in mcxlab so that cfg.vol can be realloc in mcx_shapes
* 2022-01-26 [8503125] do not reset cfg.vol when rasterizing cfg.shapes
* 2022-01-26 [3f22070] fix normalization in multiple detector RF replay
* 2022-01-26 [cdfd468] apply normalization to both real and imaginary jacobain for RF replay
* 2022-01-26 [87a310e] one can use ~ to ignore fluence output in octave, not in matlab
* 2022-01-26 [d45f084] allow users to explicitly disable fluence output by accepting cfg.issave2pt
* 2022-01-25 [376a730] partial fix to RF Jacobian calculation, need verification
* 2022-01-25 [d6e2b9e] NaN value in mua_float and muamus_float signifies a 0-value voxel
* 2022-01-24 [c9f2ad9] force threejs version to avoid breaking update in R136
* 2022-01-14 [51483eb] add template specialization for polarized mode
* 2022-01-12 [3487dfe] update the example for the polarized MCX
* 2021-12-15 [b9e046a] fix out of bounds error due to limited precision of R_PI
* 2021-12-15 [3b10265] fix the built-in example to match the update in e5dfd78f28f31d710e02206cb2835aabcd4d5508
* 2021-12-15 [dbe17af] no Stoke vector output for unpolarized MCX simulation
* 2021-12-15 [99293dd] add sanity check for incident Stokes vector
* 2021-12-13 [f1537bd] no need to check constant memory usage in polarized mode
* 2021-12-13 [61281ae] use prop.g to return the anisotropy computed from Mie
* 2021-12-12 [3b0ecc0] fix #133, handling underflowing denorms in float to half conversion for muamus_float
* 2021-12-11 [979f691] Move scattering matrix from constant memory to global memory
* 2021-11-29 [5c13f4b] avoid divided by zero on windows cygwin gcc
* 2021-11-29 [ef57f4b] allow make double to compile
* 2021-11-28 [0c96fe8] accept JData styled NaN in the JSON input for srcdir
* 2021-11-26 [a4545a4] fix #131, mcxplotshapes now plots shapes with correct scale
* 2021-11-04 [2585471] making svmc matlab demos compatible with Octave 5
* 2021-11-03 [5976811] replace matlab-only function with more portable code
* 2021-11-01 [37e121c] update preprint version url
* 2021-10-21 [7a77bf7] display rendering frame rate
* 2021-10-18 [99592c1] fix: #114 improve robustness to unknown boundry conditions
* 2021-10-14 [1aa2922] feat: Add one-sheet hyperboloid gaussian beam
* 2021-10-07 [86d56c2] feat: output prop. along with det. photon profile
* 2021-10-07 [24f4698] fix: ensure the largest grid to be accumulated
* 2021-10-06 [e5dfd78] feat: Support target mus or musp in polarized MCX
* 2021-10-06 [ae9216d] remove old det photon data after a new simulation
* 2021-10-05 [8cb21b5] support downloading detected photon data in mcxcloud
* 2021-10-04 [81ff4b1] fix rf replay bugs reported by Pauliina Hirvi
* 2021-09-24 [833bf6a] Reorganize some kernel code to optimize SVMC speed
* 2021-09-20 [605c15f] Fix numerical error of intersection test in SVMC
* 2021-09-20 [392ee87] Reorder code to fix photon detection for SVMC
* 2021-09-07 [5c44c6e] fix trajectory saving buffer length bug
* 2021-08-20 [99ea2b6] avoid continuous mua/mus inputs be treated as 0-label if mua=mus=0
* 2021-08-01 [943197a] Reorder preprocessing code to allow detector in SVMC Mask detector voxels only after the volume has been fully prepared!
* 2021-07-27 [65359f7] avoid extra level of square brackets for Optode.Detector
* 2021-07-27 [6b2f074] accept 3-element param1
* 2021-07-27 [2633bfb] avoid param1 missing error if not present
* 2021-07-23 [192613b] fix offset of cylinder along the axis direction, close #119
* 2021-07-17 [fc0465d] add tutorial 2 link
* 2021-07-17 [8c72d17] restore accidentally removed analytics tag
* 2021-07-13 [566df5e] provide flags to help access the detp.jdat file
* 2021-07-12 [b97c0f6] return metadata when loading simulation from library
* 2021-07-12 [3be6603] add default tab in the direct link,return mcx error if failed
* 2021-07-12 [70fb2a7] fix mixlabel byte order
* 2021-07-11 [24df0c3] add comment on raw voxel binary data layout
* 2021-07-07 [53d7ac0] fix shared mem misalignment error, close #118
* 2021-07-06 [7f8a2ac] allow ArrayZipSize to accept 1x2 array
* 2021-07-05 [9b00fa3] fix initial tab
* 2021-07-05 [2737853] deep copy data.options to avoid script error
* 2021-07-05 [0398b95] fix several bug while recording utorials
* 2021-07-04 [f5974ed] add preprint link
* 2021-07-04 [5d21a0d] create mcx cloud tutorial, add link
* 2021-07-03 [df0a48b] support tab param in url to open default tab
* 2021-07-03 [4c3f240] link json in direct link, remove schema
* 2021-07-03 [da6595e] add newline to json file download
* 2021-07-03 [cc3c06d] fix X/Y/ZSlabs parsing, restore original schemas
* 2021-07-03 [7c5054d] internal normalization of srcdir
* 2021-07-02 [877e9fe] get user id and group at runtime
* 2021-07-02 [22d6ffe] fix X/Y/ZSlabs schemas
* 2021-07-01 [270bb7c] prepare for beta testing
* 2021-06-30 [4b6df28] rename mcxone to mcxcloud, add help info
* 2021-06-30 [66b77fb] partial fix of json2mcx.m conversion issues
* 2021-06-25 [c399efa] enable negative g value support
* 2021-06-23 [3c642ce] set maximum characters to read for fscanf, fix #117
* 2021-06-23 [606b3d1] handle empty detector array in json2mcx
* 2021-06-22 [b537143] give a warning if the output type is not jacobian in replay
* 2021-06-17 [363d2d8] support reading .jdat file for replay
* 2021-06-04 [7191ca3] make thumbnail the same size when updating
* 2021-06-04 [5a2e13e] add tab overflow control
* 2021-06-04 [59e6be2] layout adjustments
* 2021-06-04 [4b55c88] minor polishing
* 2021-06-03 [1c29578] fix regression
* 2021-06-03 [3aedee6] add LengthUnit, MediaFormat in schema, support number and string for DebugFlag/SaveDataMask
* 2021-06-03 [64c5dd0] fix unnecessary shared memory allocation related to invcdf
* 2021-06-03 [ebf1ea1] * support user-defined phase functions via cfg.invcdf, close #13
* 2021-06-03 [0731511] revert back to no restarting policy so that overtime jobs can be killed
* 2021-06-02 [4d2a891] process cache,fix fullname,fix job status,fix server-side limit,kill overtime job
* 2021-06-02 [a08d676] update the skinvessel benchmark
* 2021-06-02 [168db14] * feat: save Mie function outputs mus, g to a file
* 2021-06-02 [57a44c5] feat: Add anisotropy g as an output of Mie func.
* 2021-06-02 [7387394] finally fix crossdomain post, change jsonp to json,test simu lib edit
* 2021-06-01 [95c6e1d] test:use default BC for all polarizedMC benchmarks
* 2021-06-01 [98697de] Add a three-layer slab demo for polarizedMC
* 2021-06-01 [7d86804] Add visualization for polarized MC example(MATLAB)
* 2021-05-31 [7d82a51] fix: resolve valgrind complaint: uninit. values
* 2021-05-31 [d6c9743] Add outputs in mcx2json.m to support polarizedMC
* 2021-05-31 [5088678] Add an example for polarized MC
* 2021-05-31 [d3054fd] Add document for polarized MC in mcxlab
* 2021-05-31 [44e0e9c] fea: extend loadmch.m to load output Stokes vector
* 2021-05-31 [a51cb52] feat: support polarized MC in command line (JSON)
* 2021-05-30 [d7921fe] skip checklimit if json is directly loaded from lib
* 2021-05-30 [65870f5] gui fine adjustment,use hash to update runcount,enable restart on fail,permit mcxpub update
* 2021-05-30 [692adfb] fix broken link
* 2021-05-30 [7a159ab] merge css
* 2021-05-30 [55bb1ea] initial drag and drop support, not working
* 2021-05-30 [fc9ca38] add meta headers, other minor adjustments
* 2021-05-29 [96cf071] support embedding src pattern in the all-in-one json/jdata file
* 2021-05-28 [450462c] * Add document for functions used in polarized MC
* 2021-05-28 [cbc3340] Optimize Stokes vector computation
* 2021-05-28 [9bd2ce0] Remove redundant code in preprocessing
* 2021-05-28 [06a9c6b] fix: resolve nan results due to numerical error
* 2021-05-28 [d9d1d0a] rewrite some code to save computation
* 2021-05-28 [9195141] Add an example to show polarized photon simulation
* 2021-05-27 [2b87275] fix: rewrite code for better readability
* 2021-05-26 [d836c81] fix: correct formula for stokes parameter update
* 2021-05-25 [105d5a9] * feat: Add stokes parameter output in MCXLAB
* 2021-05-25 [87d8847] * feat: add polarized photon simulation
* 2021-05-23 [d398cc9] add simulation restrictions for initial public testing of mcx cloud
* 2021-05-23 [26536d3] feat: add preprocessing for polarized MC in mcxlab
* 2021-05-22 [f0975c5] * support ring/annulus shaped source via disk source
* 2021-05-21 [6ed9727] * support svmc in command line;add svmc example
* 2021-05-21 [3d0a793] reading 8-byte svmc volume format from input file
* 2021-05-20 [4010d99] move svmc repacking to mcx_preprocess
* 2021-05-20 [3214c1b] remove duplicated preprocessing codes in mcx and mcxlab,fix detbc bug in command line
* 2021-05-20 [54b0602] run batch of jobs in each call to fill all GPU devices
* 2021-05-20 [de9850c] * add -K short option and svmc mediatype
* 2021-05-19 [660a8b8] relocate db and workspace folder to non www-data accessible paths
* 2021-05-19 [64f3008] update acknowledgement list
* 2021-05-19 [c168a87] can update thumbnail, add credit links
* 2021-05-19 [b9361a1] update to mcxcloud scripts
* 2021-05-15 [cef630b] save volume in jdata format by default
* 2021-05-15 [c50f871] define Frequency in json file instead of Omega
* 2021-05-15 [b4e7b57] initial support RF mua Jacobian in replay, thx Ilkka Nissilä, formula based on Juha Heiskala PhD thesis p45
* 2021-05-10 [073b168] * mcxcloud initial preview at JBO hot-topics
* 2021-05-05 [5732e6a] update front and backends
* 2021-05-01 [ee3f88d] update and rename mcxcloudd and mcxserver.cgi
* 2021-05-01 [eac952d] fix cylinder schema, add footer
* 2021-04-14 [aaa1eab] add download, fix jsonp callback, render output volume
* 2021-04-10 [aaef1f3] draw 3d fluence,use orth camera,add cancel
* 2021-04-04 [4ab8105] add src rendering, fix material color
* 2021-04-02 [1ed5272] fix cylinder and layer object drawing bug
* 2021-04-02 [f4ba0b4] add md5 digest for each submitted json for cache lookup
* 2021-03-31 [2c55c3b] change basic tab name
* 2021-03-31 [3c466a1] now mcxcloud can render 3D volumes, float32 buffer only
* 2021-03-29 [b379b2b] initial support in rendering 3d volume, add schema to support jdata ND array
* 2021-03-28 [31345a1] support Domain.Volume to encode JData-formatted 3D array
* 2021-03-28 [9c2e8c7] rendering all shape types, bbx as dashed box,add tag based material color
* 2021-03-27 [9f6e82c] avoid repainting preview
* 2021-03-26 [5109d29] add normal material, add box, subgrid and cylinder
* 2021-03-25 [ad0b814] draw grid from Domain.Dim
* 2021-03-25 [9b0cf95] fine tune fonts, add big tab initial screen, add svg background, add funding info
* 2021-03-25 [77f8f7a] add three.js for 3d preview
* 2021-03-24 [4274c77] rename mcxcloud.txt to mcxcloud
* 2021-03-24 [dc25a87] * add mcx cloud service server and client files, partially working
* 2021-03-22 [f9bc07c] use tabs in mcxone, add jquery by default
* 2021-03-18 [d8b88e1] fix unwanted double-precision math functions
* 2021-03-11 [f6ce5bd] update variable and function name to follow the convention
* 2021-03-11 [ca2ce60] add example: comparison of surface diffuse reflectance between MC and Diffusion
* 2021-03-05 [bcbb324] change window sizes using 96dpi default setting
* 2021-03-05 [5c8d27f] fix Name shape object schema
* 2021-03-03 [02add69] * MCX json schema and json editor are working, added more Shapes objects
* 2021-03-01 [940d725] wrapping up json input import feature in mcxstudio
* 2021-02-28 [64d629c] parse src/detector, media and shape
Updates since v2020:
* 2021-02-27 [a3b8457]*open/import JSON input file in MCX Studio
* 2021-01-07 [9811c83] reorder the input data layout to match the change in preprocessing
* 2020-10-22 [991910e] add function comment and revert unnecessary changes
* 2020-10-22 [3343338]*add benchmarks from SVMC paper to mcxlab
* 2020-10-19 [de87cbf] resolve code alignment issue
* 2020-10-18 [5acd287] fix photon detection issue for SVMC mode (by Shijie Yan)
* 2020-10-18 [61dbf63] fix ray-tracing issue after the initial template implementation
* 2020-10-17 [fbb4f8c] initial implementation of template for SVMC mode (by Shijie Yan)
* 2020-10-08 [dad83c6] resolve conflict between two branches to elimate mismatch in demo_focus_mirror_bc.m
* 2020-10-08 [fb61782]*sync master branch into nuvox(SVMC) branch (by Shijie Yan)
* 2020-09-20 [75f08c5] remove empty depends
* 2020-09-20 [fa98229] fix incorrect dependency
* 2020-09-20 [d748d29] add octave package files for mcxlab and mcxtools
* 2020-09-16 [cf3b1f0] fix typo, change default exe path
* 2020-09-16 [15e9946]*fix warnings found by debian packaging at https://mentors.debian.net/package/mcx/
* 2020-09-16 [04bb0e7] add man pages for other binaries
* 2020-09-14 [aca9f97] remove additional debian packging warnings
* 2020-09-14 [ce4e341] add desktop icon files
* 2020-09-14 [eb0aa9f] allow new lines in string values in json
* 2020-09-14 [4b1301a] set default exe folder to /usr/libexec, fall back to ~/bin/
* 2020-09-14 [643e4a1]*add photon as unified cmd for mcx/mcxcl/mmc,polish for debian packaging
* 2020-09-14 [a67bc6d] updates to ease debian packaging
* 2020-09-08 [8983305] Inno Installer Setup paths and file details fixed
* 2020-09-07 [a6bc5a9] another attempt to fix #105
* 2020-09-07 [ca303dd] change default shortcut group name, fix #105
* 2020-09-06 [0313d4c] install mcxstudio to 64bit folder, close #105
* 2020-09-04 [37b4914] add demo script for mirror bc
* 2020-09-04 [e561890] make mcxplotvol work in matlab 2010 or earlier
* 2020-09-04 [9518cfa] handle mirror bc correctly, close #104
* 2020-09-04 [64896aa]*reset pattern center position following a failed launch, fix #103
* 2020-09-02 [5af2e76] fix -geometry 0x0 error, see https://forum.lazarus.freepascal.org/index.php?topic=40593.0
* 2020-09-01 [dd4be78] add cubesph60b to match example/benchmark2
* 2020-08-30 [971ffac] fix extended ascii letters
* 2020-08-29 [6eb9596] update mcxcreate.m, add mcxplotshapes.m to render json shapes
* 2020-08-29 [0199dad] clean up code and add comments for SVMC
* 2020-08-29 [94d55a7]*add mcxcreate, force mcxlab return one output
* 2020-08-28 [d917751] give an error for unsupported single dash option
* 2020-08-28 [093c9ba]*add pre-processing for SVMC mode
* 2020-08-28 [a79e116] add mode delphi in carbon unit
* 2020-08-27 [63e5a5f] handle det radii less than or equal to 0.5, fix #101
* 2020-08-27 [8f93ee2] fix make mex link error
* 2020-08-26 [65f0fe4] fix issrcfrom0 offset
* 2020-08-26 [79f9d70]*multiply voxelsize with det radius
* 2020-08-26 [d5c3c11] fix mcxpreview det radis issue, require srcpos and tend in mcxlab
* 2020-08-24 [1af5507] avoid error on mac
* 2020-08-24 [2fce8e5] add missing carbon unit for mac
* 2020-08-24 [6f11857] add command line option cheatsheet
* 2020-08-24 [5046de0] fix cmake command
* 2020-08-24 [cea663b] test cmake in travis
* 2020-08-24 [782b4a3] massive update of documentation
* 2020-08-24 [041e386] massive update to README to describe all output formats
Between 2020 and 2023, seven new journal papers have been published as the
result of this project, including [Yan2020]. Please see the full list at
http://mcx.space/#publication
* [Yan2020] Shijie Yan and Qianqian Fang* (2020), "Hybrid mesh and voxel based Monte Carlo
algorithm for accurate and efficient photon transport modeling in complex bio-tissues,"
Biomed. Opt. Express, 11(11) pp. 6262-6270.
* [Fang2022] Qianqian Fang, Shijie Yan, "MCX Cloud—a modern, scalable, high-performance
and in-browser Monte Carlo simulation platform with cloud computing," J. Biomed. Opt.
27(8) 083008, 2022
* [Yan2022] Shijie Yan, Steven L. Jacques, Jessica C. Ramella-Roman, Qianqian Fang,
"Graphics processing unit-accelerated Monte Carlo simulation of polarized light in
complex three-dimensional media," J. of Biomedical Optics, 27(8), 083015 (2022)
* [Zhang2022] Yuxuang Zhang, Qianqian Fang, "BlenderPhotonics – an integrated open-source
software environment for three-dimensional meshing and photon simulations in complex
tissues," J. of Biomedical Optics, 27(8), 083014 (2022)
* [RaayaiArdakani2022] Matin Raayai Ardakani, Leiming Yu, David R. Kaeli, Qianqian Fang,
"Framework for Denoising Monte Carlo Photon Transport Simulations Using Deep Learning,"
J Biomed Opt. 2022 May;27(8):083019. doi: 10.1117/1.JBO.27.8.083019
* [Yuan2021] Yaoshen Yuan, Shijie Yan, and Qianqian Fang*, "Light transport modeling in
highly complex tissues using the implicit mesh-based Monte Carlo algorithm,"
Biomed. Optics Express, 12(1), 147-161, (2021)
* [Hirvi2023] Hirvi P, Kuutela T, Fang Q, Hannukainen A, Hyvonen N, Nissilä I. Effects of
atlas-based anatomy on modelled light transport in the neonatal head. Phys Med Biol.
2023 May 11. doi: 10.1088/1361-6560/acd48c. PMID: 37167982.
---------------------------------------------------------------------
== # Introduction ==
Monte Carlo eXtreme (MCX) is a fast physically-accurate photon simulation
software for 3D heterogeneous complex media. By taking advantage of
the massively parallel threads and extremely low memory latency in a
modern graphics processing unit (GPU), this program is able to perform Monte
Carlo (MC) simulations at a blazing speed, typically hundreds to
a thousand times faster than a single-threaded CPU-based MC implementation.
MCX is written in C and NVIDIA CUDA. It only be executed on NVIDIA GPUs.
If you want to run hardware-accelerated MCX simulations on AMD/Intel GPUs
or CPUs, please download MCX-CL (MCX for OpenCL), which is written in OpenCL.
MCX and MCX-CL are highly compatible.
Due to the nature of the underlying MC algorithms, MCX and MCX-CL are
ray-tracing/ray-casting software under-the-hood. Compared to commonly
seen ray-tracing libraries used in computer graphics or gaming
engines, MCX-CL and MCX have many unique characteristics. The most
important difference is that MCX/MCX-CL are rigorously based on physical
laws. They are numerical solvers to the underlying radiative transfer equation
(RTE) and their solutions have been validated across many publications
using optical instruments and experimental measurements. In comparison,
most graphics-oriented ray-tracers have to make many approximations in
order to achieve fast rendering, enable to provide quantitatively accurate
light simulation results. Because of this, MCX/MCX-CL have been extensively
used by biophotonics research communities to obtain reference solutions and
guide the development of novel medical imaging systems or clinical
applications. Additionally, MCX/MCX-CL are volumetric ray-tracers; they
traverse photon-rays throughout complex 3-D domains and computes physically
meaningful quantities such as spatially resolved fluence, flux, diffuse
reflectance/transmittance, energy deposition, partial pathlengths,
among many others. In contrast, most graphics ray-tracing engines
only trace the RGB color of a ray and render it on a flat 2-D screen.
In other words, MCX/MCX-CL gives physically accurate 3-D light distributions
while graphics ray-tracers focus on 2-D rendering of a scene at the camera.
Nonetheless, they share many similarities, such as ray-marching computation,
GPU acceleration, scattering/absorption handling etc.
The algorithm of this software is detailed in the References
[Fang2009,Yu2018,Yan2020]. A short summary of the main features includes:
* 3D heterogeneous media represented by voxelated array
* support over a dozen source forms, including wide-field and pattern illuminations
* boundary reflection support
* time-resolved photon transport simulations
* saving photon partial path lengths and trajectories
* optimized random number generators
* build-in flux/fluence normalization to output Green's functions
* user adjustable voxel resolution
* improved accuracy with atomic operations
* cross-platform graphical user interface
* native Matlab/Octave support for high usability
* flexible JSON interface for future extensions
* multi-GPU support
* advanced features: photon-replay, photon-sharing, and more
This software can be used on Windows, Linux and Mac OS. MCX is written in C/CUDA
and requires NVIDIA GPUs (support for AMD/Intel CPUs/GPUs via ROCm is still
under development). A more portable OpenCL implementation of MCX, i.e. MCXCL,
was announced on July, 2012 and supports almost all NVIDIA/AMD/Intel CPU and GPU
models. If your hardware does not support CUDA, please download MCXCL from the
below URL:
http://mcx.space/wiki/index.cgi?Learn#mcxcl
---------------------------------------------------------------------------
== # Requirement and Installation ==
Please read this section carefully. The majority of failures using MCX were
found related to incorrect installation of NVIDIA GPU driver.
Please browse http://mcx.space/#documentation for step-by-step
instructions.
For MCX-CUDA, the requirements for using this software include
* a CUDA capable NVIDIA graphics card
* pre-installed NVIDIA graphics driver
You must install a CUDA capable NVIDIA graphics card in order to use
MCX. A list of CUDA capable cards can be found at [2]. The oldest
graphics card that MCX supports is the Fermi series (circa 2010).
Using the latest NVIDIA card is expected to produce the best
speed. You must have a fermi (GTX 4xx) or newer
(9xx/10xx/20xx/30xx/40xx series) graphics card. The default release
of MCX supports atomic operations and photon detection.
In the below webpage, we summarized the speed differences
between different generations of NVIDIA GPUs
http://mcx.space/gpubench/
For simulations with large volumes, sufficient graphics memory
is also required to perform the simulation. The minimum amount of
graphics memory required for a MC simulation is Nx*Ny*Nz
bytes for the input tissue data plus Nx*Ny*Nz*Ng*4 bytes for
the output flux/fluence data - where Nx,Ny,Nz are the dimensions of the
tissue volume, Ng is the number of concurrent time gates, 4 is
the size of a single-precision floating-point number.
MCX does not require double-precision capability in your hardware.
To install MCX, you need to download the binary executable compiled for your
computer architecture (32 or 64bit) and platform, extract the package
and run the executable under the <mcx root>/bin directory.
For Windows users, you must make sure you have installed the appropriate
NVIDIA driver for your GPU. You should also configure your OS to run
CUDA simulations. This requires you to open the mcx/setup/win64 folder
using your file explorer, right-click on the "apply_timeout_registry_fix.bat"
file and select "Run as administrator". After confirmation, you should
see a windows command window with message
<pre>
Patching your registry
Done
Press any key to continue ...
</pre>
You MUST REBOOT your Windows computer to make this setting effective.
The above patch modifies your driver settings so that you can run MCX
simulations for longer than a few seconds. Otherwise, when running MCX
for over a few seconds, you will get a CUDA error: "unspecified error".
Please see the below link for details
http://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
If you use Linux, you may enable Intel integrated GPU (iGPU) for display while
leaving your NVIDIA GPU dedicated for computing using `nvidia-prime`, see
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
or choose one of the 4 other approaches in this blog post
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
== # Running Simulations ==
To run a simulation, the minimum input is a configuration (text) file, and, if
the input file does not contain built-in domain shape descriptions, an external
volume file (a binary file with a specified voxel format via `-K/--mediabyte`).
Typing `mcx` without any parameters prints the help information and a list of
supported parameters, as shown below:
<pre>###############################################################################
# Monte Carlo eXtreme (MCX) -- CUDA #
# Copyright (c) 2009-2023 Qianqian Fang <q.fang at neu.edu> #
# http://mcx.space/ #
# #
# 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 #
###############################################################################
$Rev::e02c77$ v2023 $Date::2023-08-12 14:16:55 -04$ 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 [0|int|mch](--seed) set random-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
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-65535 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
-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://github.com/NeuroJSON/jnifti,
MATLAB/Octave: JSONLab toolbox https://github.com/NeuroJSON/jsonlab,
Python: PyJData: https://pypi.org/project/jdata
JavaScript: JSData: https://github.com/NeuroJSON/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
--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
</pre>
To further illustrate the command line options, below one can find a sample command
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
the command above asks mcx to manually (`-A 0`) set GPU threads, and launch 16384
GPU threads (`-t`) with every 64 threads a block (`-T`); a total of 1e7 photons (`-n`)
are simulated by the first GPU (`-G 1`) and repeat twice (`-r`) - i.e. total 2e7 photons;
the media/source configuration will be read from a JSON file named `input.json`
(`-f`) and the output will be labeled with the session id “test” (`-s`); the
simulation will run 10 concurrent time gates (`-g`) if the GPU memory can not
simulate all desired time gates at once. Photons passing through the defined
detector positions are saved for later rescaling (`-d`), and the saved photon
data include detector id (letter 'd' in -w), partial path (letter 'p' in -w)
and exit position (letter 'x' in -w); refractive index mismatch is considered
at media boundaries (`-b`).
Historically, MCX supports an extended version of the input file format (.inp)
used by tMCimg. However, we are phasing out the .inp support and strongly
encourage users to adopt JSON formatted (.json) input files. Many of the
advanced MCX options are only supported in the JSON input format.
A legacy .inp MCX input file looks like this:
<pre>
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
</pre>
Note that the scattering coefficient mus=musp/(1-g).
The volume file (semi60x60x60.bin in the above example),
can be read in two ways by MCX: row-major[3] or column-major
depending on the value of the user parameter "-a". If the volume file
was saved using matlab or fortran, the byte order is column-major,
and you should use "-a 0" or leave it out of the command line.
If it was saved using the fwrite() in C, the order is row-major,
and you can either use "-a 1".
You may replace the binary volume file by a JSON-formatted shape file.
Please refer to Section V for details.
The time gate parameter is specified by three numbers:
start time, end time and time step size (in seconds). In
the above example, the configuration specifies a total time
window of [0 1] ns, with a 0.1 ns resolution. That means the
total number of time gates is 10.
MCX provides an advanced option, -g, to run simulations when
the GPU memory is limited. It specifies how many time gates to simulate
concurrently (when the GPU does not have sufficient memory to simulate
all desired time gates all together). Users may want to limit that number
to less than the total number specified in the input file - and by default
it runs one gate at a time in a single simulation. But if there's
enough memory based on the memory requirement in Section II, you can
simulate all 10 time gates (from the above example) concurrently by using
"-g 10" in which case you have to make sure the video card has at least
60*60*60*10*5=10MB of free memory. If you do not include the -g,
MCX will assume you want to simulate just 1 time gate at a time..
If you specify a time-gate number greater than the total number in the
input file, (e.g, "-g 20") MCX will stop when the 10 time-gates are
completed. If you use the autopilot mode (-A), then the time-gates
are automatically estimated for you.
---------------------------------------------------------------------------
== # Using JSON-formatted input files ==
Starting from version 0.7.9, MCX accepts a JSON-formatted input file in
addition to the legacy .inp input files. JSON (JavaScript Object Notation)
is a portable, human-readable and "fat-free" text format to represent
complex and hierarchical data. Using the JSON format makes a input file
self-explanatory, extensible and easy-to-interface with other applications
(like MATLAB and Python).
A sample JSON input file can be found under the examples/quicktest
folder. The same file, qtest.json, is also shown below:
<pre>
{
"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
}
]
}
}
</pre>
A JSON input file requiers several root objects, namely "Domain", "Session",
"Forward" and "Optode". Other root sections, like "Help", will be ignored.
Each object is a data structure providing information