Previous Up Next

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 ...
  1. There are more choices, including an ``else''.

  2. They apply to all elements (primitive components).

  3. 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.
Previous Up Next