SPICELib.src

Source code of SPICELib

SPICELib.src.ANALYSES SPICELib.src.INIT SPICELib.src.INTERFACE SPICELib.src.SOURCE SPICELib.src.SPECIAL SPICELib.src.WAVEFORMS

Information





Library Designer Documentation



1. ARCHITECTURE


2. DEVICE MODELS


3. ANALYSES


1. ARCHITECTURE

A two-level architecture is proposed (see Figure 1): The list of files and subpackages of package SPICELib.src is shown in Table 1.


Figure 1. Two-level architecture of SPICELib.


Table 1. Complete list of files and packages of SPICELib.src.
File Package (SPICELib.src.)
analyses.mo ANALYSES
breakout.mo BREAKOUT
functions.mo
init.mo INIT
interface.mo INTERFACE
source.mo WAVEFORMS
SOURCE
special.mo SPECIAL


1.1 CONTROLLER LEVEL: ANALYSIS MODELS

An important feature of SPICELib device models is their variable structure nature. A different device model is formulated for each analysis mode: static model (DC analysis), AC small-signal model (AC analysis), and large-signal model (transient analysis). The transitions among these three device formulations are carried out in simulation time.

A DC analysis In addition, some bias point calculation algorithms require the combined use of the three device formulations. See Figure 2, where S.M.I., S.M.R., GMIN and D.M.R. stand for the four bias point calculation algorithms supported by SPICELib.
Figure 2. Some analysis require the combined use of several device formulations.


ANALYSES package contains the OP, TRAN and AC models. Bias point calculation is a part of OP and AC analyses and it is an option of TRAN analysis. Therefore, the four bias point calculation algorithms are programmed in a separate partial model, called BiasPointCalculation, inherited by the analysis models (see Fig. 1). Device models have a variable structure and signals are defined to control the model structure transitions. Each analysis model consist on an ordered sequence of elementary operations implying changes in the device model structure. Analysis models set the control signals in order to accomplish the required device-model structure changes. Control signals and global variables, evaluated in the analysis models, are shown in Figure 3.
Figure 3. Control signals, global variables and global parameters.


1.2 CONTROLLED LEVEL: DEVICE MODELS

Device models are grouped in three packages: The models of BREAKOUT and SOURCE packages allow the composition of user-defined circuits, while the SPECIAL's provide one way to specify the initial conditions. In addition, a fourth package containing the device model interfaces has been defined: INTERFACE.

1.3 INITIALISATION FILE

The initialisation file, init.mo, contains the INIT package. The control signals, the global variables and the global parameters (see Fig. 3) are defined in the INIT package. It contains two partial models: The same set of control signals, variables and parameters are defined in both partial models: Analysis model variables are inner ones, while Part variables are outer ones.

1.4 GLOBAL PARAMETERS

Two global parameters have been defined (see Fig. 3). TimeScale parameter is used for setting the length of the source ramping processes of some bias point calculation algorithms. In addition, it is used for establishing the time elapsed between consecutive control signal transitions (conceptually similar to the system clock period). To this end, the integer constant TIME_SLOT constant is defined in the analysis models. It represents a porcentage (1 to 100). The time between consecutive events, CLOCK, is defined as shown in Fig. 3.

2. DEVICE MODELS

2.1 LINEAR RESISTOR

Resistor model is shown in Figure 4. The purpose of the static-model IC1-like circuits (switches, R_EPS resistors and voltage sources) is clamping the DC-formulation voltage at the resistor pins. The bias point claculation algorithm "dynamic model ramping" requires the following operation: clamping the DC formulation voltage to the instantaneous value of the large-signal formulation. The ctrl_RBREAK_Tran2DC signal controls this information transfer between formulations. When ctrl_ RBREAK_Tran2DC becomes true:
Figure 4. Resistor model.



2.2 CAPACITOR

Linear and voltage-dependent capacitors have to be modelled. The partial model Capacitor (BREAKOUT package) describes all the capacitor behavior except its large-signal and AC small-signal capacitance. The Capacitor1 model (linear capacitor) and semiconductor-device capacitors models extend the Capacitor model. CBREAK is a linear capacitor without high index problems. It consists of Capacitor1 in series with a resistor.

Capacitor static formulation is shown in Figure 5. The implementation of the IC property requires the IC2-like circuit (switch, R_EPS resistor and vClampDC source).

Large-signal model is shown in Figure 5. IC2-like circuit is also included because the "dynamic model ramping" algorithm uses the large-signal formulation during the bias point calculation. The Boolean signals controls the static and large-signal model switches respectively.

The capacitor parameter IC_ENABLED enables or disables the IC property. It allows distinguishing between the cases when IC is intentionally set to zero and those cases when the IC property is not enabled.

The signal ctrl_IC_mode controls vClampDC and vClampTran voltages. Some bias point calculation algorithms need the independent source ramping from zero up to their nominal initial values. When implementing these algorithms, the voltage clamping sources of the IC symbols and the capacitor IC property need also be ramped from zero to their respective IC values. Two cases are distinguished:
Figure 5. Capacitor model.


The model of the capacitor IC property depends on whether the bias point is calculated or the calculation is skipped (see Fig. 6):
Figure 6. Implementation of the initial conditions.



2.3 INDUCTOR

Linear inductors have to be modelled. The partial model Inductor (BREAKOUT package) describes all the inductor behavior except its large-signal and AC small-signal inductance. The Lbreak model (linear inductor) model extends the Inductor model. Inductor static formulation is shown in Figure 7. The implementation of the IC property requires the circuit shown in figure 7 (switch, R_BIG resistor and iClampDC source).

Large-signal model is shown in Figure 7. The switch, R_BIG resistor and iClampDC source are also included because the "dynamic model ramping" algorithm uses the large-signal formulation during the bias point calculation. The Boolean signals controls the static and large-signal model switches respectively.

The inductor parameter IC_ENABLED enables or disables the IC property. It allows distinguishing between the cases when IC is intentionally set to zero and those cases when the IC property is not enabled.

The signal ctrl_IC_mode controls iClampDC and iClampTran voltages. Some bias point calculation algorithms need the independent source ramping from zero up to their nominal initial values. When implementing these algorithms, the voltage clamping sources of the IC symbols and the inductor and capacitor IC property need also be ramped from zero up to their respective IC values. Two cases are distinguished:
Figure 7. Inductor model.


The model of the inductor IC property depends on whether the bias point is calculated or the calculation is skipped (see Fig. 7):



2.4 PN-JUNCTION DIODE

The PN-junction diode model is the PSpice model (see Massobrio, G. and Antognetti P.: Semiconductor Device Modeling with SPICE. McGraw-Hill 2 edition, 1998).
SPICELib diode model, PSPICE_diode, is composed of a linear resistor (of Rbreak class), a voltage dependent capacitor and a voltage controlled non linear current source (see Fig. 8).


Figure 8. Diode model.


2.4.1 Voltage-dependent capacitor

It extends the partial model Capacitor, defining the large-signal and the AC small-signal capacitance. The mathematical relationship between the large-signal capacitance of the diode, C, and the large signal voltage drop across the capacitor, v, is a two-branches function, that can be conveniently described using the modelica expresion if then else:

Cd(v) is a continuous, highly non-linear function of v (sum of several exponentila terms). In order to illustrate the shape of the C-V characteristic of the C-V characteristic, the C-V curve of D1N4002 diode is represented in Fig. 9.


Figure 9. C-V characteristic of D1N4002.


2.4.2 Voltage-controlled current source

The static and large-signal constitutive relation of the source are:

In Figure 10 the I-V characteristic of diode D1N4002 is shown.

Figure 10. I-V characteristic of D1N4002.


2.5 LEVEL1 N-CHANNEL MOSFET

SPICELib N-MOS model, SPICE2_MOS1, is composed of linear resistors (of Rbreak class), voltage dependent capacitors and voltage controlled non linear current sources (see Fig. 11).


Figure 11. N-MOS model.


The drain-to-source current (Ids) and the gate capacitances (CGB, CGS and CGD) are function of the variables VDS, VGS and VBS. However, VGS and VBS cannot be calculated form the terminal variables of the IDS) source model (i. e., the voltage and current at their pins). Gate capacitors modeling presents a similar problem. This situation is solved in SPICELib defining the variables VDS, VGS and VBS as inner variables of the transistor model, and as outer variables of its components: the IDS current source and the gate capacitors.
The variables are defined as follows:
VDS=noEvent(abs(CGS.v-CGD.v))
VGS=max(CGS.v, CGD.v)
VBS=max(CBS.v, CBD.v)
C.v represents the voltage drop across the capacitor C. As all terms C.v are state-variables of the large signal MOSFET model, these definitions tear the computational-casuality loops of the MOSFET large-signal description.

2.5.1 IDS current source

Drain-to source current is described by Eq. (1) when the transistor is in the linear region and by Eq. (2) when it is in the saturation region. Equations (1) y (2) are valid for VDS>0 (normal mode). For VDS lower than 0 (inverted mode), SPICELib switches the source and drain in equations (1) and (2).

2.5.2 Gate capacitances

The three gate capacitances (i.e. CGB, CGS and CGD) are nonlinear, continuous functions of VGS. In addition, CGS and CGD are functions of VDS when the transistor operates in the linear region.
For VDS<0 (inverted mode), SPICELib switches the source and drain in the capacitance calculation. The transition between CGS and CGD at VDS=0 is discontinuous in the SPICE2 model. In SPICELib a continuous link between CGS and CGD in the vicinity of VDS=0 has been introduced.

2.6 LEVEL1 P-CHANNEL MOSFET

SPICELib P-MOS model, SPICE2_MOS1P, is composed of linear resistors (of Rbreak class), voltage dependent capacitors and voltage controlled non linear current sources (see Fig. 11).


Figure 12. P-MOS model.


The drain-to-source current (Ids) and the gate capacitances (CBG, CSG and CDG) are function of the variables VSD, VSG and VSB. However, VSG and VSB cannot be calculated form the terminal variables of the ISD) source model (i. e., the voltage and current at their pins). Gate capacitors modeling presents a similar problem. This situation is solved in SPICELib defining the variables VSD, VSG and VSB as inner variables of the transistor model, and as outer variables of its components: the ISD current source and the gate capacitors.
The variables are defined as follows:
VSS=noEvent(abs(CSG.v-CDG.v))
VSG=max(CSG.v, CDG.v)
VSB=max(CSB.v, CDB.v)
C.v represents the voltage drop across the capacitor C. As all terms C.v are state-variables of the large signal MOSFET model, these definitions tear the computational-casuality loops of the MOSFET large-signal description.

2.6.1 ISD current source

Source-to-drain current is described by Eq. (3) when the transistor is in the linear region and by Eq. (4) when it is in the saturation region. Equations (3) y (4) are valid for VSD>0 (normal mode). For VSD lower than 0 (inverted mode), SPICELib switches drain and source in equations (3) and (4).

2.6.2 Gate capacitances

The three gate capacitances (i.e. CBG, CSG and CDG) are nonlinear, continuous functions of VSG. In addition, CSG and CDG are functions of VSD when the transistor operates in the linear region.
For VSD<0 (inverted mode), SPICELib switches the drain and source in the capacitance calculation. The transition between CSG and CDG at VSD=0 is discontinuous in the SPICE2 model. In SPICELib a continuous link between CSG and CDG in the vicinity of VSD=0 has been introduced.


2.7 INDEPENDENT SOURCES

There are a lot of similarities between the models of the voltage and the current independent sources: The characteristics in common are defined in the partial model Stimulus (SOURCE package), and the source models (i.e., VSource and ISource) inherit it.

Source model parameters allow defining the DC and AC characteristics of the source: DC_VALUE, AC_MAG and AC_PHASE. Time-dependent waveforms used in the transient analyses are defined in the WAVEFORM package: EXP, PULSE, PWL, CONST and SIN. The Stimulus model inherits the waveform model as a replaceable model. Therefore, the waveform model can be redeclared when instantiating the source model (no waveform is selected by default). Some examples are provided in Table 2.

Table 2. Examples of source instantiations.
DC and AC specifications SOURCE.VSource V1( DC_VALUE=3, AC_MAG=10, AC_PHASE=45 );
EXP waveform SOURCE.VSource V1( DC_VALUE=3, AC_MAG=10, AC_PHASE=45,
redeclare model TransientSpecification = WAVEFORMS.EXP( S1=1,S2=2,TD1=1,TC1=1, TD2=3,TC2=1 ));
PULSE waveform SOURCE.VSource V1( DC_VALUE=3, AC_MAG=10,
redeclare model TransientSpecification = WAVEFORMS.PULSE( S1=1,S2=2, TD=1,TR=1, PW=3,TF=1, PER=8 ));
PWL waveform SOURCE.VSource V1( DC_VALUE=3, AC_MAG=10, AC_PHASE=30,
redeclare model TransientSpecification = WAVEFORMS.PWL( signalCorners = { 1, 2, 4, 8, 16 }, timeCorners = { 0, 1, 2, 3, 4 } ));


2.7.1 DC analysis

The control signal ctrl_DC enables or disables the DC model (see Fig. 6):
Figure 8. Independent sources. Static model.


In order to set the source value when calculating the initial transient condition, a parameter is associated to each waveform model: TRANS_INITIAL. This parameter coincides with the waveform initial value.

The parameter ctrl_OP_value determines the source value during the static model solution: The parameter ctrl_OP_mode determines the mode of reaching the previous value: The "dynamic model ramping" algorithm requires the cancellation of the independent sources. The control signal ctrl_IS_inhibit allows this operation (see Fig. 7). While it is true:
Figure 8. Independent sources. Device models.


2.7.2 Transient analysis

The control signal ctrl_Tran determines (see Fig. 8): While ctrl_Tran==false, the source value is determined by the parameter ctrl_IS_TranOP:
Figure 9. Independent sources. Large-signal model.


2.7.3 AC small-signal analysis

While the control signal ctrl_AC is true, the AC small-signal value of the source is set according to the source parameters AC_MAG and AC_PHASE. Otherwise, the value is zero.

2.7.4 Model of the disabled formulations

It is important to notice that while a model formulation is not enabled, the correspondent values of the independent sources are zero. In this situation, the circuit node voltages are trivially calculated and the simulation computational effort is not unnecessarily increased. The control signals that enable each of the three formulations are: 2.7.5 Total power dissipation

The bias point calculation includes the evaluation of the total power dissipation. It is calculated adding the contribution of all the independent voltage sources. The calculation is implemented thanks to the Modelica capability of describing "physical fields". The PowerDisipation connector is defined. The model of the voltage source contains: The "environment" (inner) connector is defined in the BiasPointCalculation model.

3. ANALYSES

3.1 BIAS POINT CALCULATION

SPICELib provides four alternative algorithms for solving the circuit static model: The SOLVE_STATIC parameter determines which of the four algorithms to use.

Two control signals, internal to the analysis models, are defined to synchronize the bias point calculation with other analysis operations: The BiasPointCalculation model reads the value of biasPoint signal and writes biasPointCalculated.

Next, the four algorithms are briefly discussed. The control signal transitions required for algorithm completion are shown, but for the sake of clarity, their cause-effect relationships are omitted. Two additional comments: 3.1.1 Static model iteration (SOLVE_STATIC:=0)

The solution of the static problem is left in hands of the modelling environment. SPICELib has two symbols to provide an initial guess for Newton-Raphson algorithm: NODESET1 and NODESET2. The implementation of the algorithm is shown in Fig. 9.

Figure 10. Static model iteration algorithm.

3.1.2 Static model ramping (SOLVE_STATIC:=1)

This algorithm consists in ramping the static-formulation value of the independent sources from zero up to their target values. The clamping voltages of the IC symbols and the capacitor IC property are also adequately ramped. The value of the parameter TimeScale determines the length of the ramping. The algorithm is implemented by means of the signal transitions shown in Fig. 10.

Figure 11. Static model ramping algorithm.

3.1.3 GMIN stepping (SOLVE_STATIC:=2)

GMIN stepping attempts to find a solution for the static model (with power supplies at 100%) by starting with a large value of GMIN, initially 1.0e10 times the nominal value. If a solution is found at this setting, SPICELib reduces GMIN by a factor of 10 and tries again. This continues until either GMIN is back to the nominal value, or a repeating cycle fails to converge. This algorithm makes heavy use of equation continuity with respect to GMIN model parameters. The implementation of this algorithm is shown in Fig. 11.

Figure 12. GMIN stepping algorithm.

3.1.4 Dynamic model ramping (SOLVE_STATIC:=3)

The initial condition to iterate the static model is obtained by simulating the large-signal model. A transient analysis is performed: all sources are ramped up from zero to the desired initial value for the simulation and this value is held for some time to allow the circuit to stabilise. Then the large-signal formulation voltages are transferred to the static model (using ctrl_RBREAK_Tran2DC and ctrl_IS_inhibit). This static-circuit setting is held for a clock cycle. Then, the power supplies are connected to the circuit, the resistor voltage-clamping circuits are disconnected, and the static model is solved. The implementation of the algorithm is shown in Fig. 12.

Figure 13. Dynamic model ramping algorithm.

3.2 BIAS POINT ANALYSIS

The OP analysis (see Fig. 13):
Figure 14. OP analysis signals.

3.3 AC SWEEP ANALYSIS

The TYPE_AC_SWEEP parameter defines the frequency sweep type: AC small-signal analysis (see Fig. 14): When biasPointCalculated becomes true, the AC analysis: The simulation is finished one clock cycle after the frequency reaches END_FREQUENCY.
Figure 15. AC analysis signals.

3.4 TRANSIENT ANALYSIS

When the transient simulation is started, the value of the time variable is different of zero. For this reason, a variable is defined to measure the transient simulation time: TIME. The length of the transient simulation is set by the TSTOP parameter.

The transient analysis depends on the SKIP_INITIAL_TRAN_SOLUTION parameter (see Table 3).

Table 3. Transient analysis with and w/o initial calculation.
SKIP_INITIAL_TRAN_SOLUTION:=false When biasPointCalculated becomes true, the circuit static model contains the transient initial solution. Then (see Fig. 15):
  • ctrl_CBREAK_Tran2DC becomes true. The large-signal circuit state is initialised to the static-circuit voltage values.
  • ctrl_Tran becomes true. The large-signal device models are enabled.
The simulation terminates when timeTran reaches the value TRAN_STOP_TIME.
SKIP_INITIAL_TRAN_SOLUTION:=true At initial time (see Fig. 16):
  • ctrl_CBREAK_Tran2IC becomes true. The large-signal circuit state is initialised to the IC-property correspondent values.
  • ctrl_Tran becomes true. The large-signal device models are enabled.



Figure 16. Transient analysis with initial calculation.


Figure 17. Transient analysis without initial calculation.

NameDescription
ANALYSES  
BREAKOUT  
Rect2Polar  
Decibels  
Rad2Deg  
Deg2Rad  
INIT  
INTERFACE  
SOURCE  
SPECIAL  
WAVEFORMS  


SPICELib.src.Rect2Polar

Modelica definition

function Rect2Polar 
  input Real rect[2];
  output Real module;
  output nonSI.Angle_deg angle;
protected 
  SI.Angle angFirst;
  constant Real pi=3.14159265358979;
algorithm 
  module := sqrt(rect*rect);
  angFirst := if not module > 0 then 0 else arcsin(abs(rect[2])/module);
  angle := if rect[1] < 0 then pi - angFirst else angFirst;
  angle := if rect[2] < 0 then -angle else angle;
  angle := 180*angle/pi;
end Rect2Polar;

SPICELib.src.Decibels

Modelica definition

function Decibels 
  input Real x;
  output Real x_dB;
algorithm 
  x_dB := if x > 0 then 20*ln(x)/ln(10) else -1e-100;
end Decibels;

SPICELib.src.Rad2Deg

Modelica definition

function Rad2Deg 
  input SI.Angle angle_rad;
  output nonSI.Angle_deg angle_deg;
protected 
  constant Real pi=3.14159265358979;
algorithm 
  angle_deg := 180*angle_rad/pi;
end Rad2Deg;

SPICELib.src.Deg2Rad

Modelica definition

function Deg2Rad 
  input nonSI.Angle_deg angle_deg;
  output SI.Angle angle_rad;
protected 
  constant Real pi=3.14159265358979;
algorithm 
  angle_rad := pi*angle_deg/180;
end Deg2Rad;

HTML-documentation generated by Dymola Tue Oct 14 18:26:24 2003 .