ahkab.netlist_parser¶

Parse spice-like netlist files and generate circuits instances.

The syntax is explained in Netlist Syntax and it’s based on [2] whenever possible.

[2]	http://newton.ex.ac.uk/teaching/CDHW/Electronics2/userguide/

Introduction¶

This module has one main circuit that is expected to be useful to the end user: parse_circuit(), which encapsulates parsing a netlist file and returns the circuit, the simulation objects and the post-processing directives (such as plotting instructions).

Additionally, the module provides utility functions related to parsing, among which the end user may be interested in the convert() function, which allows converting from SPICE-like representations of floats, booleans and strings to their Python representations.

The last type of functions in the module are utility functions to go through the netlist files and remove comments.

Except for the aforementioned functions, the rest seem to be more suitable for developers than end users.

Overview¶

Function for parsing¶

`parse_circuit`(filename[, ...])	Parse a SPICE-like netlist
`main_netlist_parser`(circ, netlist_lines, ...)
`parse_elem_resistor`(line, circ)	Parses a resistor from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the resistor element.
`parse_elem_capacitor`(line, circ)	Parses a capacitor from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the capacitor element.
`parse_elem_inductor`(line, circ)	Parses a inductor from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the inductor element.
`parse_elem_inductor_coupling`(line, circ[, ...])	Parses a inductor coupling from the line supplied, returns a list holding the inductor coupling element.
`parse_elem_vsource`(line, circ)	Parses a voltage source from the line supplied, adds its nodes to the circuit instance and returns a list holding the element.
`parse_elem_isource`(line, circ)	Parses a current source from the line supplied, adds its nodes to the circuit instance and returns a list holding the current source element.
`parse_elem_diode`(line, circ[, models])	Parses a diode from the line supplied, adds its nodes to the circuit instance and returns a list holding the diode element.
`parse_elem_mos`(line, circ, models)	Parses a MOS transistor from the line supplied, adds its nodes to the circuit instance and returns a list holding the element.
`parse_elem_vcvs`(line, circ)	Parses a voltage-controlled voltage source (VCVS) from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the VCVS element.
`parse_elem_vccs`(line, circ)	Parses a voltage-controlled current source (VCCS) from the line supplied, adds its nodes to the circuit instance and returns a list holding the VCCS element.
`parse_elem_cccs`(line, circ)	Parses a current-controlled current source (CCCS) from the line supplied, adds its nodes to the circuit instance and returns a list holding the CCCS element.
`parse_elem_ccvs`(line, circ)	Parses a current-controlled voltage source (CCVS) from the line supplied, adds its nodes to the circuit instance and returns a list holding the CCVS element.
`parse_elem_switch`(line, circ[, models])	Parses a switch device from the line supplied, adds its nodes to the circuit instance and returns a list holding the switch element.
`parse_elem_user_defined`(line, circ)	Parses a user defined element.
`parse_models`(models_lines)
`parse_time_function`(ftype, line_elements, stype)	Parses a time function of type ftype from the line_elements supplied.
`parse_postproc`(circ, postproc_direc)
`parse_ics`(directives)
`parse_analysis`(circ, directives)	Parses the analyses.
`parse_single_analysis`(line)	Parses an analysis
`parse_temp_directive`(line)	Parses a TEMP directive:
`parse_param_value_from_string`(astr[, rtype, ...])	Search the string for a `<param>=<value>` couple and returns a list.
`parse_ic_directive`(line)	Parses an ic directive and assembles a dictionary accordingly.
`parse_sub_declaration`(subckt_lines)	Returns a circuit.subckt instance that holds the subckt information, ready to be instantiated/called.
`parse_sub_instance`(line, circ, subckts_dict)	Parses a subckt call/instance.
`parse_include_directive`(line, netlist_wd)	.include <filename> [*comments]

Utility functions for conversions¶

`convert`(astr, rtype[, raise_exception])	Convert a string to a different representation
`convert_units`(string_value)	Converts a value conforming to SPICE’s syntax to `float`.
`convert_boolean`(value)	Converts the following strings to a boolean:

Utility functions for file/txt handling¶

`join_lines`(fp, line)	Read the lines coming up in the file.
`is_valid_value_param_string`(astr)	Has the string a form like `<param_name>=<value>`?
`get_next_file_and_close_current`(file_list, ...)

Module reference¶

exception NetlistParseError[source]¶: Netlist parsing exception.

convert(astr, rtype, raise_exception=False)[source]¶

Convert a string to a different representation

Parameters:

astr : str: The string to be converted.
rtype : type: One among float, if a float sould be parsed from astr, bool, for parsing a boolean or str to get back a string (no parsing).
raise_exception : boolean, optional: Set this flag to True if you wish for this function to raise ValueError if parsing fails.

Returns:

ret : object: The parsed data.

convert_boolean(value)[source]¶

Converts the following strings to a boolean: yes, 1, true to True no, false, 0 to False

raises NetlistParserException

Returns: boolean

convert_units(string_value)[source]¶

Converts a value conforming to SPICE’s syntax to float.

Quote from the SPICE3 manual:

A number field may be an integer field (eg 12, -44), a floating point field (3.14159), either an integer or a floating point number followed by an integer exponent (1e-14, 2.65e3), or either an integer or a floating point number followed by one of the following scale factors:

T = 1e12, G = 1e9, Meg = 1e6, K = 1e3, mil = 25.4x1e-6, m = 1e-3, u = 1e-6, n = 1e-9, p = 1e-12, f = 1e-15

Raises:	ValueError – if the supplied string can’t be interpreted according

to the above.

Returns:

num : float: A float representation of string_value.

get_next_file_and_close_current(file_list, file_index)[source]¶

is_valid_value_param_string(astr)[source]¶

Has the string a form like <param_name>=<value>?

Note

No spaces.

Returns:

ans : a boolean: The answer to the above question.

join_lines(fp, line)[source]¶: Read the lines coming up in the file. Each line that starts with ‘+’ is added to the previous line (line continuation rule). When a line not starting with ‘+’ is found, the file is rolled back and the line is returned.

main_netlist_parser(circ, netlist_lines, subckts_dict, models)[source]¶

parse_analysis(circ, directives)[source]¶

Parses the analyses.

Parameters:

circ: circuit class instance: The circuit description
directives: list of tuples: The list should be assembled as (line, line_number).

Both of them are returned by parse_circuit()

Returns:

a list of the analyses

parse_circuit(filename, read_netlist_from_stdin=False)[source]¶

Parse a SPICE-like netlist

Directives are collected in lists and returned too, except for subcircuits, those are added to circuit.subckts_dict.

Returns:

(circuit_instance, analyses, plotting directives)

parse_elem_capacitor(line, circ)[source]¶

Parses a capacitor from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the capacitor element.

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit to which the capacitor is to be connected.

Returns:

elements_list : list: A list containing a ahkab.components.Capacitor element.

parse_elem_cccs(line, circ)[source]¶

Parses a current-controlled current source (CCCS) from the line supplied, adds its nodes to the circuit instance and returns a list holding the CCCS element.

Syntax:

FX N+ N- VNAME VALUE

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the CCCS is to be inserted.

Returns:

elements_list : list: A list containing a ahkab.components.sources.FISource element.

parse_elem_ccvs(line, circ)[source]¶

Parses a current-controlled voltage source (CCVS) from the line supplied, adds its nodes to the circuit instance and returns a list holding the CCVS element.

CCVS syntax:

HXXX N1 N2 VNAME VALUE

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the CCVS is to be inserted.

Returns:

elements_list : list: A list containing a ahkab.components.sources.HVSource element.

parse_elem_diode(line, circ, models=None)[source]¶

Parses a diode from the line supplied, adds its nodes to the circuit instance and returns a list holding the diode element.

Diode syntax:

DX N+ N- <MODEL_LABEL> <AREA=xxx>

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the diode will be inserted.

Returns:

elements_list : list: A list containing a ahkab.diode.Diode element.

parse_elem_inductor(line, circ)[source]¶

Parses a inductor from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the inductor element.

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit to which the inductor is to be connected.

Returns:

elements_list : list: A list containing a ahkab.components.Inductor element.

parse_elem_inductor_coupling(line, circ, elements=[])[source]¶

Parses a inductor coupling from the line supplied, returns a list holding the inductor coupling element.

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit to which the inductor coupling is to be connected.

Returns:

elements_list : list: A list containing a ahkab.components.InductorCoupling element.

parse_elem_isource(line, circ)[source]¶

Parses a current source from the line supplied, adds its nodes to the circuit instance and returns a list holding the current source element.

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the current source is to be inserted.

Returns:

elements_list : list: A list containing a ahkab.components.sources.ISource element.

parse_elem_mos(line, circ, models)[source]¶

Parses a MOS transistor from the line supplied, adds its nodes to the circuit instance and returns a list holding the element.

MOS syntax:

::: MX ND NG NS KP=xxx Vt=xxx W=xxx L=xxx type=n/p <LAMBDA=xxx>

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit to which the element will be added.

Returns:

elements_list : list: A list containing a MOS element.

parse_elem_resistor(line, circ)[source]¶

Parses a resistor from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the resistor element.

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit instance to which the resistor is to be connected.

Returns:

elements_list : list: A list containing a ahkab.components.Resistor element.

parse_elem_switch(line, circ, models=None)[source]¶

Parses a switch device from the line supplied, adds its nodes to the circuit instance and returns a list holding the switch element.

General syntax:

SW1 n1 n2 ns1 ns2 model_label

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the switch is to be connected.
models : dict, optional: The currently defined models.

Returns:

elements_list : list: A list containing a ahkab.switch.switch_device element.

parse_elem_user_defined(line, circ)[source]¶

Parses a user defined element.

In order for this to work, you should write a module that supplies the elem class.

Syntax: Y<X> <n1> <n2> module=<module_name> type=<type> [<param1>=<value1> ...]

This method will attempt to load the module <module_name> and it will then look for a class named <type>.

An object will be instatiated with the following arguments: n1, n2, param_dict, get_int_id_func, convert_units_func Where: n1: is the anode of the element n2: is the cathode param_dict: is a dictionary, its elements are {param1:value1, ...} get_int_id_func, convert_units_func are two function that may be used in the __init__ method, if needed. get_int_id_func: a function that gives back the internal name of a node convert_units_func: utility function to convert eg 1p -> 1e-12

See ideal_oscillators.py for a reference implementation. Parameters:

line : string: The netlist line.
circ : circuit instance.: The circuit to which the element will be added.

Returns:

elements_list : list: A list containing a ahkab.components.sources.HVSource element.

Parameters: line: the line circ: the circuit instance.

Returns: [userdef_elem]

parse_elem_vccs(line, circ)[source]¶

Parses a voltage-controlled current source (VCCS) from the line supplied, adds its nodes to the circuit instance and returns a list holding the VCCS element.

Syntax:

GX N+ N- NC+ NC- VALUE

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the VCCS is to be inserted.

Returns:

elements_list : list: A list containing a ahkab.components.sources.GISource element.

parse_elem_vcvs(line, circ)[source]¶

Parses a voltage-controlled voltage source (VCVS) from the line supplied, adds its nodes to the circuit instance circ and returns a list holding the VCVS element.

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the VCVS is to be inserted.

Returns:

elements_list : list: A list containing a ahkab.components.sources.EVSource element.

parse_elem_vsource(line, circ)[source]¶

Parses a voltage source from the line supplied, adds its nodes to the circuit instance and returns a list holding the element.

Parameters:

line : string: The netlist line.
circ : circuit instance: The circuit in which the voltage source is to be inserted.

Returns:

elements_list : list: A list containing a ahkab.components.sources.VSource element.

parse_ic_directive(line)[source]¶: Parses an ic directive and assembles a dictionary accordingly.

parse_ics(directives)[source]¶

parse_include_directive(line, netlist_wd)[source]¶: .include <filename> [*comments]

parse_models(models_lines)[source]¶

parse_param_value_from_string(astr, rtype=<type 'float'>, raise_exception=False)[source]¶

Search the string for a <param>=<value> couple and returns a list.

Parameters:

astr : str: The string to be converted.
rtype : type: One among float, if a float sould be parsed from astr, bool, for parsing a boolean or str to get back a string (no parsing).
raise_exception : boolean, optional: Set this flag to True if you wish for this function to raise ValueError if parsing fails.

Returns:

ret : object: The parsed data. If the conversion fails and raise_exception is not set, a string is returned.

If rtype is float (the type), its default value, the method will attempt converting astr to a float. If the conversion fails, a string is returned.
If set rtype to str (again, the type), a string will always be returned, as if the conversion failed.

This prevents '0' (str) being detected as float and converted to 0.0, ending up being a new node instead of the reference.

Notice that in <param>=<value> there is no space before or after the equal sign.

Returns:

alist : [param, value]: where param is a string and value is parsed as described.

parse_postproc(circ, postproc_direc)[source]¶

parse_single_analysis(line)[source]¶

Parses an analysis

Parameters:

line : str: The netlist line from which an analysis statement is to be parsed.

Returns:

an : dict: A dictionary with its parameters as keys.

Raises:	NetlistParseError – if the analysis is not parsed correctly.

parse_sub_declaration(subckt_lines)[source]¶: Returns a circuit.subckt instance that holds the subckt information, ready to be instantiated/called.

parse_sub_instance(line, circ, subckts_dict, models=None)[source]¶

Parses a subckt call/instance.

Gets name and nodes connections
Looks in subckts_dict for a matching subckts_dict[name]
Builds a circuit wrapper
Calls main_netlist_parser() on the subcircuit code (with the wrapped circuit)

Returns: a elements list

parse_temp_directive(line)[source]¶

Parses a TEMP directive:

The syntax is:

.TEMP <VALUE>

parse_time_function(ftype, line_elements, stype)[source]¶

Parses a time function of type ftype from the line_elements supplied.

Parameters:

ftype : str: One among "pulse", "exp", "sin", "sffm" or "am".
line_elements : list of strings: The tokens describing the time function. The list mustn’t hold the "type=<ftype>" element
stype : str: Set this to “current” for current sources, “voltage” for voltage sources

See ahkab.time_functions.pulse, ahkab.time_functions.sin, ahkab.time_functions.exp, ahkab.time_functions.sffm and ahkab.time_functions.am for more.

Returns:

time_function : object: A time-function instance