----- file created by makedoc on: Thu Nov  5 15:14:56 2009
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/intens.pro -----

 NAME:
	INTENS
 PURPOSE:
	calculates the intensity from a file or set of files
 CATEGORY:
	SHADOW's utilities.
 CALLING SEQUENCE:
	intens,shadow_in,intens_out,Keyword_parameters
 INPUTS:
	shadow_in  may be:
          a SHADOW file (between quotes): eg. 'begin.dat' or
          an IDL-SHADOW structure (without quotes)
 OPTIONAL INPUT PARAMETERS:
	intens_out the name of an IDL variable with the intensity values
 KEYWORD PARAMETERS:
		NOLOST = consider losses
			0 all rays (default option)
			1 exclude losses;
               POLARIZATION = when set to 1 calculates the polarization 
                              parameters:
                              Is (total intensity for s-polarization)
                              Ip (total intensity for p-polarization)
                              S0-stokes = |Es|^2 + |Ep|^2
                              S1-stokes = |Es|^2 - |Ep|^2
                              S2-stokes = 2 |Es| |Ep| cos(phase_s-phase_p)
                              S3-stokes = 2 |Es| |Ep| sin(phase_s-phase_p)
               NSPLIT = set this keyword to an integer to make the
                        calculations in NSPLIT blocks to increase statistics. 
                        For example, using 25000 rays and NSPLIT=5, 
                        the intensity will be calculated for 5 blocks
                        of 5000 rays each.
               BLOCK =This keywors is passed to GetShCol (do not use it
                      together with NSPLIT)
               VERBOSE = Set this keyword to 1 to print some results
 OUTPUTS (When NSPLIT is set):
               SPLITRES = an array of NSPLIT dimension with the 
                        intensity of each group. Only works if NSPLIT
			 is defined. 
               SPLITMEAN = The mean intensity times NSPLIT
               SPLITERROR = The standard deviation of the  intensity 
			times NSPLIT
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	None.
 PROCEDURE;
	Similar to SHADOW's original.
 MODIFICATION HISTORY:
	M. Sanchez del Rio. ESRF. Grenoble, Oct 1992
	96/04/16 MSR change fix() by long() in line 16 (to work for
		large number of rays)
       2006/12/08 srio@esrf.fr fixes a bug when nolost=1
       2009/01/12 srio@esrf.eu rewrites it using getShCol. Added NSPLIT

