Base API

flux(im::IntensityMap)

Computes the flux of a intensity map

visibility(mimg, p)

Computes the complex visibility of model m at coordinates p. p corresponds to the coordinates of the model. These need to have the properties U, V and sometimes Ti for time and Fr for frequency.

Notes

If you want to compute the visibilities at a large number of positions consider using the visibilitymap.

Warn

This is only defined for analytic models. If you want to compute the visibility for a single point for a non-analytic model, please use the visibilitymap function and create an UnstructuredDomain with a single point.

visibilitymap(model::AbstractModel, p)

Computes the complex visibilities at the locations p.

visibilitymap!(vis::AbstractArray, model::AbstractModel, p)

Computes the complex visibilities vis in place at the locations p

intensitymap(model::AbstractModel, p::AbstractSingleDomain)

Computes the intensity map of model. For the inplace version see intensitymap!

intensitymap!(buffer::AbstractDimArray, model::AbstractModel)

Computes the intensity map of model by modifying the buffer

allocate_vismap(m::AbstractModel, g::AbstractSingleDomain)

Allocate the default map specialized by the grid g

allocate_imgmap(m::AbstractModel, g::AbstractSingleDomain)

Allocate the default map specialized by the grid g

create_imgmap(array, g::AbstractSingleDomain)

Create a map of values specialized by the grid g in the image domain. The default is to call create_map with the same arguments.

create_vismap(array, g::AbstractSingleDomain)

Create a map of values specialized by the grid g in the visibility domain. The default is to call create_map with the same arguments.

amplitude(model, p)

Computes the visibility amplitude of model m at the coordinate p. The coordinate p is expected to have the properties U, V, and sometimes Ti and Fr.

If you want to compute the amplitudemap at a large number of positions consider using the amplitudemap function.

amplitudemap(m::AbstractModel, p)

Computes the visibility amplitudemap of the model m at the coordinates p. The coordinates p are expected to have the properties U, V, and sometimes Ti and Fr.

bispectrum(model, p1, p2, p3)

Computes the complex bispectrum of model m at the uv-triangle p1 -> p2 -> p3

If you want to compute the bispectrum over a number of triangles consider using the bispectrummap function.

bispectrummap(m, p1, p2, p3)

Computes the closure phases of the model m at the triangles p1, p2, p3, where pi are coordinates.

closure_phase(model, p1, p2, p3, p4)

Computes the closure phase of model m at the uv-triangle u1,v1 -> u2,v2 -> u3,v3

If you want to compute closure phases over a number of triangles consider using the closure_phasemap function.

closure_phasemap(m,
               p1::AbstractArray
               p2::AbstractArray
               p3::AbstractArray
               )

Computes the closure phases of the model m at the triangles p1, p2, p3, where pi are coordinates.

logclosure_amplitude(model, p1, p2, p3, p4)

Computes the log-closure amplitude of model m at the uv-quadrangle u1,v1 -> u2,v2 -> u3,v3 -> u4,v4 using the formula

\[C = \log\left|\frac{V(u1,v1)V(u2,v2)}{V(u3,v3)V(u4,v4)}\right|\]

If you want to compute log closure amplitudemap over a number of triangles consider using the logclosure_amplitudemap function.

logclosure_amplitudemap(m::AbstractModel,
                      p1,
                      p2,
                      p3,
                      p4
                     )

Computes the log closure amplitudemap of the model m at the quadrangles p1, p2, p3, p4.

mpol(pimg::AbstractPolarizedModel, p)

Return the fractional linear polarization of the model m at point p.

polellipse(pimg::AbstractPolarizedModel, p)

Compute the polarization of the polarized model.

polarization(pimg::AbstractPolarizedModel, p)

Return the polarization vector (Q, U, V) of the model m at point p.

fracpolarization(pimg::AbstractPolarizedModel, p)

Return the fractional polarization vector (Q/I, U/I, V/I) of the model m at point p.

mbreve(pimg, p)

Explicit m̆ function used for convenience.

AbstractModel

The Comrade abstract model type. To instantiate your own model type you should subtybe from this model. Additionally you need to implement the following methods to satify the interface:

Mandatory Methods

• visanalytic: defines whether the model visibilities can be computed analytically. If yes then this should return IsAnalytic() and the user must to define visibility_point. If not analytic then visanalytic should return NotAnalytic().
• imanalytic: defines whether the model intensities can be computed pointwise. If yes then this should return IsAnalytic() and the user must to define intensity_point. If not analytic then imanalytic should return NotAnalytic().
• radialextent: Provides a estimate of the radial extent of the model in the image domain. This is used for estimating the size of the image, and for plotting.
• flux: Returns the total flux of the model.
• intensity_point: Defines how to compute model intensities pointwise. Note this is must be defined if imanalytic(::Type{YourModel})==IsAnalytic().
• visibility_point: Defines how to compute model visibilties pointwise. Note this is must be defined if visanalytic(::Type{YourModel})==IsAnalytic().

Optional Methods:

• ispolarized: Specified whether a model is intrinsically polarized (returns IsPolarized()) or is not (returns NotPolarized()), by default a model is NotPolarized()
• visibilitymap_analytic: Vectorized version of visibility_point for models where visanalytic returns IsAnalytic()
• visibilitymap_numeric: Vectorized version of visibility_point for models where visanalytic returns NotAnalytic() typically these are numerical FT's
• intensitymap_analytic: Computes the entire image for models where imanalytic returns IsAnalytic()
• intensitymap_numeric: Computes the entire image for models where imanalytic returns NotAnalytic()
• intensitymap_analytic!: Inplace version of intensitymap
• intensitymap_numeric!: Inplace version of intensitymap

visanalytic(::Type{<:AbstractModel})

Determines whether the model is pointwise analytic in Fourier domain, i.e. we can evaluate its fourier transform at an arbritrary point.

If IsAnalytic() then it will try to call visibility_point to calculate the complex visibilities. Otherwise it fallback to using the FFT that works for all models that can compute an image.

imanalytic(::Type{<:AbstractModel})

Determines whether the model is pointwise analytic in the image domain, i.e. we can evaluate its intensity at an arbritrary point.

If IsAnalytic() then it will try to call intensity_point to calculate the intensity.

ispolarized(::Type)

Trait function that defines whether a model is polarized or not.

radialextent(model::AbstractModel)

Provides an estimate of the radial size/extent of the model. This is used internally to estimate image size when plotting and using modelimage

DensityAnalytic

Internal type for specifying the nature of the model functions. Whether they can be easily evaluated pointwise analytic. This is an internal type that may change.

struct IsAnalytic <: ComradeBase.DensityAnalytic

Defines a trait that a states that a model is analytic. This is usually used with an abstract model where we use it to specify whether a model has a analytic fourier transform and/or image.

struct NotAnalytic <: ComradeBase.DensityAnalytic

Defines a trait that a states that a model is analytic. This is usually used with an abstract model where we use it to specify whether a model has does not have a easy analytic fourier transform and/or intensity function.

visibility_point(model::AbstractModel, p)

Function that computes the pointwise visibility. This must be implemented in the model interface if visanalytic(::Type{MyModel}) == IsAnalytic()

visibilties_analytic(model, p)

Computes the visibilties of a model using using the analytic visibility expression given by visibility_point.

visibilties_analytic!(vis, model)

Computes the visibilties of a model in-place, using using the analytic visibility expression given by visibility_point.

visibilties_numeric(model, p)

Computes the visibilties of a model using a numerical fourier transform. Note that none of these are implemented in ComradeBase. For implementations please see Comrade.

visibilties_numeric!(vis, model)

Computes the visibilties of a model in-place using a numerical fourier transform. Note that none of these are implemented in ComradeBase. For implementations please see Comrade.

intensity_point(model::AbstractModel, p)

Function that computes the pointwise intensity if the model has the trait in the image domain IsAnalytic(). Otherwise it will use construct the image in visibility space and invert it.

intensitymap_analytic(m::AbstractModel, p::AbstractSingleDomain)

Computes the IntensityMap of a model m using the image dimensions p by broadcasting over the analytic intensity_point method.

intensitymap_analytic!(img::IntensityMap, m::AbstractModel)

Updates the img using the model m by broadcasting over the analytic intensity_point method.

intensitymap_numeric(m::AbstractModel, p::AbstractSingleDomain)

Computes the IntensityMap of a model m at the image positions p using a numerical method. This has to be specified uniquely for every model m if imanalytic(typeof(m)) === NotAnalytic(). See Comrade.jl for example implementations.

intensitymap_numeric!(img::IntensityMap, m::AbstractModel)

Updates the img using the model m using a numerical method. This has to be specified uniquely for every model m if imanalytic(typeof(m)) === NotAnalytic(). See Comrade.jl for example implementations.

imagepixels(fovx, fovy, nx, ny, x0=0, y0=0; posang=0.0, executor=Serial(), header=NoHeader())

Construct a grid of pixels with a field of view fovx and fovy and nx and ny pixels. This points are the pixel centers and the field of view goes from the edge of the first pixel to the edge of the last pixel. The x0, y0 offsets shift the image origin over by (x0, y0) in the image plane.

Arguments:

• fovx::Real: The field of view in the x-direction
• fovy::Real: The field of view in the y-direction
• nx::Integer: The number of pixels in the x-direction
• ny::Integer: The number of pixels in the y-direction

Keyword Arguments:

• x0::Real=0: The x-offset of the image
• y0::Real=0: The y-offset of the image
• posang::Real=0: The position angle of the grid, relative to RA=0 axis.
• executor=Serial(): The executor to use for the grid, default is serial execution
• header=NoHeader(): The header to use for the grid

RectiGrid(dims::NamedTuple{Na}; executor=Serial(), header=ComradeBase.NoHeader(), posang=0.0)
RectiGrid(dims::NTuple{N, <:DimensionalData.Dimension}; executor=Serial(), header=ComradeBase.NoHeader(), posang=0.0)

Creates a rectilinear grid of pixels with the dimensions dims. The convention is that the first two dimension are the spatial dimensions X/U and Y/V. The remaining dimensions can be anything, for example:

• (:X, :Y, :Ti, :Fr)
• (:X, :Y, :Fr, :Ti)
• (:X, :Y) # spatial only

where X/U,Y/V are the RA and DEC spatial dimensions in image/visibility space respectively, Ti is the time dimension and Fr is the frequency dimension.

Note that the majority of the time users should just call imagepixels to create a spatial grid.

Optional Arguments

• executor: specifies how different models are executed. The default is Serial which mean serial CPU computations. For threaded computations use ThreadsEx() or load OhMyThreads.jl to uses their schedulers.
• header: specified underlying header information for the grid. This is used to store information about the image such as the source, RA and DEC, MJD.
• posang: specifies the position angle of the grid, relative to RA=0 axis. Note that when posang != 0 the X and Y coordinate are relative to the rotated grid and not the on sky RA and DEC orientation. To see the true on sky points you can access them by calling domainpoints(grid).

Examples

dims = RectiGrid((X(-5.0:0.1:5.0), Y(-4.0:0.1:4.0), Ti([1.0, 1.5, 1.75]), Fr([230, 345])); executor=ThreadsEx())
dims = RectiGrid((X = -5.0:0.1:5.0, Y = -4.0:0.1:4.0, Ti = [1.0, 1.5, 1.75], Fr = [230, 345]); executor=ThreadsEx()))

UnstructuredDomain(dims::NamedTuple; executor=Serial(), header=ComradeBase.NoHeader)

Builds an unstructured grid (really a vector of points) from the dimensions dims. The executor is used controls how the grid is computed when calling visibilitymap or intensitymap. The default is Serial which mean regular CPU computations. For threaded execution use ThreadsEx() or load OhMyThreads.jl to uses their schedulers.

Note that unlike RectiGrid which assigns dimensions to the grid points, UnstructuredDomain does not. This is becuase the grid is unstructured the points are a cloud in a space

dims(g::AbstractSingleDomain)

Returns a tuple containing the dimensions of g. For a named version see ComradeBase.named_dims

named_dims(g::AbstractSingleDomain)

Returns a named tuple containing the dimensions of g. For a unnamed version see dims

axisdims(img::IntensityMap)
axisdims(img::IntensityMap, p::Symbol)

Returns the keys of the IntensityMap as the actual internal AbstractRectiGrid object. Optionall the user can ask for a specific dimension with p

domainpoints(g::AbstractSingleDomain)

Create a grid iterator that can be used to iterate through different points. All grid methods must implement this method.

fieldofview(img::IntensityMap)
fieldofview(img::IntensityMap)

Returns a named tuple with the field of view of the image.

pixelsizes(img::IntensityMap)
pixelsizes(img::AbstractRectiGrid)

Returns a named tuple with the spatial pixel sizes of the image.

phasecenter(img::IntensityMap)

Computes the phase center of an intensity map. Note this is the pixels that is in the middle of the image.

executor(g::AbstractSingleDomain)

Returns the executor used to compute the intensitymap or visibilitymap

Serial()

Uses serial execution when computing the intensitymap or visibilitymap

ThreadsEx(;scheduler::Symbol = :dynamic)

Uses Julia's Threads @threads macro when computing the intensitymap or visibilitymap. You can choose from Julia's various schedulers by passing the scheduler as a parameter. The default is :dynamic, but it isn't considered part of the stable API and may change at any moment.

header(g::AbstractSingleDomain)

Returns the headerinformation of the dimensions g

header(img::IntensityMap)

Retrieves the header of an IntensityMap

NoHeader

MinimalHeader{T}

A minimal header type for ancillary image information.

Fields

• source: Common source name

• ra: Right ascension of the image in degrees (J2000)

• dec: Declination of the image in degrees (J2000)

• mjd: Modified Julian Date in days

• frequency: Frequency of the image in Hz

struct IntensityMap{T, N, D, G<:(ComradeBase.AbstractRectiGrid{D}), A<:AbstractArray{T, N}, R<:Tuple, Na} <: AbstractDimArray{T, N, D, A<:AbstractArray{T, N}}

This type is the basic array type for all images and models that obey the ComradeBase interface. The type is a subtype of DimensionalData.AbstractDimArray however, we make a few changes to support the Comrade API.

1. The dimensions should be specified by an AbstractRectiGrid interface. Usually users just need the RectiGrid grid, for rectilinear grids.
2. There are two ways to access the dimensions of the array. dims(img) will return the usual DimArray dimensions, i.e. a Tuple{DimensionalData.Dim, ...}. The other way to access the array dimensions is using the getproperty, e.g., img.X will return the RA/X grid locations but stripped of the usual DimensionalData.Dimension material. This getproperty behavior is *NOT CONSIDERED** part of the stable API and may be changed in the future.
3. Metadata is stored in the AbstractRectiGrid type through the header property and can be accessed through metadata or header

The most common way to create a IntensityMap is to use the function definitions

julia> g = imagepixels(10.0, 10.0, 128, 128; header=NoHeader())
julia> X = g.X; Y = g.Y
julia> data = rand(128, 128)
julia> img1 = IntensityMap(data, g)
julia> img2 = IntensityMap(data, (;X, Y); header=header(g))
julia> img1 == img2
true
julia> img3 = IntensityMap(data, 10.0, 10.0; header=NoHeader())

Broadcasting, map, and reductions should all just obey the DimensionalData interface.

IntensityMap(data::AbstractArray, g::AbstractRectiGrid; refdims=(), name=Symbol(""))

Creates a IntensityMap with the pixel fluxes data on the grid g. Optionally, you can specify a set of reference dimensions refdims as a tuple and a name for array name.

UnstructuredMap(data::AbstractVector, dims::UnstructuredDomain)

A map that is defined on an unstructured domain. This is typically just a vector of values. The vector of locations of the visibilities are stored in dims. Otherwise this behaves very similarly to IntensityMap, except that is isn't a grid.

For instance the locations of the visibilities can be accessed with axisdims, as well as the usual getproperty and propertynames functions. Like with IntensityMap during execution the executor is used to determine the execution context.

Returns the base image of a intensity map type object

centroid(im::AbstractIntensityMap)

Computes the image centroid aka the center of light of the image.

For polarized maps we return the centroid for Stokes I only.

second_moment(im::AbstractIntensityMap; center=true)

Computes the image second moment tensor of the image. By default we really return the second cumulant or centered second moment, which is specified by the center argument.

For polarized maps we return the second moment for Stokes I only.

second_moment(im::IntensityMap; center=true)

Computes the image second moment tensor of the image. By default we really return the second cumulant or centered second moment, which is specified by the center argument.

stokes(m::AbstractPolarizedModel, p::Symbol)

Extract the specific stokes component p from the polarized model m

stokes(m::AbstractArray{<:StokesParams}, p::Symbol)

Extract the specific stokes component p from the polarized image m.

abstract type AbstractPolarizedModel <: ComradeBase.AbstractModel

A generic polarized model. To implement the use needs to follow the AbstractModel implementation instructions. In addtion there is an optional method stokes(model, p::Symbol) which extracts the specific stokes parameter of the model. The default that the different stokes parameters are stored as fields of the model. To overwrite this behavior overload the function.

struct StokesParams{T} <: StaticArraysCore.FieldVector{4, T}

Static vector that holds the stokes parameters of a polarized complex visibility

To convert between a StokesParams and CoherencyMatrix use the convert function

convert(::CoherencyMatrix, StokesVector(1.0, 0.1, 0.1, 0.4))

abstract type ElectricFieldBasis

An abstract type whose subtypes denote a specific electric field basis.

struct RPol <: PolarizedTypes.ElectricFieldBasis

The right circular electric field basis, i.e. a right-handed circular feed.

struct LPol <: PolarizedTypes.ElectricFieldBasis

The left circular electric field basis, i.e. a left-handed circular feed.

struct XPol <: PolarizedTypes.ElectricFieldBasis

The horizontal or X electric feed basis, i.e. the horizontal linear feed.

struct YPol <: PolarizedTypes.ElectricFieldBasis

The vertical or Y electric feed basis, i.e. the vertical linear feed.

struct PolBasis{B1<:Union{Missing, PolarizedTypes.ElectricFieldBasis}, B2<:Union{Missing, PolarizedTypes.ElectricFieldBasis}}

Denotes a general polarization basis, with basis vectors (B1,B2) which are typically <: Union{ElectricFieldBasis, Missing}

CirBasis <: PolBasis

Measurement uses the circular polarization basis, which is typically used for circular feed interferometers.

LinBasis <: PolBasis

Measurement uses the linear polarization basis, which is typically used for linear feed interferometers.

struct CoherencyMatrix{B1, B2, T} <: StaticArraysCore.FieldMatrix{2, 2, T}

Coherency matrix for a single baseline with bases B1 and B2. The two bases correspond to the type of feeds used for each telescope and should be subtypes of PolBasis. To see which bases are implemented type subtypes(Rimes.PolBasis) in the REPL.

For a circular basis the layout of the coherency matrix is

RR* RL*
LR* RR*

which can be constructed using

c = CoherencyMatrix(RR, LR, RL, LL, CirBasis())

For a linear basis the layout of the coherency matrix is

XX* XY*
YX* YY*

which can be constructed using

c = CoherencyMatrix(XX, YX, XY, YY, CirBasis())

For a mixed (e.g., circular and linear basis) the layout of the coherency matrix is

RX* RY*
LX* LY*

or e.g., linear and circular the layout of the coherency matrix is

XR* XL*
YR* YL*

These coherency matrices can be constructed using:

# Circular and linear feeds i.e., |R><X|
c = CoherencyMatrix(RX, LX, RY, LY, LinBasis(), CirBasis())
# Linear and circular feeds i.e., |X><R|
c = CoherencyMatrix(XR, YR, XL, YL, LinBasis(), CirBasis())

evpa(m::Union{StokesParams, CoherencyMatrix})

Compute the evpa of a stokes vect or cohereny matrix.

evpa(pimg::AbstractPolarizedModel, p)

electric vector position angle or EVPA of the polarized model pimg at p

m̆(m::Union{StokesParameters{<:Complex}, CoherencyMatrix)

Computes the complex fractional linear polarization of the complex or visibility quantities. Note that this function can also be called used mbreve

m̆(pimg::AbstractPolarizedModel, p)
mbreve(pimg::AbstractPolarizedModel, p)

Computes the fractional linear polarization in the visibility domain

m̆ = (Q̃ + iŨ)/Ĩ

To create the symbol type m\breve in the REPL or use the mbreve function.

linearpol(s)

Computes linearpol from a set of stokes parameters s.

linearpol(pimg::AbstractPolarizedModel, p)

Return the complex linear polarization of the model m at point p.

innerprod(::Type{T}, XPol(), YPol())

Computes the complex inner product of two elements of a complex Hilbert space X and Y where base element of the output is T.

basis_components([T=Float64,], e::ElectricFieldBasis, b::PolBasis)

Returns a static vector that contains the components of the electric field basis vector e in terms of the polarization basis b. The first argument is optionally the eltype of the static vector.

Examples

julia> basis_components(Float64, R(), PolBasis{XPol,Y}())
2-element StaticArraysCore.SVector{2, ComplexF64} with indices SOneTo(2):
 0.7071067811865475 + 0.0im
                0.0 - 0.7071067811865475im

julia> basis_components(R(), PolBasis{XPol,Y}())
2-element StaticArraysCore.SVector{2, ComplexF64} with indices SOneTo(2):
 0.7071067811865475 + 0.0im
                0.0 - 0.7071067811865475im


julia> basis_components(Float64, X(), PolBasis{XPol,Y}())
2-element StaticArraysCore.SVector{2, ComplexF64} with indices SOneTo(2):
 1.0 + 0.0im
 0.0 + 0.0im

basis_transform([T=Float64,], b1::PolBasis, b2::PolBasis)
basis_transform([T=Float64,], b1::PolBasis=>b2::PolBasis)

Produces the transformation matrix that transforms the vector components from basis b1 to basis b2. This means that if for example E is the circular basis then basis_transform(CirBasis=>LinBasis)E is in the linear basis. In other words the columns of the transformation matrix are the coordinate vectors of the new basis vectors in the old basis.

Example

julia> basis_transform(CirBasis()=>LinBasis())
2×2 StaticArraysCore.SMatrix{2, 2, ComplexF64, 4} with indices SOneTo(2)×SOneTo(2):
 0.707107-0.0im       0.707107-0.0im
      0.0-0.707107im       0.0+0.707107im

polarization(s)

Returns the (Q, U, V) polarization vector as a 3-element static vector.

polarization(pimg::AbstractPolarizedModel, p)

Return the polarization vector (Q, U, V) of the model m at point p.

fracpolarization(s)

Returns the (Q/I, U/I, V/I) fractional polarization vector as a 3-element static vector.

fracpolarization(pimg::AbstractPolarizedModel, p)

Return the fractional polarization vector (Q/I, U/I, V/I) of the model m at point p.

_visibilitymap(model::AbstractModel, p)

Internal method used for trait dispatch and unpacking of args arguments in visibilities

_visibilitymap!(model::AbstractModel, p)

Internal method used for trait dispatch and unpacking of args arguments in visibilities!

create_map(array, g::AbstractSingleDomain)

Create a map of values specialized by the grid g.

@threaded executor expr

Threads the for-loop expression expr using the specified executor. The executor must be one of ThreadsEx or Serial. Note that if the Threads.nthreads() == 1 we automatically default to a regular for-loop to prevent overhead.