API reference - Class NetlistSpiceReaderDelegate

Notation used in Ruby API documentation

Module: db

Description: Provides a delegate for the SPICE reader for translating device statements

Supply a customized class to provide a specialized reading scheme for devices. You need a customized class if you want to implement device reading from model subcircuits or to translate device parameters.

See NetlistSpiceReader for more details.

This class has been introduced in version 0.26.

Public constructors

new NetlistSpiceReaderDelegate ptrnewCreates a new object of this class

Public methods

void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
[const]voidapply_parameter_scaling(Device ptr device)Applies parameter scaling to the given device
voidassign(const NetlistSpiceReaderDelegate other)Assigns another object to self
[virtual]boolcontrol_statement(string line)Receives control statements not understood by the standard reader
[const]new NetlistSpiceReaderDelegate ptrdupCreates a copy of self
[virtual]boolelement(Circuit ptr circuit,
string element,
string name,
string model,
double value,
Net ptr[] nets,
map<string,variant> parameters)
Makes a device from an element line
voiderror(string msg)Issues an error with the given message.
[virtual]voidfinish(Netlist ptr netlist)This method is called when the reader is done reading a netlist successfully
[const]doubleget_scaleGets the scale factor set with '.options scale=...'
[virtual]ParseElementDataparse_element(string s,
string element)
Parses an element card
ParseElementComponentsDataparse_element_components(string s,
map<string,variant> variables = {})
Parses a string into string and parameter components.
[virtual]voidstart(Netlist ptr netlist)This method is called when the reader starts reading a netlist
[virtual]stringtranslate_net_name(string net_name)Translates a net name from the raw net name to the true net name
variantvalue_from_string(string s,
map<string,variant> variables = {})
Translates a string into a value
[const]map<string,variant>variablesGets the variables defined inside the SPICE file during execution of 'parse_element'
[virtual]boolwants_subcircuit(string circuit_name)Returns true, if the delegate wants subcircuit elements with this name

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

apply_parameter_scaling

Signature: [const] void apply_parameter_scaling (Device ptr device)

Description: Applies parameter scaling to the given device

Applies SI scaling (according to the parameter's si_scaling attribute) and geometry scaling (according to the parameter's geo_scale_exponent attribute) to the device parameters. Use this method of finish the device when you have created a custom device yourself.

The geometry scale is taken from the '.options scale=...' control statement.

This method has been introduced in version 0.28.6.

assign

Signature: void assign (const NetlistSpiceReaderDelegate other)

Description: Assigns another object to self

control_statement

Signature: [virtual] bool control_statement (string line)

Description: Receives control statements not understood by the standard reader

When the reader encounters a control statement not understood by the parser, it will pass the line to the delegate using this method. The delegate can decide if it wants to read this statement. It should return true in this case.

This method has been introduced in version 0.27.1

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

dup

Signature: [const] new NetlistSpiceReaderDelegate ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

element

Signature: [virtual] bool element (Circuit ptr circuit, string element, string name, string model, double value, Net ptr[] nets, map<string,variant> parameters)

Description: Makes a device from an element line

circuit:The circuit that is currently read.
element:The upper-case element code ("M", "R", ...).
name:The element's name.
model:The upper-case model name (may be empty).
value:The default value (e.g. resistance for resistors) and may be zero.
nets:The nets given in the element line.
parameters:The parameters of the element statement (parameter names are upper case).

The default implementation will create corresponding devices for some known elements using the Spice writer's parameter conventions.

The method must return true, if the element was was understood and false otherwise.

Starting with version 0.28.6, the parameter values can be strings too.

error

Signature: void error (string msg)

Description: Issues an error with the given message.

Use this method to generate an error.

finish

Signature: [virtual] void finish (Netlist ptr netlist)

Description: This method is called when the reader is done reading a netlist successfully

get_scale

Signature: [const] double get_scale

Description: Gets the scale factor set with '.options scale=...'

This method has been introduced in version 0.28.6.

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

new

Signature: [static] new NetlistSpiceReaderDelegate ptr new

Description: Creates a new object of this class

Python specific notes:
This method is the default initializer of the object.

parse_element

Signature: [virtual] ParseElementData parse_element (string s, string element)

Description: Parses an element card

s:The specification part of the element line (the part after element code and name).
element:The upper-case element code ("M", "R", ...).
Returns:A ParseElementData object with the parts of the element.

This method receives a string with the element specification and the element code. It is supposed to parse the element line and return a model name, a value, a list of net names and a parameter value dictionary.

'parse_element' is called on every element card. The results of this call go into the element method to actually create the device. This method can be reimplemented to support other flavors of SPICE.

This method has been introduced in version 0.27.1

parse_element_components

Signature: ParseElementComponentsData parse_element_components (string s, map<string,variant> variables = {})

Description: Parses a string into string and parameter components.

This method is provided to simplify the implementation of 'parse_element'. It takes a string and splits it into string arguments and parameter values. For example, 'a b c=6' renders two string arguments in 'nn' and one parameter ('C'->6.0). It returns data ParseElementComponentsData object with the strings and parameters. The parameter names are already translated to upper case.

The variables dictionary defines named variables with the given values.

This method has been introduced in version 0.27.1. The variables argument has been added in version 0.28.6.

start

Signature: [virtual] void start (Netlist ptr netlist)

Description: This method is called when the reader starts reading a netlist

translate_net_name

Signature: [virtual] string translate_net_name (string net_name)

Description: Translates a net name from the raw net name to the true net name

The default implementation will replace backslash sequences by the corresponding character. 'translate_net_name' is called before a net name is turned into a net object. The method can be reimplemented to supply a different translation scheme for net names. For example, to translate special characters.

This method has been introduced in version 0.27.1

value_from_string

Signature: variant value_from_string (string s, map<string,variant> variables = {})

Description: Translates a string into a value

This function simplifies the implementation of SPICE readers by providing a translation of a unit-annotated string into double values. For example, '1k' is translated to 1000.0. In addition, simple formula evaluation is supported, e.g '(1+3)*2' is translated into 8.0.

The variables dictionary defines named variables with the given values.

This method has been introduced in version 0.27.1. The variables argument has been added in version 0.28.6.

variables

Signature: [const] map<string,variant> variables

Description: Gets the variables defined inside the SPICE file during execution of 'parse_element'

In order to evaluate formulas, this method allows accessing the variables that are present during the execution of the SPICE reader.

This method has been introduced in version 0.28.6.

wants_subcircuit

Signature: [virtual] bool wants_subcircuit (string circuit_name)

Description: Returns true, if the delegate wants subcircuit elements with this name

The name is always upper case.