Table of Contents

Class VL_Detectors

Namespace
VirtualLab.Programming
Assembly
VirtualLab.Programming.dll

This class provides methods for evaluating fields.

public static class VL_Detectors
Inheritance
VL_Detectors
Inherited Members

Methods

BeamParameters(ComplexAmplitude, bool, bool, bool, bool, double, params BeamParametersSelection[])

Calculates the beam parameters of the given field.

public static List<PhysicalValue> BeamParameters(ComplexAmplitude field, bool evaluateEy = false, bool relativeToCentroid = true, bool relativeToPrincipalAxes = false, bool refineToSphericalPhase = false, double clippingThreshold = 1E-05, params BeamParametersSelection[] beamParametersToEvaluate)

Parameters

field ComplexAmplitude

The field to evaluate.

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

relativeToCentroid bool

If this parameter is set true, the detector is evaluated relative to the centroid. The default value of this optional parameter is true.

relativeToPrincipalAxes bool

If this parameter is set to true, the detector is evaluated relative set to the principal axes. The default value of this optional parameter is false.

refineToSphericalPhase bool

If this parameter is set to true the sampling is refined so that an analytical spherical phase factor can be sampled correctly. The default value of this optional parameter is false.

clippingThreshold double

All values having less than the given portion of the maximum squared amplitude in the field are ignored. The default value of this optional parameter is \(10^{-5}\).

beamParametersToEvaluate BeamParametersSelection[]

An array of BeamParametersSelection enum entries. All entries specified in this array are evaluated, all other possible beam parameters are not calculated. If this optional parameter is not specified, all beam parameters are evaluated.

Returns

List<PhysicalValue>

A list of physical values containing the evaluated beam parameters.

Centroid(DataArray2D)

Calculates the centroid or barycenter of the given amplitudes for each subset of the given data array.

public static List<PhysicalValue> Centroid(DataArray2D dataArray)

Parameters

dataArray DataArray2D

The data array.

Returns

List<PhysicalValue>

Two physical values per subset (one for the x-direction and one for the y-direction).

Exceptions

NotEquidistantException

Data are not equidistant.

ConversionEfficiency(ComplexAmplitude, ComplexAmplitude, bool, ComplexAmplitude?, ComplexAmplitude?)

Calculates the conversion efficiency of the given field.

public static PhysicalValue ConversionEfficiency(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, ComplexAmplitude? evaluationRegion = null, ComplexAmplitude? incidentField = null)

Parameters

field ComplexAmplitude

The field for which the conversion efficiency is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (conversion efficiency of 100 %).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion ComplexAmplitude

The region taken into account for calculation of the conversion efficiency. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

incidentField ComplexAmplitude

The incident field defining the original power of the field. If this optional parameter is not specified, the power of the field is used instead.

Returns

PhysicalValue

A single physical value, namely the conversion efficiency.

ConversionEfficiency(ComplexAmplitude, ComplexAmplitude, bool, IRegion1D2D?, ComplexAmplitude?)

Calculates the conversion efficiency of the given field.

public static PhysicalValue ConversionEfficiency(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, IRegion1D2D? evaluationRegion = null, ComplexAmplitude? incidentField = null)

Parameters

field ComplexAmplitude

The field for which the conversion efficiency is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (conversion efficiency of 100 %).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion IRegion1D2D

The region taken into account for calculation of the conversion efficiency. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

incidentField ComplexAmplitude

The incident field defining the original power of the field. If this optional parameter is not specified, the power of the field is used instead.

Returns

PhysicalValue

A single physical value, namely the conversion efficiency.

CreateDetectorResult(List<PhysicalValueComplex>)

Creates a detector result object from a list of complex-valued physical values.

public static DetectorResultObject CreateDetectorResult(List<PhysicalValueComplex> physicalValues)

Parameters

physicalValues List<PhysicalValueComplex>

The list of physical values.

Returns

DetectorResultObject

The detector result object.

CreateDetectorResult(List<PhysicalValue>)

Creates a detector result object from a list of real-valued physical values.

public static DetectorResultObject CreateDetectorResult(List<PhysicalValue> physicalValues)

Parameters

physicalValues List<PhysicalValue>

The list of physical values.

Returns

DetectorResultObject

The detector result object.

CreateDetectorResult(IDocument, string, string)

Creates a detector result object from a document (Harmonic Field, Data Array etc.).

public static DetectorResultObject CreateDetectorResult(IDocument document, string description, string group = "")

Parameters

document IDocument

The document.

description string

The description of the result.

group string

With this optional parameter you can group the results, for example you can put the results for Ex into one group and the results for Ey into another. The group name is appended to the actual detector name. For technical reasons, grouping does not work for lists of physical values.

Returns

DetectorResultObject

The detector result object.

CreateDetectorResult(params PhysicalValueBase[])

Creates a detector result object from one or more physical values, which can be real-valued or complex-valued. Usage note: you can also pass an array of PhysicalValueBase or a list of PhysicalValueBase (the later by conversion to an array via calling the ToArray() method).

public static DetectorResultObject CreateDetectorResult(params PhysicalValueBase[] physicalValues)

Parameters

physicalValues PhysicalValueBase[]

One or more physical values.

Returns

DetectorResultObject

The detector result object.

FiberCouplingEfficiency(ComplexAmplitude, ComplexAmplitude, ComplexAmplitude?)

Calculates the fiber coupling efficiency for the given field and the given fiber mode.

public static PhysicalValue FiberCouplingEfficiency(ComplexAmplitude field, ComplexAmplitude fiberMode, ComplexAmplitude? incidentField = null)

Parameters

field ComplexAmplitude

The field to evaluate.

fiberMode ComplexAmplitude

The fiber mode.

incidentField ComplexAmplitude

The incident field defining the original power of the field. If this optional parameter is not specified, the power of the field is used instead.

Returns

PhysicalValue

The fiber coupling efficiency.

FiberCouplingEfficiency_ModeDiameter(ComplexAmplitude, double, ComplexAmplitude?)

Calculates the fiber coupling efficiency for the given field and the given fiber mode. A Gaussian mode field is assumed.

public static PhysicalValue FiberCouplingEfficiency_ModeDiameter(ComplexAmplitude field, double modeDiameter, ComplexAmplitude? incidentField = null)

Parameters

field ComplexAmplitude

The field to evaluate.

modeDiameter double

The diameter of the Gaussian fiber mode.

incidentField ComplexAmplitude

The incident field defining the original power of the field. If this optional parameter is not specified, the power of the field is used instead.

Returns

PhysicalValue

The fiber coupling efficiency.

FiberCouplingEfficiency_NumericalAperture(ComplexAmplitude, double, ComplexAmplitude?)

Calculates the fiber coupling efficiency for the given field and the given fiber mode. A Gaussian mode field is assumed.

public static PhysicalValue FiberCouplingEfficiency_NumericalAperture(ComplexAmplitude field, double numericalAperture, ComplexAmplitude? incidentField = null)

Parameters

field ComplexAmplitude

The field to evaluate.

numericalAperture double

The numerical aperture of the fiber.

incidentField ComplexAmplitude

The incident field defining the original power of the field. If this optional parameter is not specified, the power of the field is used instead.

Returns

PhysicalValue

The fiber coupling efficiency.

Maximum(ComplexField, FieldQuantity)

Retrieves the maximum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

public static double Maximum(ComplexField field, FieldQuantity fieldQuantity)

Parameters

field ComplexField

The field for which the maximum is retrieved.

fieldQuantity FieldQuantity

Specifies for which field quantity (amplitude, phase, real part, imaginary part, or squared amplitude) the maximum shall be retrieved.

Returns

double

The maximum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

Maximum(ComplexField, FieldQuantity, out Vector)

Retrieves the maximum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

public static double Maximum(ComplexField field, FieldQuantity fieldQuantity, out Vector position)

Parameters

field ComplexField

The field for which the maximum is retrieved.

fieldQuantity FieldQuantity

Specifies for which field quantity (amplitude, phase, real part, imaginary part, or squared amplitude) the maximum shall be retrieved.

position Vector

Returns the pixel coordinate of the maximum. The lower left corner of the field has the position (0; 0).

Returns

double

The maximum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

MaximumRelativeIntensityOfStrayLight(ComplexAmplitude, ComplexAmplitude, bool)

Calculates the maximum relative stray light intensity within the given field.

public static PhysicalValue MaximumRelativeIntensityOfStrayLight(ComplexAmplitude field, ComplexAmplitude evaluationRegion, bool evaluateEy = false)

Parameters

field ComplexAmplitude

The field for which the stray light intensity is calculated.

evaluationRegion ComplexAmplitude

All absolute values of this field larger than zero define the evaluation region. Everything outside the evaluation region is regarded as stray light whose maximum relative intensity is determined.

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

Returns

PhysicalValue

A single physical value, namely the uniformity error.

MaximumRelativeIntensityOfStrayLight(ComplexAmplitude, IRegion1D2D?, bool)

Calculates the maximum relative stray light intensity within the given field.

public static PhysicalValue MaximumRelativeIntensityOfStrayLight(ComplexAmplitude field, IRegion1D2D? evaluationRegion, bool evaluateEy = false)

Parameters

field ComplexAmplitude

The field for which the stray light intensity is calculated.

evaluationRegion IRegion1D2D

All absolute values of this field larger than zero define the evaluation region. Everything outside the evaluation region is regarded as stray light whose maximum relative intensity is determined.

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

Returns

PhysicalValue

A single physical value, namely the uniformity error.

Minimum(ComplexField, FieldQuantity)

Retrieves the minimum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

public static double Minimum(ComplexField field, FieldQuantity fieldQuantity)

Parameters

field ComplexField

The field for which the minimum is retrieved.

fieldQuantity FieldQuantity

Specifies for which field quantity (amplitude, phase, real part, imaginary part, or squared amplitude) the minimum shall be retrieved.

Returns

double

The minimum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

Minimum(ComplexField, FieldQuantity, out Vector)

Retrieves the minimum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

public static double Minimum(ComplexField field, FieldQuantity fieldQuantity, out Vector position)

Parameters

field ComplexField

The field for which the minimum is retrieved.

fieldQuantity FieldQuantity

Specifies for which field quantity (amplitude, phase, real part, imaginary part, or squared amplitude) the minimum shall be retrieved.

position Vector

Returns the pixel coordinate of the minimum. The lower left corner of the field has the position (0; 0).

Returns

double

The minimum amplitude, phase, real part, imaginary part, or squared amplitude within the given field.

ParaxialPower(ComplexAmplitude)

Calculates the paraxial power (the \(E_{\text{z}}\) component of the field is neglected) of the specified field.

public static PhysicalValue ParaxialPower(ComplexAmplitude field)

Parameters

field ComplexAmplitude

The field for which the power is calculated.

Returns

PhysicalValue

The paraxial power of the field.

ParaxialPower(ComplexAmplitude, VectorD, VectorD)

Calculates the paraxial power (the \(E_{\text{z}}\) component of the field is neglected) of the specified rectangular region in the given field.

public static PhysicalValue ParaxialPower(ComplexAmplitude field, VectorD centerPoint, VectorD size)

Parameters

field ComplexAmplitude

The field for which the power in the specified region is calculated.

centerPoint VectorD

The center point of the region the power is to be calculated for.

size VectorD

The size of the rectangular region the power is to be calculated for .

Returns

PhysicalValue

The paraxial power in the specified region of the field.

ReadWavelengthInformation(List<DataArrayBase>, bool)

At some data arrays, especially the ones generated by the Electromagnetic Field Detector, a wavelength is stored within the data array. This method reads the wavelength information form a list of data arrays.

public static List<double> ReadWavelengthInformation(List<DataArrayBase> listDataArray, bool replaceNotGivenWavelengthsByDefault = true)

Parameters

listDataArray List<DataArrayBase>

The list of data arrays that shall be used for extraction of the data.

replaceNotGivenWavelengthsByDefault bool

By default, if any of the given data arrays contains no wavelength information, the wavelength from the Global Options is written into the resulting list and a warning is issued. However, if you set this optional parameter to false, NaN is used instead and no warning is issued. This was the default behavior up to 2026-06-05.

Returns

List<double>

The extracted list of wavelengths from the input list of data arrays.

ReadWavelengthInformation(DataArrayBase)

At some data arrays, especially the ones generated by the Electromagnetic Field Detector, a wavelength is stored within the data array. This method reads the wavelength information form a single data array.

public static double ReadWavelengthInformation(DataArrayBase dataArray)

Parameters

dataArray DataArrayBase

The data array.

Returns

double

The wavelength stored within the data array. double.NaN if no wavelength information is stored.

SeidelAberrations(ComplexAmplitude, bool, bool)

Calculates the Seidel aberrations of the given field.

public static List<PhysicalValue> SeidelAberrations(ComplexAmplitude field, bool sphericalPhaseIsReference, bool evaluateEy = false)

Parameters

field ComplexAmplitude

The field to evaluate.

sphericalPhaseIsReference bool

If set to true the aberrations are calculated relative to an analytical spherical phase factor if present.

evaluateEy bool

This parameter is no longer needed. Just left for compatibility

Returns

List<PhysicalValue>

A list of physical values containing the evaluated Seidel aberrations in wavelengths.

SignalToNoiseRatio(ComplexAmplitude, ComplexAmplitude, bool, ComplexAmplitude?, bool, SignalType)

Calculates the signal-to-noise ratio (SNR) of the given field.

public static PhysicalValue SignalToNoiseRatio(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, ComplexAmplitude? evaluationRegion = null, bool allowScaleFreedom = true, SignalType signalType = SignalType.Amplitude)

Parameters

field ComplexAmplitude

The field for which the SNR is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (SNR of infinity).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion ComplexAmplitude

The region taken into account for the SNR calculation. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

allowScaleFreedom bool

If set to true the field might be scaled with a complex value to get a better correspondence to the reference field. The default value of this optional parameter is true.

signalType SignalType

Defines for which field quantity the SNR is evaluated. The default value of this optional parameter is amplitude, i.e. the phase values do not influence the SNR calculation.

Returns

PhysicalValue

A single physical value, namely the signal-to-noise ratio.

SignalToNoiseRatio(ComplexAmplitude, ComplexAmplitude, bool, IRegion1D2D?, bool, SignalType)

Calculates the signal-to-noise ratio (SNR) of the given field.

public static PhysicalValue SignalToNoiseRatio(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, IRegion1D2D? evaluationRegion = null, bool allowScaleFreedom = true, SignalType signalType = SignalType.Amplitude)

Parameters

field ComplexAmplitude

The field for which the SNR is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (SNR of infinity).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion IRegion1D2D

The region taken into account for the SNR calculation. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

allowScaleFreedom bool

If set to true the field might be scaled with a complex value to get a better correspondence to the reference field. The default value of this optional parameter is true.

signalType SignalType

Defines for which field quantity the SNR is evaluated. The default value of this optional parameter is amplitude, i.e. the phase values do not influence the SNR calculation.

Returns

PhysicalValue

A single physical value, namely the signal-to-noise ratio.

SumOfFieldValues(ComplexField, FieldQuantity)

Calculates the sum of all amplitude, phase, real part, imaginary part, or squared amplitude values within the given field.

public static double SumOfFieldValues(ComplexField field, FieldQuantity fieldQuantity)

Parameters

field ComplexField

The field for which the sum is calculated.

fieldQuantity FieldQuantity

Specifies for which field quantity (amplitude, phase, real part, imaginary part, or squared amplitude) the sum shall be calculated.

Returns

double

The sum of all amplitude, phase, real part, imaginary part, or squared amplitude values within the given field.

UniformityError(ComplexAmplitude, ComplexAmplitude, bool, ComplexAmplitude?, SignalType)

Calculates the uniformity error of the given field with respect to a given reference field.

public static PhysicalValue UniformityError(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, ComplexAmplitude? evaluationRegion = null, SignalType signalType = SignalType.Amplitude)

Parameters

field ComplexAmplitude

The field for which the uniformity error is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (uniformity error of zero).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion ComplexAmplitude

The region taken into account for calculation of the uniformity error. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

signalType SignalType

Defines for which field quantity the uniformity error is evaluated. The default value of this optional parameter is amplitude, i.e. the phase values do not influence the calculation of the uniformity error.

Returns

PhysicalValue

A single physical value, namely the uniformity error.

UniformityError(ComplexAmplitude, ComplexAmplitude, bool, IRegion1D2D?, SignalType)

Calculates the uniformity error of the given field with respect to a given reference field.

public static PhysicalValue UniformityError(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, IRegion1D2D? evaluationRegion = null, SignalType signalType = SignalType.Amplitude)

Parameters

field ComplexAmplitude

The field for which the uniformity error is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (uniformity error of zero).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion IRegion1D2D

The region taken into account for calculation of the uniformity error. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

signalType SignalType

Defines for which field quantity the uniformity error is evaluated. The default value of this optional parameter is amplitude, i.e. the phase values do not influence the calculation of the uniformity error.

Returns

PhysicalValue

A single physical value, namely the uniformity error.

UniformityError(DataArray2D, int, DataArray2D)

Calculates the uniformity error for a given two-dimensional data array with respect to the given reference data.

public static PhysicalValue? UniformityError(DataArray2D dataArray, int subsetIndex, DataArray2D referenceData)

Parameters

dataArray DataArray2D

The two-dimensional data array for which the evaluation shall be done. Must be equidistant in both x- and y-direction.

subsetIndex int

The index of the subset that is evaluated.

referenceData DataArray2D

The two-dimensional reference data that shall be used for evaluation. Must be equidistant in both x- and y-direction and contain only one subset.

Returns

PhysicalValue

The uniformity error for the given input parameters.

Exceptions

ArgumentException

The data array to analyze has to be equidistant in x- and y-direction. or The reference field for analyzing the uniformity of a data array has to be equidistant in x- and y-direction.

WindowEfficiency(ComplexAmplitude, ComplexAmplitude, bool, ComplexAmplitude?, ComplexAmplitude?)

Calculates the window efficiency of the given field.

public static PhysicalValue WindowEfficiency(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, ComplexAmplitude? evaluationRegion = null, ComplexAmplitude? incidentField = null)

Parameters

field ComplexAmplitude

The field for which the window efficiency is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (window efficiency of 100 %).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion ComplexAmplitude

The region taken into account for calculation of the window efficiency. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

incidentField ComplexAmplitude

The incident field defining the original power of the field. If this optional parameter is not specified, the power of the field is used instead.

Returns

PhysicalValue

A single physical value, namely the window efficiency.

WindowEfficiency(ComplexAmplitude, ComplexAmplitude, bool, IRegion1D2D?, ComplexAmplitude?)

Calculates the window efficiency of the given field.

public static PhysicalValue WindowEfficiency(ComplexAmplitude field, ComplexAmplitude referenceField, bool evaluateEy = false, IRegion1D2D? evaluationRegion = null, ComplexAmplitude? incidentField = null)

Parameters

field ComplexAmplitude

The field for which the window efficiency is calculated.

referenceField ComplexAmplitude

The reference field, i.e. how the field should look like in an ideal case (window efficiency of 100 %).

evaluateEy bool

If this optional parameter is set to true, the Ey-component of the field is evaluated instead of the Ex-component.

evaluationRegion IRegion1D2D

The region taken into account for calculation of the window efficiency. If this optional parameter is not specified, all absolute values of the reference field larger than zero define the evaluation region.

incidentField ComplexAmplitude

The incident field defining the original power of the field. If this optional parameter is not specified, the power of the field is used instead.

Returns

PhysicalValue

A single physical value, namely the window efficiency.

ZernikeFringeAberrations(ComplexAmplitude, int, bool, bool)

Calculates the Zernike fringe aberrations of the given field.

public static List<PhysicalValue> ZernikeFringeAberrations(ComplexAmplitude field, int numberOfCoefficients, bool sphericalPhaseIsReference, bool evaluateEy = false)

Parameters

field ComplexAmplitude

The field to evaluate.

numberOfCoefficients int

The maximum coefficient index to evaluate. Must be in the range 1 to 37.

sphericalPhaseIsReference bool

If set to true the aberrations are calculated relative to an analytical spherical phase factor if present.

evaluateEy bool

This parameter is no longer needed. The more "powerful" vectorial component of Ex and Ey is used for locally polarized fields. Just left for compatibility.

Returns

List<PhysicalValue>

A list of physical values containing the evaluated Zernike fringe aberrations in wavelengths.