AscEditor

Class used for manipulating LTSpice asc files.

class spicelib.AscEditor(asc_filename, encoding='autodetect')

Bases: BaseSchematic, BaseSubCircuit

Class made to update directly the LTspice ASC files

add_component(component, **kwargs)

Adds a component to the design. If the component already exists, it will be replaced by the new one. kwargs are implementation specific and can be used to pass additional information to the implementation.

Parameters:

component (Component) – Component to be added to the design.

Returns:

Nothing

Return type:

None

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

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

add_library_paths(*paths)

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

Adding paths for searching for symbols and libraries

begin_update()

Returns the update permission for the schematic. This is used to determine if the schematic can be updated or not.

property circuit_file: Path

Returns the path of the circuit file.

copy_from(editor)

Clones the contents of the given editor

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)

Adds an update to the netlist updates list

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 the SchematicComponent object representing the given reference in the schematic file.

Parameters:

reference (str) – The reference of the component

Returns:

The SchematicComponent object

Raises:

ComponentNotFoundError – If the component is not found.

Return type:

SchematicComponent

get_component_attribute(reference, attribute)

Returns 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 retrieved

Returns:

Value of the attribute being sought

Return type:

str

Raises:

ComponentNotFoundError - In case the component is not found KeyError - In case the attribute is not found

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 value of the port of the component.

Parameters:

reference (str) – Reference of the component

Returns:

List with the ports of the component

Return type:

str

Raises:

ComponentNotFoundError - In case the component is not found KeyError - In case the port is not found

get_component_parameters(element, as_dicts=False)

Returns the parameters of a component that are related with Spice operation. That is: Value, Value2, SpiceModel, SpiceLine, SpiceLine2, plus all contents of SpiceLine, SpiceLine2

Parameters:

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

• as_dicts (bool) – will report the contents of SpiceLine and SpiceLine2 inside a SpiceLine/SpiceLine2 instead of separately.

Returns:

parameters of the circuit element in dictionary format.

Raises:

ComponentNotFoundError - In case the component is not found

NotImplementedError - for not supported operations

Return type:

dict

get_component_position(reference)

Returns the position and rotation of the component

get_component_value(element)

Returns the value of a component retrieved from the netlist.

Parameters:

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

Returns:

value of the circuit element .

Return type:

str

Raises:

ComponentNotFoundError - In case the component is not found

NotImplementedError - for not supported operations

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_parameter(param)

Retrieves a Parameter 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(reference)

Returns an AscEditor file corresponding to the symbol

get_subcircuit_named(name)

Returns a hierarchical subdesign by its name

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

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. Note: 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.

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 (str) – The instruction to remove.

Returns:

True if the instruction was found and removed, False otherwise

Return type:

bool

reset_netlist(**kwargs)

Resets the netlist to the original state

save_as(new_circuit_filepath)

Saves the current state of the netlist to a new file. This is useful when you want to keep the original file unchanged. This updates the file pointer to the new file.

Parameters:

new_circuit_filepath (str | Path) – File name of the new circuit file.

Returns:

Nothing

Return type:

None

save_netlist(run_netlist_file)

Saves the current state of the netlist to a .asc file. For writing to a .net or .cir file, use the LTspice.create_netlist() method instead.

Parameters:

run_netlist_file (str | Path | StringIO) – File name of the netlist file.

Returns:

Nothing

Return type:

None

scale(offset_x, offset_y, scale_x, scale_y, round_fun=None)

Scales the schematic

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(element, **kwargs)

Sets the parameters of a component that are related with Spice operation. That is: Value, Value2, SpiceModel, SpiceLine, SpiceLine2, or any parameters are or could be in SpiceLine, SpiceLine2. Unknown parameters will be added to SpiceLine. Setting None removes the parameter if possible.

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_position(reference, position, rotation)

Sets the position and rotation of the component.

Parameters:

• reference (str) – The reference of the component

• position (Point) – The new position of the component

• rotation (ERotation) – The new rotation of the component

set_component_value(device, value)

Sets the value of the component

Parameters:

• device (str) – The reference of the component

• value (str | float | int | complex) – The new value

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(element, model)

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

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

Parameters:

• element (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)

Adds a parameter to the SPICE netlist.

Usage:

editor.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

simulator_lib_paths: list[str]

This is initialised with typical locations found for LTspice. 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.

updated()

property was_modified: bool

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.