Binary Interface

This page documents the direct command-line usage of the generated calcPhiASE binary.

For general setup and dependency information, see Getting Started.

Compilation

In order to use haseongpu from the command line, manual compilation is required.

For compilation details see Compilation.

After compilation, the executable is available as:

./build/calcPhiASE

Usage

The binary can be run directly with command-line options:

./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:

./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:

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_<timestamp>.vtk

  • phiase_<timestamp>.vtk

  • mse_<timestamp>.vtk

  • total_rays_<timestamp>.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.