# HP ADS 1.5 User-defined Models User Manual

Brand: HP, Pages: 216, PDF Size: 1.33 MB

### Page 31 from 216

Characteristics of User-Compiled Elements 1-25 typedef struct _UserNonLinDef UserNonLinDef;

struct _UserNonLinDef

{

int numIntNodes; /* # internal nodes of device */

/* Evaluate linear part (Y-pars) of device model */

boolean (*analyze_lin)(IN UserInstDef *pInst, IN double omega)

/* Evaluate nonlinear part of device model:

nonlinear current out of each pin, nonlinear charge at each pin

* derivative (w.r.t. pin voltage) of each

* nonlinear pin current, i.e. nonlinear conductance g,

* derivative (w.r.t. pin voltage) of each

* nonlinear pin charge, i.e. nonlinear capacitance c */

boolean (*analyze_nl)(IN UserInstDef *pInst, double *pinVoltage);

/* Evaluate small-signal AC model:

* compute total (linear+linearized) Y-pars of device */

boolean (*analyze_ac)(IN UserInstDef *pInst, IN double *pinVoltage, IN

double omega);

struct _SeniorModel *modelDef; /* user-defined Senior MODEL (arbitrary) */

/* Evaluate bias-dependent linear noise model:

compute total (linear+linearized) noise-current correlation parameters

(normalized to FOUR_K_TO, siemens) of device */

boolean (*analyze_ac_n)(IN UserInstDef *pInst, IN double *pinVoltage,

IN double omega);

};

A transient response function can be defined for any element (linear or nonlinear) by

defining the functions in the

UserTranDef type shown.

numIntNodes is an arbitrary number of nodes internal to the element. In its model,

the element must compute the contributions at all its pins, which are ordered and

numbered (starting at zero) with the external pins first, followed by internal pins. If a

UserNonLinDef type is defined for the element, the numIntNodes in that structure must

match this definition.

Special routines are available to simplify the use of ideal resistors, capacitors,

inductors, and transmission lines within a transient element. For the circuit

simulator engine to perform the appropriate allocations, the number of these

elements (except resistors) must be predefined using

numCaps, numInds, and

numTlines.

### Page 32 from 216

1-26 Characteristics of User-Compiled Elements

Building User-Compiled Analog Models

The analyze_tr function must compute and load the instantaneous time domain

response of the element, using the element's pin voltages as inputs. The passed array

pinVoltage contains the instantaneous voltages at both the external and internal

pins.

If P is the total number of pin voltages, formulate nonlinear current and charges at

each pin n as follows:

rn (t) = f (v0(t),v1(t),..., vP-1 (t)) where rn is the current out of the pin or charge

response. These responses and their voltage derivatives (nonlinear conductances and

capacitances) must be computed and loaded using the

add_tr_iq and add_tr_gc

functions, respectively. Note that the derivatives are used to help converge to a

solution, therefore the simulator may reach a solution even if they are not exact.

However, under certain simulation conditions, inexact derivatives may cause

convergence problems. Also, for convergence reasons, they should be continuous.

### Page 33 from 216

Characteristics of User-Compiled Elements 1-27

The fix_tr function is called just before transient analysis begins. Its only purpose is

to set up ideal transmission lines for the user. Using the

add_tr_tline function,

transmission line nodes and physical constants are defined. Once the transmission

line is defined here, time-domain analysis of it is performed automatically without

any further action by the user in the

analyze_tr function.

typedef struct _UserTranDef UserTranDef;

struct _UserTranDef

{

int numIntNodes; /* internal nodes of device */

int numCaps; /* number of explicit capacitors */

int numInds; /* number of explicit inductors */

int numTlines; /* number of explicit transmission lines */

boolean useConvolution; /* use linear response for convolution */

/* Evaluate transient model

* nonlinear currents out of each pin,

* nonlinear charge at each pin

* derivative (w.r.t. pin voltage) of each

* nonlinear pin current, i.e. nonlinear conductance g,

* derivative (w.r.t. pin voltage) of each

* nonlinear pin charge, i.e. nonlinear capacitance c */

boolean (*analyze_tr)(IN UserInstDef *pInst, IN double *pinVoltage);

/* Pre-transient analysis routine used to allocate, compute and

* connect ideal transmission lines */

boolean (*fix_tr)(IN UserInstDef *pInst);

};

Each user-defined item placed in a design is represented in the ADS Simulator by the

item type

UserInstDef. All the fields, except seniorData, in an item are set up by ADS

Simulator and must not be changed.

seniorData can refer to arbitrary data and is

meant to be managed by user code exclusively.

typedef struct _UserInstDef UserInstDef;

struct _UserInstDef

{

char *tag; /* item name */

UserElemDef *userDef; /* access to user-element definition */

UserParamData *pData; /* item's parameters */

void *eeElemInst; /* EEsof's element item */

void *eeDevInst; /* EEsof's nonlinear device item */

void *seniorData; /* data allocated/managed/used only by

Senior module (arbitrary) */

};

### Page 34 from 216

1-28 Characteristics of User-Compiled Elements

Building User-Compiled Analog Models

The get_params function, below, loads the passed item eeElemInst parameter values

into

pData, which must be big enough to store all parameters. It is used to obtain

referenced item (such as model substrate) parameters. Note that user-defined item

parameters are already available in the

UserInstDef.pData array, so there is no need

to call

get_params for user item parameters. It returns TRUE if successful, FALSE

otherwise.

extern boolean get_params (IN void *eeElemInst, OUT UserParamData *pData);

These functions are useful to indicate program status in various stages of execution,

such as during module boot-up, element analyses, and pre- or post-analysis.

extern void send_info_to_scn (IN char *msg); /* write msg to Status/

Progress window */

extern void send_error_to_scn (IN char *msg); /* write msg to Errors/

Warnings window */

In nonlinear analyses, for each set of independent input values (bias, frequency,

power, or swept variable), ADS simulator attempts to find the steady state solution

iteratively. In each iteration, nonlinear parts of all element items, including

user-defined items, are evaluated. This function returns

TRUE whenever the first

iteration is in progress. It is most useful for parameter range checking, which is

sufficient to do at the first iteration.

extern boolean first_iteration (void);

This function returns TRUE whenever the circuit is being analyzed at the first point in

a frequency plan. Note that this can happen many times in one simulation command

for example, if there is another swept variable, or if an optimization/yield analysis is

requested.

If a one-time-only operation is to be performed per circuit, the

pre_analysis function

is recommended instead of this function.

extern boolean first_frequency (void);

The function below computes the normalized complex noise correlation matrix for a

passive element, given its Y-pars, operating temperature and number of pins.

extern boolean passive_noise (IN COMPLEX *yPar, IN double tempC, IN int

numNodes, OUT COMPLEX *nCor);

### Page 35 from 216

Characteristics of User-Compiled Elements 1-29

The function below computes the normalized complex noise correlation 2*2 matrix for

an active 3-terminal, 2-port element/network, given its Y-pars and measured noise

parameters. Note that if

numFloatPins is 2, the common (reference) third terminal is

ground.

extern boolean active_noise (IN COMPLEX *yPar, IN NParType *nPar, int

numFloatPins, OUT COMPLEX *nCor);

The function below must be called (usually from nonlinear model's analyze_lin and

analyze_ac procedure) to add the linear complex Y-parameter (iPin, jPin) branch

contribution. This call must be done even for linear capacitive branches at DC (omega

= 0), this will establish the Jacobian matrix entry location for subsequent non-zero

harmonic omega.

extern boolean add_lin_y (INOUT UserInstDef *userInst, IN int iPin, IN int

jPin, IN COMPLEX y);

The function below must be called (from nonlinear model's analyze_ac_n function) to

add the complex noise-current correlation term iNcorr (Siemens, normalized to

FOUR_K_TO) from the (iPin, jPin) branch.

extern boolean add_lin_n (INOUT UserInstDef *userInst, IN int iPin, IN int

jPin, IN COMPLEX iNcorr);

The function below must be called (from nonlinear model's analyze_nl function) to

add the nonlinear conductance and capacitance contribution for the (iPin, jPin)

branch.

extern boolean add_nl_gc (INOUT UserInstDef *userInst, IN int iPin, IN int

jPin, IN double g, IN double c);

The function below must be called (from nonlinear model's analyze_nl function) to

add the nonlinear current and charge contribution at the device pin iPin.

extern boolean add_nl_iq (INOUT UserInstDef *userInst, IN int iPin, IN

double current, IN double charge);

The function below can be called (from nonlinear model's analyze_nl function) to get

tau seconds delayed (iPin, jPin) voltage difference. Note that tau must not be

dependent on device pin voltages--it is an ideal delay.

extern boolean get_delay_v (INOUT UserInstDef *userInst, IN int iPin, IN

int jPin, IN double tau, OUT double *vDelay);

Any transient support function that follows can use ground as a pin by using this

special macro:

#define GND -1