Updated documentation afer resistor model update.

ChangeLog

@@ -1,6 +1,16 @@
+2003-09-20  Paolo Nenzi <p.nenzi@ieee.org>
+
+	* src/spicelib/devices/res/*, src/spicelib/analysis/nevalsrc.c,
+	  doc/ngspice.texi, DEVICES: Added new features to resistors: 
+	  flicker noise, tempereature difference with the rest of the 
+	  circuit, noiseless resistors. The implementation of dtemp 
+	  required a change in the nevalsrc.c file in the function that 
+	  computes the noise densities. Updated documentation. 
+	  
+
 2003-09-18  Paolo Nenzi <p.nenzi@ieee.org>
 	
-	* src/spicelib/frontend/dctrcv.c: Corrected temperature sweep.
+	* src/spicelib/analysis/dctrcv.c: Corrected temperature sweep.
 	  Initial temp was the circuit temperature and not the start
 	  value in the input line. There was a missing call to CKTtemp().
 

DEVICES

@@ -10,11 +10,29 @@ This file it is useful in writing ngspice documentation.
 *************************  Linear devices  ********************************
 ***************************************************************************
 
-CAP - Capacitor
-      Initial Release
-
-IND - Inductor
-      Initial Release
+CAP 	- Capacitor
+      	Initial Release
+
+IND 	- Inductor
+      	Initial Release
+
+RES	- Simple linear resistor
+	Initial Release.
+	Ver:	N/A
+	Class:	R
+	Level:	1 (and only)
+	Status:	
+		
+	Enhancements over the original model:
+	
+	- Parallel Multiplier
+	- Different value for ac analysis
+	- Temperature difference from circuit temperature
+	- Noiseless resistor
+	- Flicker noise
+	- Preliminary technology scaling support
+	- Xspice extensions
+	- Cider extensions
 
 RES - Resistor
       This is a modified version of the spice3 resistance model. This model 
@@ -226,7 +244,7 @@ BSIM3v2 - BSIM model level 3
 
 BSIM4   - BSIM model level 4 (0.18 um)
         Initial Release. 
-        Ver:    4.2.1 (Updated in rewor 14)
+        Ver:    4.2.1 (Updated in rework 14)
         Class:  M
         Level:  14
         Status: TO BE TESTED
@@ -239,7 +257,27 @@ BSIM4   - BSIM model level 4 (0.18 um)
       
       *) Rework 14: Updated to 4.21 YET UNTESTED.
 	 
-	 
+HiSIM	- Hiroshima-university STARC IGFET Model
+	Initial Release.
+	Ver:	1.2.0
+	Class:	M
+	Level:	TBD
+	Status:	TO BE TESTED
+	
+	This is the HiSIM model available from Hiroshima University
+	(Ultra-Small Device Engineering Laboratory)
+	
+	Web site:
+	http://home.hiroshima-u.ac.jp/usdl/HiSIM.shtml
+	http://www.starc.or.jp/kaihatu/pdgr/hisim/index.html
+	
+	Enhancements over the original model:
+	
+	- Parallel Multiplier
+	- Xspice extensions
+	- Cider extensions
+	- Copynodeset (?)
+	
 ***************************************************************************	 
 *****************************    SOI Devices   ****************************
 ***************************************************************************
@@ -320,4 +358,4 @@ EKV  - EKV model
        
        Web site at:
        http://legwww.epfl.ch/ekv/
-            
+            

doc/ngspice.texi

@@ -1770,10 +1770,10 @@ in the direction of voltage drop).
  General form:
 
 @example
-  RXXXXXXX N1 N2 VALUE <ac=val> <m=val> <scale=val>
+  RXXXXXXX n+ n- value <ac=val> <m=val> <scale=val> <dtemp = val> 
+  +        <noisy = 0|1>
 @end example
 
-
  Examples:
 
 @example
@@ -1783,23 +1783,79 @@ in the direction of voltage drop).
   RL 1 4 2K m=2
 @end example
 
+Ngspice has a fairly complex model for resistors. It can simulate both
+discrete and semiconductor resistors. Semiconductor resistors in ngspice
+means: resistors described by geometrical parameters. So, do not expect 
+detailed modeling of semiconductor effects.
 
-N1 and N2 are the two element nodes.  VALUE is the resistance (in ohms)
-and may be positive or negative but not zero. It is possible to specify
-a different resistance value for ac calculations, using the "ac" 
-parameter. The value of ac resistance must not be zero. If you do not
-specify the "ac" parameter, it will be defaulted to VALUE.
+@option{n+} and @option{n-} are the two element nodes, @option{value} is the 
+resistance (in ohms) and may be positive or negative but not zero. If you 
+need to simulate very small resistors (0.001 Ohm or less) , you should use 
+CCVS (transresistance), it is less efficient but improves numerical 
+accuracy (a small resistance is a large conductance).   
+ 
+Ngspice can assign a resistor instance a different value for AC analysis,
+specified using the @option{ac} keyword. This value must not be zero as 
+described above. The AC resistance is used in AC analysis only (not Pole-Zero
+nor noise).  If you do not specify the @option{ac} parameter, it is defaulted 
+to @option{value}.
+
+The @option{m} parameter is the "multiplication factor", and can be used to 
+simulate "m" instances of the same kind in parallel. This parameter affects 
+all analyses. 
+
+The @option{scale} keyword let the designer choose a different scale for 
+elements. This option is not yet very useful, it will fully implemented in the
+future to perform technology scaling. At present is here as a work in progress.
+
+The operating temperature of instances can be changed using the @option{dtemp}
+keyword. Ngspice simulates the circuit with all components at the same single 
+temperature (the circuit temperature). To adjust the temperature of a resistor 
+instance you can define its temperature difference from the rest of the 
+circuit using @option{dtemp}.
+
+If you want to simulate temperature dependence of a resistor, you need to
+specify its temperature coefficients, using a @command{.model} line, like in the
+example below:
+@example
+  RE1 1 2 700 std dtemp=5 
+  
+  .MODEL std tc1=0.001
+@end example
 
-The "m" parameter is the "multiplication factor" and scale is the "scale"
-factor:
-                   Resistance = Resistance * Scale / M
-Setting m to "val" is like putting m equal resistance in parallel.
-The "scale" parameter let the designer to choose a different scale
-for elements. 
+Instance temperature is useful even if resistance does not varies with it, since
+the thermal noise generated by a resistor depends on its absolute temperature. 
 
-Note: ac parameter can be considered "safe" since rework-11 
-      Scale parameter is not applied to l,w and other geometric
-      parameters. 
+Resistors in ngspice generates two different noises: thermal and flicker. While 
+thermal noise is always generated in the resistor, to add a flicker noise source
+you have to add a @command{.model} card defining the flicker noise parameters.
+It is possible to simulate resistors that do not generate any kind of noise 
+using the @option{noisy} keyword  and assigning zero to it, as in the 
+following example:
+
+@example
+  Rmd 134 57 1.5k noisy=0 
+@end example
+
+Ngspice calculates the nominal resistance as described below:
+
+@tex
+$$
+    R_{nom} = {{{\rm VALUE} * {\rm scale}} \over m}
+$$
+$$
+    R_{acnom} =  {{{\rm ac} * {\rm scale}} \over m}
+$$
+@end tex
+@ifnottex
+@example
+                        Rnom = value * scale / m
+			Racnom = ac * scale / m
+@end example
+@end ifnottex
+
+If you are interested in temperature effects or noise equations, read the
+following section on semiconductor resistors.
 
 @node  Semiconductor Resistors, Semiconductor Resistor Model (R), Resistors, Elementary Devices
 @subsection  Semiconductor Resistors
@@ -1807,8 +1863,8 @@ Note: ac parameter can be considered "safe" since rework-11
  General form:
 
 @example
-  RXXXXXXX N1 N2 <VALUE> <MNAME> <L=LENGTH> <W=WIDTH> <TEMP=T> 
-           m=<val> <ac=val> <scale=val>
+  RXXXXXXX n+ n- <value> <mname> <l=lenght> <w=width> <temp=t> 
+  +        <dtemp=val> m=<val> <ac=val> <scale=val> <noisy = 0|1>
 @end example
 
 
@@ -1819,20 +1875,20 @@ Note: ac parameter can be considered "safe" since rework-11
   RMOD 3 7 RMODEL L=10u W=1u
 @end example
 
+This is the more general form of the resistor presented before (@pxref{Resistors}) 
+and allows the modeling of temperature effects and for the calculation of the 
+actual resistance value from strictly geometric information and the 
+specifications of the process.  If @option{value} is specified, it overrides 
+the geometric information and defines the resistance.  If @option{mname} is 
+specified, then the resistance may be calculated from the process information 
+in the model @option{mname} and the given @option{lenght} and @option{width}.  
+If @option{value} is not specified, then @option{mname} and @option{lenght}
+must be specified.  If @option{width} is not specified, then it is taken
+from the default width given in the model.  
 
-
-This is the more general form of the resistor presented in section
-6.1, and allows the modeling of temperature effects and for the
-calculation of the actual resistance value from strictly geometric
-information and the specifications of the process.  If VALUE is
-specified, it overrides the geometric information and defines the
-resistance.  If MNAME is specified, then the resistance may be
-calculated from the process information in the model MNAME and the
-given LENGTH and WIDTH.  If VALUE is not specified, then MNAME and
-LENGTH must be specified.  If WIDTH is not specified, then it is taken
-from the default width given in the model.  The (optional) TEMP value
-is the temperature at which this device is to operate, and overrides
-the temperature specification on the .OPTION control line.
+The (optional) @option{temp} value is the temperature at which this device is 
+to operate, and overrides the temperature specification on the 
+@command{.option} control line and the value specified in @option{dtemp}.  
 
 
 
@@ -1845,63 +1901,92 @@ the resistance to be calculated from geometric information and to be
 corrected for temperature.  The parameters available are:
 
 @multitable @columnfractions .15 .4 .2 .1 .1
-@item name @tab parameter @tab units @tab default @tab example
-@item TC1 @tab first order temperature coeff.
-          @tab Z/°C @tab 0.0
-@item TC2 @tab second order temperature coeff.
-          @tab Z/°C@math{^2} @tab 0.0
-@item RSH @tab sheet resistance
-          @tab Z/[] @tab - @tab 50
-@item DEFW @tab default width
-          @tab meters @tab 1e-6 @tab 2e-6
+@item name   @tab parameter @tab units @tab default @tab example
+@item TC1    @tab first order temperature coeff.
+                            @tab Ohm/°C @tab 0.0
+@item TC2    @tab second order temperature coeff.
+                            @tab Ohm/°C@math{^2} @tab 0.0
+@item RSH    @tab sheet resistance
+                            @tab Ohm/[] @tab - @tab 50
+@item DEFW   @tab default width
+                            @tab meters @tab 1e-6 @tab 2e-6
 @item NARROW @tab narrowing due to side etching
-          @tab meters @tab 0.0 @tab 1e-7
+                            @tab meters @tab 0.0 @tab 1e-7
 @item SHORT  @tab shortening due to side etching 
-          @tab meters @tab 0.0 @tab 1e-7         
-@item TNOM @tab parameter measurement temperature
-          @tab °C @tab 27 @tab 50
+                            @tab meters @tab 0.0 @tab 1e-7         
+@item TNOM   @tab parameter measurement temperature
+                            @tab °C @tab 27 @tab 50
+@item KF     @tab  flicker noise coefficient 
+                            @tab - @tab 0.0 @tab 5e-15 
+@item AF     @tab  flicker noise exponent 
+                            @tab - @tab 0.0 @tab 1.0
 @end multitable
 
 
-The sheet resistance is used with the narrowing parameter and L and W
-from the resistor device to determine the nominal resistance by the
-formula
+The sheet resistance is used with the narrowing parameter and @option{l} 
+and @option{w} from the resistor device to determine the nominal resistance 
+by the formula
 
 @tex
 $$
-    R = {\rm RSH} {L - {\rm SHORT} \over W - {\rm NARROW}}
+    R_{nom} = {\rm rsh} {l - {\rm SHORT} \over w - {\rm NARROW}}
 $$
 @end tex
 @ifnottex
 @example
-                        L - SHORT
-                R = RSH ----------
-                        W - NARROW
+                           L -  SHORT
+                Rnom = RSH ----------
+                           W - NARROW
 @end example
 @end ifnottex
 
-DEFW is used to supply a default value for W if one is not specified for
-the device.  If either RSH or L is not specified, then the standard
-default resistance value of 1k Z is used.  TNOM is used to override the
-circuit-wide value given on the .OPTIONS control line where the
-parameters of this model have been measured at a different temperature.
-After the nominal resistance is calculated, it is adjusted for
-temperature by the formula:
+@option{DEFW} is used to supply a default value for @option{w} if one is 
+not specified for the device.  If either @option{RSH} or @option{L} is not 
+specified, then the standard default resistance value of 1k Ohm is used.  
+@option{TNOM} is used to override the circuit-wide value given on the 
+@command{.options} control line where the parameters of this model have 
+been measured at a different temperature. 
 
+After the nominal resistance is calculated, it is adjusted for temperature 
+by the formula:
 
 @tex
 $$
-   R(T) = R(T_0) \Bigl( 1 + TC_1 (T - T_0) + TC_2 (T-T_0)^2 \Bigr)
+   R(T) = R({\rm TNOM}) \Bigl( 1 + TC_1 (T - {\rm TNOM}) + TC_2 (T-{\rm TNOM})^2 \Bigr)
 $$
+where $R({\rm TNOM}) = R_{nom} \vert R_{acnom}$.
 @end tex
 @ifnottex
 @example
-                                               2
-  R(T) = R(T ) [1 + TC  (T - T ) + TC  (T - T ) ]
-            0         1       0      2       0
+                                                     2
+  R(T) = R(TNOM) [1 + TC  (T - TNOM) + TC  (T - TNOM) ]
+                        1                2       
+  where R(TNOM) = Rnom or Racnom
 @end example
 @end ifnottex
 
+In the above formula, "T" represents the instance temperature, which can be
+explicitly using the @option{temp} keyword or os calculated using the 
+circuit temperature and and @option{dtemp}, if present.
+
+If both @option{temp} and @option{dtemp} are specified, the latter is ignored.
+
+A small list of sheet resistances (in Ohm/[]) for conductors is shown below.
+The table represents typical values for MOS processes in the 0.5 - 1 um 
+range. The table is taken from: @emph{N. Weste, K. Eshraghian - Principles of 
+CMOS VLSI Design 2nd Edition,  Addison Wesley}.
+
+@multitable @columnfractions .55 .15 .15 .15 
+@item Material @tab Min. @tab Typical @tab Max.
+@item Intermetal (metal1 - metal2) @tab   0.005 @tab 0.007 @tab 0.1 
+@item Top-metal (metal 3)          @tab   0.003 @tab 0.004 @tab 0.05
+@item Polysilicon                  @tab   15    @tab 20    @tab 30
+@item Silicide                     @tab   2     @tab 3     @tab 6
+@item Diffusion(n+,p+)             @tab   10    @tab 25    @tab 100
+@item Silicided diffusion          @tab   2     @tab 4     @tab 10
+@item n-well                       @tab   1000  @tab 2000  @tab 5000
+@end multitable
+
 
 @node  Capacitors, Semiconductor Capacitors, Semiconductor Resistor Model (R), Elementary Devices
 @subsection  Capacitors
@@ -6112,7 +6197,38 @@ values above may be node names in the running circuit, or real values.
 If more than one condition is given, e.g.  stop after 4 when @math{v(1) > 4}
 when @math{v(2) < 2}, the conjunction of the conditions is implied.
 
+@subsection  Sysinfo:  Print system information
+
+ General Form:
+
+@example
+     sysinfo
+@end example
+
+
+The command prints system information useful for sending bug report
+to developers.  Information consists of:
+
+@itemize @bullet
+@item Name of the operating system,
+@item Name of the node,
+@item Current release of the operating system,
+@item Current version of this release,
+@item Name of hardware type.
+@end itemize
+
+The example below shows the use of this command.
 
+@example
+ngspice 1 -> sysinfo
+Linux janus.wayout.net 2.4.20 #1 SMP Tue Jun 10 18:58:26 CEST 2003 i686 
+ngspice 2 -> 
+@end example
+
+@strong{Note:} This command may not be available on your environment, if
+it is not available, please send analogous information when submitting
+bug reports. 
+ 
 
 @node  Tf, Trace, Stop, Commands
 @subsection  Tf*: Run a Transfer Function analysis