mcx
v2024.2 (Interstellar Ion)
Tabela de conteúdo:
MCX v2024.2 contém novos recursos importantes e correções de bugs críticos. É uma atualização fortemente recomendada para todos os usuários.
Especificamente, o MCX v2024.2 recebeu três novos recursos importantes:
Semelhante ao recurso de função de fase definido pelo usuário incluído no MCX v2023, o primeiro recurso permite aos usuários definir a distribuição do ângulo zenital para lançar um fóton, em relação ao vetor de direção da fonte, também por meio de um CDF inverso discretizado (função de distribuição cumulativa) . No MATLAB/Octave, eles podem ser definidos como cfg.invcdf ou cfg.angleinvcdf , respectivamente. Fornecemos scripts de demonstração prontos para uso em mcxlab/examples/demo_mcxlab_phasefun.m e demo_mcxlab_launchangle.m .
O segundo recurso permite que os usuários especifiquem mais de uma fonte do mesmo tipo ao definir srcpos , srcdir , srcparam1 e srcparam2 . Cada fonte pode ter peso independente controlado pelo 4º elemento do srcpos.
Além dos novos recursos, foi descoberto um bug grave que afeta todas as simulações pattern e pattern3d que não usam compartilhamento de fótons, consulte
#212
Por causa desse bug, MCX/MCX-CL em versões mais antigas tem simulado dados de padrão quadrado/padrão3d em vez do próprio padrão. Se sua simulação usa esses dois tipos de fonte e você não usa compartilhamento de fótons (ou seja, simulando vários padrões juntos), atualize seu MCX/MCX-CL e execute novamente suas simulações. Este bug afeta apenas saídas volumétricas de fluência/fluxo; não afeta saídas de refletância difusa ou padrões binários.
Ele também inclui uma correção de bug do nº 195 em relação à perda de precisão ao salvar a refletância difusa.
Queremos agradecer a Haohui Zhang por relatar uma série de problemas críticos (#195 e #212), e a Liam Keegan por contribuir com um patch para estender a fonte da fenda (#214). ShijieYan e fanyuyen também contribuíram para correções de bugs e melhorias.
As atualizações detalhadas podem ser encontradas no log de alterações abaixo
Monte Carlo eXtreme (MCX) é um software de simulação de fótons rápido e fisicamente preciso para meios complexos heterogêneos 3D. Aproveitando os threads massivamente paralelos e a latência de memória extremamente baixa em uma moderna unidade de processamento gráfico (GPU), este programa é capaz de realizar simulações de Monte Carlo (MC) a uma velocidade incrível, normalmente centenas a mil vezes mais rápida do que um único. Implementação de MC baseada em CPU -threaded.
MCX é escrito em C e NVIDIA CUDA. Ele só pode ser executado em GPUs NVIDIA. Se você deseja executar simulações MCX aceleradas por hardware em GPUs ou CPUs AMD/Intel, baixe MCX-CL (MCX para OpenCL), que é escrito em OpenCL. MCX e MCX-CL são altamente compatíveis.
Devido à natureza dos algoritmos MC subjacentes, MCX e MCX-CL são softwares de rastreamento/casting de raios subjacentes. Em comparação com bibliotecas de rastreamento de raios comumente usadas em computação gráfica ou mecanismos de jogos, MCX-CL e MCX têm muitas características exclusivas. A diferença mais importante é que MCX/MCX-CL são rigorosamente baseados em leis físicas. Eles são solucionadores numéricos da equação de transferência radiativa subjacente (RTE) e suas soluções foram validadas em muitas publicações usando instrumentos ópticos e medições experimentais. Em comparação, a maioria dos traçadores de raios orientados a gráficos precisam fazer muitas aproximações para obter uma renderização rápida, permitindo fornecer resultados de simulação de luz quantitativamente precisos. Por causa disso, o MCX/MCX-CL tem sido amplamente utilizado por comunidades de pesquisa em biofotônica para obter soluções de referência e orientar o desenvolvimento de novos sistemas de imagens médicas ou aplicações clínicas. Além disso, MCX/MCX-CL são traçadores de raios volumétricos; eles atravessam raios de fótons por domínios 3-D complexos e calculam quantidades fisicamente significativas, como fluência espacialmente resolvida, fluxo, refletância/transmitância difusa, deposição de energia, comprimentos de caminho parciais, entre muitos outros. Em contraste, a maioria dos mecanismos gráficos de rastreamento de raios apenas rastreiam a cor RGB de um raio e a renderizam em uma tela plana 2D. Em outras palavras, o MCX/MCX-CL fornece distribuições de luz 3D fisicamente precisas, enquanto os traçadores de raios gráficos se concentram na renderização 2D de uma cena na câmera. No entanto, eles compartilham muitas semelhanças, como computação de marcha de raios, aceleração de GPU, manipulação de dispersão/absorção, etc.
O algoritmo deste software está detalhado nas Referências [Fang2009,Yu2018,Yan2020]. Um breve resumo dos principais recursos inclui:
Este software pode ser usado em Windows, Linux e Mac OS. MCX é escrito em C/CUDA e requer GPUs NVIDIA (o suporte para CPUs/GPUs AMD/Intel via ROCm ainda está em desenvolvimento). Uma implementação OpenCL mais portátil do MCX, ou seja, MCXCL, foi anunciada em julho de 2012 e suporta quase todos os modelos de CPU e GPU NVIDIA/AMD/Intel. Se o seu hardware não suportar CUDA, baixe o MCXCL no URL abaixo:
https://mcx.space/wiki/index.cgi?Learn#mcxcl
Por favor, leia esta seção com atenção. A maioria das falhas ao usar o MCX foram encontradas relacionadas à instalação incorreta do driver da GPU NVIDIA.
Navegue em https://mcx.space/#documentation para obter instruções passo a passo.
Para MCX-CUDA, os requisitos para usar este software incluem
Você deve certificar-se de que o driver gráfico NVIDIA foi instalado corretamente. Uma lista de placas compatíveis com CUDA pode ser encontrada em [2]. A arquitetura de GPU mais antiga em que o código-fonte MCX pode ser compilado é Fermi ( sm_20 ). Espera-se que o uso da placa NVIDIA mais recente produza a melhor velocidade. Os binários lançados oficialmente (incluindo arquivos mex e módulos pmcx ) podem ser executados em GPUs NVIDIA tão antigas quanto Kepler (GTX-730, sm_35 ). Todos os binários MCX podem ser executados diretamente em gerações futuras de GPUs NVIDIA sem a necessidade de recompilação, portanto, compatíveis com versões futuras.
Na página abaixo, resumimos as diferenças de velocidade entre diferentes gerações de GPUs NVIDIA
https://mcx.space/gpubench/
Para simulações com grandes volumes, também é necessária memória gráfica suficiente para realizar a simulação. A quantidade mínima de memória gráfica necessária para uma simulação MC é Nx*Ny*Nz bytes para os dados de tecido de entrada mais Nx*Ny*Nz*Ng*4*2 bytes para os dados de fluxo/fluência de saída - onde Nx,Ny,Nz são as dimensões do volume do tecido, Ng é o número de portas de tempo simultâneas, 4 é o tamanho de um número de ponto flutuante de precisão simples, 2 é para a memória extra necessária para garantir a precisão da saída (# 41). MCX não requer suporte de precisão dupla em seu hardware.
MCX armazena propriedades ópticas e posições de detectores na memória constante. Normalmente, as GPUs NVIDIA fornecem cerca de 64 KB de memória constante. Como resultado, só podemos o número total de propriedades ópticas mais o número de detectores não pode exceder 4.000 (4.000 * 4 * 4 = 64 k).
Além disso, o MCX armazena dados de fótons detectados dentro da memória compartilhada, que também varia entre 42 kB a 100 kB por processador de fluxo em diferentes gerações de GPU. Se o seu domínio contiver muitos tipos de mídia, é possível que a alocação da memória compartilhada exceda o limite. Você também receberá um erro de "memória insuficiente".
Para instalar o MCX, você precisa baixar o executável binário compilado para a arquitetura e plataforma do seu computador (32 ou 64 bits), extrair o pacote e executar o executável no diretório {mcx root}/bin .
Para usuários do Windows, você deve certificar-se de ter instalado o driver NVIDIA apropriado para sua GPU. Você também deve configurar seu sistema operacional para executar simulações CUDA. Isso requer que você abra a pasta mcx/setup/win64 usando seu explorador de arquivos, clique com o botão direito no arquivo apply_timeout_registry_fix.bat e selecione “Executar como administrador” . Após a confirmação, você deverá ver uma janela de comando do Windows com mensagem
Patching your registry
Done
Press any key to continue ...
Você DEVE REINICIAR seu computador Windows para tornar esta configuração efetiva. O patch acima modifica as configurações do driver para que você possa executar simulações MCX por mais de alguns segundos. Caso contrário, ao executar o MCX por mais de alguns segundos, você receberá um erro CUDA: “erro não especificado”.
Por favor, veja o link abaixo para detalhes
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
Se você usa Linux, você pode habilitar a GPU integrada Intel (iGPU) para exibição enquanto deixa sua GPU NVIDIA dedicada para computação usando nvidia-prime , consulte
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
ou escolha uma das outras 4 abordagens nesta postagem do blog
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
Percebemos que executando Ubuntu Linux 22.04 com kernel 6.5 em um laptop com GPU híbrida com Intel iGPU e GPU NVIDIA, você deve configurar o laptop para usar a GPU NVIDIA como GPU primária escolhendo "NVIDIA (Modo de desempenho)" na seção Perfis PRIME de Configurações do servidor NVIDIA X. Você também pode correr
sudo prime-select nvidia
para atingir o mesmo objetivo. Caso contrário, a simulação poderá travar seu sistema após funcionar por alguns segundos. Um laptop com GPU híbrida combinando uma GPU NVIDIA com um AMD iGPU não parece ter esse problema se estiver usando Linux.
Além disso, o driver NVIDIA (520 ou mais recente) tem uma falha conhecida ao executar no kernel Linux 6.x (como aqueles no Ubuntu 22.04). Ver
https://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153
Quando o laptop está no modo "desempenho" e sai da suspensão, o MCX ou qualquer programa CUDA falha ao executar com um erro
MCX ERROR(-999):unknown error in unit mcx_core.cu:2523
Isso ocorre porque o módulo do kernel nvida-uvm não pode ser recarregado após a suspensão. Se você teve uma sessão MATLAB aberta, você deve fechar o MATLAB primeiro e executar os comandos abaixo (se o MATLAB estiver aberto, você verá rmmod: ERROR: Module nvidia_uvm is in use )
sudo rmmod /dev/nvidia-uvm
sudo modprobe nvidia-uvm
após o comando acima, o MCX deverá poder ser executado novamente.
As novas gerações de computadores Mac não suportam mais GPUs NVIDIA ou AMD. você terá que usar a versão OpenCL do MCX, MCX-CL baixando-o em
https://mcx.space/wiki/?Learn#mcxcl
Para executar uma simulação, a entrada mínima é um arquivo de configuração (texto) e, se o arquivo de entrada não contiver descrições de formato de domínio integradas, um arquivo de volume externo (um arquivo binário com um formato voxel especificado via -K/--mediabyte ). Digitar mcx sem nenhum parâmetro imprime as informações de ajuda e uma lista de parâmetros suportados, conforme mostrado abaixo:
###############################################################################
# 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
Para ilustrar melhor as opções de linha de comando, abaixo pode-se encontrar um exemplo de comando
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
o comando acima pede ao mcx para definir manualmente ( -A 0 ) os threads de GPU e iniciar 16384 threads de GPU ( -t ) com cada 64 threads por bloco ( -T ); um total de 1e7 fótons ( -n ) são simulados pela primeira GPU ( -G 1 ) e repetidos duas vezes ( -r ) - ou seja, total de 2e7 fótons; a configuração de mídia/fonte será lida a partir de um arquivo JSON chamado input.json ( -f ) e a saída será rotulada com o id de sessão “test” ( -s ); a simulação executará 10 intervalos de tempo simultâneos ( -g ) se a memória da GPU não puder simular todos os intervalos de tempo desejados de uma vez. Os fótons que passam pelas posições definidas do detector são salvos para reescalonamento posterior ( -d ); a incompatibilidade do índice de refração é considerada nos limites da mídia ( -b ).
Historicamente, o MCX oferece suporte a uma versão estendida do formato de arquivo de entrada (.inp) usado pelo tMCimg. No entanto, estamos descontinuando o suporte .inp e incentivamos fortemente os usuários a adotarem arquivos de entrada formatados em JSON (.json). Muitas das opções avançadas do MCX são suportadas apenas no formato de entrada JSON.
Um arquivo de entrada legado .inp MCX se parece com isto:
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
Observe que o coeficiente de espalhamento mus=musp/(1-g).
O arquivo de volume ( semi60x60x60.bin no exemplo acima), pode ser lido de duas maneiras pelo MCX: row-major[3] ou column-major dependendo do valor do parâmetro do usuário -a . Se o arquivo de volume foi salvo usando matlab ou fortran, a ordem dos bytes é a coluna principal e você deve usar -a 0 ou deixá-lo fora da linha de comando. Se foi salvo usando fwrite() em C, a ordem é linha maior e você pode usar -a 1 .
Você pode substituir o arquivo de volume binário por um arquivo shape formatado em JSON. Consulte a Seção V para obter detalhes.
O parâmetro time gate é especificado por três números: hora de início, hora de término e tamanho do intervalo de tempo (em segundos). No exemplo acima, a configuração especifica uma janela de tempo total de [0 1] ns, com resolução de 0,1 ns. Isso significa que o número total de portões de tempo é 10.
MCX oferece uma opção avançada, -g, para executar simulações quando a memória da GPU é limitada. Ele especifica quantos intervalos de tempo serão simulados simultaneamente. Os usuários podem querer limitar esse número a menos do que o número total especificado no arquivo de entrada - e por padrão ele executa uma porta por vez em uma única simulação. Mas se houver memória suficiente com base no requisito de memória na Seção II, você pode simular todos os 10 intervalos de tempo (do exemplo acima) simultaneamente usando -g 10 Nesse caso, você deve garantir que a placa de vídeo tenha pelo menos 60*60 *60*10*5=10 MB de memória livre. Se você não incluir o -g , o MCX assumirá que você deseja simular apenas 1 portão de tempo por vez. Se você especificar um número de portão de tempo maior que o número total no arquivo de entrada, (por exemplo, -g 20 ) O MCX irá parar quando os 10 intervalos de tempo forem concluídos. Se você usar o modo de piloto automático ( -A ), os intervalos de tempo serão estimados automaticamente para você.
A partir da versão 0.7.9, o MCX aceita um arquivo de entrada formatado em JSON, além do formato de entrada convencional do tipo tMCimg. JSON (JavaScript Object Notation) é um formato de texto portátil, legível por humanos e “sem gordura” para representar dados complexos e hierárquicos. Usar o formato JSON torna um arquivo de entrada autoexplicativo, extensível e fácil de interagir com outros aplicativos (como MATLAB).
Um exemplo de arquivo de entrada JSON pode ser encontrado na pasta exemplos/teste rápido. O mesmo arquivo, qtest.json , também é mostrado abaixo:
{
"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
}
]
}
}
Um arquivo de entrada JSON requer vários objetos raiz, nomeadamente Domain , Session , Forward e Optode . Outras seções raiz, como Help , serão ignoradas. Cada objeto é uma estrutura de dados que fornece informações indicadas pelo seu nome. Cada objeto pode conter vários subcampos. As ordens dos campos do mesmo nível são flexíveis. Para cada campo, você sempre pode encontrar os campos equivalentes nos arquivos de entrada *.inp . Por exemplo, o campo VolumeFile no Domain
