#include <ml2d.h>

Inheritance diagram for ML2DBaseProgram:

Collaboration diagram for ML2DBaseProgram:

Public Member Functions
void	initSamplingStuff ()

	ML2DBaseProgram ()

virtual void	produceSideInfo ()=0
	Try to merge produceSideInfo1 and 2. More...

virtual void	produceSideInfo2 ()=0
	Try to merge produceSideInfo1 and 2. More...

virtual void	iteration ()=0

virtual void	expectation ()=0
	Integrate over all experimental images. More...

virtual void	endIteration ()
	Do some task at the end of iteration. More...

virtual void	maximization ()=0
	Update all model parameters, adapted for IEM blocks use. More...

virtual void	setNumberOfLocalImages ()
	Set the number of images, this function is useful only for MPI. More...

virtual void	randomizeImagesOrder ()
	Randomize initial images order, only once. More...

virtual void	createThreads ()
	Create working threads. More...

virtual void	destroyThreads ()
	Exit threads and free memory. More...

virtual void	writeOutputFiles (const ModelML2D &model, OutputType outputType=OUT_FINAL)=0
	Write output files. More...

virtual bool	checkConvergence ()

virtual void	addPartialDocfileData (const MultidimArray< double > &data, size_t first, size_t last)=0
	Add docfiledata to docfile. More...

virtual void	run ()
	Main function of the program. More...

virtual void	defineBasicParams (XmippProgram *prog)

virtual void	defineAdditionalParams (XmippProgram prog, const char sectionLine)

virtual void	defineHiddenParams (XmippProgram *prog)

Public Member Functions inherited from XmippProgram
const char *	getParam (const char *param, int arg=0)

const char *	getParam (const char param, const char subparam, int arg=0)

int	getIntParam (const char *param, int arg=0)

int	getIntParam (const char param, const char subparam, int arg=0)

double	getDoubleParam (const char *param, int arg=0)

double	getDoubleParam (const char param, const char subparam, int arg=0)

float	getFloatParam (const char *param, int arg=0)

float	getFloatParam (const char param, const char subparam, int arg=0)

void	getListParam (const char *param, StringVector &list)

int	getCountParam (const char *param)

bool	checkParam (const char *param)

bool	existsParam (const char *param)

void	addParamsLine (const String &line)

void	addParamsLine (const char *line)

ParamDef *	getParamDef (const char *param) const

virtual void	quit (int exit_code=0) const

virtual int	tryRun ()

void	initProgress (size_t total, size_t stepBin=60)

void	setProgress (size_t value=0)

void	endProgress ()

void	processDefaultComment (const char param, const char left)

void	setDefaultComment (const char param, const char comment)

virtual void	initComments ()

virtual void	defineParams ()

virtual void	readParams ()

void	setProgramName (const char *name)

void	addUsageLine (const char *line, bool verbatim=false)

void	clearUsage ()

void	addExampleLine (const char *example, bool verbatim=true)

void	addSeeAlsoLine (const char *seeAlso)

void	addKeywords (const char *keywords)

const char *	name () const

virtual void	usage (int verb=0) const

virtual void	usage (const String &param, int verb=2)

int	version () const

virtual void	show () const

virtual void	read (int argc, const char **argv, bool reportErrors=true)

virtual void	read (int argc, char **argv, bool reportErrors=true)

void	read (const String &argumentsLine)

	XmippProgram ()

	XmippProgram (int argc, const char **argv)

virtual	~XmippProgram ()

Public Attributes
FileName	fn_img

FileName	fn_ref

FileName	fn_root

FileName	fn_frac

FileName	fn_sig

FileName	fn_doc

FileName	fn_oext

FileName	fn_scratch

FileName	fn_control

String	cline

bool	do_mirror

bool	fix_fractions

bool	fix_sigma_offset

bool	fix_sigma_noise

int	istart

int	iter

int	Niter

size_t	dim

size_t	dim2

size_t	hdim

double	ddim2

size_t	nr_psi

size_t	nr_flip

double	psi_step

double	psi_max

size_t	nr_nomirror_flips

size_t	nr_images_global

size_t	nr_images_local

size_t	myFirstImg

size_t	myLastImg

double	eps

MetaDataDb	MDimg

MetaDataDb	MDref

MetaDataDb	MDlog

std::vector< Matrix2D< double > >	F

std::vector< Image< double > >	Iold

MultidimArray< double >	P_phi

MultidimArray< double >	Mr2

bool	fast_mode

double	C_fast

std::vector< Matrix1D< double > >	Vtrans

bool	zero_offsets

bool	limit_rot

double	search_rot

bool	save_mem1

bool	save_mem2

bool	save_mem3

std::vector< double >	imgs_oldphi

std::vector< double >	imgs_oldtheta

bool	do_ML3D

bool	do_generate_refs

std::vector< std::vector< double > >	imgs_offsets

double	trymindiff_factor

double	df

double	df2

double	dfsigma2

bool	do_norm
	Re-normalize internally. More...

std::vector< double >	imgs_scale

std::vector< double >	imgs_bgmean

std::vector< double >	imgs_trymindiff

std::vector< int >	imgs_optrefno

double	average_scale

int	factor_nref

int	refs_per_class

std::vector< double >	conv

size_t	current_image

ModelML2D	model

ModelML2D *	current_model

size_t	blocks

size_t	current_block

std::vector< size_t >	img_id

MultidimArray< double >	docfiledata

bool	do_restart

bool	referenceExclusive

bool	allowFastOption

bool	allowThreads

bool	allowIEM

bool	allowRestart

String	defaultRoot

int	defaultNiter

int	defaultStartingIter

int	threads

String	outRefsMd

MultidimArray< double >	spectral_signal

int	seed

Public Attributes inherited from XmippProgram
bool	doRun

bool	runWithoutArgs

int	verbose
	Verbosity level. More...

int	debug

Additional Inherited Members
Protected Member Functions inherited from XmippProgram
void	defineCommons ()

Protected Attributes inherited from XmippProgram
int	errorCode

ProgramDef *	progDef
	Program definition and arguments parser. More...

std::map< String, CommentList >	defaultComments

int	argc
	Original command line arguments. More...

const char **	argv

Detailed Description

MLalign2D parameters.

Definition at line 128 of file ml2d.h.

Constructor & Destructor Documentation

◆ ML2DBaseProgram()

ML2DBaseProgram::ML2DBaseProgram ( )

Definition at line 30 of file ml2d.cpp.

 {
     do_ML3D = false;
     refs_per_class = 1;
     defaultNiter = 100;
     defaultRoot = "ml2d";
     referenceExclusive = allowFastOption = true;
     allowThreads = allowRestart = allowIEM = true;
     defaultNiter = 100;
     blocks = 1;
     factor_nref = 1;
     outRefsMd = "";
 }

Member Function Documentation

◆ addPartialDocfileData()

virtual void ML2DBaseProgram::addPartialDocfileData	(	const MultidimArray< double > &	data,
		size_t	first,
		size_t	last
	)

pure virtual

Add docfiledata to docfile.

Implemented in ProgMLF2D, and ProgML2D.

◆ checkConvergence()

bool ML2DBaseProgram::checkConvergence ( )

virtual

Definition at line 119 of file ml2d.cpp.

 {
 //#define DEBUG_JM
 #ifdef DEBUG_JM
     std::cerr<<">>>>>>>> entering checkConvergence"<<std::endl;
 #endif
 
     if (iter == 0)
         return false;
 
     bool converged = true;
     double convv, avg2;
     MultidimArray<double> Maux;
 
     Maux.resize(dim, dim);
     Maux.setXmippOrigin();
 
     conv.clear();
 
     for (int refno = 0; refno < model.n_ref; refno++)
     {
         convv = -1;
 
         if (model.Iref[refno].weight() > 0.)
         {
             Maux = Iold[refno]() * Iold[refno]();
             avg2 = Maux.computeAvg();
             if (avg2 > 0.)
             {
               convv = 1. / avg2;
               Maux = Iold[refno]() - model.Iref[refno]();
               Maux = Maux * Maux;
               convv *= Maux.computeAvg();
               if (convv > eps)
                   converged = false;
             }
         }
         conv.push_back(convv);
     }
 
 #ifdef DEBUG_JM
     std::cerr<<"<<<<<< leaving checkConvergence"<<std::endl;
 
 #endif
 #undef DEBUG_JM
 
     return converged;
 }//close function checkConvergence

◆ createThreads()

virtual void ML2DBaseProgram::createThreads ( )

inlinevirtual

Create working threads.

Reimplemented in ProgML2D.

Definition at line 289 of file ml2d.h.

290 {}

◆ defineAdditionalParams()

void ML2DBaseProgram::defineAdditionalParams	(	XmippProgram *	prog,
		const char *	sectionLine
	)

virtual

Reimplemented in ProgMLF2D.

Definition at line 266 of file ml2d.cpp.

 {
     prog->addParamsLine(sectionLine);
     prog->addParamsLine(" [ --eps <float=5e-5> ]         : Stopping criterium");
     prog->addParamsLine(formatString(" [ --iter <int=%d> ]           : Maximum number of iterations to perform ", defaultNiter));
     prog->addParamsLine(" [ --psi_step <float=5.> ]       : In-plane rotation sampling interval [deg]");
     prog->addParamsLine(" [ --noise <float=1> ]          : Expected standard deviation for pixel noise ");
     prog->addParamsLine(" [ --offset <float=3.> ]         : Expected standard deviation for origin offset [pix]");
     prog->addParamsLine(" [ --frac <docfile=\"\"> ]      : Docfile with expected model fractions (default: even distr.)");
     prog->addParamsLine(" [ -C <double=1e-12> ]         : Significance criterion for fast approach ");
     prog->addParamsLine(" [ --zero_offsets ]             : Kick-start the fast algorithm from all-zero offsets ");
     if (allowRestart)
         prog->addParamsLine(" [ --restart <iter=1> ]  : restart a run with all parameters as in the logfile ");
     prog->addParamsLine(" [ --fix_sigma_noise ]           : Do not re-estimate the standard deviation in the pixel noise ");
     prog->addParamsLine(" [ --fix_sigma_offset ]          : Do not re-estimate the standard deviation in the origin offsets ");
     prog->addParamsLine(" [ --fix_fractions ]             : Do not re-estimate the model fractions ");
     prog->addParamsLine(" [ --student <df=6>]            : Use t-distributed instead of Gaussian model for the noise ");
     prog->addParamsLine("                                : df = Degrees of freedom for the t-distribution ");
     prog->addParamsLine(" [ --norm ]                     : Refined normalization parameters for each particle ");
     prog->addParamsLine(" [ --save_memA ]                : Save memory A(deprecated)");
     prog->addParamsLine(" [ --save_memB ]                : Save memory B(deprecated)");
 
 }

◆ defineBasicParams()

void ML2DBaseProgram::defineBasicParams ( XmippProgram * prog )

virtual

Divide the definition of params in several functions, also allowing other programs to include the ML2D params definition

Reimplemented in ProgMLF2D.

Definition at line 226 of file ml2d.cpp.

 {
     prog->addParamsLine("   -i <input_file>                : Metadata or stack with input images ");
 
     String orStr = "", lb = "", rb = "";
     if (!referenceExclusive)
     {
         orStr = "";
         lb = "[";
         rb = "]";
     }
     prog->addParamsLine(" [ --nref <int=1> ]                  : Number of references to generate automatically (recommended)");
     prog->addParamsLine(" [ --ref <reference_file=\"\">  ]    : Image, stack or metadata with initial(s) references(s)");
 
     prog->addParamsLine(formatString(" [ --oroot <rootname=%s> ]    : Output rootname", defaultRoot.c_str()));
     prog->addParamsLine(" [ --mirror ]                   : Also check mirror image of each reference ");
 
     if (allowFastOption)
     {
         prog->addParamsLine(" [ --fast ]                     : Use pre-centered images to pre-calculate significant orientations.");
         prog->addParamsLine(":++ If this flag is set part of the integration over all references, rotations and translations is skipped.");
         prog->addParamsLine(":++ The program will store all (=N_imgs*N_refs=) origin offsets that yield the maximum probability of observing");
         prog->addParamsLine(":++ each experimental image, given each of the references. In the first iterations a complete integration over");
         prog->addParamsLine(":++ all references, rotations and translations is performed for all images. In all subsequent iterations, for all");
         prog->addParamsLine(":++ combinations of experimental images, references and rotations, the probability of observing the image given");
         prog->addParamsLine(":++ the optimal origin offsets from the previous iteration is calculated. Then, if this probability is not");
         prog->addParamsLine(":++ considered \"significant\", we assume that none of the other translations will be significant, and we skip");
         prog->addParamsLine(":++ the integration over the translations. A combination of experimental image, reference and rotation is considered");
         prog->addParamsLine(":++ as \"significant\" if the probability at the corresponding optimal origin offsets is larger than C times the");
         prog->addParamsLine(":++ maximum of all these probabilities for that experimental image and reference (by default C=1e-12) This version");
         prog->addParamsLine(":++ may run up to ten times faster than the original, complete-search approach, while practically identical results may be obtained.");
 
     }
     if (allowThreads)
         prog->addParamsLine(" [ --thr <N=1> ]                : Use N parallel threads ");
     if (allowIEM)
         prog->addParamsLine(" [ --iem <blocks=1>]            : Number of blocks to be used with IEM");
 
 }

◆ defineHiddenParams()

void ML2DBaseProgram::defineHiddenParams ( XmippProgram * prog )

virtual

Definition at line 290 of file ml2d.cpp.

 {
     prog->addParamsLine("==+++++ Hidden arguments ==");
     prog->addParamsLine(" [--scratch <scratch=\"\">]");
     prog->addParamsLine(" [--debug <int=0>]");
     prog->addParamsLine(" [--no_sigma_trick]");
     prog->addParamsLine(" [--trymindiff_factor <float=0.9>]");
     prog->addParamsLine(" [--random_seed <int=-1>]");
     prog->addParamsLine(" [--search_rot <float=999.>]");
     prog-> addParamsLine(" [--load <N=1>]");
 
     //fixme: only for debug
     prog->addParamsLine("[--no_iem] : bla bla bla");
 }

◆ destroyThreads()

virtual void ML2DBaseProgram::destroyThreads ( )

inlinevirtual

Exit threads and free memory.

Reimplemented in ProgML2D.

Definition at line 294 of file ml2d.h.

295 {}

◆ endIteration()

void ML2DBaseProgram::endIteration ( )

virtual

Do some task at the end of iteration.

Reimplemented in ProgMLF2D, MpiProgMLF2D, and MpiProgML2D.

Definition at line 168 of file ml2d.cpp.

 {
     // Write output files
     addPartialDocfileData(docfiledata, myFirstImg, myLastImg);
     writeOutputFiles(model, OUT_ITER);
 }

◆ expectation()

virtual void ML2DBaseProgram::expectation ( )

pure virtual

Integrate over all experimental images.

Implemented in ProgMLF2D, ProgML2D, MpiProgMLF2D, and MpiProgML2D.

◆ initSamplingStuff()

void ML2DBaseProgram::initSamplingStuff ( )

Set sampling stuff; flipping matrices, psi_step etc. Also create 0, 90, 180 & 270 degree flipping, as well as mirror

Definition at line 44 of file ml2d.cpp.

 {
     // Set sampling stuff: flipping matrices, psi_step etc.
     Matrix2D<double> A(3, 3);
     psi_max = 90.;
     nr_psi = CEIL(psi_max / psi_step);
     psi_step = psi_max / nr_psi;
     nr_flip = nr_nomirror_flips = 4;
     // 0, 90, 180 & 270 degree flipping, as well as mirror
     A.initIdentity();
     F.push_back(A);
     A(0, 0) = 0.;
     A(1, 1) = 0.;
     A(1, 0) = 1.;
     A(0, 1) = -1;
     F.push_back(A);
     A(0, 0) = -1.;
     A(1, 1) = -1.;
     A(1, 0) = 0.;
     A(0, 1) = 0;
     F.push_back(A);
     A(0, 0) = 0.;
     A(1, 1) = 0.;
     A(1, 0) = -1.;
     A(0, 1) = 1;
     F.push_back(A);
     if (do_mirror)
     {
         nr_flip = 8;
         A.initIdentity();
         A(0, 0) = -1;
         F.push_back(A);
         A(0, 0) = 0.;
         A(1, 1) = 0.;
         A(1, 0) = 1.;
         A(0, 1) = 1;
         F.push_back(A);
         A(0, 0) = 1.;
         A(1, 1) = -1.;
         A(1, 0) = 0.;
         A(0, 1) = 0;
         F.push_back(A);
         A(0, 0) = 0.;
         A(1, 1) = 0.;
         A(1, 0) = -1.;
         A(0, 1) = -1;
         F.push_back(A);
     }
     // Set limit_rot
     limit_rot = (search_rot < 180.);
 }

◆ iteration()

virtual void ML2DBaseProgram::iteration ( )

pure virtual

Implemented in ProgMLF2D, and ProgML2D.

◆ maximization()

virtual void ML2DBaseProgram::maximization ( )

pure virtual

Update all model parameters, adapted for IEM blocks use.

Implemented in ProgMLF2D, and ProgML2D.

◆ produceSideInfo()

virtual void ML2DBaseProgram::produceSideInfo ( )

pure virtual

Try to merge produceSideInfo1 and 2.

Implemented in ProgMLF2D, MpiProgMLF2D, and ProgML2D.

◆ produceSideInfo2()

virtual void ML2DBaseProgram::produceSideInfo2 ( )

pure virtual

Try to merge produceSideInfo1 and 2.

Implemented in ProgMLF2D, MpiProgMLF2D, ProgML2D, and MpiProgML2D.

◆ randomizeImagesOrder()

void ML2DBaseProgram::randomizeImagesOrder ( )

virtual

Randomize initial images order, only once.

Definition at line 96 of file ml2d.cpp.

 {
     //This static flag is for only randomize once
     static bool randomized = false;
 
     if (!randomized)
     {
         std::mt19937 g(seed);
         //-------Randomize the order of images
         std::shuffle(img_id.begin(), img_id.end(), g);
         randomized = true;
     }
 }//close function randomizeImagesOrder

◆ run()

void ML2DBaseProgram::run ( )

virtual

Main function of the program.

Reimplemented from XmippProgram.

Definition at line 176 of file ml2d.cpp.

 {
     bool converged = false;
     //CREATE_LOG(LOG_FN(fn_root));
 
     LOG(" starting produceSideInfo\n");
     produceSideInfo();
 
     //Do some initialization work
     LOG(" starting produceSideInfo2\n");
     produceSideInfo2();
 
     //Create threads to be ready for work
     LOG(" createThreads\n");
     createThreads();
 
     LOG(" starting iterations\n");
     // Loop over all iterations
     for (iter = istart; !converged && iter <= Niter; iter++)
     {
         if (verbose)
             std::cout << "  Multi-reference refinement:  iteration " << iter << " of " << Niter << std::endl;
 
         for (int refno = 0;refno < model.n_ref; refno++)
             Iold[refno]() = model.Iref[refno]();
 
         //Perform an ML iteration
         iteration();
 
         // Check convergence
         converged = checkConvergence();
 
         // Do some task before ending iteration
         endIteration();
 
     } // end loop iterations
 
     if (verbose)
     {
         std::cout << (converged ?
                       "--> Optimization converged!" :
                       "--> Optimization was stopped before convergence was reached!")
         << std::endl;
     }
 
     writeOutputFiles(model, OUT_FINAL);
     destroyThreads();
     CLOSE_LOG();
 }

◆ setNumberOfLocalImages()

void ML2DBaseProgram::setNumberOfLocalImages ( )

virtual

Set the number of images, this function is useful only for MPI.

Reimplemented in MpiProgML2D.

Definition at line 110 of file ml2d.cpp.

 {
     nr_images_local = nr_images_global;
     //the following will be override in the MPI implementation.
     //  nr_images_local = divide_equally(nr_images_global, size, rank, myFirstImg,
     //                                   myLastImg);
 }

◆ writeOutputFiles()

virtual void ML2DBaseProgram::writeOutputFiles	(	const ModelML2D &	model,
		OutputType	outputType = `OUT_FINAL`
	)

pure virtual

Write output files.

Implemented in ProgMLF2D, ProgML2D, MpiProgMLF2D, and MpiProgML2D.

Member Data Documentation

◆ allowFastOption

bool ML2DBaseProgram::allowFastOption

Definition at line 239 of file ml2d.h.

◆ allowIEM

bool ML2DBaseProgram::allowIEM

Definition at line 239 of file ml2d.h.

◆ allowRestart

bool ML2DBaseProgram::allowRestart

Definition at line 239 of file ml2d.h.

◆ allowThreads

bool ML2DBaseProgram::allowThreads

Definition at line 239 of file ml2d.h.

◆ average_scale

double ML2DBaseProgram::average_scale

Overall average scale (to be forced to one)

Definition at line 213 of file ml2d.h.

◆ blocks

size_t ML2DBaseProgram::blocks

Definition at line 227 of file ml2d.h.

◆ C_fast

double ML2DBaseProgram::C_fast

Fast mode

Definition at line 182 of file ml2d.h.

◆ cline

String ML2DBaseProgram::cline

Command line

Definition at line 134 of file ml2d.h.

◆ conv

std::vector<double> ML2DBaseProgram::conv

Store convergence

Definition at line 219 of file ml2d.h.

◆ current_block

size_t ML2DBaseProgram::current_block

Definition at line 229 of file ml2d.h.

◆ current_image

size_t ML2DBaseProgram::current_image

Definition at line 221 of file ml2d.h.

◆ current_model

ModelML2D * ML2DBaseProgram::current_model

Definition at line 224 of file ml2d.h.

◆ ddim2

double ML2DBaseProgram::ddim2

Definition at line 152 of file ml2d.h.

◆ defaultNiter

int ML2DBaseProgram::defaultNiter

Definition at line 241 of file ml2d.h.

◆ defaultRoot

String ML2DBaseProgram::defaultRoot

Definition at line 240 of file ml2d.h.

◆ defaultStartingIter

int ML2DBaseProgram::defaultStartingIter

Definition at line 241 of file ml2d.h.

◆ df

double ML2DBaseProgram::df

Degrees of freedom for the t-student distribution

Definition at line 204 of file ml2d.h.

◆ df2

double ML2DBaseProgram::df2

Definition at line 204 of file ml2d.h.

◆ dfsigma2

double ML2DBaseProgram::dfsigma2

Definition at line 204 of file ml2d.h.

◆ dim

size_t ML2DBaseProgram::dim

dimension of the images

Definition at line 151 of file ml2d.h.

◆ dim2

size_t ML2DBaseProgram::dim2

Definition at line 151 of file ml2d.h.

◆ do_generate_refs

bool ML2DBaseProgram::do_generate_refs

Flag for generation of initial models from random subsets

Definition at line 198 of file ml2d.h.

◆ do_mirror

bool ML2DBaseProgram::do_mirror

Flag for checking mirror images of all references

Definition at line 137 of file ml2d.h.

◆ do_ML3D

bool ML2DBaseProgram::do_ML3D

Flag for using ML3D

Definition at line 196 of file ml2d.h.

◆ do_norm

bool ML2DBaseProgram::do_norm

Re-normalize internally.

Flag to refine normalization of each experimental image

Definition at line 207 of file ml2d.h.

◆ do_restart

bool ML2DBaseProgram::do_restart

Flag for restart

Definition at line 236 of file ml2d.h.

◆ docfiledata

MultidimArray<double> ML2DBaseProgram::docfiledata

MultidimArray for mpi passing of docfiledata

Definition at line 234 of file ml2d.h.

◆ eps

double ML2DBaseProgram::eps

Stopping criterium

Definition at line 170 of file ml2d.h.

◆ F

std::vector<Matrix2D<double> > ML2DBaseProgram::F

vector for flipping (i.e. 90/180-degree rotations) matrices

Definition at line 174 of file ml2d.h.

◆ factor_nref

int ML2DBaseProgram::factor_nref

Number of (2D/3D) references to be generated

Definition at line 215 of file ml2d.h.

◆ fast_mode

bool ML2DBaseProgram::fast_mode

Fast mode

Definition at line 180 of file ml2d.h.

◆ fix_fractions

bool ML2DBaseProgram::fix_fractions

Flag whether to fix estimates for model fractions

Definition at line 139 of file ml2d.h.

◆ fix_sigma_noise

bool ML2DBaseProgram::fix_sigma_noise

Flag whether to fix estimate for sigma of noise

Definition at line 143 of file ml2d.h.

◆ fix_sigma_offset

bool ML2DBaseProgram::fix_sigma_offset

Flag whether to fix estimate for sigma of origin offset

Definition at line 141 of file ml2d.h.