***
*** notes.txt
***

June 15th, 2017
Chris Bridge, Version 1.0, Loading Bench Data in DVM
cbridge@simplis.com 603-782-4684

Contents
	1. Overview
	2. Files Included In The Archive
	3. How It Works (top level view)
	4. IMPORT_FILENAME
	5. SPECS_FILENAME
	6. Known Issues

1. Overview

	This archive contains example files and scripts for a prototype system which 
	loads bench waveform data into DVM after each DVM test. The implementation
	uses several files and custom scripts which will be described in section 2.
	The implementation we chose uses tab delimited text files to instruct the 
	scripts what data to process, and what specifications to check. This system
	is in no way complete, nor is it the only way to implement the system, rather
	this method yields an easy to read set of files which can be edited in any
	text editor or Microsoft Excel.

	This is only a prototype and the custom scripts used are not supported in any
	way. You may use or modify this framework in any way you like.

2. Files Included In The Archive

Directories and their functions

	bench data 1
		holds the measured bench data to be loaded into DVM. This directory is 
		stored on the DVM Control Symbol as the IMPORT_DIR property value.

	css
		Contains the custom cascading style sheet file for the DVM reports.

	docs
		The documentation directory

	Modeling Blocks
		The directory of schematic component files for the example schematic.

	scripts
		Custom scripts for the example.

	support
		LoadComponentValues files which configure the schematic. Docs:
		(http://www.simplis.com/documentation/link/simplis/17560) 
		(http://www.simplis.com/documentation/link/simplis/16186)

	testplans
		Contains the testplans for the example, currently only one testplan exists.
	
Files

	These two files contain import commands (IMPORT_FILENAME) and specification information (SPECS_FILENAME).
		bench data 1\import.txt
		bench data 1\design_specs.txt

	These three files contain waveform data in ASCII format:
		bench data 1\Ac Analysis\Bode Plot\Vin Nominal\100% Load\ac.txt
		bench data 1\Steady-State\Steady-State\Vin Minimum\50% Load\pop.txt
		bench data 1\Transient\Step Load\Vin Maximum\50% Load to 100% Load\tran.txt

	Style sheet for the reports:
		css\modified.css
	
	Documentation:
		docs\DVM Proposal V1.0.pptx
		docs\measurement_defs.txt
		docs\notes.txt

	.SXCMP files:
		Modeling Blocks\3p2zcompensator.sxcmp
		Modeling Blocks\delay_block_both.sxcmp
		Modeling Blocks\delay_block_falling.sxcmp
		Modeling Blocks\delay_block_rising.sxcmp
		Modeling Blocks\drive_logic_and_drivers.sxcmp
		Modeling Blocks\latched_comparator.sxcmp

	Scripts:
		scripts\check_specs.sxscr
		scripts\function_filter.sxscr
		scripts\import_data.sxscr
		scripts\import_data_worker.sxscr
		scripts\register_functions.sxscr
	
	LoadComponentValues Files:
		support\default.txt
		support\stepload.txt
	
	The testplan:
		testplans\data_import_example.testplan

	Test Schematic:
		bench_data_example.sxsch

3. How It Works (top level view):

	Each DVM test in the testplan (testplans\data_import_example.testplan)
	configures the schematic for the test to be performed. 
	After the simulation completes, two post process scripts are run.
	The post process scripts are written in the SIMetrix script language.
	This language uses simple structured programming (no objects)
	and the scripts are supported by a host of binary commands and functions.
	Users can add their own custom binary functions, as either binary (C++ DLL),
	or as SIMetrix scripts. In this example we have provided an filter function
	which is implemented as a SIMetrix script. The script file
	(scripts\function_filter.sxscr) contains that code.
	
	--- Waveform Data Import ---
	
		These two scripts:
			
			scripts\import_data.sxscr
			scripts\check_specs.sxscr
		
		are DVM post process scripts and as such are passed a fixed set of 
		arguments. One of these arguments identifies the DVM Control Symbol
		on the schematic. This allows the post process scripts to read all
		DVM Control Symbol properties, including three special properties
		we have added to the Control Symbol on the example schematic:
		
			IMPORT_DIR
				Defines the root directory which holds the data to load from disk.
				Both IMPORT_FILENAME and SPECS_FILENAME files are expected
				to reside in this directory. In this example, IMPORT_DIR
				is set to "bench data 1".

			IMPORT_FILENAME
				Defines the filename in IMPORT_DIR directory w/ instructions
				for data import. In this example, this file is located at:
				"bench data 1\import.txt"

			SPECS_FILENAME
				Defines the filename for the design specifications file in 
				the IMPORT_DIR directory. In this example, this file is located at:
				"bench data 1\check_specs.txt"
		
		The scripts\import_data.sxscr script loads waveform data from files on disk,
		using a "worker" script (scripts\import_data_worker.sxscr). The import_data
		script first determines the directory where any data resides by reading the
		current test label, which is passed into the script by DVM, and by reading
		DVM Control Symbol's IMPORT_DIR property. It then passes this information
		onto the worker script, along with other information.
		
		The import_data_worker script is passed the IMPORT_FILENAME, which is
		stored on the DVM Control Symbol, along with the current test objective type
		and the data directory where the data to load is being stored. Our 
		implementation using the test label to determine the location of the data and
		is certainly not the only way to store and access data. It was simple
		to implement and is robust. An alternate solution would be some data structure
		which effectively maps the current test's label to a directory containing
		waveform data.
		
		The worker script opens the IMPORT_FILENAME, in this example, this file is:
		
			bench data 1\import.txt
		
		It then processes commands to create graphs, curves, and measurements. In
		the SIMetrix waveform viewer, these three elements can be thought of as having
		a hierarchical arraignment:
		
			Graphs
				Curves
					Measurements
		
		The post process scripts only process the data defined in the IMPORT_FILENAME.
		You can have additional data in the data directory for the test, and DVM
		will ignore this data unless explicitly told to process it.
	
	--- Specification checking ---
	
		The scripts\check_specs.sxscr script checks design specifications - in DVM, specifications
		are defined as a PASS/FAIL condition based on comparison of a measurement to a numerical value.
		Measurements are typically made on curves using fixed probe measurements, or in this extension
		of the program, measurements are defined in the IMPORT_FILENAME. Both types of measurements
		output the measured value to the graph viewer legend, under the curve name.
		All measurements are expected to be made by fixed probes, or defined in the IMPORT_FILENAME,
		which is processed by the import_data.sxscr script.
		
		The specification checking is performed by reading in the SPECS_FILENAME, which
		contains the specification information, and by reading all measurements on the
		waveform viewer. The script then finds matches between curve names on the waveform
		viewer and the curve names defined in the SPECS_FILENAME.
		Curve names in DVM are expected to be unique.
		
		If a match for the curve name is found, the script processes all measurements
		for that curve defined in the SPECS_FILENAME, and concatenates a specification
		string to be returned to DVM. The concatenated specification string is passed 
		back to DVM via the standard DVM script interface (retval[1] in these scripts).

4. IMPORT_FILENAME

	The IMPORT_FILENAME file is a plain ASCII text file with tab delimiters. 
	The file is located in the IMPORT_DIR directory.
	From left to right, the columns are:
	
		- Test Type
		- Action
		- File
		- Existing Graph Name
		- Curve Name
		- Grid Index
		- Axis Name
		- Color
		- Function/Measurement
	
	- Column descriptions
		a) Test Type. The Test Type column is one of the test objectives. This example implements three test
		objectives:
	
			- Bode Plot
			- Step Load
			- Steady-State

		Adding more objectives is a simple task.
		
		When the file is read in, the post process script knows the currently executing test label.
		This label is defined in the testplan, is passed to the script via the standard DVM script interface,
		and allows the script to decode the test objective.
		
		Only import actions matching the Test Type will be processed.
		
		b) Action. The Action column tells the script what action to take, currently there are three implemented:

			- Graph ~ load a text file containing waveform vectors as a SIMetrix data group
			- Curve ~ Plot a curve using vectors from the File
			- Measure ~ Make a measurement on the curve
		
		c) File. Defines the file which contains the waveform data. Waveform data must be formatted
		so that it can be read in with the OpenGroup command (http://www.simplis.com/documentation/link/simplis/7502).
		Each curve plotted must have the correct file associated with it's entry so the script can plot the data.
		
		d) Existing Graph Name. This is the name of an existing graph on which to plot curves.
		See examples or any dvm_graph_object_file.txt in a DVM report directory for names.
		
		e) Curve Name. The curve name on the waveform viewer.
		
		f) Grid Index. DVM has a graph object system to uniquely define the location
		of curves on analog axes. Docs here: (http://www.simplis.com/documentation/link/simplis/4623)
		Curves with the same Graph Name, Grid Index, and Axis Name are output to the same axis.
		
			- A1 is the lowest analog axis
			- A2 is the second grid from the bottom, etc.
		
		g) Axis Name. The axis name is a string alias to identify different axes
		
		h) Color. The hex RGB color.
		
		i) Function/Measurement. This is the most important column of all. This column defines
		the vector expression plotted on the graph for curves or the built-in measurements for Measure entries.
		
			For Curves: You can plot a simple vector, such as :vout, the vector names are defined
			in the header row of the waveform data file, above the waveform vector y-axis data.
			You can also plot expressions involving functions, including your own custom functions.
			In the example directory is a generic filter function, implemented in a SIMetrix script.
			It uses a low level binary IIR filter function (http://www.simplis.com/documentation/link/simplis/8449)
			to plot a low pass filtered version of the waveform. UserFilter(:vout,20Meg) will plot a 20MHz
			single pole filtered version of the :vout vector.
			
			This system is extremely powerful. You can write any functions needed to manipulate
			vector data before it is plotted on the waveform viewer. The functions can be written
			in the SIMetrix script language, or in C++ and compiled into a DLL.
			
			Functions written in the SIMetrix script language need to be registered as functions.
			The registration process tells the program that a specific function name should call
			a specific script. You register functions with the RegisterUserFunction Command
			(http://www.simplis.com/documentation/link/simplis/7552). In this example, the script
			(scripts\function_filter.sxscr) is registered as the UserFilter() function during the
			first test in the testplan.
			
			This first test, with label "Setup" doesn't launch a simulation, but instead runs a post process
			script which runs the (scripts\register_functions.sxscr) script which in turn 
			registers the script (scripts\function_filter.sxscr) as a script function UserFilter.
			
			Curves are plotted using the ArbitraryCurve() DVM function. See (http://www.simplis.com/documentation/link/simplis/4517)
		
			For Measurements: This is the "measure specification", which is syntax used
			for all built-in measurements in SIMetrix/SIMPLIS. The first part of the measurement
			is the string name of the measurement. The next four fields correspond to true/false
			flags from the measurement dialog:
			
				- Cursor Span
				- AC Coupled
				- Per Cycle
				- Display on Schematic
			
			In this implementation all flags should be set to 0.
			
			You can also write your own measurements. These custom measurements will be available
			for use in this system. 

5. SPECS_FILENAME

	The SPECS_FILENAME file is a plain ASCII text file with tab delimiters. 
	The file is located in the IMPORT_DIR directory.
	From left to right, the columns are:
	
		- Test Type
		- Curve Name
		- Measurement Name on Legend
		- Min
		- Max
		- Spec Name
		- Text if Passes
		- Text if Fails
		
		a) Test Type. As with 4a. Specifications which match test type will be executed.
		
		b) Curve Name. The curve name on the waveform viewer to get measurement data from.
		
		c) Measurement Name on Legend. This is the text on the waveform viewer legend.
		it identifies the measurement on the curve to get the measured data for.
		
		d) Min. The minimum specification value. Must be a number, can be engineering notation.
		
		e) Max. As with Min, the max spec value. Same rules.
		
		f) Spec Name. Text string output to the report indicating the specification.
		Any string without spaces.
		
		g) Text if Passes. A text string output to the DVM report if the measured value passes.
		%meas, %min, %max are replaced with the Measured Value, Min Spec, and Max Spec respectively.
		
		h) Text if Fails. As with Text if Passes.
		
		Additional notes. The program checks the string length of the Min and Max columns. 
		If both are provided, the program checks if the measured value is between Min and Max.
		If only Min or Max is provided, the program acts accordingly. Measured values are
		compared to specification values with greater than and less than operators. Thus,
		if, in the unlikely event that the measured value equals a spec value, the test will
		fail.
		
		Any failing specification for a test will mark that test a FAIL in the test report.
		Using this system, design specifications can be checked versus both simulation and
		bench waveform data. The resulting overview report will indicate tests which failed
		for either bench or simulation data which falls out of specification.

6. Known Issues

	An error message is output for the Steady State test:
	
ERROR: in simplis_dvm_advanced_util_graph_object_set_params: Cannot find graph object for 
Index	graph_obj_array 
    0	'Curve'
    1	''
    2	'DVM LOAD'
    3	''
    4	'DVM VLOAD'
    5	''
    6	'A1'
    7	'DVM VLOAD Bench (5Meg BW)'
    8	''
    9	''

	We need to look into this. It appears that the curve is being plotted correctly and perhaps
	this message is a "false positive."
	
	
	