MALT template, scripts, and documentation

Updated and packaged by Steve Whiteley (stevew@wrcad.com)
Available from http://wrcad.com/freestuff.html

11/14/2015

Added new parser code in init.c, which allows white space in the right
side of parameter definitions.  In particular, one can now include
command line options in the wrspice/jspice3 calls in init.config,
e.g.,

  SPICE_CALL_NAME  = wrspice -j

The "-j" (jspice3 compatibility mode) is no longer added internally
for wrspice.

Notes from Quentin Herr:

  The circuit example would also benefit from *not* having the netlist
  values pre-defined in the .param file before being used in the .cir
  file.  This may have been useful at the time...now days I just use
  the .cir file by itself because you can include whatever math you
  want to do in there.

  Finally, people are likely to conclude that the optimization
  algorithm is ineffective unless they transform parameters to log
  space.  [Herr, Quentin P., and Mark W.  Johnson.  "Improved methods
  for yield-optimization of digital logic." Applied Superconductivity,
  IEEE Transactions on 11.1 (2001):  1078-1081.] Might be possible to
  handle this in the circuit example without modifying the Malt
  code...not sure.

--------------------------
11/06/2015

To run the tutorial example:
1. You must build the malt executable, and place it in your
   shell search path.
2. Either WRspice or Jspice3 must be installed (see wrcad.com
   for info about these programs).

You should edit init.config and set the SPICE_CALL_NAME
as appropriate by commenting/uncommenting the two choices.

In this version of malt, there is only one executable, named "malt". 
In the text below, make the following substitutions:

init ->  malt -i
opt  ->  malt -o
marg ->  malt -m

In the text below, "jspice" represents either wrspice or jspice3.

The scripts will handle either simulator transparently, other than
setting SPICE_CALL_NAME in init.config.

--------------------------------------------------------------------
MALT TUTORIAL 


1. What is MALT?
This is your tutorial guide to MALT, so named for its multi-parameter 
optimization function.  The user must supply a circuit description, 
nominal parameter values for which the circuit works correctly, and 
definitions of the input and output nodes of the circuit.  MALT does 
the rest; it first generates pass/fail criteria which are then used to 
calculate parameter margins and optimize parameter values.  This 
tutorial consists of three parts: installation, description of 
commands using an example circuit, and a description of the 
algorithms and suggestions for their effective use.


2. How to Get Help
The developers, Quentin Herr and Kris Gaj, can not be far away.  We 
welcome your questions and comments.


3. Installation
Please proceed as follows to get started.  The following line should 
be added to your .cshrc file:
	set path = (TRW $path)
(the above line should set the path to the executables opt, marg, init.)


4. The MALT Command "init"

We will now step through the program features using the example 
files in the directory MALT/IN.  The "init" command generates a 
pass/fail file using three files which together describe the xor gate:
*	xor.cir is a simple jspice circuit description with one 
important difference; the values of all relevant parameters are 
given as variables.  In this example, the subcircuits which comprise 
the xor gate are defined in the .include files at the beginning of the 
circuit description.  Refer the these subcircuits the see the variable 
names and how they are used.
*	xor.param is a jspice file which assigns nominal values to the 
variables used in the above circuit description.  In this example, the 
explicit variable assignments are made in the .include files.  We 
hope the exemplary use of URI's growing standard library of circuit 
components in the above files will inspire you to do likewise.
*	xor.io is a jspice file which defines the input/output nodes of 
the circuit.  This information is used by MALT to generate the 
pass/fail criteria.  The first line gives the numbers of clock, input, 
internal, and output nodes in the circuit.  Line two is an artifact 
appearing for the benefit of HOSE which runs using these same 
circuit description files, but that's a different story...just include 
this line as it is.  The next three lines name and explicitly identify 
the nodes and the associated junctions.

From your MALT directory, the command
	init xor
will generate the file "IN/xor.passfail".  In general terms, the 
pass/fail file contains instructions to check the phase of the 
junctions at the output nodes once every clock cycle.  It is 
imperative that the circuit works correctly using the nominal 
parameter values.  Otherwise, the pass/fail criteria will not be 
correct.  The file features syntax which is reminiscent of that used 
in the jspice .check operation range mapping.  The user may modify 
the file as desired but be forewarned that the syntax can be 
difficult.

At this point you can check the circuit behavior with the command
	jspice graph
which performs the circuit simulation and graphs the voltage and 
phase at the given nodes.  Secondly, you can check the file 
"OUT/xor.nom.logic" which traces the pulses at the input, output, and 
internal nodes.  This file is automatically generated by the "init" 
command.


5. The MALT Command 'opt'

The 'opt' command performs multi-parameter optimization which 
calculates parameter margins, centers parameter values in the 
operating region using an iterative process, and then recalculates 
parameter margins.  The .cir and .passfail files described above are 
used in addition to the following files:
*	xor.param1 is a jspice file which assigns numerical values to 
all parameters except those which are to optimized; these are 
assigned variable values param[n].
*	xor.init1 is a data file containing the number of parameters to 
be optimized, their names, nominal values, percent variations 
reflecting the fabrication process, and the low and high limits on 
parameter values.

From your MALT directory, the command 
	opt xor 1
will initiate the optimization procedure, with output directed to the 
screen and the file "OUT/xor.out1".

To perform a second optimization, you could write files "xor.param2" 
and "xor.init2".  The command "opt xor 2" would then optimize the 
given parameters using the same pass/fail and circuit description 
files described above.


6. The MALT Command 'marg'

The 'marg' command calculates (one dimensional) parameter 
margins, lists them in ascending order, and then terminates.  It uses 
exactly the same files described for 'opt'.

From your MALT directory, the command 
	marg xor 1
will initiate calculation of margins.


7. Effective Use of the  Algorithm 'init'

The behavior of this algorithm is influenced by the variables defined 
in the "init.config" file, which is located in your MALT directory.  You 
may wish to modify some of these values after you understand their 
function.

For synchronous cells, the phase of the junctions associated with 
the output nodes is checked once every clock cycle.  The location of 
this check within the clock cycle is defined by CHECKPOINT_RATIO.  
The value of phase of is deemed correct within plus/minus 
FAIL_THESHOLD of the expected value.  INPUTS_CHECKED gives 
optional checking of the input junctions to insure against backward 
traveling pulses.  For asynchronous cells, the relevant junctions are 
checked at time intervals before and after each expected phase 
change.

Consider the following issues:
*	Does the circuit work correctly using the nominal parameter 
values?
*	Do the input pulses test the full range of circuit behavior?
*	Does the simulation test the full range of circuit behavior?


8. Effective use of the Algorithm "opt"

The operating region of the circuit is approximated in multi-
dimensional parameter space by connecting points lying on the 
boundary to form a convex hull.  The largest possible ellipsoid is 
inscribed in the hull, with axes in proportion to the parameter 
spread value.  Parameter values are taken to lie at the ellipsoid 
center.   Boundary points are added in an iterative process.

The program terminates automatically when the axes fail to 
increase by one percent or more over several iterations.  To force 
the program to terminate while it is running, erase the ITERATE file 
in your MALT directory.  The program will still recalculate margins 
before exiting, so it may take awhile.  Attempts to terminate using 
control-C are generally not successful and may lose your output.  
Points are found using a binary search between the minimum and 
maximum parameter values.  BINSEARCH_ACCURACY, defined in the 
'init.config' file, is defined as a percentage of the nominal value.

Consider the following issues:
*	Parameter value limits are defined by the user in the .init file.  
Make sure these limits are not restricting your optimization.
*	Concavities in the operating region are not dealt with 
correctly because the approximating hull is always convex.  In 
Redefinition of parameters can solve this problem.
*	Optimization is most effective using nine or less parameters.
*	For a larger circuit, successive optimizations taking several 
parameters at a time has proven highly effective.  The critical 
parameter(s) must always be included in each successive 
optimization in order to obtain meaningful results.

