Troubleshoot a SPICE Conversion of an IGBT Subcircuit

This example shows how to troubleshoot the conversion of a SPICE insulated gate bipolar transistor (IGBT) subcircuit and convert it into an equivalent Simscape™ component. The subcircuit2ssc function converts all the subcircuit components inside a SPICE netlist file into one or more equivalent Simscape files. However, in some cases, you must manually edit the original SPICE netlist.

Open the IGBT Subcircuit

In this example, you will convert this IGBT to a Simscape component, add it to a model, and simulate the model. The IGBT subcircuit combines the bipolar junction transistor (BJT) and SPICE Level 1 metal-oxide-semiconductor field-effect transistor (MOSFET) models and equations with a drain-gate capacitance model. To open the SPICE netlist, in the MATLAB command window, enter edit ee_igbt_subckt_original.cir.

% Display ee_igbt_subckt_original.cir
type('ee_igbt_subckt_original.cir')

% Create a temporary directory and change present working directory
ee_igbt_subckt_temporary_directory;

% Create a subdirectory called +myIGBT
if ~exist('+myIGBT', 'dir')
    mkdir('+myIGBT')
end
* Fast and accurate SPICE IGBT model

.SUBCKT IGBTMODEL C G 0
.FUNC WDSJ(X1,X2) {SQRT(12.422*{ESI}*VDS(X1)/(X2))}
.FUNC VDS(X) {SQRT(X^2+0.01^2)/2}
M1 N1 N2 0 0 MOSN
RG G N2 {5.7-7M*(125-TEMP)} 
Q1 0 N1 C BJTP
CGDOX N3 N2 0.1N
VICGDOX N1 N3 0
GCGD N1 N2
+VALUE = {(COXD*AGD*ESI/(WDSJ(V(N1,N2),{NB})*COXD+AGD*ESI))*I(VICGDOX)}

.PARAM TEMP=25
.PARAM AGD=50 ESI=1.0359 NB=2 COXD=175 VTO={4+7M*(125-TEMP)}
.MODEL MOSN NMOS (IS=20N KP=20 VTO={VTO} RD=0.5M CGSO=160U)
.MODEL BJTP PNP (BF=0.26 TF=1.5U CJC=0.6N RE=1M BR=0.44 IS=2E-15 NF=2 XTI=6 XTB=5)

.ENDS IGBTMODEL

Modify the IGBT SPICE Subcircuit

Not all SPICE subcircuits can be directly converted with the subcircuit2ssc function. If you run the subcircuit2ssc conversion directly on this file you will receive the following error:

"Error using spiceSubckt/extractSubcktDefinitionStrings (line 1182)"
"Connecting public nodes to ground is illegal."
"Error in spiceSubckt/loadSubckt (line 379)"
                "this.extractSubcktDefinitionStrings; % parse the subckt line"
"Error in spiceSubckt (line 69)"
                "this.loadSubckt(fullNetlist); % populate the object properties"
"Error in subcircuit2ssc (line 55)"
    "subcircuitArray(ii) = spiceSubckt(file,subcctName(ii));"
"Error in subcircuit2ssc (line 31)"
        "subcircuit2ssc(netlist,target);"

The conversion generates an error because the SPICE subcircuit connected a public node directly to node 0. In SPICE, node 0 is ground. To resolve the error, update the SPICE netlist file by renaming node 0 to node E.

If you now run subcircuit2ssc and then ssc_build you will receive the following error:

"Failed to generate 'myIGBT_lib'"
"Caused by:"
    "Error using ne_parselibrarypackage (line 66)"
    "Error: Class member redefinition has been found:"
        "Error using myIGBT.igbtmodel> (line 22)"
        "Class member 'temp' is defined."
        "Error using myIGBT.igbtmodel> (line 31)"
        "Class member 'temp' is defined."

The build generates an error because the SPICE subcircuit includes the definition of a local parameter named TEMP which is a reserved SPICE variable name for global temperature. To resolve the error and use the global temperature, remove the local parameter definition of TEMP from the SPICE library file. Alternatively, if you want to specify a local temperature, choose a name other than TEMP for the local parameter.

Save the changes into a new file named ee_igbt_subckt_modified.cir.

% Display ee_igbt_subckt_modified.cir
type('ee_igbt_subckt_modified.cir')
* Fast and accurate SPICE IGBT model

.SUBCKT IGBTMODEL C G E
.FUNC WDSJ(X1,X2) {SQRT(12.422*{ESI}*VDS(X1)/(X2))}
.FUNC VDS(X) {SQRT(X^2+0.01^2)/2}
M1 N1 N2 E E MOSN
RG G N2 {5.7-7M*(125-TEMP)}
Q1 E N1 C BJTP
CGDOX N3 N2 0.1N
VICGDOX N1 N3 0
GCGD N1 N2
+VALUE = {(COXD*AGD*ESI/(WDSJ(V(N1,N2),{NB})*COXD+AGD*ESI))*I(VICGDOX)}

.PARAM AGD=50 ESI=1.0359 NB=2 COXD=175 VTO={4+7M*(125-TEMP)}
.MODEL MOSN NMOS (IS=20N KP=20 VTO={VTO} RD=0.5M CGSO=160U)
.MODEL BJTP PNP (BF=0.26 TF=1.5U CJC=0.6N RE=1M BR=0.44 IS=2E-15 NF=2 XTI=6 XTB=5)

.ENDS IGBTMODEL

To see the differences between the two files, in the MATLAB command window, enter visdiff('ee_igbt_subckt_original.cir','ee_igbt_subckt_modified.cir').

Run this command to convert the SPICE subcircuit of the ee_igbt_subckt_modified.cir model to a Simscape component and place the generated files in the newly created directory called +myIGBT:

subcircuit2ssc('ee_igbt_subckt_modified.cir','+myIGBT')
Netlist converted. Review Simscape component files and make
manual edits for any unsupported items before building the
Simscape library located at:
+myIGBT.

Generate the Simscape library using the ssc_build function.

ssc_build myIGBT
Generating Simulink library 'myIGBT_lib' in the current directory '/tmp/Bdoc20a_1378877_157800/tp8fb497d5_3be9_4789_9a8e_4f31d48de7f1' ...

Open the Converted IGBT Model

The igbtmodel.ssc file stored in the +myIGBT directory is the converted Simscape component obtained by running the subcircuit2ssc function on the modified SPICE netlist. The subcircuit2ssc function also converted all the functions implemented in the SPICE subcircuit and stored them in a subdirectory named +igbtmodel_simscape_functions. To edit the generated simscape component, in the MATLAB command window, enter edit +myIGBT/igbtmodel.ssc.

open_system('ee_igbt_subckt')
set_param(find_system('ee_igbt_subckt','FindAll', 'on','type','annotation','Tag','ModelFeatures'),'Interpreter','off')

To adjust the Simscape global temperature, in the Environment Parameters block, modify the Temperature parameter.

Verify Simulation Results

The ee_igbt_subckt_verification script compares collector current versus collector-emitter voltage curves for a range of gate-emitter voltages with the SPICE netlist simulation results, which are stored in the ee_igbt_subckt_data.mat MAT-file. The gate-emitter voltages, Vge, are 8 V, 10 V, 12 V, 15 V, and 20 V. The Vce voltage sweeps from 0 V to 10 V.

ee_igbt_subckt_verification;

To plot these characteristics with different settings, double-click the block labeled Define Conditions (Vge and Vce) and define the vector of Vge and the minimum and maximum Vce voltages. In the model, to run the simulations and plot the results, click plot curves.

Clean Up

Finally, delete the temporary directory and all its subdirectories.

% Delete temporary directory
if exist('originalDirectory','var')
    cd (originalDirectory);
    rmdir(temporaryDirectory,'s')
    clear temporaryDirectory originalDirectory;
end