A Class for performing the Clark Clean Algorithm on Arrays. More...

#include <ClarkCleanLatModel.h>

Inheritance diagram for casa::ClarkCleanLatModel:

Public Member Functions
	ClarkCleanLatModel ()
	The default constructor does nothing more than initialise a zero length array to hold the deconvolved model. More...

	ClarkCleanLatModel (casacore::Lattice< casacore::Float > &model)
	Construct the ClarkCleanLatModel object and initialise the model. More...

	ClarkCleanLatModel (casacore::Lattice< casacore::Float > &model, casacore::Lattice< casacore::Float > &mask)
	Construct the ClarkCleanLatModel object and initialise the model ans mask. More...

	ClarkCleanLatModel (casacore::Lattice< casacore::Float > &model, casacore::Lattice< casacore::Float > &residual, casacore::Lattice< casacore::Float > &mask)
	Construct the ClarkCleanLatModel object and initialise the model ans mask. More...

virtual	~ClarkCleanLatModel ()
	Destroy! More...

virtual const casacore::Lattice < casacore::Float > &	getModel () const
	Return the current model. More...

virtual void	setModel (const casacore::Lattice< casacore::Float > &model)
	Set the current model. More...

virtual void	setModel (casacore::Lattice< casacore::Float > &model)

const casacore::Lattice < casacore::Float > &	getMask () const

void	setMask (const casacore::Lattice< casacore::Float > &mask)

void	setResidual (casacore::Lattice< casacore::Float > &residual)

virtual const casacore::Lattice < casacore::Float > &	getResidual () const

casacore::Int	getNumberIterations ()

casacore::Float	getMaxResidual ()

casacore::Bool	solve (LatConvEquation &eqn)
	Using a Clark clean deconvolution proceedure solve for an improved estimate of the deconvolved object. More...

casacore::Bool	singleSolve (LatConvEquation &eqn, casacore::Lattice< casacore::Float > &residual)

virtual void	setChoose (const casacore::Bool askForChoice)
	The user can be asked whether to stop after every minor cycle. More...

virtual casacore::Bool	getChoose ()

virtual void	setPsfPatchSize (const casacore::IPosition &psfPatchSize)
	These remaining functions set various "knobs" that the user can tweak and are specific to the Clark clean algorithm. More...

virtual casacore::IPosition	getPsfPatchSize ()

virtual void	setHistLength (const casacore::uInt histBins)
	Set the size of the histogram used to determine how many pixels are "active" in a minor iteration. More...

virtual casacore::uInt	getHistLength ()

virtual void	setMaxNumberMinorIterations (const casacore::uInt maxNumMinorIterations)
	Set the maximum number of minor iterations to perform for each major cycle. More...

virtual casacore::uInt	getMaxNumberMinorIterations ()

virtual void	setInitialNumberIterations (const casacore::uInt initialNumberIterations)
	Set and get the initial number of iterations. More...

virtual casacore::uInt	getInitialNumberIterations ()

virtual void	setMaxNumberMajorCycles (const casacore::uInt maxNumMajorCycles)
	Set the maximum number of major cycles to perform. More...

virtual casacore::uInt	getMaxNumberMajorCycles ()

virtual void	setMaxNumPix (const casacore::uInt maxNumPix)
	Set the maximum number of active pixels to use in the minor iterations. More...

virtual casacore::uInt	getMaxNumPix ()

virtual void	setMaxExtPsf (const casacore::Float maxExtPsf)
	Set the maximum exterior psf value. More...

virtual casacore::Float	getMaxExtPsf ()

casacore::Float	modelFlux ()
	The total flux density in the model. More...

virtual void	setSpeedup (const casacore::Float speedup)
	An exponent on the F(m,n) factor (see Clark[1980]) which influences how quickly active pixels are treated as unreliable. More...

virtual casacore::Float	getSpeedup ()

virtual void	setCycleFactor (const casacore::Float factor)
	Set the cycle factor....the larger this is the shallower is the minor cycle. More...

virtual void	setProgress (ClarkCleanProgress &ccp)
	Set/get the progress display. More...

virtual ClarkCleanProgress &	getProgress ()

Public Member Functions inherited from casa::LinearModel< casacore::Lattice< casacore::Float > >
virtual	~LinearModel ()
	A virtual destructor is necessary. More...

Public Member Functions inherited from casa::Iterate
	Iterate ()
	Constructor. More...

virtual	~Iterate ()

void	setFree ()
	Is this a free variable? More...

void	setNotFree ()

casacore::Bool	free ()

void	setNumberIterations (const casacore::Int n)

void	setGain (const casacore::Float g)

void	setTolerance (const casacore::Float t)

void	setThreshold (const casacore::Float t)

void	setMode (const casacore::String m)

casacore::Int	numberIterations ()

casacore::Float	gain ()

casacore::Float	tolerance ()

virtual casacore::Float	threshold ()

const casacore::String	mode ()

Private Member Functions
void	doMinorIterations (CCList &activePixels, casacore::Matrix< casacore::Float > &psfPatch, casacore::Float fluxLimit, casacore::uInt &numberIterations, casacore::Float Fmn, const casacore::uInt totalIterations, casacore::Float &totalFlux)
	Do all the minor iterations for one major cycle. More...

void	cacheActivePixels (CCList &activePixels, const casacore::Lattice< casacore::Float > &residual, casacore::Float fluxLimit)

void	absHistogram (casacore::Vector< casacore::Int > &hist, casacore::Float &minVal, casacore::Float &maxVal, const casacore::Lattice< casacore::Float > &data)
	make histogram of absolute values in array More...

casacore::Float	biggestResiduals (casacore::Float &maxRes, const casacore::uInt maxNumPix, const casacore::Float fluxLimit, const casacore::Lattice< casacore::Float > &residual)
	Determine the flux limit if we only select the maxNumPix biggest residuals. More...

casacore::Float	getPsfPatch (casacore::Matrix< casacore::Float > &psfPatch, LatConvEquation &eqn)
	Work out the size of the Psf patch to use. More...

casacore::Float	maxResidual (const casacore::Lattice< casacore::Float > &residual)
	The maximum residual is the absolute maximum. More...

void	maxVect (casacore::Block< casacore::Float > &maxVal, casacore::Float &absVal, casacore::Int &offset, const CCList &activePixels)

void	subtractComponent (CCList &activePixels, const casacore::Block< casacore::Float > &maxVal, const casacore::Block< casacore::Int > &maxPos, const casacore::Matrix< casacore::Float > &psf)

casacore::Float	absMaxBeyondDist (const casacore::IPosition &maxDist, const casacore::IPosition &centre, const casacore::Lattice< casacore::Float > &psf)

casacore::Bool	stopnow ()

casacore::Int	getbig (casacore::Float const pixValPtr, casacore::Int const pixPosPtr, const casacore::Int nPix, const casacore::Float fluxLimit, const casacore::Float const residualPtr, const casacore::Float const maskPtr, const casacore::uInt npol, const casacore::Int nx, const casacore::Int ny)

void	updateModel (CCList &cleanComponents)

Detailed Description

A Class for performing the Clark Clean Algorithm on Arrays.

Intended use:

Public interface

Review Status

Date Reviewed:: yyyy/mm/dd

Prerequisite

ResidualEquation/LatConvEquation
LinearModel/LinearEquation Paradigm

Etymology

This class is called ClarkCleanLatModel because thats the algorithm it uses deconvolve the lattice-based model.

Synopsis

This class is used to perform the Clark Clean Algorithm on an Array. Only the deconvolved model of the sky are directly stored by this class. The point spread function (psf) and convolved (dirty) image are stored in a companion class which is must be derived from ResidualEquation.

The cleaning works like this. The user constructs a ClarkCleanLatModel by specifying an initial model of the sky. This can by be one,two,three... dimensional depending on the dimension of the psf (see below). The user then constructs a class which implements the forward equation between the model and the dirty image. Typically this will be the ConvolutionEquation class, although any class which has a ResidualEquation interface will be work (but perhaps very slowly, as the ConvolutionEquation class has member functions optimised for cleaning)

The user then calls the solve() function (with the appropriate equation class as an arguement), and this class will perform the Clark clean. The various clean parameters are set (prior to calling solve) using the functions derived from the Iterate class, in particular setGain(), setNumberIterations() & setThreshold() (to set a flux limit).

The solve() function does not return either the deconvolved model or the residuals. The solved model can be obtained using the getModel() function (derived from ArrayModel()) and the residual can be obtained using the residual() member function of the Convolution/Residual Equation Class.

The size and shape of the model used in this class MUST be the same as the convolved data (Dirty Image), stored in the companion ResidualEquation Class. However the model (and convolved data) can have more dimensions than the psf, as well as a different size (either larger or smaller). When the dimensionality is different the cleaning is done independendtly in each "plane" of the model. (Note this has not been implemented yet but is relatively simple to do if necessary).

This multi-dimensionalty is exploited when cleaning arrays of StokesVectors. Here the casacore::Array of StokesVectors is decomposed into a stack of 4 Floating point arrays and the cleaning is done on all the the arrays simultaneosly. The criterion for choosing the brightest pixel has been generalised by using the "length" of the Stokesvector in 4 dimensional space.

A companion class to this one is MaskedClarkCleanLatModel. This provides the same functionality but is used with MaskedArrays which indicate which regions of the model to search for clean components.

Example

 casacore::Matrix<casacore::Float> psf(12,12), dirty(10,10), initialModel(10,10);
...put appropriate values into psf, dirty, & initialModel...\.
 ClarkCleanLatModel<casacore::Float> deconvolvedModel(initialModel); 
 ConvolutionEquation convEqn(psf, dirty);
 deconvolvedModel.setGain(0.2); 
 deconvolvedModel.setNumberIterations(1000);
 casacore::Bool convWorked = deconvolvedModel.solve(convEqn);
 if (convWorked)
 ConvEqn.residual(deconvolvedModel, finalResidual);

Motivation

This class is needed to deconvolve images.

Template Type Argument Requirements (T)

have tested this class with Arrays of Float StokesVector

To Do

Make changes so that multidimensions work as advertised
compare timing with other clean implementations (ie, Mark's CleanTools, SDE, AIPS & miriad)

Definition at line 149 of file ClarkCleanLatModel.h.

Constructor & Destructor Documentation

casa::ClarkCleanLatModel::ClarkCleanLatModel ( )

The default constructor does nothing more than initialise a zero length array to hold the deconvolved model.

If this constructor is used then the actual model must be set using the setModel() function of the LatticeModel class.

casa::ClarkCleanLatModel::ClarkCleanLatModel ( casacore::Lattice< casacore::Float > & model )

Construct the ClarkCleanLatModel object and initialise the model.

casa::ClarkCleanLatModel::ClarkCleanLatModel	(	casacore::Lattice< casacore::Float > &	model,
		casacore::Lattice< casacore::Float > &	mask
	)

Construct the ClarkCleanLatModel object and initialise the model ans mask.

casa::ClarkCleanLatModel::ClarkCleanLatModel	(	casacore::Lattice< casacore::Float > &	model,
		casacore::Lattice< casacore::Float > &	residual,
		casacore::Lattice< casacore::Float > &	mask
	)

Construct the ClarkCleanLatModel object and initialise the model ans mask.

virtual casa::ClarkCleanLatModel::~ClarkCleanLatModel ( )

virtual

Destroy!

Member Function Documentation

void casa::ClarkCleanLatModel::absHistogram	(	casacore::Vector< casacore::Int > &	hist,
		casacore::Float &	minVal,
		casacore::Float &	maxVal,
		const casacore::Lattice< casacore::Float > &	data
	)

private

make histogram of absolute values in array

casacore::Float casa::ClarkCleanLatModel::absMaxBeyondDist	(	const casacore::IPosition &	maxDist,
		const casacore::IPosition &	centre,
		const casacore::Lattice< casacore::Float > &	psf
	)

private

casacore::Float casa::ClarkCleanLatModel::biggestResiduals	(	casacore::Float &	maxRes,
		const casacore::uInt	maxNumPix,
		const casacore::Float	fluxLimit,
		const casacore::Lattice< casacore::Float > &	residual
	)

private

Determine the flux limit if we only select the maxNumPix biggest residuals.

Flux limit is not exact due to quantising by the histogram

void casa::ClarkCleanLatModel::cacheActivePixels	(	CCList &	activePixels,
		const casacore::Lattice< casacore::Float > &	residual,
		casacore::Float	fluxLimit
	)

private

void casa::ClarkCleanLatModel::doMinorIterations	(	CCList &	activePixels,
		casacore::Matrix< casacore::Float > &	psfPatch,
		casacore::Float	fluxLimit,
		casacore::uInt &	numberIterations,
		casacore::Float	Fmn,
		const casacore::uInt	totalIterations,
		casacore::Float &	totalFlux
	)

private

Do all the minor iterations for one major cycle.

Cleaning stops when the flux or iteration limit is reached.

casacore::Int casa::ClarkCleanLatModel::getbig	(	casacore::Float const *	pixValPtr,
		casacore::Int const *	pixPosPtr,
		const casacore::Int	nPix,
		const casacore::Float	fluxLimit,
		const casacore::Float *const	residualPtr,
		const casacore::Float *const	maskPtr,
		const casacore::uInt	npol,
		const casacore::Int	nx,
		const casacore::Int	ny
	)

private

virtual casacore::Bool casa::ClarkCleanLatModel::getChoose ( )

virtual

virtual casacore::uInt casa::ClarkCleanLatModel::getHistLength ( )

virtual

virtual casacore::uInt casa::ClarkCleanLatModel::getInitialNumberIterations ( )

virtual

const casacore::Lattice<casacore::Float>& casa::ClarkCleanLatModel::getMask ( ) const

virtual casacore::Float casa::ClarkCleanLatModel::getMaxExtPsf ( )

virtual

virtual casacore::uInt casa::ClarkCleanLatModel::getMaxNumberMajorCycles ( )

virtual

virtual casacore::uInt casa::ClarkCleanLatModel::getMaxNumberMinorIterations ( )

virtual

virtual casacore::uInt casa::ClarkCleanLatModel::getMaxNumPix ( )

virtual

casacore::Float casa::ClarkCleanLatModel::getMaxResidual ( )

inline

Definition at line 184 of file ClarkCleanLatModel.h.

References itsMaxRes.

virtual const casacore::Lattice<casacore::Float>& casa::ClarkCleanLatModel::getModel ( ) const

inlinevirtual

Return the current model.

Implements casa::LinearModel< casacore::Lattice< casacore::Float > >.

Definition at line 172 of file ClarkCleanLatModel.h.

References itsModelPtr.

casacore::Int casa::ClarkCleanLatModel::getNumberIterations ( )

inline

Definition at line 182 of file ClarkCleanLatModel.h.

References casa::Iterate::numberIterations().

virtual ClarkCleanProgress& casa::ClarkCleanLatModel::getProgress ( )

inlinevirtual

Definition at line 281 of file ClarkCleanLatModel.h.

References itsProgressPtr.

casacore::Float casa::ClarkCleanLatModel::getPsfPatch	(	casacore::Matrix< casacore::Float > &	psfPatch,
		LatConvEquation &	eqn
	)

private

Work out the size of the Psf patch to use.

virtual casacore::IPosition casa::ClarkCleanLatModel::getPsfPatchSize ( )

virtual

virtual const casacore::Lattice<casacore::Float>& casa::ClarkCleanLatModel::getResidual ( ) const

inlinevirtual

Definition at line 180 of file ClarkCleanLatModel.h.

References itsResidualPtr.

virtual casacore::Float casa::ClarkCleanLatModel::getSpeedup ( )

virtual

casacore::Float casa::ClarkCleanLatModel::maxResidual ( const casacore::Lattice< casacore::Float > & residual )

private

The maximum residual is the absolute maximum.

void casa::ClarkCleanLatModel::maxVect	(	casacore::Block< casacore::Float > &	maxVal,
		casacore::Float &	absVal,
		casacore::Int &	offset,
		const CCList &	activePixels
	)

private

casacore::Float casa::ClarkCleanLatModel::modelFlux ( )

The total flux density in the model.

virtual void casa::ClarkCleanLatModel::setChoose ( const casacore::Bool askForChoice )

virtual

The user can be asked whether to stop after every minor cycle.

virtual void casa::ClarkCleanLatModel::setCycleFactor ( const casacore::Float factor )

virtual

Set the cycle factor....the larger this is the shallower is the minor cycle.

virtual void casa::ClarkCleanLatModel::setHistLength ( const casacore::uInt histBins )

virtual

Set the size of the histogram used to determine how many pixels are "active" in a minor iteration.

Default value of 1000 is OK for everything except very small cleans.

virtual void casa::ClarkCleanLatModel::setInitialNumberIterations ( const casacore::uInt initialNumberIterations )

virtual

Set and get the initial number of iterations.

void casa::ClarkCleanLatModel::setMask ( const casacore::Lattice< casacore::Float > & mask )

virtual void casa::ClarkCleanLatModel::setMaxExtPsf ( const casacore::Float maxExtPsf )

virtual

Set the maximum exterior psf value.

This is used to determine when to stop the minor itartions. This is normally determined from the psf and the number set here is only used if this cannot be determined. The default is zero.

virtual void casa::ClarkCleanLatModel::setMaxNumberMajorCycles ( const casacore::uInt maxNumMajorCycles )

virtual

Set the maximum number of major cycles to perform.

virtual void casa::ClarkCleanLatModel::setMaxNumberMinorIterations ( const casacore::uInt maxNumMinorIterations )

virtual

Set the maximum number of minor iterations to perform for each major cycle.

virtual void casa::ClarkCleanLatModel::setMaxNumPix ( const casacore::uInt maxNumPix )

virtual

Set the maximum number of active pixels to use in the minor iterations.

The specified number can be exceeded if the topmost bin of the histogram contains more pixels than specified here. The default is 10,000 which is suitable for images of 512by512 pixels. Reduce this for smaller images and increase it for larger ones.

virtual void casa::ClarkCleanLatModel::setModel ( const casacore::Lattice< casacore::Float > & model )

virtual

Set the current model.

Implements casa::LinearModel< casacore::Lattice< casacore::Float > >.

virtual void casa::ClarkCleanLatModel::setModel ( casacore::Lattice< casacore::Float > & model )

virtual

virtual void casa::ClarkCleanLatModel::setProgress ( ClarkCleanProgress & ccp )

inlinevirtual

Set/get the progress display.

Definition at line 280 of file ClarkCleanLatModel.h.

References itsProgressPtr.

virtual void casa::ClarkCleanLatModel::setPsfPatchSize ( const casacore::IPosition & psfPatchSize )

virtual

These remaining functions set various "knobs" that the user can tweak and are specific to the Clark clean algorithm.

The more generic parameters ie. clean gain, and maximum residual fluxlimit, are set using functions in the Iterate base class. The get functions return the value that was actually used after the cleaning was done.

set the size of the PSF used in the minor iterations. If not set it defaults to the largest useful Psf (ie. min(modelSize*2, psfSize))

void casa::ClarkCleanLatModel::setResidual ( casacore::Lattice< casacore::Float > & residual )

virtual void casa::ClarkCleanLatModel::setSpeedup ( const casacore::Float speedup )

virtual

An exponent on the F(m,n) factor (see Clark[1980]) which influences how quickly active pixels are treated as unreliable.

Larger values mean more major iterations. The default is zero. I have no experience on when to use this factor.

casacore::Bool casa::ClarkCleanLatModel::singleSolve	(	LatConvEquation &	eqn,
		casacore::Lattice< casacore::Float > &	residual
	)

casacore::Bool casa::ClarkCleanLatModel::solve ( LatConvEquation & eqn )

Using a Clark clean deconvolution proceedure solve for an improved estimate of the deconvolved object.

The convolution/residual equation contains the psf and dirty image. When called with a ResidualEquation arguement a quite general interface is used that is slow. The convolution equation contains functions that speed things up. The functions return false if the deconvolution could not be done.

casacore::Bool casa::ClarkCleanLatModel::stopnow ( )

private

void casa::ClarkCleanLatModel::subtractComponent	(	CCList &	activePixels,
		const casacore::Block< casacore::Float > &	maxVal,
		const casacore::Block< casacore::Int > &	maxPos,
		const casacore::Matrix< casacore::Float > &	psf
	)

private

void casa::ClarkCleanLatModel::updateModel ( CCList & cleanComponents )

private

Member Data Documentation

casacore::Bool casa::ClarkCleanLatModel::itsChoose

private

Definition at line 338 of file ClarkCleanLatModel.h.

casacore::Float casa::ClarkCleanLatModel::itsCycleFactor

private

Definition at line 340 of file ClarkCleanLatModel.h.

casacore::uInt casa::ClarkCleanLatModel::itsHistBins

private

Definition at line 331 of file ClarkCleanLatModel.h.

casacore::uInt casa::ClarkCleanLatModel::itsInitialNumberIterations

private

Definition at line 333 of file ClarkCleanLatModel.h.

casacore::Bool casa::ClarkCleanLatModel::itsJustStarting

private

Definition at line 343 of file ClarkCleanLatModel.h.

casacore::Bool casa::ClarkCleanLatModel::itsLocalResTL

private

Definition at line 346 of file ClarkCleanLatModel.h.

casacore::LogIO casa::ClarkCleanLatModel::itsLog

private

Definition at line 341 of file ClarkCleanLatModel.h.

casacore::Float casa::ClarkCleanLatModel::itsMaxExtPsf

private

Definition at line 335 of file ClarkCleanLatModel.h.

casacore::Int casa::ClarkCleanLatModel::itsMaxNumberMajorCycles

private

Definition at line 334 of file ClarkCleanLatModel.h.

casacore::uInt casa::ClarkCleanLatModel::itsMaxNumberMinorIterations

private

Definition at line 332 of file ClarkCleanLatModel.h.

casacore::uInt casa::ClarkCleanLatModel::itsMaxNumPix

private

Definition at line 330 of file ClarkCleanLatModel.h.

casacore::Float casa::ClarkCleanLatModel::itsMaxRes

private

Definition at line 336 of file ClarkCleanLatModel.h.

Referenced by getMaxResidual().

casacore::Lattice<casacore::Float>* casa::ClarkCleanLatModel::itsModelPtr

private

Definition at line 327 of file ClarkCleanLatModel.h.

Referenced by getModel().

ClarkCleanProgress* casa::ClarkCleanLatModel::itsProgressPtr

private

Definition at line 342 of file ClarkCleanLatModel.h.

Referenced by getProgress(), and setProgress().

casacore::IPosition casa::ClarkCleanLatModel::itsPsfPatchSize

private

Definition at line 337 of file ClarkCleanLatModel.h.

casacore::Lattice<casacore::Float>* casa::ClarkCleanLatModel::itsResidualPtr

private

Definition at line 328 of file ClarkCleanLatModel.h.

Referenced by getResidual().

const casacore::Lattice<casacore::Float>* casa::ClarkCleanLatModel::itsSoftMaskPtr

private

Definition at line 329 of file ClarkCleanLatModel.h.

casacore::Float casa::ClarkCleanLatModel::itsSpeedup

private

Definition at line 339 of file ClarkCleanLatModel.h.

casacore::Bool casa::ClarkCleanLatModel::itsWarnFlag

private

Definition at line 344 of file ClarkCleanLatModel.h.

The documentation for this class was generated from the following file:

casa/code/synthesis/MeasurementEquations/ClarkCleanLatModel.h

Private Attributes
casacore::Lattice < casacore::Float > *	itsModelPtr

casacore::Lattice < casacore::Float > *	itsResidualPtr

const casacore::Lattice < casacore::Float > *	itsSoftMaskPtr

casacore::uInt	itsMaxNumPix

casacore::uInt	itsHistBins

casacore::uInt	itsMaxNumberMinorIterations

casacore::uInt	itsInitialNumberIterations

casacore::Int	itsMaxNumberMajorCycles

casacore::Float	itsMaxExtPsf

casacore::Float	itsMaxRes

casacore::IPosition	itsPsfPatchSize

casacore::Bool	itsChoose

casacore::Float	itsSpeedup

casacore::Float	itsCycleFactor

casacore::LogIO	itsLog

ClarkCleanProgress *	itsProgressPtr

casacore::Bool	itsJustStarting

casacore::Bool	itsWarnFlag

casacore::Bool	itsLocalResTL

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

Template Type Argument Requirements (T)

To Do

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation