SLiCAP basic tutorial¶

Abstract¶

Basic SLiCAP tutorial “my first RC network”, that demonstrates some basic functions of SLiCAP.

Contents¶

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

Install SLiCAP¶

1. Download the install script installSLiCAP.p and save it in your downloads folder.
2. Sart MATLAB and navigate to this download folder.
3. Type installSLiCAP() in the MATLAB Command Window and follow the instructions.
4. After SLiCAP has been installed, type “Help” (with capital “H”) in the MATLAB Command Window. This should open the html help file in the MATLAB browser.
5. Read the Introduction so you know what you can expect from SLiCAP!

Install and configure LTspice for schematic capture¶

If you want to use LTspice as schematic capture program you also need to install and/or configure LTspice as schematic capture program for SLiCAP. To this end you need to:

1. Install the latest version of LTspice

2. Start LTspice

3. On the menu bar click Tools > Control Panel. This will bring up the LTspice control panel:

   

4. On this control panel select the Netlist Options tab and select the options as shown below:

   

5. Then select the Sym. & Lib. Search Paths tab and enter the full path to the “LTspice” subdirectory of your SLiCAP install path. This directory contains all the SLiCAP symbol definitions (*.asy files) for LTspice:

   

6. Then select the Drafting Options tab and change the font size and deselect the “Bold” checkbox as shown below. If you want, you can also select different colors for your schematics.

   

Create a project directory and a project m-file¶

In this first tutorial, we will create a SLiCAP project to evaluate, design and plot the behavior of a simple RC network. In this example we will use LTspice for creating the schematic of the network.

1. Create a directory that will contain all the files of a SLiCAP project. During this tutorial we will expect that this project directory is: ~/DATA/SLiCAP/Tutorial/myFirstProject.

2. Navigate in MATLAB to this directory and create an m-file myFirstRCproject.m with the following contents:

   clear all;                                              % this will clear the work space
   initProject('myFirstRCproject', mfilename('fullpath')); % this will initialize the project
   stophtml();                                             % this properly closes the project html index page
   

   copy code

3. Run this m-file. The result is shown in the MATLAB workspace:

   

   SLiCAP created a subdirectory structure for your project. The html tree will contain all html output of the project. The file index.html is the project’s main index file.

   The rst tree contains restructured text files and configuration and style files for python sphinx documentation package. We will not use these files in this tutorial.

   SLiCAP also creates two files that contain project information for MATLAB (slicap.p) and the Symbolic Math Toolbox MuPAD (slicap.mu).

Draw the circuit in LTspice¶

Knowledge of drawing circuits with LTspice is assumed.

1. Open LTspice and select File > New Schematic from the menu bar. Place a component on the schematic by clicking the AND gate symbol on the tool bar or by pressing the “F2” key (default Hot Keys setting). This will bring up the Select Component Symbol menu. On this menu select the directory with the SLiCAP symbols from Top Directory drop-down select box, as shown below:

   

   All SLiCAP symbol names start with “SL”!

2. Place an independent voltage source “SLV”, a resistor “SLR” and a capacitor “SLC” and create the circuit depicted below:

   

   Please note:

   1. The node of interconnection of the resistor and the capacitor is labeled as out. Later we need to refer to this node. SLiCAP will name the voltage at this node V_out.
   2. A default ground symbol (node 0) has been used.
   3. The use of the spice directive .param: it defines symbolic or numeric values of parameters.

3. Save the circuit myFirstRCnetwork.asc in the project directory.

4. If you want to display the circuit on a SLiCAP output html page, you need to create an image file of it that can be rendered by a browser. A .png file is a good candidate. You can generate a PNG from a screen dump with a graphic file editor (Paint, Gimp, Photoshop, etc.). Here we assume that the graphic file myFirstRCnetwork_asc.png has been saved in the project directory. It is shown above.

Create the netlist¶

SLiCAP can create a netlist from within the MATLAB working environment. To this end MATLAB will run the LTspice netlister in batch mode.

If automatic generation of the netlist fails, please check the following:

1. The library configuration in LTspice should be set as described in the section above
2. The location of the LTspice executable in the file LTspiceNetlist.m in the MATLAB subdirectory in the SLiCAP install path must be set correctly. You can edit LTspiceNetlist.m and change the location as desired.

We will now create an m-file that will generate the netlist, check the circuit and display the circuit, its netlist, its elements and its parameter definitions on a web page.

1. Create an m-file myFirstRCnetwork.m in the project directory:

   fileName = 'myFirstRCnetwork';         % file name without extension assigned to the variable: "fileName"
   makeNetlist(fileName);                 % This will create a netlist running LTspice in batch mode
   

If the above script does not work, you have to create a .cir file from the LTspice schematics manually. The way to do this is described below.

Check and display the circuit in SLiCAP¶

We will now check the circuit and display the circuit, its netlist, its elements and its parameter definitions on a web page.

1. Edit myFirstRCnetwork.m that you created in the previous step:

   fileName = 'myFirstRCnetwork';         % file name without extension assigned to the variable: "fileName"
   %makeNetlist(fileName);                % Uncomment this line if netlist generation from within the MATLAB environment
                                          % yields no errors, otherwise create the netlist file manually!
   checkCircuit(fileName);                % This check the netlist and creates the MNA equation of the circuit
   htmlPage('Circuit data');              % This creates a web page with the circuit data
   head2html('Circuit diagram');          % Places a header (level 2) on the web page
   img2html([fileName, '_asc.png'], 369); % This places the picture of the circuit on the web page (width=369px)
   netlist2html(fileName);                % This places the netlist on the web page
   elementData2html();                    % This places all the properties of all the network elements on the web page
   params2html();                         % This lists the symbolic and numeric values of all network parameters on the web page
   %
   % Here, we will insert instructions later
   %
   stophtml();                            % This closes the active html page
   

   copy code

2. Update the project file to execute myFirstRCnetwork.m. The project file myFirstRCproject.m is updated to:

   clear all;                                              % this will clear the work space
   initProject('myFirstRCproject', mfilename('fullpath')); % this will initialize the project
   myFirstRCnetwork();                                     % this executes the m-file: "myFirstRCnetwork.m"
   stophtml();                                             % this properly closes the project html index page
   

   copy code

3. Run the project file by typing “myFirstRCproject()” in the MATLAB Command Window.

   Below an overview of the files generated after running the project:

   
   • The index.html page is the project’s index page. It links to circuit index pages that have links to the output pages generated for each circuit. Here the only circuit index page is:
     • myFirstRCnetwork_index.html that comprises the links to:
       • myFirstRCnetwork_log.html , a log page that was generated during the checking of the circuit. This page contains error messages and debug information.
       • myFirstRCnetwork_Circuit data.html, the page with circuit data that was generated through the execution of myFirstRCproject.m.
       • Other pages that are generated by running the complete tutorial.

   Please note: numeric parameter values are obtained through recursive substitution of all parameter definitions in expressions in the element of parameter definition.

Obtain the MNA equation and display it on an html page¶

We will now obtain the MNA (Modified Nodal Analysis) matrix equation and display it on an html page.

1. We will insert a few instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % obtain the symbolic MNA matrix equation of the network %
   %
   simType('symbolic');                   % Set the simulation type to 'symbolic'
   gainType('vi');                        % Set the gain type to 'vi' (calculation of voltages or current using Cramer's rule)
   dataType('matrix');                    % Set the data type to 'matrix', this is the type of output data we want
   MNA = execute();                       % Assign the matrix equation (execution result) to the variable MNA
   htmlPage('Matrix equations');          % Create a html page to display the matrix equation
   matrices2html(MNA);                    % Put the matrix equation on this page
   

   copy code

2. Run the project file again. The matrix equation is displayed on the new html page: myFirstRCnetwork_Matrix equations.html. The instruction matrices2html() also displays a note above the equation. Just ignore it for now!

   Please note:

   • The names of the dependent variables (node voltages and branch current of current-controlled elements):
     • Nodal voltages obtain the name V_<nodeName> and will be displayed as \(V_{<nodeName>}\)
     • Branch currents obtain the name I_<vSourceName> and will be displayed as \(I_{<vSourceName>}\)

3. The MATLAB variable MNA now contains the vector with independent variables, the MNA matrix and the vector with dependent variables. The structure of the execution result is described in the html help file. To view this structure insert a the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file.

   htmlPage('Matrix equation variables');  % Create a new html page to display the separate variables of the matrix equation
   MNA_vars = MNA.results(1);              % MNA variables
   I_v = MNA_vars(1);                      % Vector with independent variables
   M   = MNA_vars(2);                      % Matrix
   D_v = MNA_vars(3);                      % Vector with independent variables
   % Display text (including LaTeX) on the active html page.
   text2html('The vector $I_v$ with the independent variables equals:');
   % Display an equation on the active html page.
   eqn2html(sym('I_v'), I_v);
   text2html('The matrix $M$ equals:');
   eqn2html(sym('M'), M);
   text2html('The vector $D_v$ with the dependent variables equals:');
   eqn2html(sym('D_v'), D_v);
   

   copy code

   The new variables are shown in the MATLAB workspace and on the new html page myFirstRCnetwork_Matrix equation variables.html.

Obtain the Laplace Transform of the transfer¶

We will now obtain a symbolic expression for the transfer from the source to the detector. The voltage source V1 will be assigned as signal source and the voltage at node out (with respect to ground) as detector voltage.

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Obtain the Laplace Transform of the source-to-detector transfer of the network
   %
   source('V1');            % The independent source 'V1' is assigned as signal source
   detector('V_out');       % The voltage between node 'out' and node '0' is assigned as detector voltage
   gainType('gain');        % The gain from source to load is the desired transfer
   dataType('laplace');     % The Laplace Transform is the data we need
                            % Note: the simulation type is still 'symbolic', we didn't change it
   gainLaplace = execute(); % The execution result (structured array) is assigned to the variable 'gainLaplace'
                            % We will unpack the structured array since we only need the expression:
   gainLaplaceExpr = gainLaplace.results(1);
   htmlPage('Laplace Transform');                                % Create a new html page.
   head2html('Laplace transform of the gain');                   % Put a heading on it
   text2html('The Laplace Transform of the gain is found as:');  % Put some text on the page
   syms('V_out', 'V_1');                                         % Define symbolic variables for the left hand side of the equation
   eqn2html(V_out/V_1, gainLaplaceExpr);                         % Place the equation on the page.
   

   copy code

2. Run the project file and open the html page with the Laplace expression.

Plot the magnitude, phase and delay characteristics¶

Plotting requires numeric analysis. SLiCAP has many built-in plot routines. We will plot the magnitude, the phase and the delay characteristics of the gain.

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Obtain the numeric Laplace Transform of the source-to-detector transfer of the network
   %
   simType('numeric');  % Set the simulation type to numeric.
   %
   % Data type is still 'laplace' which is required for plotting frequency characteristics
   % Source, detector and gain type have already been defined.
   gainLaplaceNumeric = execute();
   % Create MATLAB figure objects, later we will place them on an html page.
   figMag   = plotMag('Magnitude plot of the gain', gainLaplaceNumeric, 10, 1e5, 100);
   figdBmag = plotdBmag('dB Magnitude plot of the gain', gainLaplaceNumeric, 10, 1e5, 100);
   figPhase = plotPhase('Phase plot of the gain', gainLaplaceNumeric, 10, 1e5, 100);
   figDelay = plotDelay('Group delay of the gain', gainLaplaceNumeric, 10, 1e5, 100);
   

   copy code

2. Run the project file and the plots will be displayed.

Place the plots on an html page¶

You can also include the plots in the html output. By doing so, the plots will not be displayed in the MATLAB work space.

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Display the plots on an html page
   %
   htmlPage('Plots of the gain');          % Create a new html page
   fig2html(figMag, 'figMag.svg', 800)     % save figMag as figMag.svg in the 'html/figures' subdirectory
                                           % and place it on the page with a width of 800px
   fig2html(figdBmag, 'figdBmag.svg', 800) % As above, but now for figdBmag
   fig2html(figPhase, 'figPhase.svg', 800) % As above, but now for figPhase
   fig2html(figDelay, 'figDelay.svg', 800) % As above, but now for figDelay
   

   copy code

2. Run the project file and open the html page with the plots.

Calculate and plot the poles and zeros of the gain¶

SLiCAP can calculate the poles and zeros of a network numerically. Although this is not very exciting for this simple RC network, we will demonstrate the procedure, so you will be able to apply it for more complicated networks.

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Calculate the DC gain, the poles and the zeros of the gain using data type 'pz', simulation type 'numeric' and gain type 'gain'.
   % The latter two have already been defined correctly.
   dataType('pz');                   % Define the data type for pole-zero analysis
   gainPolesZeros = execute();       % Calculate the DC gain, the poles and the zeros
   listPZ(gainPolesZeros);           % Display the results in the MATLAB Command Window
   htmlPage('Pole-zero analysis');   % Create an html page for displaying the results
   pz2html(gainPolesZeros);          % Display the results on the html page.
   % Generate the plot: x-axis: -1900...100Hz, y-axis: -1000...1000Hz.
   figPZ = plotPZ('Pole-zero plot', gainPolesZeros, [-1900, 100], [-1000, 1000]);
   head2html('Plot');                % Put a heading on the page
   fig2html(figPZ, 'figPZ.svg', 600);% Place the figure on the html page
   

   copy code

2. Run the project file and open the html page with the DC gain, the poles and the zeros.

3. If you want the obtain values of the DC gain, the poles and the zeros for further processing, you need to unpack the structured array ‘gainPolesZeros’. The structure of the execution result is described in the html help file.

4. data type ‘pz’ calculates poles and zeros and cancels poles and zeros that have the same frequency. If you also want to display non-observable poles, use data type ‘pols’ for calculation of the poles and data type ‘zeros’ for calculation of the zeros.

5. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Calculate the poles and the zeros of the gain using data type 'poles', simulation type 'numeric' and gain type 'gain'.
   % The latter two have already been defined correctly.
   dataType('poles');                           % Define the data type for pole analysis
   gainPoles = execute();                       % Calculate the poles
   htmlPage('Separate pole and zero analysis'); % Create an html page for displaying the results
   pz2html(gainPoles);                          % Display the results on the html page.
   dataType('zeros');                           % Define the data type for zero analysis
   gainZeros = execute();                       % Calculate the zeros
   pz2html(gainZeros);                          % Display the results on the html page.
   

   copy code

6. Run the project file and open the html page with the poles and the zeros.

Calculate and plot the unit impulse response of the gain¶

Determination of symbolic expressions for the unit impulse response h(t) (Inverse Laplace Transform) and the unit step response a(t), requires symbolic pole-zero analysis. SLiCAP can perform such analysis for relatively simple circuits only (low-order).

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Calculate the unit impulse response of the gain.
   simType('symbolic');                        % Symbolic simulation
   dataType('impulse');                        % Calculate the unit impulse response of the gain (gain type has already been set)
   gainImpulse = execute();                    % Assign the execution result to the variable 'gainImpulse'
   gainImpulseExpr = gainImpulse.results(1);   % Unpack the execution result and assign the expression to 'gainImpulseExpr'
   htmlPage('Unit impulse response');          % Start a new html page
   head2html('Symbolic expression');           % Put a heading on it
   syms('h(t)');                               % Define the left hand side of the equation
   eqn2html(h(t), gainImpulseExpr);            % Write the equation to the html page
   % generate the plot of h(t)
   simType('numeric');                         % This requires numeric simulation
   figImpulse = plotTime('Impulse response', execute(), 0, 1e-3, 100); % Make the time-domain plot
   head2html('Plot');                          % Put a heading on the page
   fig2html(figImpulse, 'figImpulse.svg', 800);% Put the plot on the page
   

   copy code

2. Run the project file and open the html page with the unit impulse response.

Calculate and plot the unit step response of the gain¶

Determination of symbolic expressions for the unit impulse response h(t) (Inverse Laplace Transform) and the unit step response a(t), requires symbolic pole-zero analysis. SLiCAP can perform such analysis for relatively simple circuits only (low-order).

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Calculate the unit step response of the gain.
   simType('symbolic');                        % Symbolic simulation
   dataType('step');                           % Calculate the unit impulse response of the gain (gain type has already been set)
   gainStep= execute();                        % Assign the execution result to the variable 'gainStep'
   gainStepExpr = gainStep.results(1);         % Unpack the execution result and assign the expression to 'gainStepExpr'
   htmlPage('Unit step response');             % Start a new html page
   head2html('Symbolic expression');           % Put a heading on it
   syms('a(t)');                               % Define the left hand side of the equation
   eqn2html(a(t), gainStepExpr);               % Write the equation to the html page
   % generate the plot of h(t)
   simType('numeric');                         % This requires numeric simulation
   figStep = plotTime('Step response', execute(), 0, 1e-3, 100); % Make the time-domain plot
   head2html('Plot');                       % Put a heading on the page
   fig2html(figStep, 'figStep.svg', 800);      % Put the plot on the page
   

   copy code

2. Run the project file and open the html page with the unit step response.

Set up and solve component design equations¶

SLiCAP can be used for deriving and solving design equations for analog circuits. We will demonstrate this for a simple case. We will determine requirements for the component values of this RC network, such that it settles to an accuracy of $n$ bit within \(\tau_s\) seconds. To this end we need to determine the settling error \(\epsilon_s\) versus time and find a solution for \(\epsilon_s=2^{-n}\). The script below calculates the time-dependent relative settling error \(\epsilon_s(t)\). It then calculates the selttling time by solving \(t\) from \(\epsilon_s=2^{-n}\).

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Calculate the settling error as a function of time.
   syms('n', 't', 'epsilon_s', 'tau_s');       % Define symbolic variables
   eps = 1-gainStepExpr;                       % Calculate the relative settling error
   taus = solve(eps-2^-n, t);                  % Calculate the settling time
   htmlPage('Settling time');                  % Start a html page
   head2html('Settling time to n-bits');       % Put a heading on it
   % Put some text on the page and write the equations on the page
   text2html('The relative settling error versus time can be founs as:');
   eqn2html(epsilon_s, eps);
   text2html('The settling time to $n$ bit can be found as the solution of:');
   eqn2html(epsilon_s, 2^-n);
   text2html('This yields:');
   eqn2html(tau_s, taus);
   

   copy code

2. We will now express the resistance \(R\) in the capacitance \(C\), and vice versa for a settling time of \(\tau_s\) s to an accuracy of \(n\) bit. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Derive the design equations for the resistance R and the capacitance C of the network
   % for settling to n bit within tau_s seconds.
   syms('R', 'C');
   Rsol = solve(taus-tau_s, R);                % Symbolic design equation for the resistance
   Csol = solve(taus-tau_s, C);                % Symbolic design equation for the capacitance
   head2html('Component design equations');    % Put a heading on the page
   % Put some text on the page and write the equations on the page
   text2html(['The resistance $R$ can be written as a function of the capacitance ', ...
       '$C$ and the settling time $\\tau_s$ to $n$ bit:']);
   eqn2html(R, Rsol);
   text2html(['The capacitance $C$ can be written as a function of the resistance ', ...
       '$R$ and the settling time $\\tau_s$ to $n$ bit:']);
   eqn2html(C, Csol);
   

   copy code

3. We will now determine a numeric value for the resistance \(R\) for \(n=10\), \(C=10\) pF and \(\tau_s=100\) ns. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Determine the value of the resistance, given the capacitance and the settling time to 10 bit.
   % Substitute numeric values for C, tau_s and n in the expression for Rsol
   Rnum = subs(Rsol, [C, tau_s, n], [10e-12, 100e-9, 10]);
   head2html('Numeric example');               % Put a heading on the page and display text with the result
   text2html(['For a settling time of 100ns to 10bit, with a capacitance of 10pF, we need a resistance of: ', ...
       num2str(double(Rnum)), '$\\Omega$']);
   

   copy code

4. Run the project file and open the html page with the design equations.

Write the script to an html page¶

SLiCAP can write a script to a separate html file.

1. We will insert the following instructions above the stophtml() instruction in the myFirstRCnetwork.m script file:

   % Write the complete script to an html file
   % This writes the script to an html page and places a link on the circuit's index page.
   script2html('myFirstRCnetwork');
   

   copy code

2. Run the project and view the complete output index.html.