SpiceEditor¶

Class used for manipulating SPICE netlists. Inherits from SpiceCircuit.

class spicelib.SpiceEditor(netlist_file, encoding='autodetect', **kwargs)[source]¶

Bases: SpiceFile

Provides interfaces to manipulate SPICE netlist files. The class doesn’t update the netlist file itself. After implementing the modifications, the user should call the “save_netlist” method to write a new netlist file.

Parameters:

netlist_file (Path | str) – Name of the .NET file to parse
encoding – Forcing the encoding to be used on the circuit netlile read. Defaults to ‘autodetect’ which will call a function that tries to detect the encoding automatically. This, however, is not 100% foolproof.

Keyword Arguments:

create_blank – Create a blank ‘.net’ file when ‘netlist_file’ not exist. False by default
include_file – If an include file is being parsed, the control of the ending .END statement is suppressed.

add_component(component, **kwargs)¶

Adds a component to the netlist. The component is added to the end of the netlist, just before the .END statement. If the component already exists, it will be replaced by the new one.

Parameters:

component (Component) – The component to be added to the netlist
kwargs –
The following keyword arguments are supported:
- insert_before (str) - The reference of the component before which the new component should be inserted.
- insert_after (str) - The reference of the component after which the new component should be inserted.

Returns:

Nothing

Return type:

None

add_control_section(instruction)[source]¶

Adds a control section to the netlist. The instruction should be a multi-line string that starts with ‘.CONTROL’ and ends with ‘.ENDC’. It will be added as a ControlEditor object to the netlist.

You can also use the add_instruction() method, but that method has less checking of the format.

Parameters:: instruction (str) – control section instruction
Raises:: ValueError – if the instruction does not start with .CONTROL or does not end with .ENDC

add_instruction(instruction)¶

Adds a SPICE instruction to the netlist.

For example:

.tran 10m ; makes a transient simulation
.meas TRAN Icurr AVG I(Rs1) TRIG time=1.5ms TARG time=2.5ms ; Establishes a measuring
.step run 1 100, 1 ; makes the simulation run 100 times
.control ... control statements on multiple lines ... .endc

Parameters:: instruction (str) – Spice instruction to add to the netlist. This instruction will be added at the end of the netlist, typically just before the .BACKANNO statement
Returns:: Nothing
Return type:: None

add_instructions(*instructions)¶

Adds a list of instructions to the SPICE NETLIST.

Example:

editor.add_instructions(".STEP run -1 1023 1", ".dc V1 -5 5")

Parameters:: instructions – Argument list of instructions to add
Returns:: Nothing
Return type:: None

classmethod add_library_search_paths(*paths)[source]¶

Deprecated since version 1.1.4: Use the class method set_custom_library_paths() instead.

Adds search paths for libraries. By default, the local directory and the ~username/”Documents/LTspiceXVII/lib/sub will be searched forehand. Only when a library is not found in these paths then the paths added by this method will be searched.

Parameters:: paths (str) – Path to add to the Search path
Returns:: Nothing
Return type:: None

begin_update()¶

property circuit_file: Path¶: Returns the path of the circuit file.

class_for_instruction(instruction, cmd='')¶

clone(new_parent, **kwargs)¶

Creates a new copy of the SpiceCircuit. Changes done at the new copy do not affect the original.

Key new_name:: The new name to be given to the circuit
Key type new_name:: str
Returns:: The new replica of the SpiceCircuit object
Return type:: SpiceCircuit

custom_lib_paths: list[str]¶

The custom library paths. Not to be modified, only set via set_custom_library_paths(). This is a class variable, so it will be shared between all instances

property editor: BaseEditor | None¶: Returns the editor object representing the netlist. If the current object is a sub-circuit, it returns the parent

end_update(name, value, updates)¶

get_all_nodes()¶

Retrieves all nodes existing on a Netlist.

Returns:: Circuit Nodes
Return type:: list[str]

get_all_parameter_names()¶

Returns all parameter names from the netlist.

Returns:: A list of parameter names found in the netlist
Return type:: list[str]

get_component(reference)¶

Returns an object representing the given reference in the schematic file.

Parameters:: reference (str) – Reference of the component
Returns:: The SpiceComponent object or a SpiceSubcircuit in case of hierarchical design
Raises:: ComponentNotFoundError - In case the component is not found
Raises:: UnrecognizedSyntaxError when the line doesn’t match the expected REGEX.
Raises:: NotImplementedError if there isn’t an associated regular expression for the component prefix.
Return type:: SpiceComponent | SpiceCircuitInstance | SpiceCircuit

get_component_attribute(reference, attribute)¶

Returns the attribute of a component retrieved from the netlist.

Parameters:

reference (str) – Reference of the component
attribute (str) – Name of the attribute to be retrieved

Returns:

Value of the attribute

Return type:

str

Raises:

ComponentNotFoundError - In case the component is not found

Raises:

UnrecognizedSyntaxError when the line doesn’t match the expected REGEX.

Raises:

NotImplementedError if there isn’t an associated regular expression for the component prefix.

get_component_floatvalue(element)¶

Returns the value of a component retrieved from the netlist.

Parameters:

element (str) – Reference of the circuit element to get the value in float format.

Returns:

value of the circuit element in float type

Return type:

float

Raises:

ComponentNotFoundError - In case the component is not found

NotImplementedError - for not supported operations

get_component_nodes(reference)¶

Returns the nodes to which the component is attached to.

Parameters:: reference (str) – Reference of the circuit element to get the nodes.
Returns:: List of nodes
Return type:: list[str]

get_component_parameters(reference)¶

Returns the parameters of a component retrieved from the netlist.

Parameters:

element (str) – Reference of the circuit element to get the parameters.

Returns:

parameters of the circuit element in dictionary format.

Return type:

dict

Raises:

ComponentNotFoundError - In case the component is not found

NotImplementedError - for not supported operations

get_component_value(reference)¶

Returns the value of a component retrieved from the netlist.

Parameters:

reference (str) – Reference of the circuit element to get the value.

Returns:

value of the circuit element .

Raises:

ComponentNotFoundError - In case the component is not found

NotImplementedError - for not supported operations

Return type:

str | None

get_components(prefixes='*')¶

Returns a list of components that match the list of prefixes indicated on the parameter prefixes. In case prefixes is left empty, it returns all the ones that are defined by the REPLACE_REGEXES. The list will contain the designators of all components found.

Parameters:: prefixes (str) – Type of prefixes to search for. Examples: ‘C’ for capacitors; ‘R’ for Resistors; etc… See prefixes in SPICE documentation for more details. The default prefix is ‘*’ which is a special case that returns all components.
Returns:: A list of components matching the prefixes demanded.
Return type:: list

get_control_sections()[source]¶

Returns a list representing the control sections in the netlist. Control sections are all anonymous, so they do not have a name, just an index. They are also not parsed, they are just a list of strings (with embedded newlines).

Returns:: list of control section strings. These strings have each multiple lines, start with .CONTROL and end with .ENDC.
Return type:: list[str]

get_parameter(param)¶

Returns the value of a parameter retrieved from the netlist.

Parameters:: param (str) – Name of the parameter to be retrieved
Returns:: Value of the parameter being sought
Return type:: str
Raises:: ParameterNotFoundError - In case the component is not found

get_subcircuit(instance_name)¶

Returns an object representing a Subcircuit. This object can manipulate elements such as the SpiceEditor does.

Parameters:

instance_name (str) – Reference of the subcircuit

Returns:

SpiceCircuit instance

Return type:

SpiceCircuit

Raises:

UnrecognizedSyntaxError – when an spice command is not recognized by spicelib
ComponentNotFoundError – When the reference was not found

get_subcircuit_named(name)¶

Returns the sub-circuit object with the given name.

Parameters:: name (str) – name of the subcircuit
Returns:: _description_
Return type:: _type_

get_subcircuit_names()¶

Returns a list of the names of the sub-circuits in the netlist.

Returns:: list of sub-circuit names
Return type:: list[str]

is_read_only()¶

Check if the component can be edited. This is useful when the editor is used on non-modifiable files.

Returns:: True if the component is read-only, False otherwise
Return type:: bool

modified_subcircuits()¶

Returns a list of all sub-circuits that have been modified.

Returns:: List of modified sub-circuits
Return type:: list[SpiceCircuit]

name()¶

Returns the name of the Sub-Circuit.

Return type:: str

classmethod prepare_for_simulator(simulator)¶

Sets the library paths that should be correct for the simulator object. The simulator object should have had the executable path (spice_exe) set correctly.

This is especially useful in 2 cases:

when the simulator is running under wine, as it is difficult to detect the correct library paths in that case.
when the editor can be used with different simulators, that have different library paths.

Note

you can always also set the library paths manually via set_custom_library_paths()
this method is a class method and will affect all instances of the class

Parameters:: simulator (Simulator) – Simulator object from which the library paths will be taken.
Returns:: Nothing
Return type:: None

remove_Xinstruction(search_pattern)¶

Removes a SPICE instruction from the netlist based on a search pattern. This is a more flexible way to remove instructions from the netlist. The search pattern is a regular expression that will be used to match the instructions to be removed. The search pattern is case-insensitive, and will be applied to each line of the netlist. All matching lines will be removed.

Example: The code below will remove all AC analysis instructions from the netlist.

editor.remove_Xinstruction(r"\.AC.*")

Parameters:: search_pattern (str) – Pattern for the instruction to remove. In general, it is best to use a raw string (r).
Returns:: True if the instruction was found and removed, False otherwise
Return type:: bool

remove_component(designator)¶

Removes a component from the design. Current implementation only allows removal of a component from the main netlist, not from a sub-circuit.

Parameters:: designator (str) – Component reference in the design. Ex: V1, C1, R1, etc…
Returns:: Nothing
Raises:: ComponentNotFoundError - When the component doesn’t exist on the netlist.
Return type:: None

remove_control_section(index=0)[source]¶

Removes a control section from the netlist, based on the index in get_control_sections(). You can also use remove_instruction(), but there, the given text must match the entire control section.

Parameters:: index (int) – index of the control section to remove, according to get_control_sections()
Returns:: True if the control section was found and removed, False otherwise
Return type:: bool

remove_instruction(instruction)¶

Removes a SPICE instruction from the netlist.

Example:

editor.remove_instruction(".STEP run -1 1023 1")

This only works if the entire given instruction is contained in a line on the netlist. It uses the ‘in’ comparison, and is case-sensitive. It will remove 1 instruction at most, even if more than one could be found. remove_Xinstruction() is a more flexible way to remove instructions from the netlist.

Parameters:: instruction – The instruction to remove.
Returns:: True if the instruction was found and removed, False otherwise
Return type:: bool

reset_netlist(**kwargs)[source]¶

Reset the netlist state and reload or reinitialize its content.

Keyword Arguments:

create_blank – Create a blank ‘.net’ file when ‘netlist_file’ not exist.
include_file – If an include file is being parsed, the control of the ending .END statement is suppressed. This is useful when parsing include files, which do not have an .END statement, but are just a part of the netlist.

Returns:

True if successful, False otherwise.

Return type:

bool

run(wait_resource=True, callback=None, timeout=None, run_filename=None, simulator=None)[source]¶

Deprecated since version 1.0: Use the run method from the SimRunner class instead.

Convenience function for maintaining legacy with legacy code. Runs the SPICE simulation.

save_as(new_circuit_filepath)¶

Saves the netlist to a new file. The new file will be created if it does not exist, and overwritten if it does exist.

Parameters:: new_circuit_filepath (str or Path) – Path to the new netlist file
Returns:: Nothing
Return type:: None

save_netlist(run_netlist_file)¶

Saves the current state of the netlist to a file or a string. :param run_netlist_file: File name of the netlist file, or a StringIO object. :returns: Nothing

set_component_attribute(reference, attribute, value)¶

Sets the value of the attribute of the component. Attributes are the values that are not related with SPICE parameters. For example, component manufacturer, footprint, schematic appearance, etc. User can define whatever attributes they want. The only restriction is that the attribute name must be a string.

Parameters:

reference (str) – Reference of the component
attribute (str) – Name of the attribute to be set
value (str) – Value of the attribute to be set

Returns:

Nothing

Raises:

ComponentNotFoundError - In case the component is not found

Return type:

None

set_component_parameters(reference, **kwargs)¶

Adds one or more parameters to the component on the netlist. The argument is in the form of a key-value pair where each parameter is the key and the value is value to be set in the netlist.

Usage 1:

editor.set_component_parameters(R1, value=330, temp=25)

Usage 2:

value_settings = {'value': 330, 'temp': 25}
editor.set_component_parameters(R1, **value_settings)

Parameters:: element (str) – Reference of the circuit element.
Key <param_name>:: The key is the parameter name and the value is the value to be set. Values can either be strings; integers or floats. When None is given, the parameter will be removed, if possible.
Returns:: Nothing
Raises:: ComponentNotFoundError - In case one of the component is not found.
Return type:: None

set_component_value(reference, value)¶

Changes the value of a component, such as a Resistor, Capacitor or Inductor. For components inside sub-circuits, use the sub-circuit designator prefix with ‘:’ as separator (Example X1:R1) Usage:

runner.set_component_value('R1', '3.3k')
runner.set_component_value('X1:C1', '10u')

Parameters:

reference (str) – Reference of the circuit element to be updated.
value (str, int or float) – value to be set on the given circuit element. Float and integer values will be automatically formatted as per the engineering notations ‘k’ for kilo, ‘m’, for mili and so on.

Raises:

ComponentNotFoundError - In case the component is not found

ValueError - In case the value doesn’t correspond to the expected format

NotImplementedError - In case the circuit element is defined in a format which is not supported by this version.

If this is the case, use GitHub to start a ticket. https://github.com/nunobrum/spicelib

set_component_values(**kwargs)¶

Adds one or more components on the netlist. The argument is in the form of a key-value pair where each component designator is the key and the value is value to be set in the netlist.

Usage 1:

editor.set_component_values(R1=330, R2="3.3k", R3="1Meg", V1="PWL(0 1 30m 1 30.001m 0 60m 0 60.001m 1)")

Usage 2:

value_settings = {'R1': 330, 'R2': '3.3k', 'R3': "1Meg", 'V1': 'PWL(0 1 30m 1 30.001m 0 60m 0 60.001m 1)'}
editor.set_component_values(**value_settings)

Key <comp_ref>:: The key is the component designator (Ex: V1) and the value is the value to be set. Values can either be strings; integers or floats
Returns:: Nothing
Raises:: ComponentNotFoundError - In case one of the component is not found.

classmethod set_custom_library_paths(*paths)¶

Set the given library search paths to the list of directories to search when needed. It will delete any previous list of custom paths, but will not affect the default paths (be it from init() or from prepare_for_simulator()).

Note that this method is a class method and will affect all instances of the class.

Parameters:: paths – Path(s) to add to the Search path
Returns:: Nothing
Return type:: None

set_element_model(reference, model)¶

Changes the value of a circuit element, such as a diode model or a voltage supply. Usage:

runner.set_element_model('D1', '1N4148')
runner.set_element_model('V1' "SINE(0 1 3k 0 0 0)")

Parameters:

reference (str) – Reference of the circuit element to be updated.
model (str) – model name of the device to be updated

Raises:

ComponentNotFoundError - In case the component is not found

ValueError - In case the model format contains irregular characters

NotImplementedError - In case the circuit element is defined in a format which is not supported by this version.

If this is the case, use GitHub to start a ticket. https://github.com/nunobrum/spicelib

set_parameter(param, value)¶

Sets the value of a parameter in the netlist. If the parameter is not found, it is added to the netlist.

Usage:

runner.set_parameter("TEMP", 80)

This adds onto the netlist the following line:

.PARAM TEMP=80

This is an alternative to the set_parameters which is more pythonic in its usage and allows setting more than one parameter at once.

Parameters:

param (str) – Spice Parameter name to be added or updated.
value (str, int or float) – Parameter Value to be set.

Returns:

Nothing

Return type:

None

set_parameters(**kwargs)¶

Adds one or more parameters to the netlist. Usage:

for temp in (-40, 25, 125):
    for freq in sweep_log(1, 100E3,):
        editor.set_parameters(TEMP=80, freq=freq)

Key param_name:: Key is the parameter to be set. values the ther corresponding values. Values can either be a str; an int or a float.
Returns:: Nothing

setname(new_name)¶

Renames the sub-circuit to a new name. No check is done to the new name. It is up to the user to make sure that the new name is valid.

Parameters:: new_name (str) – The new Name.
Returns:: Nothing

simulator_lib_paths: list[str]¶

This is initialised with typical locations found for your simulator. You can (and should, if you use wine), call prepare_for_simulator() once you’ve set the executable paths. This is a class variable, so it will be shared between all instances.

property was_modified: bool¶

write_lines(stream)¶

Internal function. Do not use.

write_netlist(run_netlist_file)¶

Deprecated since version 1.x: Use save_netlist() instead.

Writes the netlist to a file. This is an alias to save_netlist.

Table of Contents

Search

SpiceEditor¶