MATLAB Interface

This page documents the MATLAB-compatible interface of HASEonGPU.

The MATLAB interface is mainly intended for compatibility with existing MATLAB or Octave workflows. If this is your first time using HASEonGPU, the Python Interface Guide is usually the better starting point.

For general setup and dependency information, see Getting Started.

Compilation

The MATLAB interface requires a compiled calcPhiASE binary, see Compilation.

Installation

No separate installation step is required.

Add calcPhiASE.m to your MATLAB path, or run your MATLAB script from a location where the wrapper can be found.

Usage

Call calcPhiASE from a MATLAB script:

[phiASE, MSE, nRays] = calcPhiASE(
    points,
    trianglePointIndices,
    betaCells,
    betaVolume,
    claddingCellTypes,
    claddingNumber,
    claddingAbsorption,
    useReflections,
    refractiveIndices,
    reflectivities,
    triangleNormalsX,
    triangleNormalsY,
    triangleNeighbors,
    triangleSurfaces,
    triangleCenterX,
    triangleCenterY,
    triangleNormalPoint,
    forbiddenEdge,
    minRaysPerSample,
    maxRaysPerSample,
    mseThreshold,
    repetitions,
    adaptiveSteps,
    nTot,
    thickness,
    laserParameter,
    crystal,
    numberOfLevels,
    backend,
    parallelMode,
    numDevices,
    nPerNode
);

The returned values are represented as two-dimensional matrices, where rows correspond to point indices and columns correspond to slice indices.

Example

A complete MATLAB example using laser pumping and cladding is provided under:

example/matlab_example/laserPumpCladdingExample.m

Typical workflow:

Compile HASEonGPU if needed
Change into example/matlab_example/
Run matlab laserPumpCladdingExample
Inspect the generated .vtk files with ParaView

Input Argument Description

The following section describes all arguments of the MATLAB call.

`points`

Element type: float
Value range: {0, ..., max(maxPointX, maxPointY)}
Size: 2 * numberOfPoints
Description: Coordinates of the 2D mesh points. All x coordinates are followed by all y coordinates.
Structure:
```
[x_1, x_2, ... x_n, y_1, y_2, ... y_n]
```

`trianglePointIndices`

Element type: int
Value range: {0, ..., numberOfPoints}
Size: 3 * numberOfTriangles
Description: Point indices defining the triangles of the mesh. Each triangle is described by three point indices.

Structure:

[triangle1_p1, triangle2_p1, ... triangleN_p1,
 triangle1_p2, triangle2_p2, ... triangleN_p2,
 triangle1_p3, triangle2_p3, ... triangleN_p3]

`betaCells`

Element type: float
Size: numberOfPoints
Description: Excited-state fraction \(\beta_i\) at the sample points.

`betaVolume`

Element type: float
Size: numberOfTriangles * (numberOfLevels - 1)
Description: Prism-centered excited-state fraction \(\beta_j\) used by the ASE ray integration.

Prism values are ordered according to the prism ID:

prismID = triangleID + layer * numberOfTriangles

Therefore, all prism values of one layer are grouped together.

`claddingCellTypes`

Element type: int
Size: numberOfTriangles
Description: Cladding type index for each triangle.

`claddingNumber`

Type: unsigned
Size: 1
Description: Selects which cladding to use.

`claddingAbsorption`

Type: float
Size: 1
Description: Absorption coefficient of the cladding.

`useReflections`

Type: bool
Size: 1
Description: Enables or disables reflections at the top and bottom planes.

`refractiveIndices`

Element type: float
Size: 4
Description: Refractive indices of the active gain medium and its surrounding media.

Structure:

[bottomInside, bottomOutside, topInside, topOutside]

`reflectivities`

Element type: float
Value range: {0, ..., 1}
Size: 2 * numberOfTriangles
Description: Reflectivities of the prism planes. First the reflectivities of the bottom plane, then the reflectivities of the top plane, both ordered by triangle index.

`triangleNormalsX`

Element type: float
Size: 3 * numberOfTriangles
Description: x-components of the normal vectors for each triangle edge.

Structure:

[triangle0_edge0, triangle1_edge0, ..., triangleN_edge0,
 triangle0_edge1, triangle1_edge1, ..., triangleN_edge1,
 triangle0_edge2, triangle1_edge2, ..., triangleN_edge2]

`triangleNormalsY`

Element type: float
Size: 3 * numberOfTriangles
Description: y-components of the normal vectors for each triangle edge.

Structure:

[triangle0_edge0, triangle1_edge0, ..., triangleN_edge0,
 triangle0_edge1, triangle1_edge1, ..., triangleN_edge1,
 triangle0_edge2, triangle1_edge2, ..., triangleN_edge2]

`triangleNeighbors`

Element type: int
Value range: {-1, 0, ..., numberOfTriangles - 1}
Size: 3 * numberOfTriangles
Description: Neighbor triangle indices for each triangle edge. -1 means that no neighboring triangle exists at that edge.

`triangleSurfaces`

Element type: float
Size: numberOfTriangles
Description: Surface area of each triangle.

`triangleCenterX`

Element type: float
Size: numberOfTriangles
Description: x-coordinates of the triangle center points.

`triangleCenterY`

Element type: float
Size: numberOfTriangles
Description: y-coordinates of the triangle center points.

`triangleNormalPoint`

Element type: unsigned
Value range: {0, ..., numberOfPoints}
Size: 3 * numberOfTriangles
Description: Point indices where the corresponding triangle normal vectors start. For each triangle, one point index is stored for each of its three edges.

`forbiddenEdge`

Element type: int
Value range: {-1, 0, 1, 2}
Size: 3 * numberOfTriangles
Description: Edge indices of the adjacent triangles. -1 means there is no adjacent triangle at that edge. 0, 1 and 2 denote the corresponding edge index in the adjacent triangle.

`minRaysPerSample`

Type: unsigned
Size: 1
Description: Minimum number of Monte Carlo rays \(N\) used for adaptive sampling.

`maxRaysPerSample`

Type: unsigned
Size: 1
Description: Maximum number of rays used for adaptive sampling.

`mseThreshold`

Type: float
Size: 1
Description: Sets the maximal MSE of the ASE value. If a sample point does not reach this threshold, the number of rays per sample point is increased up to maxRaysPerSample or resampled with repetitive sampling.

`repetitions`

Type: unsigned
Size: 1
Description: Maximum number of repetitions if the MSE threshold is not reached.

`adaptiveSteps`

Type: unsigned
Size: 1
Description: Number of adaptive steps. The range between minimum and maximum ray count is split into that many parts. Setting it to 1 disables adaptive stepping and uses only minRaysPerSample.

`nTot`

Type: float
Size: 1
Description: Active-ion concentration \(N_{\mathrm{tot}}\) of the active gain medium.

`thickness`

Type: float
Size: 1
Description: Thickness \(\Delta z\) of one prism layer of the mesh.

`laserParameter`

Type: struct
Description: Structure containing the laser material spectra. It provides the absorption and emission spectrum values, \(\sigma_a(\lambda)\) and \(\sigma_e(\lambda)\), together with the corresponding wavelength values \(\lambda\).
Required fields:
- l_abs
- l_ems
- s_abs
- s_ems
- l_res
Field layouts:

l_abs
Container type: vector. Element type: double. Supported layout: flat. Wavelength values \(\lambda\) of the absorption spectrum in nm. Accessed in MATLAB as laserParameter.l_abs.

l_ems
Container type: vector. Element type: double. Supported layout: flat. Wavelength values \(\lambda\) of the emission spectrum in nm. Accessed in MATLAB as laserParameter.l_ems.

s_abs
Container type: vector. Element type: double. Supported layout: flat. Absorption cross sections \(\sigma_a\) in cm^2, corresponding to l_abs. Accessed in MATLAB as laserParameter.s_abs.

s_ems
Container type: vector. Element type: double. Supported layout: flat. Emission cross sections \(\sigma_e\) in cm^2, corresponding to l_ems. Accessed in MATLAB as laserParameter.s_ems.

l_res
Type: scalar. Element type: double. Resolution used for linear interpolation of the spectrum. Accessed in MATLAB as laserParameter.l_res.

`crystal`

Type: struct
Description: Structure containing the crystal parameters.
Required fields:
- tfluo
Field layouts:

tfluo
Type: scalar. Element type: double. Fluorescence lifetime \(\tau\) of the active medium in seconds. Accessed in MATLAB as crystal.tfluo.

`numberOfLevels`

Type: unsigned
Size: 1
Description: Total number of mesh levels in z-direction.

`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.

`parallelMode`

Type: str
Allowed values:
- "single": threads distribute samples across GPUs/devices within one node
- "mpi": distributes samples across nodes
Description: Selects the parallelization mode.

`numDevices`

Type: unsigned
Description: Number of devices used by one process - internally HASEonGPU uses min(numDevices,availableDevices).

In single mode, this usually corresponds to the requested number of computing devices - this can be gpus or cpu sockets depending on the alpaka backend - used on the local node.

In mpi mode, this corresponds to the number of computing devices used per MPI process rank. Therefore, if nPerNode = 1 (default) , it corresponds to the number of devices used per node.

`nPerNode`

Type: unsigned
Description: Number of MPI process ranks launched per node (default = 1).

MATLAB Interface

Compilation

Installation

Usage

Example

Input Argument Description

points

trianglePointIndices

betaCells

betaVolume

claddingCellTypes

claddingNumber

claddingAbsorption

useReflections

refractiveIndices

reflectivities

triangleNormalsX

triangleNormalsY

triangleNeighbors

triangleSurfaces

triangleCenterX

triangleCenterY

triangleNormalPoint

forbiddenEdge

minRaysPerSample

maxRaysPerSample

mseThreshold

repetitions

adaptiveSteps

nTot

thickness

laserParameter

crystal

numberOfLevels

backend

parallelMode

numDevices

nPerNode

`points`

`trianglePointIndices`

`betaCells`

`betaVolume`

`claddingCellTypes`

`claddingNumber`

`claddingAbsorption`

`useReflections`

`refractiveIndices`

`reflectivities`

`triangleNormalsX`

`triangleNormalsY`

`triangleNeighbors`

`triangleSurfaces`

`triangleCenterX`

`triangleCenterY`

`triangleNormalPoint`

`forbiddenEdge`

`minRaysPerSample`

`maxRaysPerSample`

`mseThreshold`

`repetitions`

`adaptiveSteps`

`nTot`

`thickness`

`laserParameter`

`crystal`

`numberOfLevels`

`backend`

`parallelMode`

`numDevices`

`nPerNode`