Class ComplexField

Namespace

VirtualLabAPI.Core.Numerics

Assembly

VirtualLabAPI.dll

This class is a matrix of complex values. If no imaginary part is needed (real valued fields) one can set a special flag that indicates a real valued field (ComplexField with imaginary part zero). This different internal representations are used to optimize the computer memory and computational time.
Operators (\(a+b\), \(a-b\), \(a*b\) and \(a/b\)) can be used. Passing \(a\) or \(b\) as Complex or double is supported (Except of \(/\) where \(b\) may only be a scalar). Operator \(a|b\) is used for calculation of inner product of two ComplexFields: \(a|b=\sum _{j=0}^{m}\sum _{i=0}^{n}a_{{i,j}}b_{{i,j}^{\star}}\) (\(z^{\star}\) means conjugation of complex number). IsComplex property is always taken from first operand.

public class ComplexField : ILargeArray<Complex>, ICloneable, IDisposable

Inheritance

object

ComplexField

Implements

ILargeArray<Complex>

ICloneable

IDisposable

Derived

ComplexFieldDerivative1D

Inherited Members

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

ComplexField()

Creates a ComplexField with 3 × 3 sampling points. The internal data presentation is complex.

public ComplexField()

ComplexField(ComplexField)

Copy constructor.

public ComplexField(ComplexField field)

Parameters

field ComplexField

Field to copy.

ComplexField(Vector)

Creates a ComplexField with given number of sampling points. The internal data presentation is complex.

public ComplexField(Vector samplingPoints)

Parameters

samplingPoints Vector

Number of points in x- and y-direction.

ComplexField(Vector, bool, Func<int, int, double>, ParallelizationType)

Constructs a ComplexField object with given number of sampling points using a real-valued function which will be evaluated to fill in the complex amplitudes. The parameters x and y of the real function are measured in pixel coordinates whose origin is the upper left corner of the field.

public ComplexField(Vector samplingPoints, bool createComplexField, Func<int, int, double> function, ParallelizationType parallelizationType = ParallelizationType.Always)

Parameters

samplingPoints Vector

Number of pixels in x-and y-direction.

createComplexField bool

Indicates if new ComplexField should internally store real + imaginary part (createComplexField = true) or the real part only (createComplexField = false).

function Func<int, int, double>

Function delegate to be evaluated.

parallelizationType ParallelizationType

Optional type of the parallelization (ParallelizationType.AutomaticMeasure by default). Set it to ParallelizationType.NoParallelization if the method passed by the function delegate is not thread-safe.

ComplexField(Vector, bool, PrecisionMode, bool)

Creates a ComplexField with given number of sampling points. The internal data representation can be complex or real.

public ComplexField(Vector samplingPoints, bool isComplex, PrecisionMode precision = PrecisionMode.Double, bool initializeValues = true)

Parameters

samplingPoints Vector

Number of values in x- and y-direction.

isComplex bool

Indicates if new Complex Field should internally store real + imaginary part (complex = true) or the real part only (complex = false) (imaginary part is zero).

precision PrecisionMode

Optional and obsolete. Should not be used.

initializeValues bool

If this optional parameter is set to false, the field values are not initialized. Should be used only if the values are initialized immediately afterwards, but then performance is better.

ComplexField(Vector, Func<int, int, Complex>, ParallelizationType)

Constructs a ComplexField object with given number of sampling points using a complex-valued function which will be evaluated to fill in the complex amplitudes. The parameters x and y of the real function are measured in pixel coordinates whose origin is the upper left corner of the field.

public ComplexField(Vector samplingPoints, Func<int, int, Complex> function, ParallelizationType parallelizationType = ParallelizationType.Always)

Parameters

samplingPoints Vector

Number of pixels in x-and y-direction.

function Func<int, int, Complex>

Function delegate to be evaluated.

parallelizationType ParallelizationType

Optional type of the parallelization (ParallelizationType.AutomaticMeasure by default). Set it to ParallelizationType.NoParallelization if the method passed by the function delegate is not thread-safe.

ComplexField(Vector, Complex, bool)

Creates a ComplexField with given number of sampling points. The internal data representation can be complex or real. Field is filled with constant value. In case of a real valued complex field only the real part of constant value is stored.

public ComplexField(Vector samplingPoints, Complex c, bool isComplex = true)

Parameters

samplingPoints Vector

Number of values in x- and y-direction.

c Complex

Complex number with which the field is to be initialized.

isComplex bool

This optional parameter indicates if the new ComplexField should internally store real + imaginary part (true, which is the default) or the real part only (false) (imaginary part is zero).

Properties

IsComplex

Gets or sets the internal representation of the values. If IsComplex is true the real and imaginary part is stored. If IsComplex is false only the real part is stored. Then it is assumed that the imaginary part is zero. Setting this property will convert the ComplexField from present representation to new one. Information can be lost during this conversion.

public virtual bool IsComplex { get; set; }

Property Value

bool

IsOneD

Indicates whether field is one-dimensional or not.

public virtual bool IsOneD { get; }

Property Value

bool

this[int, int]

Indexer to access complex values of complex field. Property performs a range checking before every access. If you try to read a complex value and index is out of range Complex(0) is returned. If you try to set a complex value and index is out of range nothing will happen. Indexer returns always a Complex number. If IsComplex is false only the real part is stored.

public virtual Complex this[int x, int y] { get; set; }

Parameters

x int

Index for x-coordinate

y int

Index for y-coordinate

Property Value

Complex

SamplingPoints

Gets or sets the number of sampling points of this ComplexField. Setting a new number of sampling points will embed the sampling points in zero values or extract the central sampling points. See also EmbedExtract(Vector).

public virtual Vector SamplingPoints { get; set; }

Property Value

Vector

SamplingPointsOneD

Gets number of sampling points of one-dimensional field. An exception will be thrown, if field is two-dimensional.

public int SamplingPointsOneD { get; }

Property Value

int

Methods

AddConjugate()

Adds conjugated ComplexField to current one.

public void AddConjugate()

AddEqual(Complex)

Adds a Complex to all sampling points of this ComplexField.

public void AddEqual(Complex c)

Parameters

c Complex

Complex number to add to current field.

AddEqual(ComplexField)

Adds another ComplexField to current one. Both fields must have the same number of sampling points.

public void AddEqual(ComplexField field)

Parameters

field ComplexField

Complex field to add to current field.

AddEqual(ComplexField, CancellationToken)

Adds another ComplexField to current one. Both fields must have the same number of sampling points.

public void AddEqual(ComplexField field, CancellationToken cancellationToken)

Parameters

field ComplexField

Complex field to add to current field.

cancellationToken CancellationToken

Token for cooperative task cancellation.

ClipAmplitude(double)

Sets all amplitude values greater than clippingLevel to clippingLevel.

public void ClipAmplitude(double clippingLevel)

Parameters

clippingLevel double

Maximal value of amplitude.

Clone()

Clones this complex field.

public virtual object Clone()

Returns

object

Conjugate()

Conjugates current ComplexField.

public void Conjugate()

ConvertFrom2D_DoubleArray(double[,])

Converts a two dimensional double array to a two dimensional complex field

public static ComplexField ConvertFrom2D_DoubleArray(double[,] doubleArray)

Parameters

doubleArray double[,]

The double array to convert

Returns

ComplexField

Complex field, created from the double array

ConvertFrom2_1D_DoubleArrays(double[], double[])

Converts two one-dimensional double arrays to a two dimensional complex field of dimensions 2 × doubleArray1.Length

public static ComplexField ConvertFrom2_1D_DoubleArrays(double[] doubleArray1, double[] doubleArray2)

Parameters

doubleArray1 double[]

The first double array to convert

doubleArray2 double[]

The second double array to convert

Returns

ComplexField

Complex field, created from the double arrays.

ConvertFrom_1D_ComplexArray(Complex[])

Converts one one-dimensional complex array to a one-dimensional complex field

public static ComplexFieldDerivative1D ConvertFrom_1D_ComplexArray(Complex[] complexArray)

Parameters

complexArray Complex[]

The complex array to convert

Returns

ComplexFieldDerivative1D

Complex field, created from the complex array

ConvertFrom_1D_DoubleArray(double[])

Converts one one-dimensional double array to a one-dimensional complex field

public static CFieldDerivative1DReal ConvertFrom_1D_DoubleArray(double[] doubleArray)

Parameters

doubleArray double[]

The double array to convert

Returns

CFieldDerivative1DReal

Complex field, created from the double array

ConvertTo1D_DoubleArray(ComplexField, bool)

Converts a one dimensional complex field to a one dimensional double array

public static double[] ConvertTo1D_DoubleArray(ComplexField complexField, bool errorWhenComplex)

Parameters

complexField ComplexField

Complex field to convert

errorWhenComplex bool

Shall an exception be thrown if the complex field is not real valued? Please note: The Imaginary part will be ignored in every case!

Returns

double[]

Double array, created from the complex field

ConvertTo2D_DoubleArray(ComplexField, bool)

Converts a two dimensional complex field to a two dimensional double array

public static double[,] ConvertTo2D_DoubleArray(ComplexField complexField, bool errorWhenComplex)

Parameters

complexField ComplexField

Complex field to convert

errorWhenComplex bool

Shall an exception be thrown if the complex field is not real valued? Please note: The Imaginary part will be ignored in every case!

Returns

double[,]

Double array, created from the complex field

DivEqual(Complex)

Divides all values in this ComplexField by a complex number.

public void DivEqual(Complex c)

Parameters

c Complex

Complex number to divide.

DivEqual(ComplexField)

Divides this ComplexField by passed one. Both fields must have the same number of sampling points.

public void DivEqual(ComplexField field)

Parameters

field ComplexField

Complex field used as divisor.

EmbedCorner(Vector)

Embeds this ComplexField into double side-length field of zero sampling points and places the original in bottom left corner of the new field. If this ComplexField is one-dimensional, only longer side of field is doubled.

public void EmbedCorner(Vector newSize)

Parameters

newSize Vector

New Size in pixel.

EmbedExtract()

Embeds this ComplexField into double side-length field of zero sampling points and places the original in the middle of the new field. If this ComplexField is one-dimensional, only longer side of field is doubled.

public virtual void EmbedExtract()

EmbedExtract(Rectangle)

Extracts a region of this ComplexField including the bottom left corner but excluding the top right corner.

public virtual ComplexField EmbedExtract(Rectangle rectangle)

Parameters

rectangle Rectangle

Region to extract.

Returns

ComplexField

Result of operation.

EmbedExtract(Vector)

Embeds this ComplexField into field of passed size of zero sampling points and places the original in the middle of the new field. By decreasing size, field can be extracted.

public virtual void EmbedExtract(Vector newSize)

Parameters

newSize Vector

New size in pixels.

Equals(object)

Checks whether two complex fields represent the same values.

public override bool Equals(object obj)

Parameters

obj object

Complex field to be compared

Returns

bool

true if both fields have the same size and the same values.

Extract(Vector, VectorL, bool)

Extracts the given region at given position out of the current field. Points exceeding boundaries of current field will be ignored.

public ComplexField Extract(Vector size, VectorL position, bool elliptical = false)

Parameters

size Vector

size of the region to extract.

position VectorL

Position at which field is to be extracted.

elliptical bool

Elliptical extraction?

Returns

ComplexField

The extracted field

ExtractColumn(int)

Extracts a column out of the current field. Points exceeding boundaries of current field will be set to zero.

public ComplexField ExtractColumn(int colIndex)

Parameters

colIndex int

Index of the column to extract.

Returns

ComplexField

A ComplexField with only the extracted column.

ExtractRow(int)

Extracts a row out of the current field. Points exceeding boundaries of current field will be set to zero.

public ComplexField ExtractRow(int rowIndex)

Parameters

rowIndex int

index of the row to extract.

Returns

ComplexField

A ComplexField with only the extracted row.

Fill(Complex)

Fills whole current ComplexField with the specified complex value.

public void Fill(Complex c)

Parameters

c Complex

Complex value to fill the field with.

Fill(Complex, Rectangle, bool, bool)

Fills whole ComplexField inside marker with the specified complex value. If inside is set to false, field outside marker will be filled.

public void Fill(Complex c, Rectangle marker, bool inside, bool elliptical = false)

Parameters

c Complex

Complex value to fill the field with.

marker Rectangle

Region that decides where to fill.

inside bool

Fill inside or outside of the marker.

elliptical bool

Fill elliptical instead of rectangular region?

HorizontalMirror()

Performs a horizontal mirroring of this ComplexField. [SamplingPoints.X - x - 1, y] = [x, y]

public void HorizontalMirror()

Insert(ComplexField, VectorL, bool)

Inserts the given ComplexField into current field at given position. Points exceeding boundaries of current field will be ignored.

public void Insert(ComplexField field, VectorL position, bool elliptical = false)

Parameters

field ComplexField

Complex field to insert.

position VectorL

Position at which field is to be inserted (offset of 'field' to 'this').

elliptical bool

Elliptical insertion?

InsertColumn(int)

Inserts or appends an empty column.

public void InsertColumn(int colIndex)

Parameters

colIndex int

Index of column left of inserted column or -1 to append column.

InsertRow(int)

Inserts or appends an empty row.

public void InsertRow(int rowIndex)

Parameters

rowIndex int

Index of row below inserted row or -1 to append row.

InvertValues()

Sets all points where field is zero to one, and all other points of the field to zero

public void InvertValues()

LiftPositive()

Lifts real part of this ComplexField to positive numbers. Function detects the minimum real number. If this number is smaller than zero it adds the absolute value of the minimum to all values. If the minimum real number is larger than zero the present object is returned without changes.

public void LiftPositive()

ModifyComplexPart(ComplexPart, bool, double, double, CancellationToken?)

Extract, shifts or swaps complex parts of the complex field.

public void ModifyComplexPart(ComplexPart complexPart, bool makeRealValuedIfSuitable = false, double thresholdForPhaseArtifacts = 0, double amplitudeMaximum = 0, CancellationToken? cancellationToken = null)

Parameters

complexPart ComplexPart

Enumerator element for desired action on this ComplexField.

makeRealValuedIfSuitable bool

If this optional parameter is set to true the field is made real-valued if the imaginary part is zeroized. This is e.g. the case for extract amplitude and shift phase to real.

thresholdForPhaseArtifacts double

Optional threshold for suppressing phase artifacts.

amplitudeMaximum double

Optional amplitude maximum, needed for calculating an absolute artifacts threshold from the relative one.

cancellationToken CancellationToken?

Optional token for cooperative task cancellation.

ModifyPixels(Func<Complex, int, int, Complex>)

Modifies all pixels in parallel. Can be used if the new pixel value depends on the old pixel value and the current position in pixel coordinates (and maybe some fixed parameters).

public void ModifyPixels(Func<Complex, int, int, Complex> modificationMethod)

Parameters

modificationMethod Func<Complex, int, int, Complex>

The modification method for each pixel.

ModifyPixels(Func<Complex, Complex>)

Modifies all pixels in parallel. Can be used if the new pixel value depends only on the old pixel value (and maybe some fixed parameters).

public void ModifyPixels(Func<Complex, Complex> modificationMethod)

Parameters

modificationMethod Func<Complex, Complex>

The modification method for each pixel.

MultEqual(Complex)

Multiplies a Complex number to each sampling point of this ComplexField.

public void MultEqual(Complex c)

Parameters

c Complex

Complex number used as factor.

MultEqual(ComplexField)

Multiplies another ComplexField with current one. Both fields must have the same number of sampling points.

public void MultEqual(ComplexField field)

Parameters

field ComplexField

Complex field used as factor.

MultEqual(IRegion1D2D)

Multiplies a IRegion1D2D with this ComplexField.

public void MultEqual(IRegion1D2D region)

Parameters

region IRegion1D2D

Region used as factor. The coordinates of that region must be relative to this ComplexField. This means that the extension of the region is 1 and centered around (0, 0) if it covers exactly the complete ComplexField.

Normalize(Rectangle?)

Normalizes this ComplexField so that maximal amplitude inside the given rectangle is one.

public void Normalize(Rectangle? rectangle = null)

Parameters

rectangle Rectangle?

If this optional parameter is set only the region within the specified rectangle is taken into account for the calculation of the maximum being the normalization reference. Else the whole filed is normalized.

PowerEqual(Complex)

Raises every element of this ComplexField to the power of the passed complex number.

public void PowerEqual(Complex c)

Parameters

c Complex

Complex exponent.

Replicate_Periodic(Vector)

Replicates current ComplexField periodically, old field is centered around (0,0). Needs new size.

public void Replicate_Periodic(Vector newSize)

Parameters

newSize Vector

New size in pixels.

Rotate180()

Rotates this ComplexField through 180° about the field center.

public void Rotate180()

Shift(Vector, bool)

Shifts current ComplexField by a specified distance. Size is not modified, so sampling points can get lost.

public void Shift(Vector shift, bool assumePeriodicField = false)

Parameters

shift Vector

Shift in pixels.

assumePeriodicField bool

If this optional parameter is set to true a periodic field is assumed. Else zeros occur outside of the shifted original field.

ShiftColumnFromOnePositionToAnother(int, int)

Shifts a single column from one pixel index to another

public void ShiftColumnFromOnePositionToAnother(int oldColIndex, int newColIndex)

Parameters

oldColIndex int

Old pixel index of column.

newColIndex int

New pixel index of column.

ShiftRowFromOnePositionToAnother(int, int)

Shifts a single row from one pixel index to another

public void ShiftRowFromOnePositionToAnother(int oldRowIndex, int newRowIndex)

Parameters

oldRowIndex int

Old pixel index of row.

newRowIndex int

New pixel index of row.

SortColumns(int[])

Method which brings all columns into a new, given order. Since this is not optimized, it shall not be used if a) the field is to be mirrored or b) only a single column is to be shifted.

public void SortColumns(int[] newColIndices)

Parameters

newColIndices int[]

Array with the new indices for all columns: the array index is the new index, the array item is the old index.

SortRows(int[])

Method which brings all rows into a new, given order. Since this is not optimized, it shall not be used if a) the field is to be mirrored or b) only a single row is to be shifted.

public void SortRows(int[] newRowIndices)

Parameters

newRowIndices int[]

Array with the new indices for all rows: the array index is the new index, the array item is the old index.

SubEqual(Complex)

Subtracts a Complex from all sampling points of this ComplexField.

public void SubEqual(Complex c)

Parameters

c Complex

Complex number to subtract form current field.

SubEqual(ComplexField)

Subtracts another ComplexField from current one. Both fields must have the same number of sampling points.

public void SubEqual(ComplexField field)

Parameters

field ComplexField

Complex field to subtract form current field.

Transpose()

Transposes this ComplexField. This means [x, y] = [y, x].

public void Transpose()

VerticalMirror()

Performs a vertical mirroring of this ComplexField. [x, SamplingPoints.Y - y - 1] = [x, y]

public void VerticalMirror()

Operators

operator +(ComplexField, Complex)

Adds a complex value to all values of a complex field.

public static ComplexField operator +(ComplexField field, Complex c)

Parameters

field ComplexField

The ComplexField.

c Complex

The complex value.

Returns

ComplexField

The result of the operator.

operator +(ComplexField, ComplexField)

Adds two complex fields. Both fields must have the same number of sampling points. Keep in mind that the AddEqual(ComplexField) method is more performant than the += operator.

[Obsolete("Keep in mind that the AddEqual method is more performant than the += operator.")]
public static ComplexField operator +(ComplexField field1, ComplexField field2)

Parameters

field1 ComplexField

The first field to be added.

field2 ComplexField

The second field to be added.

Returns

ComplexField

The result of the operator.

Exceptions

ComplexField.FieldSizesDontMatch

operator |(ComplexField, ComplexField)

Computes the inner (or scalar) product of two complex fields as defined by (u|v) := Integrate[u(x) * v^(x), {x, -Infinity, Infinity}].

public static Complex operator |(ComplexField field1, ComplexField field2)

Parameters

field1 ComplexField

The first field.

field2 ComplexField

The second field.

Returns

Complex

The inner product.

operator /(ComplexField, Complex)

Divides a complex field by a complex number

public static ComplexField operator /(ComplexField field, Complex c)

Parameters

field ComplexField

The complex field.

c Complex

The complex number.

Returns

ComplexField

The result of the operation.

operator /(ComplexField, ComplexField)

Divides two complex fields.

public static ComplexField operator /(ComplexField field1, ComplexField field2)

Parameters

field1 ComplexField

The first field.

field2 ComplexField

The second field.

Returns

ComplexField

The result of the operation.

operator ==(ComplexField, ComplexField)

Compares two complex fields for equality

public static bool operator ==(ComplexField field1, ComplexField field2)

Parameters

field1 ComplexField

The first field.

field2 ComplexField

The second field.

Returns

bool

true if both fields represent the same data.

operator !=(ComplexField, ComplexField)

Compares two complex fields for inequality.

public static bool operator !=(ComplexField field1, ComplexField field2)

Parameters

field1 ComplexField

The first field.

field2 ComplexField

The second field.

Returns

bool

true if both fields do not represent the same data.

operator *(Complex, ComplexField)

Multiplies a complex value to a complex field.

public static ComplexField operator *(Complex c, ComplexField field)

Parameters

c Complex

The complex value.

field ComplexField

The field.

Returns

ComplexField

The result of the operator.

operator *(ComplexField, Complex)

Multiplies a complex value to all values of a complex field.

public static ComplexField operator *(ComplexField field, Complex c)

Parameters

field ComplexField

The field.

c Complex

The complex value.

Returns

ComplexField

The result of the operator.

operator *(ComplexField, ComplexField)

Multiplies two complex fields. Both fields must have the same number of sampling points. Keep in mind that the AddEqual(ComplexField) method is more performant than the += operator.

[Obsolete("Keep in mind that the AddEqual method is more performant than the += operator.")]
public static ComplexField operator *(ComplexField field1, ComplexField field2)

Parameters

field1 ComplexField

the first field

field2 ComplexField

the second field

Returns

ComplexField

The result of the operator.

Exceptions

ComplexField.FieldSizesDontMatch

operator -(Complex, ComplexField)

Subtracts a complex number and a complex field.

public static ComplexField operator -(Complex c, ComplexField field)

Parameters

c Complex

Complex number.

field ComplexField

Complex Field to subtract.

Returns

ComplexField

Difference of the complex field and the complex number.

operator -(ComplexField, Complex)

Subtracts a complex value from all values of a complex field.

public static ComplexField operator -(ComplexField field, Complex c)

Parameters

field ComplexField

The Complex Field.

c Complex

Complex number to subtract.

Returns

ComplexField

Difference of the complex field and the complex number.

operator -(ComplexField, ComplexField)

Subtracts two complex fields.

public static ComplexField operator -(ComplexField field1, ComplexField field2)

Parameters

field1 ComplexField

The first field.

field2 ComplexField

The second field.

Returns

ComplexField

The result of the operator.

Exceptions

ComplexField.FieldSizesDontMatch