
========================     COM-Poisson Code README     =========================

	  Author: Daniel Durnford (d.durnford@queensu.ca)
	  Last Updated: March 25th 2020

==================================================================================

This folder contains code to use the COM-Poisson distribution for desired 
values of the mean and Fano factor. Included are:

	- A CERN ROOT c++ file "COMPoisson.cc" containing functions to use the
	  COM-Poisson distribution. See the file "Function Summary" for information
	  about this code.

	- "Examples.cc" which contains a copy of the code in "COMPoisson.cc" with extra
	  code written to perform examples of its usage (see "Examples.pdf")

	- A compiler called "Makefile" to compile the c++ code.

	- 1000 txt files in a sub-directory "Table4_Alpha" containing the "look-up tables"
	  required to use the code (the name of the directory indicates the version of
	  the tables being used).

	- A file called "Examples.pdf" which contains descriptions of several 
	  examples/demonstrations or diagnostic tests of the COM-Poisson code.	  

------------------------     Setup Instructions     ------------------------------

To prepare this code for use:

	1. Put all of the above content ("Example.pdf" not required) into the
	   same directory.

	2. In "COMPoisson.cc" under the heading "Definition of Tables", first change
	   the string "TableDir" to the path address of the directory you have are
	   working in. 

	3. Make sure the other details of the look-up tables match the
	   version you have downloaded, i.e. the string name of the version, and 
	   parameters Mu_a, Mu_b, Mu_N, F_a, F_b, F_N. These values can be found on
	   the web-page where this repository is downloaded from.

	4. Choose the value of mu at which you want to transition to using a Gaussian.
	   This variable is called "G_Transition", and is defined just under the definition
	   of the look-up table. The default value is 100, and the maximum is 110 (otherwise
	   the code runs into numerical problems with infs).
 
	5. From a terminal, cd into the directory you have chosen and compile the 
	   c++ code using the command "make" (uses "Makefile"). If you rename the c++
	   code, make sure you change corresponding name of the ".exe" file in 
	   "Makefile".

	6. After compiling the c++ code, it can be executed with the command 
	   "./COMPoisson.exe". As is, the code should carry out the tasks of Example 1
	   described in the file "Examples.pdf", producing a histogram (a ROOT TH1D) 
	   built with the COM-Poisson distribution.

-------------------------     Trouble Shooting     -------------------------------

Below is a list of error messages that the c++ code "COMPoisson.cc" may produce:

	- "!!!!!   This pair of points is inside the Bernoulli modes   !!!!!"
	  This warning can be printed out by the functions "BuildCOM", "BuildCOM_Fast",
	  "PCOM", or "PCOM_Fast". It indicates that the values of mu and F desired are
	  inside the Bernoulli modes (not on the Bernoulli modes themselves), and are
	  therefore forbidden. Triggering this error stops the executable.

	- "Can't find the look-up table files! >:(" -> This indicates that either the
	  directory where the look-up table files are stored cannot be found or that
	  any of the other defining parameters of the look-up tables do not match
	  the version you are using. Try double-checking the name of the look-up table
	  version, location of the sub-directory, and other defining parameters to 
	  ensure they match the version you are using.

	- "Warning! BiTerp Corners are Wrong!" -> This warning indicates that the 
	  function "BiTerp" )which performs a bilinear interpolation of the look-up
	  tables) cannot find the four nearest points in mu/F space to the desired 
	  mu/F. This is likely because the table-defining parameters do not match 
	  the version of the table being used. Try checking that these values (Mu_a,
	  Mu_b, Mu_N, F_a, F_b, F_N) are set correctly.

	- "I CAN'T FIND Z! >:(" -> This warning is printed by the function "Z" when it
	  does not converge on a final value of Z after 10000 terms. This is likely 
	  because the function is being called for values of lambda or nu for which the
	  COM-Poisson distribution is undefined, or at least very extreme values. If you
	  think the values of lambda and nu are allowed, you can try manually increasing
	  the number of terms allowed before this warning, or increasing the value "tol"
	  (the required convergence tolerance).

	- "I CAN'T FIND mu! >:(" or "I CAN'T FIND var! >:(" -> This warning is printed 
	  by the function "Moments" when it does not converge on a final value of the 
	  mean or variance after 10000 terms. This is likely because the function is 
	  being called for values of lambda or nu for which the COM-Poisson distribution 
	  is undefined, or at least very extreme values. If you think the values of 
	  lambda and nu are allowed, you can try manually increasing the number of terms 
	  allowed before this warning, or increasing the value "tol" (the required 
	  convergence tolerance).

	- "Warning! Inappropriate use of cdfGauss!" -> This warning is printed by the 
	  function "cdfGauss" when it is called for a value of mu below the globally
	  defined variable "mu_point" which dictates at which point you switch to using
	  a Gaussian distribution.

