Work with SLiCAP parameters

A tutorial that demonstrates the use of parameters in the analysis of a simple CE-stage amplifier. You can read the documentation for more information on this topic.

  • You can download the (.zip) archive of this tutorial. In this tutorial we will create its content step-by-step.

Symbolic or numeric

It is not necessary to assign numeric values to parameters. In most cases, SLiCAP calculates symbolically, even if the simulation type is set to ‘numeric’. Setting the simulation type to ‘numeric’ implies that all parameter definitions will recursively be substituted into each other. Hence, if a parameter does not have a numeric value, it remains as a symbolic variable in expressions.

Current-driven, C-loaded CE-stage

We will use a current-driven and capacitively loaded CE-stage to illustrate the use of parameters in SLiCAP.

First we will define a project and a circuit. The way to do this has been described in this tutorial.

  1. Create a project directory for this tutorial.

  2. Create an m-file parameterTutorial.m that initializes the project in this directory.

    % Parameter tutorial
    % file: parameterTutorial.m
    %
    initProject('Parameter tutorial', mfilename('fullpath'));
    %
    CloadedCEstage();   % The file 'CloadedCEstage.m' needs to be created
    %
    stophtml();
    %
    

    copy file parameterTutorial.m

  3. Create a small-signal equivalent circuit of a current-driven, C-loaded CE-stage for SLiCAP, as depicted below; use LTspice for this purpose.

    ../../../_images/CloadedCEstage.png

    copy circuit file CloadedCEstage.asc

    This circuit is the small-signal equivalent diagram of a CE-stage, diven from the current source I1 and loaded with the capacitor C1. The capacitance of C1 is \(C_{\ell}\) (defined as C_ell). The base and collector nodes are labeled as ‘B’ and ‘C’, respectively. The emitter is taken as the ground node.

    The CE-stage is modeled with its hybrid-\(\pi\) equivalent circuit of which the current-dependency of the elements has been modeled in a simple way. The model equations have been given in the first .param directive on the schematic.

    \(g_m=\frac{qI_c}{kT}\), where Boltzmann’s constant \(k\), the charge of an electron \(q\), and the absolute temperature \(T\) are built-in parameters. For information on built-in parameters please read the documentation.

    \(r_{\pi}=\frac{\beta_{AC}}{g_m}\), where \(\beta_{AC}\) is the small-signal current gain of the transistor (assumed current-independent).

    \(c_{\pi}=C_{JE}+g_m \tau_F\), where \(C_{JE}\) is the base-emitter depletion capacitance and \(\tau_F\) is the forward transit time.

    \(r_o=\frac{V_{AF}}{I_c}\), where \(V_{AF}\) is the forward Early voltage.

    \(c_{\mu}=C_{JC}\), where \(C_{JC}\) is the base-collector depletion capacitance.

    Voltage dependencies of the circuit elements have not been modeled.

    The second .param directive defines the cut-off frequency of the transistor, we will use it in this tutorial:

    \(f_T=\frac{g_m}{2\pi(c_{\pi}+c_{\mu})}\).

    The last .param directive assigns numeric values to the parameters.

  4. Create the netlist, check the circuit and display the circuit data on an html page.

    The script file CloadedCEstage.txt shows the instructions. The html output file is CloadedCEstage_Circuit data.html.

Change and obtain parameter definitions

Instead of working with html output, many SLiCAP instructions have return values that can be displayed in the MATLAB Command Window. After you have run parameterTutorial.m, all circuit data is available in the MATLAB (Symbolic Math Toolbox) environment. Below we will demonstrate how to get this data to the MATLAB environment.

  1. Obtain a list of all circuit parameters by typing params() in the MATLAB Command Window:

    paramList = params();             % This assigns a list with parameter names to the variable 'paramList'.
    

    copy code

  2. Obtain the symbolic definition of a parameter by setting the simulation type to ‘symbolic’ and then using the function getParValue(<parameterName>).

    simType('symbolic');              % Set the simulation type to 'symbolic'.
    f_T = getParValue('f_T');         % Assign the symbolic definition of the circuit parameter 'f_T'.
                                      % to the MATLAB variable 'f_T'.
    beta_AC = getParValue('beta_AC'); % Assign the symbolic definition of the circuit parameter 'beta_AC'.
                                      % to the MATLAB variable 'beta_AC'.
    

    copy code

  3. Obtain the numeric value (the value after recursive substitution of all parameter definitions) by setting the simulation type to ‘numeric’ and then using the function getParValue(<parameterName>):

    simType('snumeric');              % Set the simulation type to 'numeric'.
    f_T = getParValue('f_T');         % Assign the numeric definition of the circuit parameter 'f_T'.
                                      % to the MATLAB variable 'f_T'.
    beta_AC = getParValue('beta_AC'); % Assign the numeric definition of the circuit parameter 'beta_AC'.
                                      % to the MATLAB variable 'beta_AC'.
    

    copy code

  4. Create a list with symbolic parameter definitions of which the indexes correspond with those of the corresponding parameter names:

    simType('symbolic');              % Set the simulation type to 'symbolic'
    pNames = params();                % Assign a list of parameter names to the MATLAB variable 'pNames'.
    pDefs = params();                 % Assign a list of parameter names to the MATLAB variable 'pDefs'.
                                      % These names will be replaced with the symbolic definitions.
    %
    % Replace the parameter names in pDefs with their definition:
    for i = 1:length(pNames)
     try:
       pDefs(i) = getParValue(pDefs(i));
     catch
     end
    end
    

    copy code

  5. Create symbolic MATLAB variables that have the same name as circuit parameters:

    syms(params());                   % Create MATLAB variables with names
                                      % corresponding with those of circuit parameters
    

    copy code

  6. Delete the definition of a parameter (here we will delete the definition of ‘f_T’):

    delPar('f_T');                    % This only deletes the definition,
                                      % the parameter will still exist.
    

    copy code

  7. (Re)define a parameter:

    defPar('f_T', 'g_m/2/pi/(c_pi+c_mu)')    % This redefines the parameter 'f_T'.
    

    copy code

Parameter stepping

Parameter stepping is enabled with the instuction stepOn() and disabled with the instruction stepOff(). If disabled all step settings are preserved, only the execution of an analysis is performed without parameter stepping. SLiCAP supports the following step methods:

  • Linear stepping

    Linear stepping stepMethod('lin') requires the definition of a step variable, its start value, its stop value and the number of steps (the number of values is the number of steps plus one!):

    stepVar('I_C');      % Assign the collector current 'I_C" as step variable
    stepMethod('lin');   % Use linear stepping
    stepStart('10u');    % Start at I_C=10uA
    stepStop('1m');      % Stop st I_C=1mA
    stepNum('99');       % Take 100 values
    
  • Logarithmic stepping stepMethod('log') requires the definition of a step variable, its start value, its stop value and the number of steps (number of values = number of steps + 1). The stepping range cannot include zero.

    stepVar('I_C');      % Assign the collector current 'I_C" as step variable
    stepMethod('lin');   % Use logarithmic stepping
    stepStart('10u');    % Start at I_C=10uA
    stepStop('1m');      % Stop st I_C=1mA
    stepNum('99');       % Take 99 steps (100 values); this differs from spice
                         % spice uses the number of steps per decade
                         % SLiCAP uses the total number of steps
    
  • List stepping stepMethod('list') requires the definition of a step variable and a list of values:

    stepVar('I_C');      % Assign the collector current 'I_C" as step variable
    stepMethod('list');  % Use list stepping
    % Array with values of the step parameter:
    stepList([1e-6, 2e-6, 5e-6, 10e-6, 20e-6, 50e-6, 100e-6]);
    
  • Array stepping of multiple parameters stepMethod('array') requires the definition of a character array with step parameters and a matrix with values. Each row of this matrix holds the values of all step parameters for one run:

    stepVars({'I_C', 'C_JE', 'tau_F'});  % Step variables that will be stepped concurrently
    stepMethod('array');                 % Use array stepping
    % Array with values of the step parameters,
    % each row carries the parameter values for one run,
    % each column carries the values of a particular parameter for all runs.
    stepArray([10e-6 2e-12 1e-9; 100e-6 1.8e-12 1.1e-9; 1e-3 1.5e-12 1.5e-9]);
    

Plot parameters against each other

The first application of stepping involves the plotting of parameters against each other, a technique that can be helpful for defining model equations in such a way that they sufficienly accurate fit to measurement data or to data obtained from other simulators. The following script will plot the \(f_T(I_C)\) curve of the transistor in this tutorial. Insert this code just above the ‘stophtml()’ instruction in the script file CloadedCEstage.m:

simType('numeric');                         % Set the simulation type to 'numeric'.
                                            % because we want to make a plot.
stepVar('I_C');                             % Define the independent variable 'IC'.
                                            % as step variable.
stepStart('10u');                           % Start at I_C=10uA.
stepStop('10m');                            % Stop at I_C=10mA.
stepNum(100);                               % Take 100 steps for a smooth plot.
stepMethod('log');                          % Use logarithmic stepping.
stepOn();                                   % Enable stepping.
paramData = getStepParams({'I_C', 'f_T'});  % Get the step values of 'I_C' and 'f_T'.
%
% There is not (yet) a simple plot function for parameter plotting,
% use standard MATLAB code instead.
%
f_T_I_C = figure();                         % Create a MATLAB figure object.
loglog(paramData.I_C, paramData.f_T);       % Plot x=I_C and y=f_T on log-log scale.
xlabel('I_C');                              % Add the x-axis label.
ylabel('f_T');                              % Add the y-axis label.
title('f_T versus I_C');                    % Put a title on the axis.
legend('f_T(I_C)');                         % Add a legend to the axis

copy code

The figure below shows the \(f_T(I_C)\) curve of this transistor according to this simple model.

../../../_images/f_T_I_C.svg

You can place this plot on a separate html page (‘Parameter plot’) by adding the following lines just above the ‘stophtml()’ instruction in the script file CloadedCEstage.m:

%
htmlPage('Parameter plot');                 % Start a new html page.
head2html('f_T versus I_C');                % Put a heading on the html page.
fig2html(f_T_I_C, 'f_T_I_C.svg', 500);      % Put the plot on the html page.

copy code

The generated html page is CloadedCEstage_Parameter plot.html.

Stepped execution of instructions

We will now demonstrate the execution of an instruction with parameter stepping. We will do this by calculating the DC value and the poles and zeros of the transimpedance gain of the capacitively loaded CE-stage as a function of different combinations of \(I_C\), \(C_{JE}\) and \(\tau_F\). We will use array stepping. Please insert the script below just above the ‘stophtml()’ instruction in the script file CloadedCEstage.m:

%
% Stepped pole-zero analysis of the transimpedance gain
% of the C-loaded CE-stage.
%
simType('numeric');
gainType('gain');
source('I1');
detector('V_C');
dataType('pz');
%
stepVars({'I_C', 'C_JE', 'tau_F'}); % Step variables that will be stepped concurrently
stepMethod('array');                % Use array stepping
% Array with values of the step parameters,
% each row carries the parameter values for one run,
% each column carries the values of a particular parameter for all runs.
stepArray([10e-6 2e-12 1e-9; 100e-6 1.8e-12 1.1e-9; 1e-3 1.5e-12 1.5e-9]);
htmlPage('Transimpedance PZ analysis');
pz2html(execute);

copy code

The html page CloadedCEstage_Transimpedance PZ analysis.thml shows the results.

Plotting of stepped execution results

Array stepping

Plots with array stepping slightly differ from plots with other stepping methods:

  • The legend shows run numbers instead of values of the step variable.
  • Array stepping uses ‘x’ and ‘o’ as symbols for poles and zeros, respectively. Other step methods use ‘.’ instead.

We will now plot the poles and the zeros of the transimpedance gain using array stepping as defined in the example above (multiple-run plotting with data type ‘pz’ (yet) supported); we will use ‘poles’ and ‘zeros’ separately. Please insert the script below just above the ‘stophtml()’ instruction in the script file CloadedCEstage.m:

%
htmlPage('Stepped PZ plots');
dataType('poles');
poleRuns = execute();
dataType('zeros');
zeroRuns = execute();
%
% You can combine multiple execution results in one plot
% You can use 'auto' for the x-scale and/or the y-scale
%
plotPZ('Poles and zeros of the transimpedance', [poleRuns, zeroRuns], 'auto', 'auto');
%
% We need to zoom in to see all the poles and zeros
%
zerosPlot = plotPZ('Zeros of the transimpedance', zeroRuns, [0, 15e9], 'auto');
fig2html(zerosPlot, 'zerosPlot.svg', 600);
polesPlot = plotPZ('Poles of the transimpedance', poleRuns, [-1e7, 0], 'auto');
fig2html(polesPlot, 'polesPlot.svg', 600);
dominantPolesPlot = plotPZ('Dominant poles of the transimpedance', poleRuns, [-60e3, 0], 'auto');
fig2html(dominantPolesPlot, 'dominantPolesPlot.svg', 600);

copy code

The html page CloadedCEstage_Stepped PZ plots.thml shows the results.

We will now plot the magnitude, the phase and the delay characteristics of the transimpedance gain with array stepping. Please insert the script below just above the ‘stophtml()’ instruction in the script file CloadedCEstage.m:

%
htmlPage('Frequency-domain plots');
dataType('laplace');
laplaceResult = execute();
magPlot   = plotMag('Magnitude transimpedance [Ohm]', laplaceResult, 1e3, 1e9, 100);
phasePlot = plotPhase('Phase transimpedance [deg]', laplaceResult, 1e3, 1e9, 100);
delayPlot = plotDelay('Delay transimpedance [s]', laplaceResult, 1e3, 1e9, 100);
fig2html(magPlot, 'magPlot.svg', 800);
fig2html(phasePlot, 'phasePlot.svg', 800);
fig2html(delayPlot, 'delayPlot.svg', 800);

copy code

The html page CloadedCEstage_Frequency-domain plots.html shows the results.

Lin log and list stepping - frequency-domain and time-domain plots

We will now demonstrate plotting of analysis results with linear stepping of one variable. Similar results are obtained with logarithmic or list stepping methods. First we will demonstrate frequency domain plotting with a small number of steps. Please insert the script below just above the ‘stophtml()’ instruction in the script file CloadedCEstage.m:

%
htmlPage('Frequency-domain plots step I_C');
stepVar('I_C');              % Use I_C as step variable
stepMethod('lin');           % Use linear stepping
stepStart('100u');           % Start at 100uA
stepStop('1m');              % Stop at 1mA
stepNum(9);                  % Take 9 steps (10 values)
laplaceResult = execute();
magPlot   = plotMag('Magnitude transimpedance [Ohm], step I_C', laplaceResult, 1e3, 1e9, 100);
phasePlot = plotPhase('Phase transimpedance [deg], step I_C', laplaceResult, 1e3, 1e9, 100);
delayPlot = plotDelay('Delay transimpedance [s], step I_C', laplaceResult, 1e3, 1e9, 100);
fig2html(magPlot, 'magPlot_IC.svg', 800);
fig2html(phasePlot, 'phasePlot_IC.svg', 800);
fig2html(delayPlot, 'delayPlot_IC.svg', 800);

copy code

The html page CloadedCEstage_Frequency-domain plots step I_C.html shows the results.

Time-domain plots behave similar as frequency-domain plots.

Lin log and list stepping - PZ plots

Root-locus plots can be generated through stepping of a root-locus variable. The step methos should be ‘lin’, ‘log’ or ‘list’. In the following script we will plot the dominant poles of the transimpedance gain of the C-loaded CE-stage, while stepping the collector current of the transistor linearly from 100uA to 1mA. Please insert the script below just above the ‘stophtml()’ instruction in the script file CloadedCEstage.m:

%
htmlPage('PZ plot step I_C');
dataType('poles');          % Plot the poles only
stepNum(49);                % Increase the number of points to 50
figPZ_IC = plotPZ('Transimpedance: dominant poles vs. I_C', execute(), [-60e3, 0], 'auto');
fig2html(figPZ_IC, 'fig_PZ_IC.svg', 600);

copy code

The html page CloadedCEstage_PZ plot step I_C.html shows the results.