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 run using the cylindrical example:

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

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 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, \(\sigma_a\) and \(\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 \(\sigma_a(\lambda)\) and \(\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_<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.