RawRead and PlotData

class spicelib.RawRead(raw_filename, traces_to_read=None, dialect=None, verbose=True)

Bases: PlotInterface

Class for reading Spice wave Files. It can read all types of Files, and can handle multiple plots in 1 file. If stepped data is detected, it will also try to read the corresponding LOG file so to retrieve the stepped data.

Parameters:

• raw_filename (str or pathlib.Path) – The file containing the RAW data to be read

• traces_to_read (str, list or tuple) – A string or a list containing the list of traces to be read. If None is provided, only the header is read and all trace data is discarded. If a ‘*’ wildcard is given or no parameter at all then all traces are read.

• dialect (str | None) – The simulator used. Please select from [“ltspice”,”qspice”,”ngspice”,”xyce”]. If not specified, dialect will be auto detected. This is likely only needed for older versions of ngspice and xyce. ltspice and qspice can reliably be auto detected.

• verbose (bool) – If True, then the class will log debug information. Defaults to True.

Raises:

SpiceReadException – in case of a syntax error in the RAW file, or if the encoding is not recognized.

property aliases: dict[str, str]

QSpice defines aliases for some of the traces that can be computed from other traces.

property axis: Axis | None

Deprecated since version 1.4.5: Use get_axis() method instead.

The axis of the RAW file, if it exists.

property backannotations: list[str]

List to store the backannotations found in the RAW file header

property dialect: str | None

The dialect of the RAW file, either ‘ltspice’, ‘qspice’, ‘ngspice’ or ‘xyce’

property encoding: str

The encoding of the RAW file is either ‘utf_8’ or ‘utf_16_le’. It is automatically detected when reading the file. If the file was not read yet, an empty string is returned. If the RAW file contains multiple plots, the encoding of the first plot is returned.

export(columns=None, step=-1, **kwargs)

Returns a native python class structure with the requested trace data and steps. It consists of an ordered dictionary where the columns are the keys and the values are lists with the data.

This function is used by the export functions.

Parameters:

• step (int | list[int]) – Step number to retrieve. If not given, it will return all steps

• columns (list | None) – List of traces to use as columns. Default is all traces

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame constructor

Returns:

A pandas DataFrame

Return type:

dict[str, list]

property flags: list[str]

List of Flags that are used in this plot. See RAW File Structure for details.

get_axis(step=0)

This function is equivalent to get_trace(0).get_wave(step) instruction. It also implements a workaround on a LTSpice issue when using 2nd Order compression, where some values on the time trace have a negative value.

Parameters:

step (int) – Step number, defaults to 0

Raises:

RuntimeError – if the RAW file does not have an axis.

Returns:

Array with the X axis

Return type:

ndarray | list[float]

get_len(step=0)

Returns the length of the data at the give step index.

Parameters:

step (int) – the step index, defaults to 0

Returns:

The number of data points

Return type:

int

get_nr_plots()

Returns the number of plots in the RAW file.

Returns:

Number of plots

Return type:

int

get_plot_name()

Returns the type of the plot read from the RAW file. Some examples:

• ‘AC Analysis’,

• ‘DC transfer characteristic’,

• ‘Operating Point’,

• ‘Transient Analysis’,

• ‘Transfer Function’,

• ‘Noise Spectral Density’,

• ‘Frequency Response Analysis’,

• ‘Noise Spectral Density Curves’,

• ‘Integrated Noise’

Returns:

plot name

Return type:

str

get_plot_names()

Returns a list of plot names in the RAW file.

Returns:

List of plot names

Return type:

list[str]

get_raw_properties()

Get all raw properties.

Returns:

Dictionary of all raw properties

Return type:

dict[str, str]

get_raw_property(property_name=None)

Get a property. By default, it returns all properties defined in the RAW file.

Parameters:

property_name (str) – name of the property to retrieve. If None, all properties are returned.

Returns:

Property object

Raises:

ValueError if the property doesn’t exist

Return type:

str | dict[str, str]

get_steps(**kwargs)

Returns the steps that correspond to the query set in the **kwargs parameters. Example:

raw_read.get_steps(V5=1.2, TEMP=25)

This will return all steps in which the voltage source V5 was set to 1.2V and the TEMP parameter is 24 degrees. This feature is only possible if a .log file with the same name as the .raw file exists in the same directory. Note: the correspondence between step numbers and .STEP information is stored on the .log file.

Key kwargs:

key-value arguments in which the key correspond to a stepped parameter or source name, and the value is the stepped value.

Returns:

The steps that match the query

Return type:

list[int] | range

get_time_axis(step=0)

Deprecated since version 1.0: Use get_axis() method instead.

This function is equivalent to get_trace(‘time’).get_time_axis(step) instruction. It’s workaround on a LTSpice issue when using 2nd Order compression, where some values on the time trace have a negative value.

get_trace(trace_ref)

Retrieves the trace with the requested name (trace_ref).

Parameters:

trace_ref (str | int) – Name of the trace or the index of the trace

Returns:

An object containing the requested trace

Raises:

IndexError – When a trace is not found

Return type:

Axis | TraceRead

get_trace_names()

Returns a list of exiting trace names of the RAW file.

Returns:

trace names

Return type:

list[str]

get_wave(trace_ref, step=0)

Retrieves the trace data with the requested name (trace_ref), optionally providing the step number.

Parameters:

• trace_ref (str | int) – Name of the trace or the index of the trace

• step (int) – Optional parameter specifying which step to retrieve.

Returns:

A numpy array containing the requested waveform.

Raises:

IndexError – When a trace is not found

Return type:

ndarray

property has_axis: bool

Indicates if the RAW file has an axis. This is True for all RAW file plots except for ‘Operating Point’, ‘Transfer Function’, and ‘Integrated Noise’.

property nPoints: int

Number of points in the RAW file

property nVariables: int

Number of variables in the RAW file

property plots: list[PlotData]

List of plots in the RAW file. Each plot is an instance of a class that inherits from PlotData. Note that all properties and methods of plots[0] are also available directly in the RawRead class.

property raw_params: OrderedDict

Deprecated since version 1.4.5: Use get_raw_properties() or get_raw_property() method instead.

Dictionary to store the parameters found in the RAW file header. The keys are the parameter names, and the values are the parameter values.

property raw_type: str

‘

Type:

The type of the RAW file, either ‘binary

Type:

‘ or ‘values

property steps: list[dict[str, int]] | None

List of steps in the RAW file, if it exists. If the RAW file does not contain stepped data, this will be None. If the RAW file contains stepped data, this will be a list of step numbers.

to_csv(filename, columns=None, step=-1, separator=',', **kwargs)

Saves the data to a CSV file.

Parameters:

• filename (str | Path) – Name of the file to save the data to

• columns (list[str] | None) – List of traces to use as columns. Default is all traces

• step (int | list[int]) – Step number to retrieve. If not given, it

• separator (str) – separator to use in the CSV file

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame.to_csv function

to_dataframe(columns=None, step=-1, **kwargs)

Returns a pandas DataFrame with the requested data.

Parameters:

• step (int | list[int]) – Step number to retrieve. If not given, it

• columns (list | None) – List of traces to use as columns. Default is all traces

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame constructor

Returns:

A pandas DataFrame

Return type:

pandas.DataFrame

to_excel(filename, columns=None, step=-1, **kwargs)

Saves the data to an Excel file.

Parameters:

• filename (str | Path) – Name of the file to save the data to

• columns (list | None) – List of traces to use as columns. Default is None, meaning all traces

• step (int | list[int]) – Step number to retrieve, defaults to -1

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame.to_excel function

Raises:

ImportError – when the ‘pandas’ module is not installed

class spicelib.PlotData(raw_file, raw_filename, plot_nr, encoding, dialect, verbose)

Bases: PlotInterface

Class for holding plot data. This class is used to hold the data of a plot, including the axis and traces.

Do not instantiate this class directly, use the RawRead class instead.

property aliases: dict[str, str]

QSpice defines aliases for some of the traces that can be computed from other traces.

property axis: Axis | None

Deprecated since version 1.4.5: Use get_axis() method instead.

The axis of the RAW file, if it exists.

property backannotations: list[str]

List to store the backannotations found in the RAW file header

property dialect: str | None

The dialect of the RAW file, either ‘ltspice’, ‘qspice’, ‘ngspice’ or ‘xyce’

property encoding: str

The encoding of the RAW file, either ‘utf_8’ or ‘utf_16_le’

export(columns=None, step=-1, **kwargs)

Returns a native python class structure with the requested trace data and steps. It consists of an ordered dictionary where the columns are the keys and the values are lists with the data.

This function is used by the export functions.

Parameters:

• step (int | list[int]) – Step number to retrieve. If not given, it will return all steps

• columns (list | None) – List of traces to use as columns. Default is all traces

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame constructor

Returns:

A pandas DataFrame

Return type:

dict[str, list]

property flags: list[str]

List of Flags that are used in this plot. See RAW File Structure for details.

get_axis(step=0)

This function is equivalent to get_trace(0).get_wave(step) instruction. It also implements a workaround on a LTSpice issue when using 2nd Order compression, where some values on the time trace have a negative value.

Parameters:

step (int) – Step number, defaults to 0

Raises:

RuntimeError – if the RAW file does not have an axis.

Returns:

Array with the X axis

Return type:

ndarray | list[float]

get_len(step=0)

Returns the length of the data at the give step index.

Parameters:

step (int) – the step index, defaults to 0

Returns:

The number of data points

Return type:

int

get_plot_name()

Returns the type of the plot read from the RAW file. Some examples:

• ‘AC Analysis’,

• ‘DC transfer characteristic’,

• ‘Operating Point’,

• ‘Transient Analysis’,

• ‘Transfer Function’,

• ‘Noise Spectral Density’,

• ‘Frequency Response Analysis’,

• ‘Noise Spectral Density Curves’,

• ‘Integrated Noise’

Returns:

plot name

Return type:

str

get_raw_properties()

Get all raw properties.

Returns:

Dictionary of all raw properties

Return type:

dict[str, str]

get_raw_property(property_name=None)

Get a property. By default, it returns all properties defined in the RAW file.

Parameters:

property_name (str) – name of the property to retrieve. If None, all properties are returned.

Returns:

Property object

Raises:

ValueError if the property doesn’t exist

Return type:

str | dict[str, str]

get_steps(**kwargs)

Returns the steps that correspond to the query set in the **kwargs parameters. Example:

raw_read.get_steps(V5=1.2, TEMP=25)

This will return all steps in which the voltage source V5 was set to 1.2V and the TEMP parameter is 24 degrees. This feature is only possible if a .log file with the same name as the .raw file exists in the same directory. Note: the correspondence between step numbers and .STEP information is stored on the .log file.

Key kwargs:

key-value arguments in which the key correspond to a stepped parameter or source name, and the value is the stepped value.

Returns:

The steps that match the query

Return type:

list[int] | range

get_time_axis(step=0)

Deprecated since version 1.0: Use get_axis() method instead.

This function is equivalent to get_trace(‘time’).get_time_axis(step) instruction. It’s workaround on a LTSpice issue when using 2nd Order compression, where some values on the time trace have a negative value.

get_trace(trace_ref)

Retrieves the trace with the requested name (trace_ref).

Parameters:

trace_ref (str | int) – Name of the trace or the index of the trace

Returns:

An object containing the requested trace

Raises:

IndexError – When a trace is not found

Return type:

Axis | TraceRead

get_trace_names()

Returns a list of exiting trace names of the RAW file.

Returns:

trace names

Return type:

list[str]

get_wave(trace_ref, step=0)

Retrieves the trace data with the requested name (trace_ref), optionally providing the step number.

Parameters:

• trace_ref (str | int) – Name of the trace or the index of the trace

• step (int) – Optional parameter specifying which step to retrieve.

Returns:

A numpy array containing the requested waveform.

Raises:

IndexError – When a trace is not found

Return type:

ndarray

property has_axis: bool

Indicates if the RAW file has an axis. This is True for all RAW file plots except for ‘Operating Point’, ‘Transfer Function’, and ‘Integrated Noise’.

property has_data: bool

Indicates if the plot has data.

property nPoints: int

Number of points in the RAW file

property nVariables: int

Number of variables in the RAW file

property raw_params: OrderedDict

Deprecated since version 1.4.5: Use get_raw_properties() or get_raw_property() method instead.

Dictionary to store the parameters found in the RAW file header. The keys are the parameter names, and the values are the parameter values.

property raw_type: str

‘

Type:

The type of the RAW file, either ‘binary

Type:

‘ or ‘values

read_trace_data(list_of_traces)

Reads the trace data from the binary section of the RAW file.

property steps: list[dict[str, int]] | None

List of steps in the RAW file, if it exists. If the RAW file does not contain stepped data, this will be None. If the RAW file contains stepped data, this will be a list of step numbers.

to_csv(filename, columns=None, step=-1, separator=',', **kwargs)

Saves the data to a CSV file.

Parameters:

• filename (str | Path) – Name of the file to save the data to

• columns (list[str] | None) – List of traces to use as columns. Default is all traces

• step (int | list[int]) – Step number to retrieve. If not given, it

• separator (str) – separator to use in the CSV file

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame.to_csv function

to_dataframe(columns=None, step=-1, **kwargs)

Returns a pandas DataFrame with the requested data.

Parameters:

• step (int | list[int]) – Step number to retrieve. If not given, it

• columns (list | None) – List of traces to use as columns. Default is all traces

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame constructor

Returns:

A pandas DataFrame

Return type:

pandas.DataFrame

to_excel(filename, columns=None, step=-1, **kwargs)

Saves the data to an Excel file.

Parameters:

• filename (str | Path) – Name of the file to save the data to

• columns (list | None) – List of traces to use as columns. Default is None, meaning all traces

• step (int | list[int]) – Step number to retrieve, defaults to -1

• kwargs (**dict) – Additional arguments to pass to the pandas.DataFrame.to_excel function

Raises:

ImportError – when the ‘pandas’ module is not installed