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 run using the ``cylindrical`` example: .. code-block:: bash ./build/calcPhiASE \ --input-path=./example/c_example/input/cylindrical \ --output-path=/tmp/ \ --parallel-mode=single \ --backend=Host_Cpu_CpuSerial \ --min-rays=10000 \ --max-rays=100000 \ --reflection=0 \ --repetitions=4 \ --adaptive-steps=4 \ --numDevices=1 \ --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 \ --backend=Host_Cpu_CpuSerial \ --min-rays=10000 \ --max-rays=100000 \ --reflection=0 \ --repetitions=4 \ --adaptive-steps=4 \ --numDevices=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. ``--backend=`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Type: ``str`` * Description: Selects the alpaka backend used for the simulation. For details on available runtime backends and backend naming, see the runtime selection section of :doc:`Backend Selection `. Backend names depend on the alpaka backends compiled into the binary and on the devices available on the machine where it is run. If ``--backend=`` is set to a string that does not match any available backend, ``calcPhiASE`` exits with an error and prints the backend names that can be selected by this binary. This is also a practical way to discover the valid runtime strings for a compiled binary. ``--parallel-mode=[single|mpi]`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Selects the parallelization mode. * ``single`` runs HASEonGPU on a single node * ``mpi`` uses MPI for distributed execution (run binary with mpiexec) ``--min-rays=`` ^^^^^^^^^^^^^^^ Minimum number of rays used per sample point. ``--max-rays=`` ^^^^^^^^^^^^^^^ Maximum number of rays used per sample point. ``--nDevices=`` ^^^^^^^^^^^^^^^^ Number of Devices HASEonGPU should use. On Cuda or Hip Platform this is equivalent to the number of Gpus the application should use (on a single node). In ``single`` 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. ``--monochromatic=`` ^^^^^^^^^^^^^^^^^^^^ Selects monochromatic or spectral propagation. When ``true``, HASEonGPU uses one constant absorption/emission cross-section pair, :math:`\sigma_a` and :math:`\sigma_e`, for the whole calculation. The values are read from ``sigmaA.txt`` and ``sigmaE.txt``. Wavelength files are ignored in this mode. When ``false``, HASEonGPU uses wavelength-dependent spectra: ``lambdaA.txt`` with ``sigmaA.txt`` for absorption and ``lambdaE.txt`` with ``sigmaE.txt`` for emission, representing :math:`\sigma_a(\lambda)` and :math:`\sigma_e(\lambda)`. These spectra are interpolated according to ``--spectral-resolution``. Accepted values: * ``true`` / ``1``: monochromatic calculation using one ``sigmaA``/``sigmaE`` pair * ``false`` / ``0``: spectral calculation using wavelength-dependent data Default: ``false`` ``--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.