PROFASI
Version 1.5

The default histogram utility in ProFASi is based on His1D. More...
#include <His1D.hh>
Public Member Functions  
His1D ()  
Default constructor.  
His1D (int nbl)  
Create His1D with nbl blocks (create nbl histograms)  
His1D (double xmn, double xmx, int npnts, int numblocks=1)  
Construct with xmin, xmax, number of bins and number of blocks.  
His1D (double xmn, double xmx, double bnsz, int numblocks=1)  
Construct with xmin, xmax, bin size and number of blocks.  
His1D (const His1D &)  
Copy constructor (copies data, so do not initialize after this!)  
His1D &  operator= (const His1D &) 
Assignment operator (copies data, do not initialize after this!)  
void  Name (std::string nm) 
Give it a name.  
void  init () 
Initializes using info about range etc.  
void  reset () 
Reset all data (init calls this)  
void  NBlocks (int n) 
Make it a histogram of n blocks.  
int  NBlocks () const 
Return the number of blocks.  
long  n_entries (int i) const 
number of entries in block i  
long  n_entries_in_range (int i) const 
number of entries in block i in range  
void  Range (double x0, double x1) 
Set range.  
void  Nbins (int v) 
Set number of bins.  
int  Nbins () const 
Get number of bins.  
void  set_bin_size (double sz) 
Set bin size.  
double  Xmin () const 
Get xmin.  
double  Xmax () const 
Get xmax.  
double  Xbin () const 
Get bin size.  
double  xval (int i) 
x value for the middle of i'th bin  
double  yval (int iblk, int i) 
y value for the middle of i'th bin  
int  put (double x, int iblk=0) 
put value x into the iblk block  
int  nput (double howmanytimes, double x, int iblk) 
put n indentical values at once  
double  normalize () 
normalize histogram so that each block sums to 1  
double  unnormalize () 
unnormalize histogram so that each block sums to its occupancy  
virtual void  Export (const char *filename, int normmode=2, int datlayout=2) 
Export data in text format to a given file.  
int  Import (const char *filename) 
Import histogram data written in the format of Export function.  
virtual His1D &  operator+= (His1D &) 
Add information from another given histogram.  
This class can be used to construct histograms of one variable in ProFASi. In practice, the derived class AdaptiveHis, which can adjust its own range is used. But most of the functionality of the histograms is implemented in His1D, and is described here. Typical use:
His1D his; his.Range(0,25); his.NBins(100); his.init(); while (you are doing something useful) { do_some_great_calculations(); x=a_very_important_number(); his.put(x); } his.Export("his_avim.dat");
When you "put" lots of numbers into a His1D object as above, it measures how often the values you put were in different bins. The bins are calculated between the range you provide and the number of bins you set. Upon "Export()", you get a file with what the histogram has measured. Just how the measured histograms are reported in the output file varies, and needs a bit more explanation.
A histogram may or may not be normalized. If it is not normalized, the y values for each x bin is simply the frequency of data points in the range (x0.5*dx, x+0.5*dx). There is a function normalize() that can ask the histogram to normalize its data, so that the sum of the y values for all x bins is 1. The normalization can be undone with the unnormalize() function. But an explicit call to normalize() is normally not necessary. When the histogram is saved, the data written to the file is normalized, without changing the internal frequency counts. This way, a histogram can save normalized data at intermediate stages during a run, without messing up the frequencies. So, you don't normally need to call normalize().
Sometimes, the absolute observed frequencies rather than normalized data is of interest. So, it should be possible to save them. Therefore, the function "Export()" can be given a normalization mode parameter.
his.Export
("his_avim.dat",0);
The raw frequencies are then saved with no normalization. Two additional modes of normalization are supported. Normalization mode 1 means that the sum of the values at all bins is 1. In normalization mode 2, sum of the values at each bin multiplied by the bin sizes is 1. In mode 1, two histograms of the same data, with different bin sizes, will superficially look different when plotted. The one with bigger bins will end up with larger amplitudes. In mode 2, the height of the histogram plots will be unchanged when bin size is changed.
Another important aspect of His1D objects is that they are intrinsically indexed. Meaning, if you need 8 histograms for the same quantity corresponding to 8 values of some state designator, you only need one His1D. But you give it 8 blocks with the NBlocks(int) function. As an example, we take a parallel tempering run with 64 temperatures. Histograms of energy at every temperature is interesting. But then we end up with 64 histograms for total energy, and 64 again for every other quantity we wish to measure. In situations like this, you create a His1D object with many blocks, 64 in this case. Data for different blocks are written into the same output file, and of course, each block is separately normalized. In principle, this is just a way to combine related histograms into one file for the output, and one object for less cumbersome handling in the program.
There are two supported layouts for the histogram data. One can choose the desired layout by passing an additional parameter to "Export()".
his.Export
("his_avim.dat", 2,2);
The layout referred to as "profasi_his_v1" is the layout familiar to ProFASi users from older versions of the program. The data blocks are organized as:
b0 x0 y00 b0 x1 y01 b0 x2 y02 b0 x3 ... ... blank line b1 x0 y10 b1 x1 y11 etc.
In the above, b0, b1 etc were integer block identifiers. The different blocks could represent, for instance, different temperatures. Plotting this kind of a histogram file in GNUPLOT is easy:
gnuplot>
p "myhis.dat" u 2:3 w l
This gives one line for each block. But this format is not very economic. The X values are repeated in every block. The numbers b0, b1 etc are written many times. The second supported format addresses these issues. The layout referred to as "profasi_his_v2" is like this:
x0 y00 y10 y20 y30 ... x1 y01 y11 y21 y31 ... x2 y02 y12 y22 y31 ... etc.
The first column has the X values. The subsequent columns have the Y data for blocks 0, 1, 2 ... The block numbers are never written. The X values are written once. To plot it in GNUPLOT write:
gnuplot>
p "myhis.dat" u 1:someblock w l
This will plot only one line at a time, depending on what block you choose.
If the histogram has only a single block, the block id is always 0 and is not written even in the layout profasi_his_v1. In this situation, the two layouts are equivalent. Histograms generated with ProFASi versions up to 1.2 were always in layout profasi_his_v1. In version 1.5, the default layout is changed to profasi_his_v2. The program his1dmerge (See Merging and converting ProFASi histograms with his1dmerge) can be used to change histogram data layout as well as normalization modes.
His1D::His1D  (  double  xmn, 
double  xmx,  
double  bnsz,  
int  numblocks = 1 

) 
The given range (xmn, xmx) is symmetrically extended to accommodate an integral number of bins of the requested size, if needed.

virtual 
Choose between different normalization modes and data layout options as described above.
Reimplemented in prf_utils::AdaptiveHis.
void His1D::set_bin_size  (  double  sz  ) 
Create bins of a given size. The existing histogram range is extended to accommmodate an integral number of bins.