HbFree v. 0.1
User's Guide

Gennady Serdyuk

19-Sept-2000

1  Copyright and License

Copyright (C) 2000, Gennady Serdyuk.

[Definitions:] 
["Package"]

refers to the collection of files distributed by the Copyright Holder.

["Copyright]

Holder" is the person is named in the copyright or copyrights for the package.

["Recepient"]

is you, if you're thinking about using, copying or distributing this Package.

Copyright Holder grants to the Recipient a non-exclusive, royalty-free license limited to use, copy, distribute without charging for a fee this Package, provided that the above copyright notice appears in all copies made of Package and both the copyright notice and this license appear in supporting documentation. All other rights (including, but not limited to, the right to sell Package, the right to sell or distribute derivative works of Package, the right to distribute Package for a fee, and the right to include Package or derivative works of Package in a for-sale product or service) are reserved by the Copyright Holder.

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

In no event shall Copyright Holder become liable to Recipient or any other party, for any loss or damages, consequential or otherwise, including but not limited to time, money, or goodwill, arising from use or possession, authorized or not, of Package by Recipient or any other party..

2  Introduction

This is still pre-release of documentation, so some items may be not finished or not clear. Let me know -I will fix (gs).

HbFree is a package of programs, which is intended for simulation of radio-frequency and microwave (RF&MW) (selective) analog non-autonomous nonlinear circuits in frequency domain. Used 2-dimensional representation allows precisely simulate circuits under quasi-harmonic excitation. It may be suitable to analyze electronic circuits, which behavior is essentially depends on nonlinear properties of electronic devices circuit consists of. There are power amplifiers, mixers, modulators, detectors, etc.

Circuits may contain linear components (resistors, capacitors, inductors, transmission lines) and nonlinear (diodes and MESFETs).

Program implements piecewise harmonic balance (HB) technique, which is quite widely used in RF&MW CAD industry.

HbFree uses own input file format, but is equipped with translator, which can translate SPICE files (with minor changes) to simulator's input file format.

HbFree package consists of translator, simulator, utilities and documentation.

3  Theoretic Background

Harmonic balance technique is derived from circuit description equation (it is system of nonlinear ordinary differential equations, in general):

f (t,x,[(dx)/(dt)],..,[(dkx)/(dtk)]) = a(t)+l(t,x,[(dx)/(dt)],..,[(dkx)/(dtk)])+n(t,x,[(dx)/(dt)],..,[(dkx)/(dtk)]) = 0

where:

[ a(t) ]- circuit excitation
[ l(t,x,[(dx)/(dt)],..,[(dkx)/(dtk)]) ]- linear differential operator
[ n(t,x,[(dx)/(dt)],..,[(dkx)/(dtk)]) ]- general nonlinear differential operator
[ k ]- maximum derivative order
[ t ]- time

By applying Fourier transformation to it, it is possible to transfer the first equation to frequency domain.

Fn(w,Xn) = A(w)+L(k,w)*Xn+N(w,Xn) = 0

for n = 0,+¥ ;

Where Xn - n -th harmonic (complex).

Using of Fourier transformation implies fundamental assumption about periodic processes in system. In the case of nonautonomous circuit excitations A(t) should be periodic. After Furrier transformation have been applied system equations formulated at every frequency in the circuit - namely basic frequencies (frequencies of excitations) and high-order frequencies (harmonics and combinations, if excitation is multitone). These nonlinear equations have to be solved to obtain result - amplitudes and phases of variables.

Frequency-domain formulation is native for linear elements - lumped and distributed. Contrary, it is hard enough to represent most distributed elements in time domain. It is the first advantage of the harmonic balance approach vs. direct time-domain integration of system equations. The second is explicitiness of solution. If time-domain integration of circuit equation is used, it is necessary to over the transient process (for high quality circuits it may takes hundreds of periods), detect steady state (for mixers period of intermediate frequency may exceeds thousands of periods of local oscillator or signal frequency) and make Fourier transformation of resulting solution. If period is taken improperly, then certain errors in results will occur. In case of harmonic balance amplitudes and phases are the direct results of solution process.

3.1  HaBala Features

The node voltages basis is used to formulate harmonic balance equations. This implies some restrictions onto available elements and/or values of parameters. E.g. resistors should not be equal to zero, voltage sources should have internal resistance, etc. It may violate results (in strict sense), but, practically, all parameters can be set to values, that resultiong error can be neglected.

Some special efforts was made in the field of global convergence of used nonlinear equations solution method. Two main approaches was tested - using the a-priory information about ``working point'' of the nonlinearities and applying modifications to Newton process (namely - linear search along Newton direction, as it was described in []). The second approach delivers better robastness and convergence speed.

4  2-dimensional frequency

HB approach is used to simulate non-autonomous processes in nonlinear circuits.

In the HB approach it is assumed, that circuit is driven with several periodic sources.

Consider simple nonlinear circuit, which is diven by sinusoidel source with frequency F1. Steady state respone of such circuit will be periodical (with the same period as excitation) but will contain (precisely - infinite) number of harmonic members with frequencies n*F1. We can put correspondent frequencies on the X axis and amplitudes on the Y axis. Thus we obtain spectrum of responce as at Fig. .

*0.8!pics/grid1d.gif

Figure 1: 1-dimensional frequency grid and correspondent spectre.

And now consider, that circuit is driven by two sinusoidal sources with frequencies F1 and 2*F1. We can use the same representation - second excitation will coinside with second harmonic of fundamental (F1) exciation.

But things are not so simple in general. Assume, that second frequency is independent to F1. This is usuall in mixers and power amplifiers under two-tone exciation. In this case specrum became more complicated - not only harmonics, but combination frequencies are present in responce. And we can see as at the Fig. .

*0.8!pics/grid.gif

Figure 2: 2-Dimensional frequency grid and spectre.

It is possible to represent this case as 2-dimensional. Essential frequencies are represented onto frequency plane as solid crosses. In this case fundamentals have coordinates (0,1) and (1,0), DC have usual coordinate (0,0) and all harmonics of first fundamental have coordinates (n,0), n=2.. ¥. Compare with representation 1-tone spectre onto 2-dimensional plane ( Fig. 1.)

HaBala uses 2-dimesional representation of the spectre, present into the circuit. To specify circuit responce, it is necessary to set F1 and F2 and to list pairs of integers of all combinations, which are assumed as nonzero.

5  Package Structure

Package consists of several programs, which should interact in a certain way.

Flowchart Fig. is intended to explain main components of Package.

*0.9!pics/flowchart.png

Figure 3: HbFree flowchart

``hb'' (also called ``HaBala'' or HABALA - means HArmonic BALAnce) is the central part of package. It is HB simulator itself. As it uses own circuit description format (which definition is not included in the documentation), translator to this format is provided. This translator (named ``s2h'') translates SPICE circuit description into intermediate representation, suitable for HABALA. To provide additional data, necessary for proper translation of SPICE circuit to HABALA input, translator configuration file is used. During translation variables names are changed. To restore initial variables names, which was changed by translator, ``hnr'' program is used.

S2h translator produces three useful files. The first one is the intermediate circuit description file will be used by simulator immediately after translation. The second one - ``spice-habala'' node table will be used later to restore initial node names. The third - log - should be rewieved in case translation errors - see ``Translator'' section.

HABALA produces two files as output. The first one is the log file, which contains information about solution process and results. It should be reviewed after simulation to detect the reason - why simulation was finished. Iterative procedure is used to solve the system of HB equations; it may coverge to solution, but may do not. More precisely it will be described in ``Translator'' section.

``hbf'' script (or executable - depending on the system) describes the way components should be integrated.

6  Task Description

Task description consists of circuit description and regime description. Both parts may be mixed into one file.

The first line of file is treated as task name.

Each line started with ``*'' is treated as comment line.

Each line started with ``+'' is treated as previous line continuation.

Circuit description is almost conform to SPICE input landuage with some restrictions.

Many SPICE directives ( they started with ``.'' in the first position of the line) are ignored. As HbFree is intended for HB simulation, so usual SPICE's analisys types (.AC, .DC, .DISTO, .NOICE, .OP, .PZ, .SENS, .TF and .TRAN) are not supported and correspondent directives will be ignored. SPICE directive .OPTIONS will be ignored too.

Supported directives are:

.SUBCKT - subcircuit definition

.ENDS - end subcircuit definition

.END - end file

.INCLUDE - include file

.MODEL - model definition

New directive .HB is added to describe main parameters of simulation (circuit regime), if many .HB directives are denoted, only last directive will be used. New directive .HB_OPTIONS is added to describe additional simulation parameters (desired precision tolerances, etc.).

Unfortunately, do not all SPICE devices are implemented. More, HB simulation program (named ``hb'' or ``HaBala'') was designed independently, so it have own model library. Compatibility between SPICE and HABALA models is described in respective sections.

6.1  Circuit Description

Circuit may contain usual types of elements: R, L, C, I, V, T, O, D, Z.

Values may be followed by scaling suffixes - f, p, n, u, m, mil, K, Meg, G, T

Nodes in element description can be denoted as numbers or as strings.

.MODEL directive is used to define model of the element.

.SUBCKT / .ENDS directives are used to define subcircuit.

6.2  Directives

There are two aditional directives to set circuits regime and paremeters of solution process: .HB and .HB_OPTIONS

6.2.1   HB directive

.HB directive looks like this:

.HB F1=<f1> F2=<f2> n01 n02 n11 n12 n21 n22 n31 n32 ... nxx
e.g.:

.HB F1=1.5 F2=0  0 0  1 0  2 0  3 0  4 0  5 0  

+ 6 0  7 0  8 0  9 0 

describes 1-dimensional frequency grid (DC + 9 harmonics).

.HB F1=1.5G F2=1.57G 0 0  1 0  0 1 

+ 0 2  1 1  2 0  1 -1 

+ 0 3  1 2  2 1  3 0  2 -1  1 -2 

+ 0 4  1 3  2 2  3 1  4 0  3 1 

This directive sets two-dimensional frequency grid with 19 points on plane.

6.2.2  HB_OPTIONS directive

It looks like the following:

.HB_OPTIONS PAR1=<value1> PAR2=<value2> ... PAR3=<value3>
Possible parameter names, values and their meanings are the same as in the Translator Configuration File .

6.3   Translator Configuration File

For proper translation of SPICE input file into HaBala representation additional parameters should be specified. They are gathered into Translator configuration file.

All parameters may be divided onto two groups. The first group consists of parameters, which are necessary to complete elements description, the second - default values to control the solution process.

Translator configuration file have the following look:

* commnet line

* may 

PARAMETER = value

...

* another one comment

PARAMETER = value

If some parameter have been defined twice, only last definition is valid.

Available parameters are defined in the following sections.

6.3.1  L,C, and V Parasitics

Rl = 0.01

Gc = 1.e-5

Ri = 0.001

6.3.2  Diode additional parameters

In addition to ``.MODEL'' parameters, several paremeters are specified into Translator Configuration File:

U0=0.5 

DU=0.1

These parameters control solution process under certain circumstances. Do not change them (or simply delete from file - defaults will be used)

k_Diode_f0=0.8
This parameter sets the linearization point of C(u) characteristic. Linearization point =VJ * k_Diode_f0. Value of k_Diode_f0 should be < 1.

Rsmin=1.0
Lower boundary of RS. Should be >0.

6.3.3  MESFET additional parameters

Some default and boundary values for MESFET model transformation are specified in configuration file too. These parameters mostly described in section .

MESFET_RDMIN=0.1
Minumum available value of RD

MESFET_RSMIN=0.1
Minumum available value of RS

MESFET_RG=0.1
Default value of Rg; Value of Rg = R2

MESFET_CDS=0.0
Value of drain-source capacitance C13

MESFET_IS0=0.0
Value of saturation current of gate-source Schottkey diode

MESFET_N=1.0
Define emission coeficient of gate-source Schottkey diode.

MESFET_RDS=1.E09
Drain-Source parasitic; default = 1.E09

MESFET_RGS=1.E09
Gate-source parasitic; default = 1.E09

MESFET_UBOUND=0.52

MESFET_STEPM=0.12

Parameters for a-priori Newton method globalization (it is possible to delete them from file and use default values from inside the ``s2h'' translator).

6.3.4  Solution control parameters

EPSIW = 1.e-5
(real, default=1.e-5). Some circuit elements (sources) have frequency as a parameter. From the other hand - in directive .HB will be set frequency grid (set of harmonics) and oscillating sources shold be distributed onto this frequency grid. Namely - each source will be assigned onto certain frequency of this frequency grid (see Fig. 2) if their frequencies are equal. As exact equality is impossible over real numbers - EPSIW is the relative precision of comparison.

EPSSOL = 1.e-6
(real, default=1.e-6). Required precision of solution. It is a half of quadratic norm of imbalance in Amperes. If half of square root of sum of squares of all imbalances is less than EPSSOL it is assumed the solution have found.

EPSDU = 1.e-6
(real, default=1.e-6). Minimum possible correction of node voltages. If half of quadratic norm of correction vector is less than EPSDU - it is assumed that model properties are poor and convergence is too slow to continue solution. Note: IT IS NOT A VALID SOLUTION. ONLY IMBALANCE DEFINES NEARNESS OF TRUE SOLUTION.

EPSMIN = 1.e-7
(real, default=1.e-7). Parameter used to disclose local minimum of the system of nonlinear equation (if task F=0 is interpreted as min{F t *F} ). It is better to set it to a quite low value - e.g. to 1.e-12 or 1.e-18.

MAXDU = 0
(real, default=0). Maximum possible node voltage correction of Newton method (l2-norm of correction vector). 0- not checked.

LIMIT = 500
(integer, default=500). Maximum quantity of iterations of Newton method. Integer. Is set to 500.

MGLOB = 1 
(integer, default=1). Strategy of globalization of Newton method setting. 0 - no strategy chosen, 1 - used linear search in Newton direction (better).

IAPR = 0
(integer, default=0). Usage of heuristic method of Newton step limitation (it do not allow voltage drop over diode junction be larger then 1V). 0 - No, 1 - Yes.

KNC = 32
(integer, power of 2, default=32). Length of one-dimensional FFT.

The following variables switches print mode in HaBala:

KPRLEN = 0
Switch output regime of circuit reading part of program: 0 - print nothing, 1 - print main messages, 2 - print a lot. (default = 1);

KPRSRT = 0
Switch output regime of circuit nodes sorting part: 0 - print nothing, 1 - print main messages, 2 - print a lot. (default = 0);

KPRNKR = 0
Switch output regime of grid generation part : 0 - print nothing, 1 - print main messages, 2 - print a lot. (default = 0);

KPRLIN = 0
Switch output regime of linear subcircuit solution: 0 - print nothing, 1 - print main messages, 2 - print a lot. (default = 0);

KPRSOL = 0
Switch output regime of solving of nonlinear equations: 0 - print nothing, 1 - print main messages, 2 - print a lot. (default = 0);

7  Available Elements

7.1  R, L, C

RXXXX node1 node2 value

CXXXX node1 node2 value

Translated into the parallel capacor C and conductance G.

G value is described into translator configuration file.

LXXXX node1 node2 value
Translated into the series inductor L and resistor R.

R value is described into translator configuration file.

7.2  Sources

VXXXX N+ N- [[DC/TRAN] DCVALUE] [AC ACVALUE [ACPHASE]] 

+                 [PULSE(..)|SIN (..)|EXP(..)|PWL(..)|SFFM(..)]

+                 [DISTOF1 F1MAG [F1PHASE]] 

+                 [DISTOF2 F2MAG [F2PHASE]] 

IXXXX N+ N- [[DC] DCVALUE] [AC ACVALUE [ACPHASE]] 

+                 [PULSE(..)|SIN (..)|EXP(..)|PWL(..)|SFFM(..)]

+                 [DISTOF1 F1MAG [F1PHASE]] 

+                 [DISTOF2 F2MAG [F2PHASE]] 

N+ and N- are positive and negative nodes.

AC section is ignored by translator

PULSE, SIN, EXP, PWL and SFFM sections are ignored by translator, but parameters should be enclosed into parenthesis.

DC/RAN value will be assumed as value of DC source.

DISTOF1 value (and phase) will be assumed as value of frequency F1 (see .HB directive 6.2.1), and DISTOF2 - respectively F2. Voltages and currents are effective (not maximum - in contrast to SPICE). Phases are in degrees.

Voltage sources assumed have internal (parasitic) resistance Ri (see Transator Configuration File 6.3)

7.3  Lossless Transmission Line

TXXXX N1 N2 N3 N4 Z0=VALUE [TD=DELAY | F=FREQ NL=NORMLEN]

+                 [IC=...]

N1 and N2 are nodes of port 1, N3 and N4 - port 2.

TD or F and NL should be specified.

In Translator Configuration File one more parameter is specified. It is Rline - series resistance of line in ``short circuit'' resonance'' (resistance to ground of 1/4-wavelength stub at resonance frequency).

7.4  Lossy Transmission Line

OXXXX N1 N2 N3 N4 MODELNAME

.MODEL <MODELNAME> LTRA R=<val> [L=<val> G=<val>] C=<val> 

+                  [LEN=<val>]

+                  [OTHER_PARAMS]

Lossy transmission line is translated into LOSSLESS transmission line - so R and G are assumed 0.

The reason is HABALA feature. It have model of lossless line and models for strip/microstrip lines, but not have model for lossy line. As model of lossy transmission line will be implemented in HABALA, it will be reflected in this guide.

L and C values should be specified.

LEN assumed =1 if not specified.

OTHER_PARAMS are ignored.

7.5  Diode

DXXX NA NC DIODEMODEL

.MODEL DIODEMODEL D IS=<val> RS=<val> N=<val> TT=<val> CJ0=<val> 

+                 VJ=<val> M=<val>

+                 [OTHER_PARAMS]

*0.7!pics/diod.gif

Figure 4: Diode model.

The model of diode is implemented in HABALA is shown at Fig 4. Main formulaes of the model are the following:

i(u) = Iso·(easu-1) ;

C(u) = [(Cj0)/(Ö{1-[(u)/(f)]})] ;

It is quite similar to SPICE's dide model. To translate SPICE model to HABALA, the following transformations and assumtions are made:

SPICE parameterHABALA parameterNotes
IS Is0 = IS*AREA
RS Rs = [(RS)/(AREA)] >Rsmin
N as = [(q)/((k·T·N))] = [36.6676/(N)]
TT-assumed = 0
CJO Cj0 = CJ0·AREA
Vj f = Vj
M-assumed = 0.5
Cp = 0
Ls = 0

OTHER_PARAMS are ignored.

In addition several paremeters are set into Translator Configuration File:

U0=0.5 

DU=0.1

These parameters control solution process under certain circumstances. Do not change them (or simply delete from file - defaults will be used)

k_Diode_f0=0.8
This parameter sets the linearization point of C(u) characteristic. Linearization point =VJ * k_Diode_f0. Value of k_Diode_f0 should be < 1.

Rsmin=1.0
Lower boundary of RS. Should be >0.

7.6   MESFET .

ZXXXX ND NG NS MNAME

.MODEL MNAME (NMF | PMF) VTO=<val> BETA=<val> B=<val> 

+             ALPHA=<val> LAMBDA=<val>

+             RD=<val> RS=<val> 

+             CGS=<val> CGD=<val>

+             PB=<val>

+             [OTHER_PARAMS]

The modified Curtice []model is implemented in HABALA simulator. It scematics is shown at Fig. .

*1!pics/mesfet1.gif

Figure 5: MESFET model is implemented in HABALA

Main formulaes of the model are:


Is = b·(u1-Uth)2·(1+l·u2)·tanh(a·u2)


i(u1) = I0·(eas·u1-1)


C23(u1) = C230
  æ
 ú
Ö
1- u1
f
 

It is diffrent from Statz model [], so translations are used.

SPICE parameterHABALA parameterNotes
VTO Vth = -VTO
BETA b = BETA*AREA
B-assumed B=1
ALPHA a = ALPHA
LAMBDA l = LAMBDA
RD R1 = RD/AREA RD ³ MESFET_RDMIN 1 )
RS R3 = RD/AREA RS ³ MESFET_RSMIN 1 )
CGS C230 = CGS 2 )
CGD C12 = CGD constant 2 )
PB f = PB
R2 = MESFET_RG MESFET_RG 1 )
C13 = MESFET_CDS MESFET_CDS 1 ), 2 )
I0 = MESFET_IS0 MESFET_IS0 1 ), 2 )
as = [(q)/((k·T·MESFET_N))] = [36.6676/(MESFET_N)] MESFET_N 1 )
R31 = MESFET_RDS MESFET_RDS 1 )
R23 = MESFET_RGS MESFET_RGS 1 )
1 ) parameter is defined in config file
2 ) parameter should be dependent on AREA, but it is not implemented.

8  Limitations

8.1   Number of Harmonics

Number of hamonics should not be larger than 20.

8.2  Task Size

Owerall task size should not be larger than 180 complex variables.

Task size TS=NN*HN, where:

NN - total number of nonlinear nodes. Note, that each diode yields 2 nonlinear nodes, each MESFET - 3;

HN - number of harmonics in .HB directive (see 8.1).

8.3  Elements Quantity

Elements quantity is not limited explicitly. Limitations are derived from the following:

Maximum number of parameters = 1000;

Maximum number of units to store information about elements = 1000;

9  Additional Information

10  Bugs

11  Contact Information

Gennady Serdyuk,

ZAO ForaTech,

Ukraine, Kiev,

04111, Scherbakova, St., 36A

E-mail: gserdyuk@mail.ru

ph/fax: 380 44 443-4984;

http://users.sovamua.com/foratech/gserdyuk

References

[]
J. E. Dennis, Jr. and Robert B. Schnabel, ``Numerical Methods for Unconstrained Optimization and Nonlinear Equations''.
[]
W.R.Curtice, ``A MESFET Model for Use on the Design of GaAs Integrated Circuits'', IEEE Trans. Microwave Theory Tech., vol. MTT-28, No5, May 1980, pp. 448-456.
[]
H.Statz et al., ``GaAs FET Device and Circuit Simulation in SPICE'', IEEE Trans. On Electron Devices, Vol. 34, Number 2, February, 1987, pp. 160-169



File translated from TEX by TTH, version 2.73.
On 9 Oct 2000, 17:36.