General functions

Collaboration diagram for General functions:

Classes
class	Tabsinc
class	KaiserBessel
class	Timer
class	BaseListener
class	TextualListener

Functions
bool	compareTwoFiles (const FileName &fn1, const FileName &fn2, size_t offset=0)
	binary comparison of two files skipping first "offset" bytes More...

Numerical functions
int	solve_2nd_degree_eq (double a, double b, double c, double &x1, double &x2, double prec=XMIPP_EQUAL_ACCURACY)
double	gaussian1D (double x, double sigma, double mu=0)
double	tstudent1D (double x, double df, double sigma, double mu=0)
double	icdf_gauss (double p)
double	cdf_gauss (double x)
double	cdf_tstudent (int k, double t)
double	cdf_FSnedecor (int d1, int d2, double x)
double	icdf_FSnedecor (int d1, int d2, double p)
double	gaussian2D (double x, double y, double sigmaX, double sigmaY, double ang, double muX=0, double muY=0)

Miscellaneous functions
size_t	divide_equally (size_t N, size_t size, size_t rank, size_t &first, size_t &last)
size_t	divide_equally_group (size_t N, size_t size, size_t myself)
template<class T >
void	computeStats (const std::vector< T > &V, double &avg, double &stddev, T &minval, T &maxval)
template<class T >
void	computeAvgStddev (const std::vector< T > &V, double &avg, double &stddev)
template<class T >
void	initConstant (std::vector< T > &V, T &value)

Complex functions
template<typename T >
void	RealImag2Complex (const T *_real, const T *_imag, std::complex< double > *_complex, int length)
template<typename T >
void	AmplPhase2Complex (const T *_ampl, const T *_phase, std::complex< double > *_complex, int length)
template<typename T >
void	Complex2RealImag (const std::complex< double > *_complex, T *_real, T *_imag, int length)
template<typename T >
void	Complex2AmplPhase (const std::complex< double > *_complex, T *_ampl, T *_phase, int length)

Random functions
These functions allow you to work in an easier way with the random functions of the Numerical Recipes. Only an uniform and a gaussian random number generators have been implemented. In fact only a uniform generator exists and the gaussian one is based on a call to it. For this reason, if you initialize the gaussian random generator, you are also initialising the uniform one. Here goes an example for uniform random numbers to show how to use this set of functions. // Initialise according to the clock randomize_random_generator(); // Show 10 random numbers between -1 and 1 for (int i=0; i<10; i++) std::cout << rnd_unif(-1,1) << std::endl;
void	init_random_generator (int seed=-1)
unsigned int	randomize_random_generator ()
double	rnd_unif ()
double	rnd_unif (double a, double b)
double	rnd_student_t (double nu)
double	rnd_student_t (double nu, double a, double b)
double	rnd_gaus ()
double	rnd_gaus (double a, double b)
double	gaus_within_x0 (double x0, double mean=0, double stddev=1)
double	gaus_outside_x0 (double x0, double mean=0, double stddev=1)
double	gaus_up_to_x0 (double x0, double mean=0, double stddev=1)
double	gaus_from_x0 (double x0, double mean=0, double stddev=1)
double	student_outside_probb (double p, double degrees_of_freedom)
double	student_within_t0 (double t0, double degrees_of_freedom)
double	student_outside_t0 (double t0, double degrees_of_freedom)
double	student_up_to_t0 (double t0, double degrees_of_freedom)
double	student_from_t0 (double t0, double degrees_of_freedom)
double	chi2_up_to_t0 (double t0, double degrees_of_freedom)
double	chi2_from_t0 (double t0, double degrees_of_freedom)
double	rnd_log (double a, double b)

Time managing
These functions are used to make time measures of the algorithms. If you know the total amount of work to do then some estimation can be done about how much time is left before finishing. The time functions are very machine dependent, we've tried to accommodate the compilation for several machines, but if still programs do not work, you may configure Xmipp to avoid these time measurements, functions are then substituted by null functions doing nothing. // Variable declaration TimeStamp t0; // Beginning of the program time_config(); ... annotate_processor_time(&t0); // Part to be measured ... // End of part to be measured print_elapsed_time(t0); While for an estimation of time to go you can make it in two ways: one analytical, and another graphical. Analytical: // Variable declaration ProcessorTimeStamp t0; double to_go; // Beginning of the program time_config(); ... annotate_processor_time(&t0); // Part to be measured for (int i=0; i<60; i++) { ... // Compute the time to go with the fraction of work already done to_go = time_to_go(t0, (double) (i + 1) / 60); std::cout << "I think you will be here " << to_go << "seconds more\n"; } // End of part to be measured print_elapsed_time(t0); Alternatively: // Variable declaration TimeStamp t0; double to_go; annotate_time(&t0); // Part to be measured for (int i=0; i<60; i++) { ... // Compute the time to go with the fraction of work already done to_go = time_to_go(t0, (double) (i + 1) / 60); std::cout << "I think you will be here " << to_go << "seconds more\n"; } // End of part to be measured print_elapsed_time(t0); Graphical: // Beginning of the program time_config(); ... // Init the progress bar with the total amount of work to do // It is very important that there is no print out to stdout but // the progress bar init_progress_bar(60); // Part to be measured for (int i=0; i<60; i++) { ... progress_bar(i+1); } // In this case the following call is useless since it has been // already done in the loop, but there are cases where a final call // with the total amount of work is not performed and although the // whole task has been finished it seems that it hasn't as the // progress bar hasn't been called with the final work but with // a quantity a little smaller. progress_bar(60); These functions is not ported to Python.
typedef struct tms	ProcessorTimeStamp
typedef size_t	TimeStamp
void	time_config ()
void	annotate_processor_time (ProcessorTimeStamp *time)
void	annotate_time (TimeStamp *time)
void	acum_time (ProcessorTimeStamp *orig, ProcessorTimeStamp *dest)
double	elapsed_time (ProcessorTimeStamp &time, bool _IN_SECS=true)
void	print_elapsed_time (ProcessorTimeStamp &time, bool _IN_SECS=true)
void	print_elapsed_time (TimeStamp &time, bool _IN_SECS=true)
double	time_to_go (ProcessorTimeStamp &time, double fraction_done)
void	init_progress_bar (long total)
void	progress_bar (long act_time)
char *	getCurrentTimeString ()
void	TimeMessage (const std::string &message)

Little/Big endian
These set of functions helps you to deal with the little/big endian problems.
size_t	xmippFREAD (void *dest, size_t size, size_t nitems, FILE *&fp, bool reverse=false)
size_t	xmippFWRITE (const void *src, size_t size, size_t nitems, FILE *&fp, bool reverse=false)
void	mapFile (const FileName &filename, char *&map, size_t &size, int &fileDescriptor, bool readOnly=true)
void	unmapFile (char *&map, size_t &size, int &fileDescriptor)
void	swapbytes (char *v, unsigned long n)
bool	IsBigEndian (void)
void	processMemUsage (double &vm_usage, double &resident_set)
bool	IsLittleEndian (void)
void	printMemoryUsed ()
#define	little22bigendian(x)   swapbytes((unsigned char*)& x,sizeof(x))

Detailed Description

Macro Definition Documentation

little22bigendian

#define little22bigendian

(

x

)

swapbytes((unsigned char*)& x,sizeof(x))

Conversion little-big endian

This function is not ported to Python.

Definition at line 1203 of file xmipp_funcs.h.

Typedef Documentation

ProcessorTimeStamp

typedef struct tms ProcessorTimeStamp

Definition at line 822 of file xmipp_funcs.h.

TimeStamp

typedef size_t TimeStamp

Definition at line 823 of file xmipp_funcs.h.

Function Documentation

acum_time()

void acum_time	(	ProcessorTimeStamp *	orig,
		ProcessorTimeStamp *	dest
	)

Accumulate time

Initially dest_time should be set to orig time. Then you acumulate successive times calling this function (Destination time=destination_time + (now - original time)) and finally the elapsed time is the dest time minus the first one (the one which initiliazed the dest time.

This function is not ported to Python.

Definition at line 658 of file xmipp_funcs.cpp.

{
    ProcessorTimeStamp now;
    times(&now);
    (*dest).tms_utime += (*dest).tms_utime + (now.tms_utime - (*orig).tms_utime);
    (*dest).tms_stime += (*dest).tms_stime + (now.tms_utime - (*orig).tms_utime);
}

AmplPhase2Complex()

template<typename T >

void AmplPhase2Complex	(	const T *	_ampl,
		const T *	_phase,
		std::complex< double > *	_complex,
		int	length
	)

Amplitude/Phase –> Complex

The output array(s) must be already resized.

This function is not ported to Python.

Definition at line 431 of file xmipp_funcs.h.

{
    T* aux_ampl = (T*) _ampl;
    T* aux_phase = (T*) _phase;
    double* aux_complex = (double*) _complex;

    for (int i = 0; i < length; i++)
    {
        double ampl = (double)(*aux_ampl++);
        double phase = (double)(*aux_phase++);
        *aux_complex++ = ampl * cos(phase);
        *aux_complex++ = ampl * sin(phase);
    }
}

annotate_processor_time()

void annotate_processor_time

(

ProcessorTimeStamp *

time

)

Annotate actual time

This annotation is used later to compute the elapsed time.

ProcessorTimeStamp t0;
annotate_processor_time(&t0);

This function is not ported to Python.

Definition at line 640 of file xmipp_funcs.cpp.

{
    times(time);
}

annotate_time()

void annotate_time

(

TimeStamp *

time

)

Annotate actual time

This annotation is used later to compute the elapsed time.

TimeStamp t0;
annotate_time(&t0);

This function is not ported to Python.

Definition at line 646 of file xmipp_funcs.cpp.

{
    struct timeval  tv;
    gettimeofday(&tv, NULL);
    struct tm tm;
    localtime_r(&tv.tv_sec,&tm);
    *time = tm.tm_hour * 3600 * 1000 + tm.tm_min * 60 * 1000 + tm.tm_sec * 1000 +
            tv.tv_usec / 1000;
}

cdf_FSnedecor()

double cdf_FSnedecor	(	int	d1,
		int	d2,
		double	x
	)

Cumulative distribution function for a Snedecor's F-distribution.

This function returns the value of the CDF of a univariate Snedecor's F-distribution with d1, d2 degrees of freedom at the point x.

Definition at line 364 of file xmipp_funcs.cpp.

{
    return betai(0.5*d1,0.5*d2,(d1*x)/(d1*x+d2));
}

cdf_gauss()

double cdf_gauss

(

double

x

)

Cumulative distribution function for a Gaussian

This function returns the value of the CDF of a univariate gaussian function at the point x.

Definition at line 241 of file xmipp_funcs.cpp.

{
    return 0.5 * (1. + erf(x/sqrt(2.)));
}

cdf_tstudent()

double cdf_tstudent	(	int	k,
		double	t
	)

Cumulative distribution function for a t-distribution

This function returns the value of the CDF of a univariate t-distribution with k degrees of freedom at the point t. Adapted by Sjors from: http://www.alglib.net/specialfunctions/distributions/student.php

Definition at line 287 of file xmipp_funcs.cpp.

{
    double EPS=5E-16;
    double result;
    double x;
    double rk;
    double z;
    double f;
    double tz;
    double p;
    double xsqk;
    int j;

    if ( t==0 )
    {
        result = 0.5;
        return result;
    }
    if ( t<-2.0 )
    {
        rk = k;
        z = rk/(rk+t*t);
        result = 0.5*betai(0.5*rk, 0.5, z);
        return result;
    }
    if ( t<0 )
    {
        x = -t;
    }
    else
    {
        x = t;
    }
    rk = k;
    z = 1.0+x*x/rk;
    if ( k%2 != 0 )
    {
        xsqk = x/sqrt(rk);
        p = atan(xsqk);
        if ( k > 1 )
        {
            f = 1.0;
            tz = 1.0;
            j = 3;
            while ( j <= k-2 && tz/f > EPS )
            {
                tz = tz*((j-1)/(z*j));
                f = f+tz;
                j = j+2;
            }
            p = p+f*xsqk/z;
        }
        p = p*2.0/PI;
    }
    else
    {
        f = 1.0;
        tz = 1.0;
        j = 2;
        while ( j<= k-2 && tz/f > EPS)
        {
            tz = tz*((j-1)/(z*j));
            f = f+tz;
            j = j+2;
        }
        p = f*x/sqrt(z*rk);
    }
    if ( t<0 )
    {
        p = -p;
    }
    result = 0.5+0.5*p;
    return result;
}

chi2_from_t0()

double chi2_from_t0	(	double	t0,
		double	degrees_of_freedom
	)

chi2 area from t0 to inf

By default the chi2 mean is 0 and the chi2 standard deviation is 1. There is no restriction over the sign of t0

Definition at line 577 of file xmipp_funcs.cpp.

{
    return 1 -chi2_up_to_t0(t0, degrees_of_freedom);
}

chi2_up_to_t0()

double chi2_up_to_t0	(	double	t0,
		double	degrees_of_freedom
	)

chi2 area from -inf to t0

By default the chi2 mean is 0 and the chi2 standard deviation is 1. There is no restriction over the sign of t0

Definition at line 572 of file xmipp_funcs.cpp.

{
    return gammp(degrees_of_freedom / 2, t0 / 2);
}

compareTwoFiles()

bool compareTwoFiles	(	const FileName &	fn1,
		const FileName &	fn2,
		size_t	offset
	)

binary comparison of two files skipping first "offset" bytes

Compare two files

Definition at line 1183 of file xmipp_funcs.cpp.

{
    char *map1,*map2;
    int fd1, fd2;
    size_t size1=-1, size2=-1;
    mapFile(fn1,map1,size1,fd1,true);
    mapFile(fn2,map2,size2,fd2,true);
    int result=memcmp(map1+offset,map2+offset,size1-offset);
    unmapFile(map1,size1,fd1);
    unmapFile(map2,size2,fd2);
    return (result==0);
}

Complex2AmplPhase()

template<typename T >

void Complex2AmplPhase	(	const std::complex< double > *	_complex,
		T *	_ampl,
		T *	_phase,
		int	length
	)

Complex –> Amplitude/Phase

The output array(s) must be already resized.

This function is not ported to Python.

Definition at line 479 of file xmipp_funcs.h.

{
    T* aux_ampl = (T*) _ampl;
    T* aux_phase = (T*) _phase;
    double* aux_complex = (double*) _complex;

    for (int i = 0; i < length; i++)
    {
        double re = *aux_complex++;
        double im = *aux_complex++;
        *aux_ampl++ = sqrt(re * re + im * im);
        *aux_phase++ = atan2(im, re);
    }
}

Complex2RealImag()

template<typename T >

void Complex2RealImag	(	const std::complex< double > *	_complex,
		T *	_real,
		T *	_imag,
		int	length
	)

Complex –> Real/Imag

The output array(s) must be already resized.

This function is not ported to Python.

Definition at line 456 of file xmipp_funcs.h.

{
    T* aux_real = (T*) _real;
    T* aux_imag = (T*) _imag;
    double* aux_complex = (double*) _complex;

    for (int i = 0; i < length; i++)
    {
        *aux_real++ = (T)(*aux_complex++);
        *aux_imag++ = (T)(*aux_complex++);
    }
}

computeAvgStddev()

template<class T >

void computeAvgStddev	(	const std::vector< T > &	V,
		double &	avg,
		double &	stddev
	)

Compute statistics of a std::vector

Definition at line 358 of file xmipp_funcs.h.

{
    if (V.size()<= 0)
        return;

    avg = 0;
    stddev = 0;

    size_t nmax=V.size();
    const T* ptr=&V[0];
    for(size_t n=0; n<nmax; ++n, ++ptr)
    {
        double val=*ptr;
        avg += val;
        stddev += val * val;
    }
    avg /= nmax;

    if (nmax > 1)
    {
        stddev = stddev / nmax - avg * avg;
        stddev *= nmax / (nmax - 1);

        // Foreseeing numerical instabilities
        stddev = sqrt(static_cast< double >(ABS(stddev)));
    }
    else
        stddev = 0;
}

computeStats()

template<class T >

void computeStats	(	const std::vector< T > &	V,
		double &	avg,
		double &	stddev,
		T &	minval,
		T &	maxval
	)

Compute statistics of a std::vector

Definition at line 317 of file xmipp_funcs.h.

{
    if (V.size()<= 0)
        return;

    avg = 0;
    stddev = 0;

    minval = maxval = V[0];

    size_t nmax=V.size();
    const T* ptr=&V[0];
    for(size_t n=0; n<nmax; ++n, ++ptr)
    {
        double val=*ptr;
        avg += val;
        stddev += val * val;

        if (val > maxval)
            maxval = val;
        else if (val < minval)
            minval = val;
    }
    avg /= nmax;

    if (nmax > 1)
    {
        stddev = stddev / nmax - avg * avg;
        stddev *= nmax / (nmax - 1);

        // Foreseeing numerical instabilities
        stddev = sqrt(static_cast< double >(ABS(stddev)));
    }
    else
        stddev = 0;
}

divide_equally()

size_t divide_equally	(	size_t	N,
		size_t	size,
		size_t	rank,
		size_t &	first,
		size_t &	last
	)

Divides a number into most equally groups

For example you want to distribute N jobs between M workers so each worker will have N/M jobs and some of them(N % M first) will have N/M + 1 jobs So for the worker 'rank' will be computed the first and last job to do Return the number of jobs assigned, that could be N/M + 1 or N/M

Divides a number into most equally groups

Definition at line 1150 of file xmipp_funcs.cpp.

{
    size_t jobs_per_worker = N / size;
    size_t jobs_resting = N % size;

    if (rank < jobs_resting)
    {
        first = rank * (jobs_per_worker + 1);
        last = first + jobs_per_worker;
    }
    else
    {
        first = rank * jobs_per_worker + jobs_resting;
        last = first + jobs_per_worker - 1;
    }

    return last - first + 1;
}

divide_equally_group()

size_t divide_equally_group	(	size_t	N,
		size_t	size,
		size_t	myself
	)

In which group (of divide_equally) is myself situated?

In which group from divide_equally is myself?

Definition at line 1169 of file xmipp_funcs.cpp.

{
    size_t first, last;
    for (size_t rank = 0; rank < size; rank++)
    {
        divide_equally(N, size, rank, first, last);
        if (myself >= first && myself <= last)
            return rank;
    }
    return -1;

}

elapsed_time()

double elapsed_time	(	ProcessorTimeStamp &	time,
		bool	_IN_SECS = true
	)

Compute elapsed time since a given annotation

Given an annotation of time, this function computes the time elapsed since then in seconds. The annotation is not modified. Usually the time is shown in seconds, but you might specify to show it in clock ticks setting the variable _IN_SECS to FALSE.

TimeStamp t0;
annotate_time(&t0);
...;
double elapsed = elapsed_time(t0);

TimeStamp t0;
annotate_time(&t0);
...;
double elapsed = elapsed_time(t0, FALSE);

This function is not ported to Python.

Definition at line 739 of file xmipp_funcs.cpp.

{
#if !defined _NO_TIME && !defined __MINGW32__
    ProcessorTimeStamp now;
    times(&now);
    double userTime = now.tms_utime - time.tms_utime;
    double sysTime = now.tms_stime - time.tms_stime;
    if (_IN_SECS)
    {
        userTime /= XmippTICKS;
        sysTime /= XmippTICKS;
    }
    return userTime + sysTime;
#endif
}

gaus_from_x0()

double gaus_from_x0	(	double	x0,
		double	mean = 0,
		double	stddev = 1
	)

Gaussian area from x0 to inf

By default the gaussian mean is 0 and the gaussian standard deviation is 1. There is no restriction over the sign of x0

Definition at line 499 of file xmipp_funcs.cpp.

{
    if (x0 > mean)
        return gaus_outside_x0(x0, mean, stddev) / 2;
    else if (x0 == mean)
        return 0.5;
    else
        return 1.0 -gaus_outside_x0(x0, mean, stddev) / 2;
}

gaus_outside_x0()

double gaus_outside_x0	(	double	x0,
		double	mean = 0,
		double	stddev = 1
	)

Gaussian area outisde -x0 to x0

By default the gaussian mean is 0 and the gaussian standard deviation is 1. x0 must be positive

Definition at line 483 of file xmipp_funcs.cpp.

{
    double z0 = (x0 - mean) / stddev;
    return erfc(ABS(z0) / sqrt(2.0));
}

gaus_up_to_x0()

double gaus_up_to_x0	(	double	x0,
		double	mean = 0,
		double	stddev = 1
	)

Gaussian area from -inf to x0

By default the gaussian mean is 0 and the gaussian standard deviation is 1. There is no restriction over the sign of x0

Definition at line 489 of file xmipp_funcs.cpp.

{
    if (x0 > mean)
        return 1.0 -gaus_outside_x0(x0, mean, stddev) / 2;
    else if (x0 == mean)
        return 0.5;
    else
        return gaus_outside_x0(x0, mean, stddev) / 2;
}

gaus_within_x0()

double gaus_within_x0	(	double	x0,
		double	mean = 0,
		double	stddev = 1
	)

Gaussian area from -x0 to x0

By default the gaussian mean is 0 and the gaussian standard deviation is 1. x0 must be positive

Definition at line 477 of file xmipp_funcs.cpp.

{
    double z0 = (x0 - mean) / stddev;
    return erf(ABS(z0) / sqrt(2.0));
}

gaussian1D()

double gaussian1D	(	double	x,
		double	sigma,
		double	mu = 0
	)

1D gaussian value

This function returns the value of a univariate gaussian function at the point x.

Definition at line 181 of file xmipp_funcs.cpp.

{
    x -= mu;
    return 1 / sqrt(2*PI*sigma*sigma)*exp(-0.5*((x / sigma)*(x / sigma)));
}

gaussian2D()

double gaussian2D	(	double	x,
		double	y,
		double	sigmaX,
		double	sigmaY,
		double	ang,
		double	muX = 0,
		double	muY = 0
	)

2D gaussian value

This function returns the value of a multivariate (2D) gaussian function at the point (x,y) when the X axis of the gaussian is rotated ang (counter-clockwise) radians (the angle is positive when measured from the universal X to the gaussian X). X and Y are supposed to be independent.

Definition at line 197 of file xmipp_funcs.cpp.

{
    // Express x,y in the gaussian internal coordinates
    x -= muX;
    y -= muY;
    double xp = cos(ang) * x + sin(ang) * y;
    double yp = -sin(ang) * x + cos(ang) * y;

    // Now evaluate
    return 1 / sqrt(2*PI*sigmaX*sigmaY)*exp(-0.5*((xp / sigmaX)*(xp / sigmaX) +
                                            (yp / sigmaY)*(yp / sigmaY)));
}

getCurrentTimeString()

char* getCurrentTimeString

(

)

Function to get current time as string

Definition at line 861 of file xmipp_funcs.cpp.

{
    time_t rawtime;
    time ( &rawtime );
    char * str = ctime (&rawtime);
    char * pos = strrchr(str, '\n');
    pos[0] = '\0'; //Remove \n end character
    return str;

}

icdf_FSnedecor()

double icdf_FSnedecor	(	int	d1,
		int	d2,
		double	p
	)

Inverse Cumulative distribution function for a Snedecor's F-distribution.

This function returns the value of the ICDF of a univariate Snedecor's F-distribution with d1, d2 degrees of freedom with probability p, i.e., it returns x such that CDF(d1,d2,x)=p

Definition at line 369 of file xmipp_funcs.cpp.

{
    double xl=0, xr=1e6;
    double xm, pm;
    do
    {
        xm=(xl+xr)*0.5;
        pm=cdf_FSnedecor(d1,d2,xm);
        if (pm>p)
        {
            xr=xm;
        }
        else
        {
            xl=xm;
        }
    }
    while (fabs(pm-p)/p>0.001);
    return xm;
}

icdf_gauss()

double icdf_gauss

(

double

p

)

Inverse Cumulative distribution function for a Gaussian

This function returns the z of a N(0,1) such that the probability below z is p

The function employs an fast approximation to z which is valid up to 1e-4. See http://www.johndcook.com/normal_cdf_inverse.html

Definition at line 212 of file xmipp_funcs.cpp.

{
    const double c[] =
        {
            2.515517, 0.802853, 0.010328
        };
    const double d[] =
        {
            1.432788, 0.189269, 0.001308
        };
    if (p < 0.5)
    {
        // F^-1(p) = - G^-1(p)
        double t=sqrt(-2.0*log(p));
        double z=t - ((c[2]*t + c[1])*t + c[0]) /
                 (((d[2]*t + d[1])*t + d[0])*t + 1.0);
        return -z;
    }
    else
    {
        // F^-1(p) = G^-1(1-p)
        double t=sqrt(-2.0*log(1-p));
        double z=t - ((c[2]*t + c[1])*t + c[0]) /
                 (((d[2]*t + d[1])*t + d[0])*t + 1.0);
        return z;
    }
}

init_progress_bar()

void init_progress_bar

(

long

total

)

Initialise the progress bar

The progress bar is initialised to count for a total amount of work. For instance, if we are to do something 60 times, the progress bar should be initialised to that value. At the same time the bar is printed with the initial guess of time left (ie, nothing "0000/????"). The number before the slash is the elapsed time since initialisation of the progress bar, while the second number is the estimation of total time that this task will take. See Time managing for a more detailed example.

init_progress_bar(60);

Definition at line 782 of file xmipp_funcs.cpp.

{
    progress_bar(-(total));
}

init_random_generator()

void init_random_generator

(

int

seed = -1

)

Reset uniform random generator to a known point

If you initialize the random generator with this function each time, then the same random sequence will be generated

init_rnd_unif();
init_rnd_unif(17891)

Definition at line 394 of file xmipp_funcs.cpp.

{
    idum = -1;
    ran1(&idum);
    if (seed != -1)
    {
        // Prevent seeds larger than 65000
        seed %=0xffff;
        for (int i = 0; i < seed; i++)
            ran1(&idum);
    }
}

initConstant()

template<class T >

void initConstant	(	std::vector< T > &	V,
		T &	value
	)

Initialize std::vector with constant value

Definition at line 390 of file xmipp_funcs.h.

{
    const T* ptr=&V[0];
    size_t nmax=V.size();
    for(size_t n=0; n<nmax; ++n, ++ptr)
        *ptr=value;
}

IsBigEndian()

bool IsBigEndian

(

void

)

Returns 1 if machine is big endian else 0

Returns true if machine is big endian else false

Definition at line 1092 of file xmipp_funcs.cpp.

{
    static const unsigned long ul = 0x01000000;
    return ((int)(*((unsigned char *) &ul)))!=0;
}

IsLittleEndian()

bool IsLittleEndian

(

void

)

Returns 1 if machine is little endian else 0 little-endian format (sometimes called the Intel format

Returns true if machine is little endian else false

Definition at line 1085 of file xmipp_funcs.cpp.

{
    static const unsigned long ul = 0x00000001;
    return ((int)(*((unsigned char *) &ul)))!=0;
}

mapFile()

void mapFile	(	const FileName &	filename,
		char *&	map,
		size_t &	size,
		int &	fileDescriptor,
		bool	readOnly = true
	)

Map file to memory.

If size is less than 0, then the whole file is mapped, and the size is correctly set to the file size.

Definition at line 970 of file xmipp_funcs.cpp.

{
    if (size<0)
    {
        struct stat file_status;
        if(stat(filename.c_str(), &file_status) != 0)
            REPORT_ERROR(ERR_IO_NOPATH,"Cannot get filesize for file "+filename);
        size = file_status.st_size;
    }
#ifdef XMIPP_MMAP
    struct stat file_status;
    if(stat(filename.c_str(), &file_status) != 0)
        REPORT_ERROR(ERR_IO_NOPATH,(String)"Cannot get filesize for file "+filename);
    size = file_status.st_size;
    if(size==0)
        REPORT_ERROR(ERR_IO_NOPATH,(String)"File size=0, cannot read it ("+filename+")");

    if (readOnly)
        fileDescriptor = open(filename.c_str(),  O_RDONLY, S_IREAD);
    else
        fileDescriptor = open(filename.c_str(),  O_RDWR, S_IREAD | S_IWRITE);
    if (fileDescriptor == -1)
        REPORT_ERROR(ERR_IO_NOPATH,(String)"Cannot open file named "+filename);

    if (readOnly)
        map = (char *) mmap(0, size, PROT_READ, MAP_SHARED, fileDescriptor, 0);
    else
        map = (char *) mmap(0, size, PROT_READ | PROT_WRITE, MAP_SHARED, fileDescriptor, 0);
    if (map == MAP_FAILED)
        REPORT_ERROR(ERR_MEM_BADREQUEST,"Write can not map memory ");
#else

    map = new char[size];
    fileDescriptor = open(filename.data(), O_RDONLY);
    if (fileDescriptor == -1)
        REPORT_ERROR(ERR_IO_NOPATH,(String)"Cannot open file named "+filename);
    int ok=read(fileDescriptor,map,size);
    if (ok==-1)
        REPORT_ERROR(ERR_IO_NOREAD,(String)"Cannot read from file named"+filename);
#endif
}

print_elapsed_time() [1/2]

void print_elapsed_time	(	ProcessorTimeStamp &	time,
		bool	_IN_SECS = true
	)

Show on screen the elapsed time since a given annotation

The format of the printing is "Elapsed time: User(13) System(1)" that means that the user has used 13 seconds and the system 1, a total of 14 seconds since the last annotation in this TimeStamp variable.

ProcessorTimeStamp t0;
annotate_processor_time(&t0);
...;
print_elapsed_time(t0);

Usually the time is shown in seconds, but you might specify to show it in clock ticks setting the variable _IN_SECS to FALSE.

This function is not ported to Python.

Definition at line 669 of file xmipp_funcs.cpp.

{
    ProcessorTimeStamp now;
    times(&now);
    double userTime = now.tms_utime - time.tms_utime;
    double sysTime = now.tms_stime - time.tms_stime;
    if (_IN_SECS)
    {
        userTime /= XmippTICKS;
        sysTime /= XmippTICKS;
    }
    std::cout << "Elapsed time: User(" << userTime << ") System(" << sysTime
    << ")\n";
}

print_elapsed_time() [2/2]

void print_elapsed_time	(	TimeStamp &	time,
		bool	_IN_SECS = true
	)

Show on screen the elapsed time since a given annotation

The format of the printing is "Elapsed time: User(13) System(1)" that means that the user has used 13 seconds and the system 1, a total of 14 seconds since the last annotation in this TimeStamp variable.

TimeStamp t0;
annotate_time(&t0);
...;
print_elapsed_time(t0);

Usually the time is shown in seconds, but you might specify to show it in clock ticks setting the variable _IN_SECS to FALSE.

This function is not ported to Python.

Definition at line 685 of file xmipp_funcs.cpp.

{
    struct timeval  tv;
    gettimeofday(&tv, NULL);
    struct tm tm;
    localtime_r(&tv.tv_sec,&tm);
    TimeStamp now = tm.tm_hour * 3600 * 1000 + tm.tm_min * 60 * 1000 + tm.tm_sec * 1000 +
                    tv.tv_usec / 1000;
    TimeStamp diff=now-time;

    std::cout << "Elapsed time: ";
    if (_IN_SECS)
        std::cout << diff/1000.0 << " secs." << std::endl;
    else
        std::cout << diff << " msecs." << std::endl;
}

printMemoryUsed()

void printMemoryUsed

(

)

Print the memory used by this process.

Definition at line 1142 of file xmipp_funcs.cpp.

{
    double virtualMemory, residentMemory;
    processMemUsage(virtualMemory, residentMemory);
    std::cout << "VM: " << virtualMemory << "kB ; RSS: " << residentMemory << " kB" << std::endl;
}

processMemUsage()

void processMemUsage	(	double &	vm_usage,
		double &	resident_set
	)

Definition at line 1105 of file xmipp_funcs.cpp.

{
    using std::ios_base;
    using std::ifstream;
    using std::string;

    vm_usage     = 0.0;
    resident_set = 0.0;

    // 'file' stat seems to give the most reliable results
    //
    ifstream stat_stream("/proc/self/stat",ios_base::in);

    // dummy vars for leading entries in stat that we don't care about
    //
    string pid, comm, state, ppid, pgrp, session, tty_nr;
    string tpgid, flags, minflt, cminflt, majflt, cmajflt;
    string utime, stime, cutime, cstime, priority, nice;
    string O, itrealvalue, starttime;

    // the two fields we want
    //
    unsigned long vsize;
    long rss;

    stat_stream >> pid >> comm >> state >> ppid >> pgrp >> session >> tty_nr
    >> tpgid >> flags >> minflt >> cminflt >> majflt >> cmajflt
    >> utime >> stime >> cutime >> cstime >> priority >> nice
    >> O >> itrealvalue >> starttime >> vsize >> rss; // don't care about the rest

    stat_stream.close();

    long page_size_kb = sysconf(_SC_PAGE_SIZE) / 1024; // in case x86-64 is configured to use 2MB pages
    vm_usage     = vsize / 1024.0;
    resident_set = rss * page_size_kb;
}

progress_bar()

void progress_bar

(

long

act_time

)

Update progress bar

With this function you can change the already done amount of work, if something is to be done 60 times and now we have already done 13 then we could tell this to the progress bar with

progress_bar(13);

The information that this thing was to be done 60 times was given at the initialisation of the progress bar. It is very important that during the use of the progress bar, nobody prints anything to stdout as it is being used by the progress bar. At the end you could make a call to progress_bar with the total amount of work just to make sure that the printout is pretty enough.

Definition at line 791 of file xmipp_funcs.cpp.

{
    static time_t startt;
    time_t currt;
    static long totlen;
    long t1, t2;
    int min, i, hour;
    double h1, h2, m1, m2;
    bool queue = (getenv("XMIPP_IN_QUEUE") != NULL);

    if (rlen == 0)
        return;
    currt = time(NULL);

    if (rlen < 0)
    {
        totlen = -rlen;
        startt = currt;
        fprintf(stdout, "0000/???? sec. ");
        if (!queue)
            for (i = 0; i < 10; i++)
                fprintf(stdout, "------");
        fflush(stdout);
    }
    else if (totlen > 0)
    {
        t1 = currt - startt;               // Elapsed time
        t2 = (long)(t1 * (double)totlen / rlen); // Total time

        hour = 0;
        min = 0;
        if (t2 > 60)
        {
            m1 = (double)t1 / 60.0;
            m2 = (double)t2 / 60.0;
            min = 1;
            if (m2 > 60)
            {
                h1 = (double)m1 / 60.0;
                h2 = (double)m2 / 60.0;
                hour = 1;
                min = 0;
            }
            else
                hour = 0;
        }

        if (hour)
            fprintf(stdout, "\r%3.2f/%3.2f %s ", h1, h2, "hours");
        else if (min)
            fprintf(stdout, "\r%3.2f/%3.2f %s ", m1, m2, "min");
        else
            fprintf(stdout, "\r%4u/%4u %4s ", (int)t1, (int)t2, "sec.");

        if (!queue)
        {
            i = (int)(60 * (1 - (double)(totlen - rlen) / totlen));
            while (i--)
                fprintf(stdout, ".");
        }

        if (rlen == totlen)
        {
            fprintf(stdout, "\n");
            totlen = 0;
        }
        fflush(stdout);
    }
}

randomize_random_generator()

unsigned int randomize_random_generator

(

)

Reset random generator according to the clock.

This time the initialisation itself assures a random sequence different each time the program is run. Be careful not to run the program twice within the same second as the initialisation will be the same for both runs. Returns seed.

Definition at line 407 of file xmipp_funcs.cpp.

{
    static  unsigned int seed;
    int rand_return;
    struct timespec highresTime;

#ifdef __MACH__ // OS X does not have clock_gettime, use clock_get_time

    clock_serv_t cclock;
    mach_timespec_t mts;
    host_get_clock_service(mach_host_self(), CALENDAR_CLOCK, &cclock);
    clock_get_time(cclock, &mts);
    mach_port_deallocate(mach_task_self(), cclock);
    highresTime.tv_sec = mts.tv_sec;
    highresTime.tv_nsec = mts.tv_nsec;
#else

    clock_gettime(CLOCK_REALTIME, &highresTime);
#endif

    srand(rand()+clock()+time(NULL)+highresTime.tv_nsec);
    rand_return = rand();

    time_t t;
    time(&t);
    //rand_return = abs(rand_return);
    idum = (-(int)(t % 10000)
            - (int)(rand_return % 10000));
    ran1(&idum);
    seed = (unsigned int)rand_return;
    return seed;
}

RealImag2Complex()

template<typename T >

void RealImag2Complex	(	const T *	_real,
		const T *	_imag,
		std::complex< double > *	_complex,
		int	length
	)

Real/Imaginary –> Complex

The output array(s) must be already resized.

This function is not ported to Python.

Definition at line 408 of file xmipp_funcs.h.

{
    T* aux_real = (T*) _real;
    T* aux_imag = (T*) _imag;
    double* aux_complex = (double*) _complex;

    for (int i = 0; i < length; i++)
    {
        *aux_complex++ = (double)(*aux_real++);
        *aux_complex++ = (double)(*aux_imag++);
    }
}

rnd_gaus() [1/2]

double rnd_gaus

(

)

Produce a gaussian random number with mean 0 and standard deviation 1

std::cout << "This random number should follow N(0,1): " << rnd_gaus()
<< std::endl;

Definition at line 466 of file xmipp_funcs.cpp.

{
    return gasdev(&idum);
}

rnd_gaus() [2/2]

double rnd_gaus	(	double	a,
		double	b
	)

Produce a gaussian random number with mean a and standard deviation b

std::cout << "This random number should follow N(1,4): " << rnd_gaus(1,2)
<< std::endl;

Definition at line 470 of file xmipp_funcs.cpp.

{
    if (b == 0)
        return a;
    else
        return b*gasdev(&idum) + a;
}

rnd_log()

double rnd_log	(	double	a,
		double	b
	)

Produce a log uniform random number between a and b

Watch out that the following inequation must hold 0<a<=b.

std::cout << "This random number should be between 1 and 1000: "
<< rnd_log(10,1000)<< std::endl;

Definition at line 583 of file xmipp_funcs.cpp.

{
    if (a == b)
        return a;
    else
        return exp(rnd_unif(log(a), log(b)));
}

rnd_student_t() [1/2]

double rnd_student_t

(

double

nu

)

Produce a t-distributed random number with mean 0 and standard deviation 1 and nu degrees of freedom

std::cout << "This random number should follow t(0,1) with 3 degrees of freedon: " << rnd_student_t(3.)
<< std::endl;

Definition at line 453 of file xmipp_funcs.cpp.

{
    return tdev(nu, &idum);
}

rnd_student_t() [2/2]

double rnd_student_t	(	double	nu,
		double	a,
		double	b
	)

Produce a gaussian random number with mean a and standard deviation b and nu degrees of freedom

std::cout << "This random number should follow t(1,4) with 3 d.o.f.: " << rnd_gaus(3,1,2)
<< std::endl;

Definition at line 457 of file xmipp_funcs.cpp.

{
    if (b == 0)
        return a;
    else
        return b*tdev(nu, &idum) + a;
}

rnd_unif() [1/2]

double rnd_unif

(

)

Produce a uniform random number between 0 and 1

std::cout << "This random number should be between 0 and 1: " << rnd_unif()
<< std::endl;

Definition at line 440 of file xmipp_funcs.cpp.

{
    return ran1(&idum);
}

rnd_unif() [2/2]

double rnd_unif	(	double	a,
		double	b
	)

Produce a uniform random number between a and b

std::cout << "This random number should be between 0 and 10: " << rnd_unif(0,10)
<< std::endl;

Definition at line 444 of file xmipp_funcs.cpp.

{
    if (a == b)
        return a;
    else
        return a + (b - a)*ran1(&idum);
}

solve_2nd_degree_eq()

int solve_2nd_degree_eq	(	double	a,
		double	b,
		double	c,
		double &	x1,
		double &	x2,
		double	prec = XMIPP_EQUAL_ACCURACY
	)

Solve second degree equation

ax^2+bx+c=0

It returns the number of real solutions, 0 if the two roots are complex and -1 if the equation is impossible to satisfy (Ex: 7=0). A number is said to be 0 if its absolute magnitude is smaller than precision. This is used to avoid dividing by 0

Definition at line 153 of file xmipp_funcs.cpp.

{
    // Degenerate case?
    if (fabs(a) < prec)
    {
        if (fabs(b) < prec)
            return -1;
        else
        {
            x1 = -c / b;
            return 1;
        }
    }

    // Normal case
    double d = b * b - 4 * a * c;
    if (d < 0)
        return 0;
    else
    {
        x1 = (-b + sqrt(d)) / (2 * a);
        x2 = (-b - sqrt(d)) / (2 * a);
        return 2;
    }
}

student_from_t0()

double student_from_t0	(	double	t0,
		double	degrees_of_freedom
	)

student area from t0 to inf

By default the student mean is 0 and the student standard deviation is 1. There is no restriction over the sign of t0

Definition at line 548 of file xmipp_funcs.cpp.

{
    return 1 -student_up_to_t0(t0, degrees_of_freedom);
}

student_outside_probb()

double student_outside_probb	(	double	p,
		double	degrees_of_freedom
	)

t0 for a given two-sided probability

This function returns t0 such that the student probability outside t0 is equal to p

Definition at line 553 of file xmipp_funcs.cpp.

{
    // Make a Bolzano search for the right value
    double pm, t1, t2, tm;
    t1 = 0;
    t2 = 100;
    do
    {
        tm = (t1 + t2) / 2;
        pm = student_outside_t0(tm, degrees_of_freedom);
        if (pm > p)
            t1 = tm;
        else
            t2 = tm;
    }
    while (fabs(pm - p) / p > 0.005);
    return tm;
}

student_outside_t0()

double student_outside_t0	(	double	t0,
		double	degrees_of_freedom
	)

student area outisde -t0 to t0

By default the student mean is 0 and the student standard deviation is 1. t0 must be positive

Definition at line 535 of file xmipp_funcs.cpp.

{
    return 1 -student_within_t0(t0, degrees_of_freedom);
}

student_up_to_t0()

double student_up_to_t0	(	double	t0,
		double	degrees_of_freedom
	)

student area from -inf to t0

By default the student mean is 0 and the student standard deviation is 1. There is no restriction over the sign of t0

Definition at line 540 of file xmipp_funcs.cpp.

{
    if (t0 >= 0)
        return 1.0 -student_outside_t0(t0, degrees_of_freedom) / 2;
    else
        return student_outside_t0(t0, degrees_of_freedom) / 2;
}

student_within_t0()

double student_within_t0	(	double	t0,
		double	degrees_of_freedom
	)

student area from -t0 to t0

By default the student mean is 0 and the student standard deviation is 1. t0 must be positive

Definition at line 529 of file xmipp_funcs.cpp.

{
    return 1 -betai(degrees_of_freedom / 2, 0.5,
                    degrees_of_freedom / (degrees_of_freedom + t0*t0));
}

swapbytes()

void swapbytes	(	char *	v,
		unsigned long	n
	)

Conversion little-big endian

This function is not ported to Python.

Definition at line 1040 of file xmipp_funcs.cpp.

{
    char            t, t0, t1, t2, t3;
    switch (n)
    {
    case 4:
        t0 = v[0];
        t1 = v[1];
        v[0]=v[3];
        v[1]=v[2];
        v[2]=t1;
        v[3]=t0;
        break;
    case 2:
        t = v[0];
        v[0] = v[1];
        v[1] = t;
        break;
    case 1:
        break;
    case 8:
        t0 = v[0];
        t1 = v[1];
        t2 = v[2];
        t3 = v[4];
        v[0]=v[7];
        v[1]=v[6];
        v[2]=v[5];
        v[3]=v[4];
        v[4]=t3;
        v[5]=t2;
        v[6]=t1;
        v[7]=t0;
        break;
    default:
        for (size_t i=0; i<n/2; i++ )
        {
            t = v[i];
            v[i] = v[n-1-i];
            v[n-1-i] = t;
        }
    }
}

time_config()

void time_config

(

)

Read the system clock frequency

This operation is needed only once in a program always we want to have a time measure, or an estimation of remaining time.

time_config();

This function is not ported to Python.

Definition at line 628 of file xmipp_funcs.cpp.

{
#ifndef __MINGW32__
    XmippTICKS = sysconf(_SC_CLK_TCK);
#else

    XmippTICKS = CLK_TCK;
#endif
}

time_to_go()

double time_to_go	(	ProcessorTimeStamp &	time,
		double	fraction_done
	)

Returns the estimated time left to finish

To make this estimation the starting time must have been annotated before and the fraction of the total amount of work must be estimated by the programmer. See Time managing for an example.

This function is not ported to Python.

Definition at line 757 of file xmipp_funcs.cpp.

{
    ProcessorTimeStamp now;
    times(&now);
    double totalTime = (now.tms_utime - time.tms_utime +
                        now.tms_stime - time.tms_stime) / XmippTICKS;
    return totalTime*(1 - fraction_done) / fraction_done;
}

TimeMessage()

void TimeMessage

(

const std::string &

message

)

Shows a message and the time it was produced

The format of the printing is "14:11:32 (12) => Hello, world", ie, The message "Hello, world" was produced at 14:11:32 o'clock of the day 12. This function needs not to read the time configuration (see time_config).

TimeMessage("Hello, world");

This function is not ported to Python.

Definition at line 768 of file xmipp_funcs.cpp.

{
    struct tm *T;
    time_t     seconds;

    if (time(&seconds) < 0)
        seconds = 0;
    T = localtime(&seconds);

    printf("%2d:%2d:%2d (day=%2d) =>%s ", T->tm_hour,
           T->tm_min, T->tm_sec, T->tm_mday, message.c_str());
}

tstudent1D()

double tstudent1D	(	double	x,
		double	df,
		double	sigma,
		double	mu = 0
	)

1D t-student value

This function returns the value of a univariate t-student function at the point x, and with df degrees of freedom

Definition at line 188 of file xmipp_funcs.cpp.

{
    x -= mu;
    double norm = exp(gammln((df+1.)/2.)) / exp(gammln(df/2.));
    norm /= sqrt(df*PI*sigma*sigma);
    return norm * pow((1 + (x/sigma)*(x/sigma)/df),-((df+1.)/2.));

}

unmapFile()

void unmapFile	(	char *&	map,
		size_t &	size,
		int &	fileDescriptor
	)

Unmap file

Definition at line 1013 of file xmipp_funcs.cpp.

{
#ifdef XMIPP_MMAP
    if (munmap(map, size) == -1)
        REPORT_ERROR(ERR_MEM_NOTDEALLOC,"Cannot unmap memory");
#else

    delete []map;
    map=NULL;
#endif

    close(fileDescriptor);
}

xmippFREAD()

size_t xmippFREAD	(	void *	dest,
		size_t	size,
		size_t	nitems,
		FILE *&	fp,
		bool	reverse = false
	)

Read from file

This function is the same as fread from C, but at the end there is a flag saying if data should be read in reverse order or not.

double f;
xmippFREAD(&f, sizeof(double), 1, fp, TRUE); // Reverse order

double f;
xmippFREAD(&f, sizeof(double), 1, fp); // Normal order

This function is not ported to Python.

Definition at line 902 of file xmipp_funcs.cpp.

{
    size_t retval;
    if (!reverse)
        retval = fread(dest, size, nitems, fp);
    else
    {
        char *ptr = (char *)dest;
        bool end = false;
        retval = 0;
        for (size_t n = 0; n < nitems; n++)
        {
            char * ptrp = ptr + size - 1;
            for (size_t i = 0; i < size; ++i, --ptrp)
            {
                if (fread(ptrp, 1, 1, fp) != 1)
                {
                    end = true;
                    break;
                }
            }
            if (end)
                break;
            else
                retval++;
            ptr += size;
        }
    }
    if (retval != nitems)
        REPORT_ERROR(ERR_IO_NOREAD,"XmippFREAD: An error occurred or End of File was reached.");

    return retval;
}

xmippFWRITE()

size_t xmippFWRITE	(	const void *	src,
		size_t	size,
		size_t	nitems,
		FILE *&	fp,
		bool	reverse = false
	)

Write to file

This function is the same as fread from C, but at the end there is a flag saying if data should be read in reverse order or not.

This function is not ported to Python.

Definition at line 937 of file xmipp_funcs.cpp.

{
    size_t retval;
    if (!reverse)
        retval = fwrite(src, size, nitems, fp);
    else
    {
        char *ptr = (char *)src;
        bool end = false;
        retval = 0;
        for (size_t n = 0; n < nitems; n++)
        {
            char * ptrp = ptr + size - 1;
            for (size_t i = 0; i < size; ++i, --ptrp)
            {
                if (fwrite(ptrp, 1, 1, fp) != 1)
                {
                    end = true;
                    break;
                }
            }
            if (end)
                break;
            else
                retval++;
            ptr += size;
        }
    }
    return retval;
}