Binary Interface ================ This page documents the direct command-line usage of the generated ``calcPhiASE`` binary. For general setup and dependency information, see :doc:`Getting Started `. Compilation ----------- In order to use haseongpu from the command line, manual compilation is required. For compilation details see :doc:`compilation`. After compilation, the executable is available as: .. code-block:: text ./build/calcPhiASE Usage ----- The binary can be run directly with command-line options: .. code-block:: bash ./build/calcPhiASE [OPTIONS] Input data is provided through an experiment folder containing preprocessed input files. These files are typically generated by a MATLAB or Python workflow. Example ------- Under ``haseongpu/example/c_example/input``, two example meshes with already preprocessed input files are provided: * ``cuboid`` * ``cylindrical`` Single-node threaded run using the ``cylindrical`` example: .. code-block:: bash ./build/calcPhiASE \ --input-path=./example/c_example/input/cylindrical \ --output-path=/tmp/ \ --parallel-mode=threaded \ --device-mode=gpu \ --min-rays=10000 \ --max-rays=100000 \ --reflection \ --repetitions=4 \ --adaptive-steps=4 \ --ngpus=4 \ --min-sample-i=0 \ --max-sample-i=1234 \ --mse-threshold=0.05 MPI run with 4 GPUs per node using the same example: .. code-block:: bash mpiexec -npernode 4 ./build/calcPhiASE \ --input-path=./example/c_example/input/cylindrical \ --output-path=/tmp/ \ --parallel-mode=mpi \ --device-mode=gpu \ --min-rays=10000 \ --max-rays=100000 \ --reflection \ --repetitions=4 \ --adaptive-steps=4 \ --ngpus=1 \ --min-sample-i=0 \ --max-sample-i=1234 \ --mse-threshold=0.05 Command-Line Arguments ---------------------- ``--input-path`` ^^^^^^^^^^^^^^^^ Path to the experiment directory. This folder contains the input files required to run one experiment. These files are usually generated by a MATLAB or Python script. ``--output-path`` ^^^^^^^^^^^^^^^^^ Path to a writable output directory. This location is used to store generated output files. ``--device-mode=[cpu|gpu]`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Selects the hardware used for the simulation. * ``cpu`` uses the original single-core CPU algorithm * ``gpu`` uses NVIDIA CUDA GPUs ``--parallel-mode=[threaded|mpi]`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Selects the parallelization mode. * ``threaded`` uses pthreads on a single node * ``mpi`` uses MPI for distributed execution ``--min-rays=`` ^^^^^^^^^^^^^^^ Minimum number of rays used per sample point. ``--max-rays=`` ^^^^^^^^^^^^^^^ Maximum number of rays used per sample point. ``--ngpus=`` ^^^^^^^^^^^^ Maximum number of GPUs to use. In ``threaded`` mode, this is typically the number of GPUs available on the local node. In ``mpi`` mode, this is usually set to ``1``. ``--min-sample-i=`` ^^^^^^^^^^^^^^^^^^^ Index of the first sample point. Normally ``0``. ``--max-sample-i=`` ^^^^^^^^^^^^^^^^^^^ Index of the last sample point. Normally ``numberOfSample - 1``. ``--verbosity=`` ^^^^^^^^^^^^^^^^ Verbosity level interpreted as a bitmask. Multiple values can be combined. * ``0``: quiet * ``1``: error * ``2``: warning * ``4``: info * ``8``: statistics * ``16``: debug * ``32``: progress bar ``--reflection`` ^^^^^^^^^^^^^^^^ Enables reflections on the upper and lower surfaces of the gain medium. ``--mse-threshold=`` ^^^^^^^^^^^^^^^^^^^^ Target mean squared error used for adaptive and repetitive sampling. ``--repetitions=`` ^^^^^^^^^^^^^^^^^^ Maximum number of repetitions performed when the MSE threshold is not met. ``--adaptive-steps=`` ^^^^^^^^^^^^^^^^^^^^^ Number of adaptive steps between minimum and maximum ray count. Setting this to ``1`` disables adaptive stepping and uses only ``--min-rays``. ``--spectral-resolution=`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Resolution used for linear interpolation of the absorption and emission spectra. ``--write-vtk=`` ^^^^^^^^^^^^^^^^ Enables writing VTK output files for post-processing and visualization. When enabled, HASEonGPU creates a subdirectory named ``vtk`` inside the specified output directory and writes VTK files containing sampled result data, for example: * ``dndt_.vtk`` * ``phiase_.vtk`` * ``mse_.vtk`` * ``total_rays_.vtk`` Accepted values: * ``true`` / ``1``: enable VTK output * ``false`` / ``0``: disable VTK output Default: ``false`` ``--config=`` ^^^^^^^^^^^^^ Optional path to a configuration file containing ``key=value`` pairs matching the command-line parameters.