ClarkCleanLatModel.h
Classes
- ClarkCleanLatModel -- A Class for performing the Clark Clean Algorithm on Arrays (full description)
Interface
- Public Members
- ClarkCleanLatModel()
- ClarkCleanLatModel(Lattice<Float> & model)
- ClarkCleanLatModel(Lattice<Float> & model, Lattice<Float> & mask)
- ClarkCleanLatModel(Lattice<Float> & model, Lattice<Float> & residual, Lattice<Float> & mask)
- virtual ~ClarkCleanLatModel()
- virtual const Lattice<Float> & getModel() const
- virtual void setModel(const Lattice<Float> & model)
- virtual void setModel(Lattice<Float> & model)
- const Lattice<Float> & getMask() const
- void setMask(const Lattice<Float> & mask)
- void setResidual( Lattice<Float> & residual)
- Float getMaxResidual()
- Bool solve(LatConvEquation & eqn)
- virtual void setChoose(const Bool askForChoice)
- virtual Bool getChoose()
- virtual void setPsfPatchSize(const IPosition & psfPatchSize)
- virtual IPosition getPsfPatchSize()
- virtual void setHistLength(const uInt histBins)
- virtual uInt getHistLength()
- virtual void setMaxNumberMinorIterations(const uInt maxNumMinorIterations)
- virtual uInt getMaxNumberMinorIterations()
- virtual void setInitialNumberIterations(const uInt initialNumberIterations)
- virtual uInt getInitialNumberIterations()
- virtual void setMaxNumberMajorCycles(const uInt maxNumMajorCycles)
- virtual uInt getMaxNumberMajorCycles()
- virtual void setMaxNumPix(const uInt maxNumPix )
- virtual uInt getMaxNumPix()
- virtual void setMaxExtPsf(const Float maxExtPsf )
- virtual Float getMaxExtPsf()
- virtual void setSpeedup(const Float speedup)
- virtual Float getSpeedup()
- virtual void setProgress(ClarkCleanProgress& ccp)
- virtual ClarkCleanProgress& getProgress()
- Private Members
- void doMinorIterations(CCList & activePixels, Matrix<Float> & psfPatch, Float fluxLimit, uInt & numberIterations, Float Fmn, const uInt totalIterations, Float& totalFlux)
- void cacheActivePixels(CCList & activePixels, const Lattice<Float> & residual, Float fluxLimit)
- void absHistogram(Vector<Int> & hist, Float & minVal, Float & maxVal, const Lattice<Float> & data)
- Float biggestResiduals(Float & maxRes, const uInt maxNumPix, const Float fluxLimit, const Lattice<Float> & residual)
- Float getPsfPatch(Matrix<Float> & psfPatch, LatConvEquation & eqn)
- Float maxResidual(const Lattice<Float> & residual)
- void maxVect(Block<Float> & maxVal, Float & absVal, Int & offset, const CCList & activePixels)
- void subtractComponent(CCList & activePixels, const Block<Float> & maxVal, const Block<Int> & maxPos, const Matrix<Float> & psf)
- Float absMaxBeyondDist(const IPosition & maxDist, const IPosition & centre, const Lattice<Float> & psf)
- Bool stopnow()
- Int getbig(Float const * pixValPtr, Int const * pixPosPtr, const Int nPix, const Float fluxLimit, const Float * const residualPtr, const Float * const maskPtr, const uInt npol, const Int nx, const Int ny)
- void updateModel(CCList & cleanComponents)
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 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
Matrix<Float> psf(12,12), dirty(10,10), initialModel(10,10);
...put appropriate values into psf, dirty, & initialModel....
ClarkCleanLatModel<Float> deconvolvedModel(initialModel);
ConvolutionEquation convEqn(psf, dirty);
deconvolvedModel.setGain(0.2);
deconvolvedModel.setNumberIterations(1000);
Bool convWorked = deconvolvedModel.solve(convEqn);
Array<Float> finalModel, residuals;
if (convWorked){
finalModel = deconvolvedModel.getModel();
ConvEqn.residual(deconvolvedModel, finalResidual);
}
Motivation
This class is needed to deconvolve images.
Template Type Argument Requirements (T)
I 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)
Member Description
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.
Construct the ClarkCleanLatModel object and initialise the model.
Construct the ClarkCleanLatModel object and initialise the model ans mask
Construct the ClarkCleanLatModel object and initialise the model ans mask
Destroy!
virtual const Lattice<Float> & getModel() const
virtual void setModel(const Lattice<Float> & model)
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.
virtual void setChoose(const Bool askForChoice)
virtual Bool getChoose()
The user can be asked whether to stop after every minor cycle
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))
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.
Set the maximum number of minor iterations to perform for each major
cycle.
Set and get the initial number of iterations
Set the maximum number of major cycles to perform
virtual void setMaxNumPix(const uInt maxNumPix )
virtual uInt getMaxNumPix()
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 setMaxExtPsf(const Float maxExtPsf )
virtual Float getMaxExtPsf()
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 setSpeedup(const Float speedup)
virtual Float getSpeedup()
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.
Set/get the progress display
void doMinorIterations(CCList & activePixels, Matrix<Float> & psfPatch, Float fluxLimit, uInt & numberIterations, Float Fmn, const uInt totalIterations, Float& totalFlux)
Do all the minor iterations for one major cycle. Cleaning stops
when the flux or iteration limit is reached.
void cacheActivePixels(CCList & activePixels, const Lattice<Float> & residual, Float fluxLimit)
void absHistogram(Vector<Int> & hist, Float & minVal, Float & maxVal, const Lattice<Float> & data)
make histogram of absolute values in array
Float biggestResiduals(Float & maxRes, const uInt maxNumPix, const Float fluxLimit, const Lattice<Float> & residual)
Determine the flux limit if we only select the maxNumPix biggest
residuals. Flux limit is not exact due to quantising by the histogram
Work out the size of the Psf patch to use.
The maximum residual is the absolute maximum.
void maxVect(Block<Float> & maxVal, Float & absVal, Int & offset, const CCList & activePixels)
void subtractComponent(CCList & activePixels, const Block<Float> & maxVal, const Block<Int> & maxPos, const Matrix<Float> & psf)
Int getbig(Float const * pixValPtr, Int const * pixPosPtr, const Int nPix, const Float fluxLimit, const Float * const residualPtr, const Float * const maskPtr, const uInt npol, const Int nx, const Int ny)