API Reference

AbstractSphericalCoefficients{C <: Number }

Supertype for collections of spherical coefficients.

Can be accessed like an AbstractVector{C} with a single index j or with a triple index (s,ℓ,m), where j = 2 * (ℓ * (ℓ + 1) + m - 1) + s.

AntennaFieldRepresentation{P <: PropagationType, C <: Number} <: AbstractVector{C}

Equivalent representation of the electromagnetic fields of an antenna (in a certain region of space where the representation converges).

Each instance of AntennaFieldRepresentation is a discretized version of the antenna fields, i.e., a collection of coefficients from which the antenna fields can be (approximately) calculated. The coefficents of the field representation can be accessed via the interface of AbstractVector{C}. In addition to the field coefficients, each instance of AntennaFieldRepresentation stores additional information which allows to calculate the electromagnetic fields from the coefficient vector. In particular, the wavenumber of the radiation frequency of the antenna field is stored.

ChangeRepresentationMap{A, B, C} <: LinearMaps.LinearMap{C}

Supertype for linear map which corresponds to a changerepresentation method.

Type Parameters

• A <: AntennaFieldRepresentation : Type of the original representation
• B <: AntennaFieldRepresentation : Type of the target representation
• C <: Complex

DipoleArray{P, E, T, C} <: AntennaFieldRepresentation{P, C}

Array of multiple small dipoles.

Behaves like an AbstractVector{C} with extra context.

Type Parameters

• P <: PropagationType
• E <: ElmagType
• T <: Number
• C <: Number

ElmagType

Indicator for Electric or Magnetic type field expansions.

FieldSampling{C}

Abstract type for various field samplings.

FirstOrderSphericalCoefficients{C} <: AbstractSphericalCoefficients{C}

Sparse representation of a collections of only first-order coefficients for a spherical wave expansion.

Can be accessed like an AbstractVector{C} with a single index j or with a triple index (s,ℓ,m), where j = 2 * (ℓ * (ℓ + 1) + m - 1) + s. All coefficients with m ≠ ± 1 are zero by definition.

Examples

values=ComplexF64.(collect(1:16))
sph_coefficients= SphericalCoefficients(values)
firstorder_sph_coefficients = FirstOrderSphericalCoefficients(sph_coefficients)
println(firstorder_sph_coefficients[1, 2, -1])
firstorder_sph_coefficients[1, 2, -1] = 111.0 im 
println(firstorder_sph_coefficients[9])

FirstOrderSphericalCoefficients(coefficients::SphericalCoefficients)

Return sparse representation of a collections of only first-order spherical coefficients. All non-first-order coefficients (index m ≠ ±1) are dropped and treated as zero.

Examples

values=ComplexF64.(collect(1:16))
sph_coefficients= SphericalCoefficients(values)
firstorder_sph_coefficients = FirstOrderSphericalCoefficients(sph_coefficients)
println(firstorder_sph_coefficients[1, 2, -1])
println(firstorder_sph_coefficients[1, 2, -2])

FitzgeraldArray{T, C}

Alias for DipoleArray{Radiated,Magnetic,T,C}

A FitzgeraldArray is used to represent an array of multiple small radiating magnetic dipoles. Behaves like an AbstractVector{C} with extra context.

Type Parameters

• T <: Number
• C <: Number

GaussLegendreθRegularϕSampling <: SphereSamplingStrategy

Sampling strategy on the sphere with regular sampling along ϕ and Gauß-Legendre-Sampling along θ.

ϕ ∈ {0, Δϕ, …, 2π - Δϕ} with Δϕ= 2π / (2L + 2). θ ∈ {acos(xᵢ)} where xᵢ are the Nθ-point Gauß-Legendre quadrature points.

Fields

• Nθ::Integer
• Jϕ::Integer

HertzArray{T, C}

Alias for DipoleArray{Radiated,Electric,T,C}

A HertzArray is used to represent an array of multiple small radiating electric dipoles. Behaves like an AbstractVector{C} with extra context.

Type Parameters

• T <: Number
• C <: Number

InterpolateMap{Y, T} <: OperationMap{T}

Abstract supertype for linear maps which performs an interpolation of predefined sampling points from spherically sampled data.

Type parameters:

• Y :: SphereSamplingStrategy : Defines the sampling points of the spherically sampled original data.
• T <: Real : Defines the number type to represent interpolation parameters, e.g. Float64 or Float32.

IrregularFieldSampling{N, T, C}

Field sampling with arbitrary probes at irregularly distributed measurement positions.

Type Parameters

• N <: ProbeAntenna
• T <: Real
• C <: Complex

IrregularFieldSampling(positions::Array{V}, eulerangles::Array{D}, probeIDs::Array{<:Integer}, probes::Vector{P}) where{V, D, P<:ProbeAntenna}

Returns an IrregularFieldSampling struct for sampling an AntennaFieldRepresentation with arbitrary probes at irregularly distributed measurement positions.

Inputs:

• positions::Array{V} : An array of 3D position vectors. Julia must be able to convert the type V into an SVector{3,T<:Real}.
• eulerangles::Array{D} : An array of 3-Tuples denoting the Euler angles χ, ϑ, and , φ for rotating the probe antenna at each sample position. The definition of the Euler angles is aligned with their definition in the rotate function. Julia must be able to convert the type D into a Tuple{T,T,T}}.
• probeIDs::Array{<:Integer} : Array of probeIDs (= indices) to assign a probe from the list probes to each sample.
• probes::Vector{P<:ProbeAntenna}: Vector of probe antennas which occur in the field sampling

LocalθLocalϕInterpolateMap{Y,orderθ,orderϕ,T} <: InterpolateMap{Y,T}

Linear map which performs a local interpolation of predefined sampling points from spherically sampled data.

Type parameters

• Y :: SphereSamplingStrategy : Defines the sampling points of the spherically sampled original data.
• orderθ : Integer which defines the interpolation order along θ.
• orderϕ : Integer which defines the interpolation order along ϕ.
• T <: Real : Defines the number type to represent interpolation parameters, e.g. Float64 or Float32.

MLFMMSource{A,M,Y,C,X} <: AntennaFieldRepresentation{Radiated,C}

MLFMM representation of the contained Radiated AntennaFieldRepresentation.

Behaves like an AbstractVector{C} with extra context.

Type Parameters

• A <: AntennaFieldRepresentation: Type of the contained field representation
• M<:ResampleMap: Type of the resample map to aggregate the internal plane wave representations
• Y <: SphereSamplingStrategy : Sampling strategy for the internal plane wave representations
• C <: Number
• X <: MLFMMTree: Type of the underlying tree structure

OperationMap{C} <: LinearMaps.LinearMap{C}

Supertype for function-like object which corresponds to a certain method acting on an AntennaFieldRepresentation.

Type Parameters

• C <: Complex

PlaneWaveExpansion{P,Y,C} <: AntennaFieldRepresentation{P,C}

Collection of electromagnetic plane waves propagating into various directions.

Behaves like an AbstractVector{C} with extra context.

Type Parameters

• P <: PropagationType
• Y <: SphereSamplingStrategy : Defines the propagation directions of the stored plane wave samples
• C <: Number

PlaneWaveExpansion(P, samplingstrategy, Eθ, Eϕ, wavenumber)

Returns a collection of electromagnetic plane waves propagating into various directions.

Arguments:

• P::PropagationType: Radiated(), Incident(), or Absorbed()
• samplingstrategy<:SphereSamplingStrategy: sampling strategy which defines the propagation directions of the plane wave samples
• Eθ::Matrix{C}: θ-component amplitudes of the plane waves
• Eϕ::Matrix{C}: ϕ-component amplitudes of the plane waves
• wavenumber: wavenumber

ProbeAntenna{A}

Wrapper around an AntennaFieldRepresentation to indicate that it is used as a probe.

Type Parameters

• A <: AntennaFieldRepresentation

PropagationType

Indicator for Radiated, Absorbed, or Incident type field expansions.

RegularθRegularϕSampling <: SphereSamplingStrategy

A regular sampling strategy on the sphere has samples equiangularly distributed along the θ- and ϕ-coordinates.

ϕ ∈ {0, Δϕ, …, 2π - Δϕ} with Δϕ= 2π / Jϕ. θ ∈ {0, Δθ, …, π - Δθ / 2} if Jθ is odd or θ ∈ {0, Δθ, …, π} if Jθ is even with Δθ = 2π / Jθ if Jθ.

Fields:

• Jθ :: Integer
• Jϕ :: Integer

SphereSamplingStrategy

Supertype for sampling strategies on a sphere.

SphericalCoefficients{C} <: AbstractSphericalCoefficients{C}

Collections of coefficients for a spherical wave expansion.

Can be accessed like an AbstractVector{C} with a single index j or with a triple index (s,ℓ,m), where j = 2 * (ℓ * (ℓ + 1) + m - 1) + s.

Examples

values=ComplexF64.(collect(1:16))
sph_coefficients= SphericalCoefficients(values)
println(sph_coefficients[9])
println(sph_coefficients[1, 2, -1])
sph_coefficients[1, 2, -1] = 111.0im
println(sph_coefficients[9])

SphericalFieldSampling{Y,H,C} <: FieldSampling{C}

Field sampling on spherical measurement surface with measurement positions distributed according to a SphereSamplingStrategy.

Type Parameters

• Y <: SphereSamplingStrategy
• H <: AbstractSphericalCoefficients
• C <: Complex

SphericalTransmitMap{S,F,C} <: TransmitMap{S,F,C}

Linear map which corresponds to a transmit method between a SphericalWaveExpansion{Radiated} and a SphericalFieldSampling.

Type Parameters

• S <: SphericalWaveExpansion{Radiated}
• F <: SphericalFieldSampling
• C <: Complex

SphericalWaveExpansion{P,H,C} <: AntennaFieldRepresentation{P, C}

Representation of an electromagnetic field as superposition spherical vector wave functions.

Behaves like an AbstractVector{C} with extra context.

Type parameters

• P <: PropagationType
• H <: AbstractSphericalCoefficients{C <: Number} : defines how the spherical coefficients are ordered in memory.
• C <: Complex

SurfaceCurrentDensity{P <: PropagationType, E <: ElmagType, S <: BEAST.Space{<: Real} , C}  <: AntennaFieldRepresentation{P, C}

Representation of an electromagnetic field via equivalent surface currents.

Behaves like an AbstractVector{C} with extra context. The type parameter E defines if electric or magnetic surface current density.

TransmitMap{A, F, C} <: OperationMap{C}

Supertype for function-like object which corresponds to a transmit method.

Type Parameters

• A <: AntennaFieldRepresentation
• F <: FieldSampling
• C <: Complex

EfieldSampling(positions::Vector{V})

Returns an IrregularFieldSampling struct for sampling the electric field of an AntennaFieldRepresentation at given positions with Hertzian dipole probes.

For an input vector positions containing N position entries, the resulting IrregularFieldSampling provides the S₂₁-measurement signal in a N × 3 matrix, where the coloumns correspond to the x-, y-, and z-component of the E-field, respectively.

Input:

• positions::Vector{V} : A vector of 3D position vectors. Julia must be able to convert the type V into an SVector{3,T<:Real}.

HfieldSampling(positions::Vector{V})

Returns an IrregularFieldSampling struct for sampling the magnetic field of an AntennaFieldRepresentation at given positions with Fitzgerald dipole probes.

For an input vector positions containing N position entries, the resulting IrregularFieldSampling provides the S₂₁-measurement signal in a N × 3 matrix, where the coloumns correspond to the x-, y-, and z-component of the H-field, respectively.

Input:

• positions::Vector{V} : A vector of 3D position vectors. Julia must be able to convert the type V into an SVector{3,T<:Real}.

asvector(object::Union{AntennaFieldRepresentation,FieldSampling})

Return the coefficient vector of an AntennaFieldRepresentation or the measurement vector of a FieldSampling.

changerepresentation(Tnew::Type{<:AntennaFieldRepresentation}, aut_field::AntennaFieldRepresentation; kwargs...)

Return an AntennaFieldRepresentation of type Tnew which represents the same antenna fields as aut_field.

The available keyword arguments kwargs depend on Tnew

Examples

# Calculate spherical wave expansion from dipole collection
shifted_hdipole=HertzArray([[0.1,0.2,0.3]], [complex.([0.0, 0.0, 1.0])],[complex(1.0)], k0)
shifted_hspherical=changerepresentation(SphericalWaveExpansion{Radiated}, shifted_hdipole)

Keyword arguments

Tnew <: SphericalWaveExpansion:

• ϵ::Real = 1e-7 : Estimated accuracy of the new representation. Will be overwriten if Lmax is defined.
• Lmax::Int = definemodeorder(Pdip, aut_field, ϵ) : Equivalent mode order of the resulting spherical expansion.

Tnew <: PlaneWaveExpansion:

• ϵ::Real = 1e-7 : Estimated accuracy of the new representation. Will be overwriten if Lmax is defined.
• Lmax::Int = definemodeorder(Pdip, aut_field, ϵ) : Equivalent mode order of the resulting spherical expansion.
• samplingstrategy::SphereSamplingStrategy = _standardsampling(Lmax),: Samplingstrategy for the resulting PlaneWaveExpansion

See also

ChangeRepresentationMap

efield!(storage, aut_field::AntennaFieldRepresentation, R; reset = true)

Store E-field vector (in cartesian coordinates) of the field representation aut_field at location R in preallocated storage. If reset=true, storage is overwritten. If reset=false, the field is added to storage.

See also: efield, ehfield!

efield(aut_field::AntennaFieldRepresentation, R) -> [Ex;Ey;Ez]

Return the E-field vector (in cartesian coordinates) of the field representation aut_field at location R.

See also: efield!, ehfield

ehfield!(storage_efield, storage_hfield, aut_field::AntennaFieldRepresentation, R; reset=true)

Store E-field and H-field vector (in cartesian coordinates) of the field representation aut_field at location R in preallocated storages. If reset=true, storages are overwritten. If reset=false, the fields are added to storage_efield and storage_hfield.

For some AntennaFieldRepresentations, data can be shared between the calculations of electric and magnetic fields. Therefore, calling ehfield! may be slightly more performant than calling efield! and hfield! separately in some cases.

See also: efield!, hfield!, ehfield

ehfield(aut_field::AntennaFieldRepresentation, R) -> [Ex;Ey;Ez], [Hx;Hy;Hz]

Returns the E-field and H-field vector (in cartesian coordinates) of the field representation aut_field at location R.

For some AntennaFieldRepresentations, data can be shared between the calculations of electric and magnetic fields. Therefore, calling ehfield may be slightly more performant than calling efield and hfield separately in some cases.

See also: efield, hfield, ehfield!

equivalentorder(aut_field::AntennaFieldRepresentation; ϵ= 1e-7)

Return the estimated spherical mode order L which is needed forin a spherical mode expansion to approximate the aut_field to the desired accuracy ϵ.

farfield(aut_field::AntennaFieldRepresentation{Radiated}, (θ, ϕ) ) -> Eθ, Eϕ
farfield(aut_field::AntennaFieldRepresentation{Radiated}, θ, ϕ ) -> Eθ, Eϕ

Return Eθ,Eϕ-far-field tuple for radiating field representation into direction specified by θ and ϕ.

See also: efield, hfield

getwavenumber(aut_field::AntennaFieldRepresentation)

Returns the wavenumber k=2 π / λ which is stored in the AntennaFieldRepresentation.

hfield!(storage, aut_field::AntennaFieldRepresentation, R; reset = true)

Store H-field vector (in cartesian coordinates) of the field representation aut_field at location R in preallocated storage. If reset=true, storage is overwritten. If reset=false, the field is added to storage.

See also: hfield, ehfield!

hfield(aut_field::AntennaFieldRepresentation, R) -> [Hx;Hy;Hz]

Return the H-field vector (in cartesian coordinates) of the field representation aut_field at location R.

See also: hfield!, ehfield

interpolate( θϕ::Tuple{T,T}, data::Union{PlaneWaveExpansion, FieldSampling}) where{T<:Real}

Returns the two polarizations of spherically sampled data at the new location defined by the tuple θϕ.

See also:

• InterPolateMap
• LocalθLocalϕInterpolateMap

inverse(opmap::OperationMap)

Return inverse linear map of opmap.

j_to_sℓm(j)

Convert single index j to multi-index s ℓ m in spherical wave expansion

resample(targetsampling::SphereSamplingStrategy, data::Union{PlaneWaveExpansion, FieldSampling})

Returns data resampled according to targetsampling

See also:

• ResampleMap

rotate(aut_field :: AntennaFieldRepresentation, χ::Number, θ::Number, ϕ::Number) -> rotated_aut_field :: AntennaFieldRepresentation

Rotate the field representation where the rotation is defined by the Euler angles χ, θ, ϕ.

This is equivalent to the original representation being represented in a rotated coordinate system, where the coordinate axes of the original coordinate system must be rotated around the Euler angles -χ, -θ, -ϕ to get the rotated coordinate frame.

The rotations are performed according to the z,y,z- sequence defined by extrinsic rotations. Extrinsic rotations are elemental rotations that occur about the axes of the fixed coordinate, i.e., not the intrinsic coordinates of the rotated object. First, the object is rotated about the global z-axis by χ. Then, the object is rotated about the global y-axis by θ. Finally, the object is rotated about the global z-axis by ϕ.

Refer to https://en.wikipedia.org/wiki/Euler_angles for more details on Euler angles.

rotate!(rotated_aut_field :: AntennaFieldRepresentation, aut_field::AntennaFieldRepresentation, χ::Number, θ::Number, ϕ::Number)

In-place rotate the field representation where the rotation is defined by the Euler angles χ, θ, ϕ.

This is equivalent to the aut_field being represented in a rotated coordinate system, where the coordinate axes of the original coordinate system must be rotated around the Euler angles -χ, -θ, -ϕ to get the rotated coordinate frame.

samples(samplingstrategy::SphereSamplingStrategy) -> ( θs::Array{Float64,1}, ϕs::Array{Float64,1} )

Return sampling points θs, ϕs for the samplingstrategy.

setwavenumber!(aut_field::AntennaFieldRepresentation, val)

Sets the wavenumber k=2 π / λ which is stored in the AntennaFieldRepresentation to val.

spatialshift!(shifted_aut_field::AntennaFieldRepresentation, aut_field::AntennaFieldRepresentation, R::AbstractVector)

Preallocated shift of aut_field to new location R.

This is equivalent to the aut_field being represented in a translated coordinate system, where the coordinate axes of the original coordinate system must be translated by -R to get the translated coordinate frame.

spatialshift(aut_field::AntennaFieldRepresentation, R::AbstractVector) -> shifted_aut_field::AntennaFieldRepresentation

Spatially shift aut_field to new location R.

This is equivalent to the aut_field being represented in a translated coordinate system, where the coordinate axes of the original coordinate system must be translated by -R to get the translated coordinate frame.

sℓm_to_j(s,ℓ,m)

Convert multi-index s ℓ m to single index j in spherical wave expansion

transmit(aut_field :: AntennaFieldRepresentation, measurement_setup :: FieldSampling{C}) -> Vector{C}

Return sampled antenna field according to the sampling defined by measurement_setup.

weightsandsamples(samplingstrategy::SphereSamplingStrategy) -> ( θweights::Array{Float64,1}, ϕweights::Array{Float64,1}, θs::Array{Float64,1}, ϕs::Array{Float64,1} )

Return integration weights θweights, ϕweights and sampling points θs, ϕs for the samplingstrategy.