Chapter 4 Behavioral modeling
Gnucap behavioral modeling is in a state of transition, so this is
subject to change in a future release.
Basically, all simple components can have a behavioral description,
with syntax designed as an extension of the Spice time dependent
sources. They are not necessarily physically realizeable. Some only
work on particular types of analysis, or over a small range of
values. Some can be used together, some cannot.
In general, all simple components are considered to have simple
transformations. A function returns one parameter as a function of
one other, as an extension of their linear behavior.
Linear behavior:
-
Capacitor
- q = C v
- Inductor
- f = L i
- Resistor
- v = I r
- Admittance
- i = Y v
- VCVS
- vo = E vi
- VCCS
- io = G vi
- CCVS
- vo = E ii
- CCCS
- io = G ii
Sources are defined as functions of time:
-
Voltage source
- v = f(t)
- Current source
- i = f(t)
For behavioral modeling / nonlinear values, replace the constant times
input by an arbitrary function:
-
Capacitor
- q = f(v)
- Inductor
- f = f(i)
- Resistor
- v = f(r)
- Admittance
- i = f(v)
- VCVS
- vo = f(vi)
- VCCS
- io = f(vi)
- CCVS
- vo = f(ii)
- CCCS
- io = f(ii)
Conditionals
- AC
- AC analysis only.
- DC
- DC (steady state) value.
- OP
- OP analysis.
- TRAN
- Transient analysis.
- FOUR
- Fourier analysis only.
- ELSE
- Anything not listed.
- ALL
- All modes.
Functions
- COMPLEX
- Complex (re, im) value.
- EXP
- Spice Exp source. (time dependent value).
- FIT
- Fit a curve with splines.
- GENERATOR
- Value from Generator command.
- POLY
- Polynomial (Spice style).
- POSY
- Posynomial (Like poly, non-integer powers).
- PULSE
- Spice Pulse source. (time dependent value).
- PWL
- Piece-wise linear.
- SFFM
- Spice Frequency Modulation (time dependent value).
- SIN
- Spice Sin source. (time dependent value).
- TANH
- Hyperbolic tangent xfer function.
Model Functions
- TABLE
- Fit a curve with splines.
- Cap
- Spice semiconductor ``capacitor'' model.
- Res
- Spice semiconductor ``resistor'' model.
4.1 Conditionals
Gnucap behavioral modeling conditionals are an extension of the ``AC''
and ``DC'' Spice source parameters.
The extensions ...
- There are more choices, including an ``else''.
- They apply to all elements (primitive components).
- Each section can contain functions and options.
The following are available:
- AC
- AC analysis only.
- DC
- DC (steady state) value.
- OP
- OP analysis.
- TRAN
- Transient analysis.
- FOUR
- Fourier analysis only.
- ELSE
- Anything not listed.
- ALL
- Anything not listed.
A value or function with no conditional keyword is equivalent to ALL. For SPICE compatibility, use only DC, AC, or nothing.
They are interpreted like a ``switch'' statement. In case of a
conflict, the last one applies. A set of precedence rules applies
when some keys are missing. It is SPICE compatible, to the extent the
features overlap.
- OP analysis
- OP, DC, ALL, TRAN, 0
- DC analysis
- DC, ALL, OP, TRAN, 0
- Transient analysis
- TRAN, ALL, DC, OP, 0
- Fourier analysis
- FOUR, TRAN, ALL, DC, OP, 0
- AC analysis, fixed sources
- AC, 0
- AC analysis, other elements
- AC, ALL, 0
4.1.1 Examples
- V12 1 0 AC 1 DC 3
- This voltage source has a value of 1
for AC analysis, 3 for DC. OP, Transient, and Fourier inherit the DC value.
- R44 2 3 OP 1 ELSE 1g
- This resistor has a value of 1 ohm
for the ``OP'' analysis, 1 gig-ohm for anything else. This might be
useful as the feedback resistor on an op-amp. Set it to 1 ohm to set
the operating point, then 1 gig to measure its open loop
characteristics, hiding the fact that the op-amp would probably
saturate if it was really left open loop.
4.2 Functions
Gnucap behavioral modeling functions are an extension of the Spice source
time dependent values.
4.2.1 The extensions
They apply to all elements (primitive components).
All accept either Spice compatible order dependent parameters, or
easier keyword=value notation.
The syntax is identical for all supported components.
4.2.2 Fixed sources
Time dependent functions are voltage or current as a function of time.
They are mostly Spice compatible, with extensions.
Nonlinear transfer functions use time as the independent variable.
Some may not make sense, but they are there anyway.
4.2.3 Capacitors and inductors
Time dependent functions are capacitance or inductance as a function
of time. They are voltage/current conserving, not charge/flux
conserving.
Nonlinear transfer functions are charge or flux as a function of input
(voltage or current). Charge and flux are conserved, and can be
probed.
4.2.4 Resistors and conductances
Time dependent functions are resistance or conductance as a function
of time.
Nonlinear transfer functions are current or voltage as a function of
input (voltage or current). Resistors define voltage as a function of
current. Conductances define current as a function of voltage.
4.2.5 Controlled sources
Time dependent functions are gain (v/v, transconductance, etc)
function of time.
Nonlinear transfer functions are output (voltage or current) as a
function of input (voltage or current).
4.2.6 Available functions
- COMPLEX
- Complex (re, im) value.
- EXP
- Spice Exp source. (time dependent value).
- FIT
- Fit a curve with splines.
- GENERATOR
- Value from Generator command.
- POLY
- Polynomial (Spice style).
- POSY
- Posynomial (Like poly, non-integer powers).
- PULSE
- Spice Pulse source. (time dependent value).
- PWL
- Piece-wise linear.
- SFFM
- Spice Frequency Modulation (time dependent value).
- SIN
- Spice Sin source. (time dependent value).
- TANH
- Hyperbolic tangent transfer function.
In addition, you may name a ``function'' defined by a .model
statement. The following .model types may be used here:
- TABLE
- Fit a curve with splines.
- Cap
- Spice semiconductor ``capacitor'' model.
- Res
- Spice semiconductor ``resistor'' model.
4.2.7 Parameters that apply to all functions
These parameters are available with all functions. Some may not make
sense in some cases, but they are available anyway.
- Bandwidth = x
- AC analysis bandwidth.
(Default = infinity.) The transfer function is frequency dependent,
with a 3 DB point at this frequency. There is frequency dependent
phase shift ranging from 0 degrees at low frequencies to 90 degrees at
high frequencies. The phase shift is 45 degrees at the specified
frequency. AC ANALYSIS ONLY.
- Delay = x
- AC analysis delay. (Default = 0.)
The signal is delayed by x seconds, effectively by a frequency
dependent phase shift. AC ANALYSIS ONLY.
- Phase = x
- AC analysis phase. (Default = 0.)
A fixed phase shift is applied. This is primarily intended for
sources, but applies to all elements. AC ANALYSIS ONLY.
- IOffset = x
- Input offset. (Default = 0.)
A DC offset is added to the ``input'' of the element, before
evaluating the function.
- OOffset = x
- Output offset. (Default = 0.)
A DC offset is added to the ``output'' of the element, after
evaluating the function.
- Scale = x
- Transfer function scale factor.
(Default = 1.) The transfer function is multiplied by a constant.
- TNOM = x
- Nominal temperature. (Default = .option TNOM)
The nominal values apply at this temperature.
- TC1 = x
- First order temperature coefficient.
(Default = 0.)
- TC2 = x
- Second order temperature coefficient.
(Default = 0.)
- IC = x
- Initial condition. An initial value, to
force at time=0. The actual parameter applied depends on the
component. (Capacitor voltage, inductor current. All others ignore
it.) You must use the ``UIC'' option for it to be used.
Temperature adjustments and scaling use the following formula:
value *= _scale * (1 + _tc1*tempdiff
+ _tc2*tempdiff*tempdiff)
where tempdiff is t - _tnom.
4.3 COMPLEX: Complex value
4.3.1 Syntax
COMPLEX realpart imaginarypart options
4.3.2 Purpose
Complex component value, using a real and imaginary part. AC only.
4.3.3 Comments
Strictly, this adds no functionality over the polar option on any
function, except notational convenience.
4.3.4 Example
- V12 2 0 complex 1,2
- A voltage source with a value of 1 + j2
volts.
4.4 EXP: Exponential time dependent value
4.4.1 Syntax
EXP args
EXP iv pv td1 tau1 td2 tau2 period
4.4.2 Purpose
The component value is an exponential function of time.
4.4.3 Comments
For voltage and current sources, this is the same as the Spice EXP function, with some extensions.
The shape of the waveform is described by the following algorithm:
ev = _iv;
for (reltime=time; reltime>=0; reltime-=_period){
if (reltime > _td1){
ev += (_pv - _iv)
* (1. - Exp(-(reltime-_td1)/_tau1));
}
if (reltime > _td2){
ev += (_iv - _pv)
* (1. - Exp(-(reltime-_td2)/_tau2));
}
}
4.4.4 Parameters
- IV = x
- Initial value. (required)
- PV = x
- Pulsed value. (required)
- TD1 = x
- Rise time delay. (Default = 0.)
- TAU1 = x
- Rise time constant. (Default = 0.)
- TD2 = x
- Fall time delay. (Default = 0.)
- TAU2 = x
- Fall time constant. (Default = 0.)
- Period = x
- Repeat period. (Default = infinity.)
4.5 FIT: Fit a curve
4.5.1 Syntax
FIT x1,y1 x2,y2 ... args
4.5.2 Purpose
Fits a set of data using piecewise polynomials, or splines.
4.5.3 Comments
This function fits a set of piecewise polynomials to a set of data.
For capacitors, this function defines charge as a function of
voltage. For inductors, it defines flux as a function of
current.
For fixed sources, it defines voltage or current as a function of
time.
The values of x must be in increasing order.
If order is 1, it is the same as PWL. If order is
3, it will use cubic splines. The result and its first two
derivatives are continuous.
Outside the specified range, it uses linear extrapolation. The
behavior depends on the parameters below and above. The
value of below or above is the derivative to use, which
is a resistance for resistors, voltage gain for a VCVS, and so on. If
it is not specified, the value is automatically determined.
The properties are determined by the value of order.
Order = 3 (cubic splines)
The default is to use ``natural'' splines, which sets the second
derivative to zero at the boundary. If a value of below or
above is specified, ``clamped'' splines will be used. In any
case, there will be a smooth transition at the boundaries. When using
``clamped'' splines, the second derivative may have a discontinuity at
the boundaries
Order = 2 (quadratic splines)
By default, the derivative at the upper end is determined by the slope
of the last segment. This is also the derivative above the range.
Below the range, the derivative determined at the lower bound is used.
It is recommended that only one of below and above be
specified. If both are specified, the splines are determined using
above, and there will be a discontinuity in the derivative at
the lower bound.
Order = 1 (piecewise linear interploation)
For first order (linear) interpolation, the default slope outside the
range is the extension of the slope in the end segments. The
parameters below and above have no effect inside the
range.
Order = 0 (piecewise constant interploation)
The resulting value is constant over the interval, and has
discontinuities at the specified points. The parameters below
and above are ignored. The slope is always 0.
4.5.4 Parameters
- Order = x
- The order of the polynomial to fit,
within the supplied data. (Default = 3) Legal values are 0, 1, 2,
and 3, only.
- Below = x
- The value of the derivative to use
below or before the specified range.
- Above = x
- The value of the derivative to use
above or after the specified range.
4.5.5 Example
- C1 2 0 fit -5,-5u 0,0 1,1u 4,2u 5,2u order=1
- This
``capacitor'' stores 5 microcoulombs at -5 volts (negative,
corresponding to the negative voltage, as expected). The charge
varies linearly to 0 at 0 volts, acting like a 1 microfarad
capacitor. (C = dq/dv). This continues to 1 volt. The 0,0 point
could have been left out. The charge increases only to 2
microcoulombs at 4 volts, for an incremental capacitance of 1u/3 or
.3333 microfarads. The same charge at 5 volts indicates that it
saturates at 2 microcoulombs. For negative voltages, the slope
continues.
4.6 GENERATOR: Signal Generator time dependent value
4.6.1 Syntax
GENERATOR scale
4.6.2 Purpose
The component ``value'' is dependent on a ``signal generator'',
manipulated by the ``generator'' command.
4.6.3 Comments
For transient analysis, the ``value'' is determined by a signal
generator, which is considered to be external to the circuit and part
of the test bench. See the ``generator'' command for more
information.
For AC analysis, the value here is the amplitude.
Strictly, all of the functionality and more is available through the
Spice-like behavioral modeling functions, but this one provides a user
interface closer to the function generator that an analog designer
would use on a real bench. It is mainly used for interactive operation.
It also provides backward compatibility with predecessors to Gnucap,
which used a different netlist format.
4.7 POLY: Polynomial nonlinear transfer function
4.7.1 Syntax
POLY c0 c1 c2 c3 ...
POLY c0 c1 c2 c3 ... args
4.7.2 Purpose
Defines a transfer function by a one dimensional polynomial.
4.7.3 Comments
For capacitors, this function defines charge as a function of
voltage. For inductors, it defines flux as a function of
current. If you have the coefficients defining capacitance or
inductance, prepending a ``0'' to the list will turn it into the
correct form for Gnucap.
For fixed sources, it defines voltage or current as a polynomial
function of time.
The transfer function is defined by:
out = c0 + (c1*in) + (c2*in^2) + ....
4.7.4 Parameters
- MIN = x
- Minimum output value (clipping).
(Default = -infinity.)
- MAX = x
- Maximum output value (clipping).
(Default = infinity)
- ABS
- Absolute value, truth value. (Default = false). If
set to true, the result will be always positive.
4.8 POSY: Polynomial with non-integer powers
4.8.1 Syntax
POSY c1,p1 c2,p2 ...
POSY c1,p1 c2,p2 ... args
4.8.2 Purpose
Defines a transfer function by a one dimensional ``posynomial'', like
a polynomial, except that the powers are arbitrary, and usually non-integer.
4.8.3 Comments
There is no corresponding capability in any SPICE that I know of.
For capacitors, this function defines charge as a function of
voltage. For inductors, it defines flux as a function of
current.
For fixed sources, it defines voltage or current as a function of
time.
Normal use of this function required positive input (voltage or
current). The result is zero if the input is negative. Raising a
negative number to a non-integer power would produce a complex result,
which implies a non-causal result, which cannot be represented in a
traditional transient analysis.
The transfer function is defined by:
if (in >= 0){
out = (c1*in^p1) + (c2*in^p2) + ....
}else{
out = 0.
}
4.8.4 Parameters
- MIN = x
- Minimum output value (clipping). (Default
= -infinity.)
- MAX = x
- Maximum output value (clipping). (Default
= infinity)
- ABS
- Absolute value, truth value. (Default = false). If
set to true, the result will be always positive.
- ODD
- Make odd function, truth value. (Default = false).
If set to true, negative values of x will be evaluated as out =
-f(-x), giving odd symmetry.
- EVEN
- Make even function, truth value. (Default = false).
If set to true, negative values of x will be evaluated as out =
f(-x), giving even symmetry.
4.8.5 Example
- E1 2 0 1 0 posy 1 .5
- The output of E1 is the
square root of its input.
4.9 PULSE: Pulsed time dependent value
4.9.1 Syntax
PULSE args
PULSE iv pv delay rise fall width period
4.9.2 Purpose
The component value is a pulsed function of time.
4.9.3 Comments
For voltage and current sources, this is the same as the Spice PULSE function, with some extensions.
The shape of a single pulse is described by the following algorithm:
if (time > _delay+_rise+_width+_fall){
// past pulse
ev = _iv;
}else if (time > _delay+_rise+_width){
// falling
interp=(time-(_delay+_rise+_width))/_fall;
ev = _pv + interp * (_iv - _pv);
}else if (time > _delay+_rise){
// pulsed value
ev = _pv;
}else if (time > _delay){
// rising
interp = (time - _delay) / _rise;
ev = _iv + interp * (_pv - _iv);
}else{
// initial value
ev = _iv;
}
4.9.4 Parameters
- IV = x
- Initial value. (required)
- PV = x
- Pulsed value. (required)
- DELAY = x
- Rise time delay, seconds. (Default = 0.)
- RISE = x
- Rise time, seconds. (Default = 0.)
- FALL = x
- Fall time, seconds. (Default = 0.)
- WIDTH = x
- Pulse width, seconds. (Default = 0.)
- PERIOD = x
- Repeat period, seconds. (Default = infinity.)
4.10 PWL: Piecewise linear function
4.10.1 Syntax
PWL x1,y1 x2,y2 ...
4.10.2 Purpose
Defines a piecewise linear transfer function or time dependent value.
4.10.3 Comments
This is similar to, but not exactly the same as, the Berkeley SPICE
PWL for fixed sources.
For capacitors, this function defines charge as a function of
voltage. For inductors, it defines flux as a function of
current.
For fixed sources, it defines voltage or current as a function of
time.
The values of x must be in increasing order.
Outside the specified range, the behavior depends on the type of
element. For fixed sources, the output (voltage or current) is
constant at the end value. This is compatible with SPICE. For other
types, the last segment is extended linearly. If you want it to
flatten, specify an extra point so the slope of the last segment is
flat.
4.10.4 Parameters
There are no additional parameters, beyond those that apply to all.
4.10.5 Example
- C1 2 0 pwl -5,-5u 0,0 1,1u 4,2u 5,2u
- This ``capacitor''
stores 5 microcoulombs at -5 volts (negative, corresponding to the
negative voltage, as expected. The charge varies linearly to 0 at 0
volts, acting like a 1 microfarad capacitor. (C = dq/dv). This
continues to 1 volt. The 0,0 point could have been left out. The
charge increases only to 2 microcoulombs at 4 volts, for an
incremental capacitance of 1u/3 or .3333 microfarads. The same charge
at 5 volts indicates that it saturates at 2 microcoulombs. For
negative voltages, the slope continues.
4.11 SFFM: Frequency Modulation time dependent value
4.11.1 Syntax
SFFM args
SFFM offset amplitude carrier modindex signal
4.11.2 Purpose
The component value is a sinusoid, frequency modulated by another sinusoid.
4.11.3 Comments
For voltage and current sources, this is the same as the Spice SFFM function, with some extensions.
The shape of the waveform is described by the following equations:
mod = (_modindex * sin(2*PI*_signal*time));
ev = _offset + _amplitude
* sin(2*PI*_carrier*time + mod);
4.11.4 Parameters
- Offset = x
- Output offset. (Default = 0.)
- Amplitude = x
- Amplitude. (Default = 1.)
- Carrier = x
- Carrier frequency, Hz. (required)
- Modindex = x
- Modulation index. (required)
- Signal = x
- Signal frequency. (required)
4.12 SIN: Sinusoidal time dependent value
4.12.1 Syntax
SIN args
SIN offset amplitude frequency delay damping
4.12.2 Purpose
The component value is a sinusoidal function of time, with optional
exponential decay.
4.12.3 Comments
For voltage and current sources, this is the same as the Spice SIN function, with some extensions.
It generates either a steady sinusoid, or a damped sinusoid.
If delay and damping are both zero, you get a steady sine
wave at the specified frequency. Otherwise, you get a damped
pulsed sine wave, starting after delay and damping out with a
time constant of 1/damping.
The shape of the waveform is described by the following algorithm:
reltime = time - _delay
if (reltime > 0.){
ev = _amplitude * sin(2*PI*_freq*reltime);
if (_damping != 0.){
ev *= exp(-reltime*_damping);
}
ev += _offset;
}else{
ev = _offset;
}
4.12.4 Parameters
- Offset = x
- DC offset. (Default = 0.)
- Amplitude = x
- Peak amplitude. (Default = 1.)
- Frequency = x
- Frequency, Hz. (required)
- Delay = x
- Turn on delay, seconds. (Default = 0.)
- Damping = x
- Damping factor, 1/seconds. (Default = 0.)
4.13 TANH: Hyperbolic tangent transfer function
4.13.1 Syntax
TANH gain limit
TANH args
4.13.2 Purpose
Defines a hyperbolic tangent, or soft limiting, transfer function.
4.13.3 Comments
There is no corresponding capability in any SPICE that I know of, but
you can get close with POLY.
For capacitors, this function defines charge as a function of
voltage. For inductors, it defines flux as a function of
current.
For fixed sources, it defines voltage or current as a function of
time, which is probably not useful.
This function describes a hyperbolic tangent transfer function similar
to what you get with a single stage push-pull amplifier, or a simple
CMOS inverter acting as an amplifier.
4.13.4 Parameters
- GAIN = x
- The small signal gain at 0 bias. (Required)
- LIMIT = x
- Maximum output value (soft clipping).
(Required)
4.13.5 Example
- E1 2 0 1 0 tanh gain=-10 limit=2 ioffset=2.5 ooffset=2.5
-
This gain block has a small signal gain of -10. The input is
centered around 2.5 volts. The output is also centered at 2.5 volts.
It ``clips'' softly at 2 volts above and below the output center, or
at .5 volts (2.5 - 2) and 4.5 volts (2.5 + 2).
4.14 .model TABLE: Fit a curve
4.14.1 Syntax
.model name TABLE x1,y1 x2,y2 ... args
4.14.2 Purpose
Fits a table of data using piecewise polynomials, or splines.
4.14.3 Comments
This function fits a set of piecewise polynomials to a set of data.
It differs from the FIT function in that the TABLE form
uses a .model statement containing the actual data, while the
FIT form has all of the data on the instance line.
See the comments section of FIT for more detail on the options.
4.14.4 Parameters
- Order = x
- The order of the polynomial to fit,
within the supplied data. (Default = 3) Legal values are 0, 1, 2,
and 3, only.
- Below = x
- The value of the derivative to use
below or before the specified range.
- Above = x
- The value of the derivative to use
above or after the specified range.
4.14.5 Example
.model nlcap table -5,-5u 0,0 1,1u 4,2u 5,2u order=1
C1 2 0 nlcap
This ``capacitor'' stores 5 microcoulombs at -5 volts (negative,
corresponding to the negative voltage, as expected). The charge
varies linearly to 0 at 0 volts, acting like a 1 microfarad capacitor.
(C = dq/dv). This continues to 1 volt. The 0,0 point could have been
left out. The charge increases only to 2 microcoulombs at 4 volts,
for an incremental capacitance of 1u/3 or .3333 microfarads. The same
charge at 5 volts indicates that it saturates at 2 microcoulombs. For
negative voltages, the slope continues. See the example under FIT for a comparison.