- V-FSV Procedure - 

Version: 1.0.0 - Date: 15/08/2006.
----------------------------------

This code implements the FSV procedure illustrated in

A. Duffy, A.Martin,T.Benson,''Progress in quantifying validation data'', 
in Proc.of Intern.Symp on EMC, Boston(USA), August 2003, pag.323-328

A. Duffy, A. Martin, G. Antonini, A. Ciccomancini Scogna, A. Orlandi 
Issues in Validation of Complex-Valued Simulations for Signal Integrity Analysis
in Proc.of Intern.Symp on EMC, S.Clara (USA), August 2004.

----------------------------------

1. SYSTEM'S REQUIREMENTS
------------------------

	1.1 Operating system: WINDOWS 2000 or more recent


2. HOW TO INSTALL
--------------------

      2.1 Copy the content of the .zip file in the working directory (i.e. "FSV")
	
	2.2 An icon file (.ico) is provided. It can be associated to the .exe file by means the usual Windows procedure

	
3. HOW TO START
---------------

	3.1 Run the program's shortcuts in Start Menu bar or Double-Click on Desktop icon 

		3.1.1 Choose "Quit" to exit the program

		3.1.2 Choose "Plot Results" to display results of previously performed analysis (see 3.3)

		3.1.3 Choose "Read Me" to have access to this document

		3.1.4 Choose "TIME DOMAIN" or  "FREQUENCY DOMAIN" to perform the FSV analysis (see 3.2). Then push "Run FSV"
		

	3.2 Select if you are applying the FSV procedure to "TIME DOMAIN" data or "FREQUENCY DOMAIN" data

		3.2.1 TIME DOMAIN: select the pair of data files (.txt) in which your data is contained

		3.2.2 FREQUENCY DOMAIN: select if you wish to compare "MAGNITUDE", "PHASE" or "COMBINED" analysis

			3.2.2.1 MAGNITUDE: select the pair of data files (.txt) in which your data is contained
			
			3.2.2.2 PHASE: select the pair of data files (.txt) in which your data is contained
			
			3.2.2.3 COMBINED: select the two pairs of data files (.txt) in which your MAGNITUDE & PHASE are contained.
				When requested insert the value of k (0 <= k <= 1)
		
		3.2.3 Select FOLDER for Output-Data.

		3.2.4 At the end of the FSV procedure a data display tool (visualizer) will be available

	3.3 The visualizer plots the results contained in the .mat file generated by the FSV procedure

		3.3.1 Select the directory in which your .mat data files are contained using push-button "Folder 1" and "Folder 2". If a 
		      .mat file is contained the push-button get the name of that .mat file
		      (usually indicating the kind of analysis "Magnitude", "Phase", "Combined"). If a .mat file is not contained, a warning
		      message is issued.
			
		3.3.2 Select the radio-button corresponding to the variable (ADMi, etc.) you want to show

			3.3.2.1 To select a new figure, the current one must be de-selected

			3.3.2.2 To select a new folder (a new directory), click on the push-button with the name of the current analysis

	            	3.3.2.3 To export the current figure in bitmap (.bmp) format, push the radio-button "Export Figure". 
				  The corresponding bitmap file will be located in the directory where the plotted data are taken.
			
*************************3.3.2.4 Push ""


4. INPUT DATA STRUCTURE & LOCATION
----------------------------------

	4.1 The pair of files compared by FSV:

		4.1.1 must be in .txt format
		
		4.1.2 must have m rows, 2 columns (frequency - magnitude , frequency - phase , time - magnitude)
		
		

5. OUTPUT DATA STRUCTURE & LOCATION
-----------------------------------

	5.1 The output data (files .fig,.txt and .mat) are saved in the subdirectory "TIME DOMAIN ANALYSIS" 
	    and "FREQUENCY DOMAIN ANALYSIS" according to the kind of analysis carried out.
		

	5.2 For the "COMBINED" analysis the output data are saved in subdirectories of the "FREQUENCY DOMAIN ANALYSIS" 
	    directory named with the value of the k parameter used.

	5.3 The output .txt files are always saved in the working directory. It contains all the coefficients used by FSV PROCEDURE:
            	Ifreq.txt --> vector of the frequencies (after synchronization)
		Datai --> vector of data files (after synchronization)
		LowDatai/Phasei --> 
		HighData/Phasei --> 
		A/F/G-DMi --> punctual parameters of the TIME/FREQUENCY ANALYSIS
		A/F/G-DMc --> confidence parameters of the TIME/FREQUENCY ANALYSIS
		A/F/G-DMiC --> punctual parameters of the COMBINED ANALYSIS
		A/F/G-DMcC --> confidence parameters of the COMBINED ANALYSIS
		A/F/G-DM_average -->contains the A/F/G-DMtot, A/F/G-Dmconf and A/F/G-DMpw_conv values.
		Path_Input_Data: contains the complete path of the two input files used in the FSV run.


6. OUTPUT RESULTS
-----------------

	6.1 There are three significant outputs:

	ADM: is a figure of merit of the comparison of amplitudes and trends of the two datasets to be compared (less it is, better is the comparison)
	FDM: is a figure of merit of the comparison of details (derivatives) of the two datasets to be compared (less it is, better is the comparison)
	GDM: is a figure of merit of the combination of ADM and GDM.

	In the plots generated by the code they are shown as:

	xDMi: values of (x = A,F,G)DM for each pair of samples of the two datasets to be compared
	xDMc: percentage of points in (x = A,F,G)DMi that fall in 6 classes of agreement:

	EXCELLENT for xDMi <= 0.1 , VERY GOOD for 0.1 < xDMi <= 0.2,
	GOOD for 0.2 < xDMi <= 0.4, FAIR for 0.4 < xDMi <= 0.8, 
	POOR for 0.8 < xDMi <= 1.6, EXTREMELY POOR for xDMi > 1.6

	xDM tot: this is the average value of (x = A,F,G)DMi. Can be considered a global figure of merit of the comparison.
	At its value is associated one of the above mentioned 6 classes.
	
	A/F/G-DMconf --> These value are computed by weighting the number of samples of the point-by-point corresponding variables.
	A/F/G-DMpw --> These value are the equivalent scale values.


7. EXAMPLES
-----------
	
	7.1 FREQUENCY DOMAIN --> MAGNITUDE: you can use S11m.txt & S11m_mws.txt (|S11| measured vs. |S11| simulated)
	
	7.2 FREQUENCY DOMAIN --> PHASE: you can use S11p.txt & S11p_mws.txt (Phase of S11 measured vs. Phase of S11 simulated)
	
	7.3 COMBINED --> you can use the above mentioned pairs introducing your k coefficients
	
	7.4 TIME DOMAIN --> MAGNITUDE: you can use V1_transient.txt & V2_transient.txt (two different sets of transient voltages) 


8. Notes
--------

	The output (X=A,F,G)ADM_average.txt files are saved in the working directory.
	It contains the coefficients resulting by FSV routine to convert the FSV value to the 
	six-point scale equivalent:
      	XDMtot 	   --> this is the average value of (x = A,F,G)DMi.
	AVGconf	   --> this is the average value of (x = A,F,G)DMc.
	AVGpw_conv --> this is the result by Algebraic Conversion Routine applied to (x = A,F,G)DMtot.
	
	**********************************************************************************************
	*****     ALGEBRIC CONVERSION ROUTINE     **********               AVGconf               *****
        ***         X=FSV ; V=Visual Rating         *******					  ****
	**********************************************************************************************
	***  					     *****					   ***
	***  If         X<=0.1   V=1 +  10(X)	     ***** AVGconf = 1*(#EX)+2*(#VG)+3*(#G)+	   ***
	***  If X>0.1 & X<=0.2   V=2 +  10(X-0.099)  *****	     +4*(#F)+5*(#P)+6*(#EP)        ***
	***  If X>0.2 & X<=0.4   V=3 +   5(X-0.199)  *****					   ***
	***  If X>0.4 & X<=0.8   V=4 +2.50(X-0.399)  ***** # = number of elements belonging to the ***
	***  If X>0.8 & X<=1.6   V=5 +1.25(X-0.799)  *****     class. It's normalized to length of *** 
	***  If X>1.6            V=6 		     *****     (Low,High) array.                   ***
	***					     *****					   ***
	**********************************************************************************************


9. CONTACTS
-----------

	Prof. A. Duffy,  DMU Applied Electromagnetic Group, apd@dmu.ac.uk
	Prof. A.Orlandi, UAq EMC Laboratory,                orlandi@ing.univaq.it
