## page was renamed from GCAT/GCAT_DOCS
#format wiki
##NOTE: add tags in the following line to make this page easily found
#pagetag template

<<TableOfContents>>

= Installation Guide =
 1. Install all required python packages
 1. Download gcat-0.1.tar.gz
 1. Unpack the file
  . tar –zxvf gcat-0.1.tar.gz
 1. Install the distribution using setup.py inside
  . python setup.py install
 1. Copy or softlink rungcat.py into your common binary path
  . cp gcat/rungcat.py ~/bin/
 1. Set environment variables
  . setenv GCAT_SPECTRE_BINARY_PATH /apps/bin/spectre
  . setenv GCAT_APS_BINARY_PATH /apps/bin/aps
 1. Run global convergence analysis by inserting proper analysis (i.e. gconv_csd/gconv_ebx) to the netlist and giving the netlist as input
  * If suffix is .scs, SPECTRE simulator is called
  {{{
rungcat.py input.scs 
}}}
  * If –l option is appended and the suffix is .scs, APS simulator is called
  {{{
rungcat.py input.scs –l aps
}}}

= User Guide =

(NOTE) Syntax is similar to typical SPECTRE analysis

 * Common GCAT parameters
  * num_retry (=32) : # of retrials when circuit failed to converge at a certain i.c. When this value is more than 1 and a simulator fail to converge with the i.c., i.c. is uniform-randomly sampled again within the hypercube box whose the most far corner point is the previous failed i.c. (this is because we need to push i.c. towards smaller values when convergence failed, assuming that the failing i.c is improbable initial condition that cause too large currents at first)
  * bbox_insts (=“”) : a list of instances/nets which should be black-boxed (i.e. abstracted). No i.c.s (initial conditions) of nodes inside bbox_insts is randomized. Names should be separated by comma (,) and there should always be comma at the end of list. (e.g bbox_insts=“xtop.inst1,”). If name is only composed of numbers it should be escaped like “\1,”.
  * inputs(=“”) : input ports of a circuit to test. Names should be separated by comma (,) and there should always be comma at the end of list. (e.g inputs=“input1,input2,”). If name is only composed of numbers it should be escaped like “\1,”.
  * outputs(=“”) : output ports of a circuit to test. If not specified, isolated X is not found because it is defined in terms of observability to a circuit’s outputs. Names should be separated by comma (,) and there should always be comma at the end of list. (e.g outputs=“output1,output2,”). If name is only composed of numbers it should be escaped like “\1,”.
  * duts (=“”) : a list of devices (instance names) under test. If specified, X graph only contains nodes inside duts. However, not like bbox_insts, i.c.s of nodes outside duts are initially randomized as well. Names should be separated by comma (,) and there should always be comma at the end of list. (e.g duts=“xtop,”) If name is only composed of numbers it should be escaped like “\1,”.
  * accuracy(=4) : accuracy that will be used in circuit simulator. In SPECTRE, 3, 4, and 5 corresponds conservative, moderate and liberal respectively. And you’d better set rforce to 1k when you use SPECTRE for better convergence.
  * tmp_work_dir(="tmp_gcat“) : temporary directory name which GCAT can use without restriction
  * summary(=${NETLIST_NAME}.gconv_${GCONV_ANALYSIS}.res) : Analysis result reporting filename
  * verbose (=“”) : a filename where verbose information will be reported
  * debug (=True) : when it is True, verbose information files are dumped into tmp_work_dir
  * writeic(=True) : when constructing histograms of initial i.c. distributions, use the starting i.c. that was tuned  by circuit simulator (with rforce in SPECTRE) instead of using the uniform-randomly generated i.c.s that were initially given to the simulator. In other words, this is in effect to get i.c.s by adding “write” option to SPECTRE.


== Entropy based X analysis : gconv_ebx ==
 * Entropy based X analysis
 * Example
 {{{
gcatstatement0 gconv_ebx N=200 t0=1e-6 bins=20
+   ic_vmax=1.1 ic_vmin=0.0 vmax=1.2 vmin=-0.1
}}}
 * Parameters
  * N : # of initial conditions (i.e. samples).
  * t0 : time to measure voltage/current distributions of circuit nodes.
  * bins : # of histogram bins.
  * ic_vmax / ic_vmin : the upper/lower limit of i.c. randomization range (ic_imax/ic_imin for currents).
  * vmax / vmin : the upper/lower limit of histogram range (imax/imin for currents).
  * thrd (=0.01) : if a node has a lower entropy value than this threshold, it is considered to be nonX.
  * Ntol(=0.1) : sample could be out of histogram range and this value sets the maximum number of samples that are allowed to be out of range (by Ntol*N).
  * ivars(=“”) : branch current variables to include in X graph (and also circuit graph and the approximated state space). For example, ivars=“in1,” or ivars=“in1,in2,”. Note that comma should always be added at the end.
  * sorting(=“IND”) : describe how to order Xs in report file. If it is “IND”, Xs are sorted according to independence degree. If it is “H”, Xs are sorted according to entropy value H(A).
  * thrd (=0.01) : if a node has a lower entropy value than this threshold, it is considered to be nonX.
  * Ntol(=0.1) : sample could be out of histogram range and this value sets the maximum number of samples that are allowed to be out of range (by Ntol*N).
  * ivars(=“”) : branch current variables to include in X graph (and also circuit graph and the approximated state space). For example, ivars=“in1,” or ivars=“in1,in2,”. Note that comma should always be added at the end.
  * sorting(=“IND”) : describe how to order Xs in report file. If it is “IND”, Xs are sorted according to independence degree. If it is “H”, Xs are sorted according to entropy value H(A).

== Cluster split detection analysis : gconv_csd ==
 * Cluster split detection analysis
 * Example
  {{{
gcatstatement1 gconv_csd Ntrajts=200 tstep=100e-12 Nsampling=4 dt=5e-12 max_simtime=4e-09
+   outputs="p1,n2"
+   ic_vmax=1.2 ic_vmin=0.0 vmax=1.3 vmin=-0.1
+   N=100 t0=100e-12 bins=20 save_xnetwork="ring.xnet.gml“ iter=2
+   verif_sim_steps=100 verif_tstep=50e-12
}}}
 * Parameters
  * Ntrajts : # of trajectories/initial conditions.
  * tstep : for this time interval, Nsampling samples are taken for every trajectory and clustering analysis and trajectory merging are applied on them. It is recommend to set tstep as the minimum period of any periodic signals in the circuit.
  * dt : short time interval to measure velocity vectors of samples in state space.
  * Nsampling(=4)  : # of trajectory samples to take for each tstep. Minimum value is 2.
  * max_simtime (=1e0) : maximum transient simulation time for every trajectory.
  * tstep1st (=0.0) : the first transient circuit simulation duration. This should be set as enough time duration after which reset is released so that nodes in a circuit including digital gates outputs are properly settles down.
  * tsampling (=0.0): time interval between consecutive “tstep”-simulations.
  * maxtracedepth (=64) : for each trajectory, its samples are stored upto maxtracedepth
  * T (=0) : least common multiple of input signals’ periods.
  * verif_sim_steps (=0) : if split is detected and both verif_sim_step and verif_tstep are nonzero, one of trajectories is selected for each different clusters and are simulated for verif_sim_step*verif_tstep. The resulting waveform is sampled for every verif_tstep and saved in png files.
  * verif_tstep (=0) : verifying simulation time step.
  * EQ_termination (=False) : for each tstep+tsampling, convergence to EQ is checked and if all trajectories are converged to a EQ, CSD will be terminated with no split.
  * X_termination (=True) : for each tstep+tsampling, X analysis is performed and when there is no X, CSD will be terminated  with no split.
  * merging_termination (=True) : if all trajectories are merged, CSD will be terminated with no split.
  * merging (=True) : do trajectory merging when this is True.
  * mg_criteria1 (=False) : If distance of two trajectories is smaller than overall distances of trajectories (<avg[distance]-mg_thrd1*std[distance]), merge them.
  * mg_thrd1 (=2) : parameter for mg_criteria1.
  * mg_criteria2 (=False) : If two trajectories has samples whose angle between displacement vector and velocity vectors of each are small(<mg_thrd2), merge them. Two latest samples are taken per trajectory and compared.
  * mg_thrd2 (=0.2) : parameter for mg_criteria2, radian.
  * mg_criteria3 (=True) : If two trajectories has samples whose angle between displacement vector and velocity vectors of each are small(<mg_thrd3), merge them. One latest sample per trajectory is taken and compared.
  * mg_thrd3 (=0.2) : parameter for mg_criteria3, radian
  * mg_criteria4 (=True) : If all samples of two trajectories are K-nearest neighbor to each other and angles between difference vectors of samples on two trajectories are close to zero (<mg_thrd4), merge them.
  * mg_thrd4 (=0.2) : parameter for mg_criteria4, radian.
  * mg_criteria5 (=False) : If all samples of two trajectories are K-nearest neighbor to each other and distance between two trajectories are small (<mg_thrd5).
  * mg_thrd5 (=1e-10) : parameter for mg_criteria5.
  * knn_angle (=0.0) : radian, a reference angle which vector based K-nearest neighbor clustering will take as parameter. If this is zero or dt is zero, velocity vector of state point is ignored. If you want to use vector based K-nearest neighbor clustering, set this values near pi/2(~1.57=pi/2).
  * polyfitm (=“”) : if this is 0, K parameter for K-nearest neighbor clustering is not estimated from polynomial fitting to pre-generated data but searched incrementally whenever K-nearest neighbor cluster is called. It is not recommended to set this as 0 because it will slow down CSD a lot, but if Nsampling*Ntrajt exceed 1000 or # of nodes in the X graph is grater than 1000, it is safer to set this as 0.
  * polyfit_order (=2) : the order that will be used for polynomial fitting
  * polyfit_iter(=0) : when this values is higher, K estimation through the polynomials becomes higher, lowering the probability of false split detection but increasing this polyfit_iter would also increase false positive rate.
  * N : # of initial conditions (i.e. samples).
  * t0 : time to measure voltage/current distributions of circuit nodes.
  * bins : # of histogram bins.
  * ic_vmax / ic_vmin : the upper/lower limit of i.c. randomization range (ic_imax/ic_imin for currents).
  * vmax / vmin : the upper/lower limit of histogram range (imax/imin for currents).
  * thrd (=0.01) : if a node has lower entropy value than this threshold, it is considered to be nonX.
  * Ntol(=0.1) : sample could be out of histogram range and this value sets the maximum number of samples that are allowed to be out of range (by Ntol*N).
  * iter(=4) : the number of iterations to dependent X identification. this is necessary because only dependent relationships between adjacent (i.e. neighboring) nodes can be found.
  * rm_isolatedX(=True) : set this as True if you want to remove isolated X.
  * rm_depX(=True) : set this as True if you want to remove isolated X.
  * max_dep_nbs(=2) : the maximum number of neighbors to check for a node’s dependency. The # of possible dependent neighbors grows exponentially as this value increases, so this values should not be large.
  * save_xnetwork (=“”) : the filename of gml file where the resulting X graph will be saved
  * xnetwork_gml (=“”) : a X graph filename to read in gml file format. When x graph is given here, XRED step in CSD is skipped.
  * reduction(=True) : if False, X reduction step in CSD is skipped and circuit graph is used as X graph.

= Tutorial =
== Cluster split detection ==
 * Coupled ring oscillator example
 {{{
simulator lang=spectre insensitive=yes

* models and parameters
include "model_130.scs" section=tt
include "model_130.scs" section=tt_mos_cap_25

parameters Supply=1.2
parameters W1=4 W2=32
parameters PNR=2

* ring oscillator
subckt inv  ( in out vdd gnd )
parameters  wp=16 lp=2 wn=8 ln=2
m_0         ( out in gnd gnd ) nmos w=wn l=ln geo=1
+           as=wn*5 ad=wn*3 ps=2*wn+2*5 pd=wn+2*3 nrd=3/wn nrs=3/wn
m_1         ( out in vdd vdd ) pmos w=wp l=lp geo=1
+           as=wp*5 ad=wp*3 ps=2*wp+2*5 pd=wp+2*3 nrd=3/wp nrs=3/wp
ends inv

xinv1p      ( p1 p2 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv2p      ( p2 p3 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv3p      ( p3 p1 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv1n      ( n1 n2 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv2n      ( n2 n3 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv3n      ( n3 n1 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2

xinv1cp     ( p1 n3 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv2cp     ( p2 n1 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv3cp     ( p3 n2 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv1cn     ( n1 p3 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv2cn     ( n2 p1 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv3cn     ( n3 p2 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2

* stimuli sources
Vgnd    ( gnd 0 )       vsource type=dc dc=0
Vdda    ( vdd gnd )     vsource type=dc dc=Supply

* analysis statement
simOPTION options temp=60 scale=0.065u

* cluster split detection analysis

gcatanls0 gconv_csd Ntrajts=200 tstep1st=100e-12 tstep=100e-12 Nsampling=4 dt=5e-12 max_simtime=4e-09
+   outputs="p1,n2"
+   ic_vmax=1.2 ic_vmin=0.0 vmax=1.3 vmin=-0.1
+   N=100 t0=100e-12 bins=20 save_xnetwork="ring.xnet.gml"
+   verif_sim_steps=100 verif_tstep=50e-12
}}}
 * run global convergence analysis
 {{{
rungcat.py ringosc_embd.scs
}}}
 * results
 {{{
### Cluster split detection summary ###
### Cluster split detectrion result ###
Cluster split = True
Number of clusters=2
Number of initial trajectories=200
Number of final trajectories=88
Number of iterations = 4
Simulation endtime=4.05e-10
}}}

== Entropy based X analysis ==
 * Coupled ring oscillator example
 {{{
simulator lang=spectre insensitive=yes

* models and parameters
include "model_130.scs" section=tt
include "model_130.scs" section=tt_mos_cap_25

parameters Supply=1.2
parameters W1=24 W2=12 // one ring
//parameters W1=32 W2=4 // two ring
//parameters W1=4 W2=32 // one ring and two points
//parameters W1=16 W2=16 // three points
parameters PNR=2

* ring oscillator
subckt inv  ( in out vdd gnd )
parameters  wp=16 lp=2 wn=8 ln=2
m_0         ( out in gnd gnd ) nmos w=wn l=ln geo=1
+           as=wn*5 ad=wn*3 ps=2*wn+2*5 pd=wn+2*3 nrd=3/wn nrs=3/wn
m_1         ( out in vdd vdd ) pmos w=wp l=lp geo=1
+           as=wp*5 ad=wp*3 ps=2*wp+2*5 pd=wp+2*3 nrd=3/wp nrs=3/wp
ends inv

xinv1p      ( p1 p2 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv2p      ( p2 p3 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv3p      ( p3 p1 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv1n      ( n1 n2 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv2n      ( n2 n3 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2
xinv3n      ( n3 n1 vdd gnd ) inv  m=2 wp=W1*PNR lp=2 wn=W1 ln=2

xinv1cp     ( p1 n3 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv2cp     ( p2 n1 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv3cp     ( p3 n2 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv1cn     ( n1 p3 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv2cn     ( n2 p1 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2
xinv3cn     ( n3 p2 vdd gnd ) inv  m=2 wp=W2*PNR lp=2 wn=W2 ln=2

* stimuli sources
Vgnd    ( gnd 0 )       vsource type=dc dc=0
Vdda    ( vdd gnd )     vsource type=dc dc=Supply

* analysis statement
simOPTION options temp=60 scale=0.065u

gcat gconv_ebx bins=20 t0=110e-12 ic_vmax=1.2 ic_vmin=0.0 N=256 vmin=-0.2 vmax=1.4
}}}
 * run global convergence analysis
 {{{
rungcat.py ringosc_embd.scs
}}}
 * results
  * NODE NAME : INDEPENDENCE DEGREE (UNCERTAINTY)
  * Both metrics are normalized [0,1.0]
  * Lower independence degree indicates more independence (Higher entropy indicates higher uncertainty)
  * Output nodes are always included in as X node list in report. They should appear at the end of list if they are not X.

 {{{
### Entropy_analysis summary ###
### X Graph profile ###
# Number of nodes = 6 
# Number of edges = 12 
p2 : 0.800389140795 (0.818060915587)
p3 : 0.823674320836 (0.767207025256)
n2 : 0.826206318514 (0.844235624551)
n1 : 0.835896963979 (0.864149994262)
n3 : 0.849358576618 (0.797365567362)
p1 : 0.867223803729 (0.886119406863)
}}}

## NOTE: the following macro displays the page tags
<<ShowPageTags>>