Module `pyspectre.core`

Python interface for Cadence Spectre

Functions

def create_analysis(session: Session, analysis_type: str, analysis_name: str) ‑> bool

Create a new analysis in the Spectre session.

To see the available analysis types check the file reference.yaml.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
analysis_type : str: The type of analysis to be created. This should be a valid analysis type recognized by the Spectre session.
analysis_name : str: The name to assign to the new analysis. This name must be unique within the session.

Returns

bool: True if the analysis was successfully created, False if the command failed to execute.

def get_analysis_parameter(session, analysis_name, parameter_name) ‑> list[tuple[str, str]]

Retrieve the attributes and their values for a specified parameter in a given analysis.

This function sends a command to the Spectre session to list all attributes associated with a specific parameter of a specified analysis. It then parses the command output and returns a list of tuples, where each tuple contains an attribute name and its corresponding value.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
analysis_name : str: The name of the analysis for which the parameter attributes are to be retrieved. This should be a valid analysis name within the current Spectre session.
parameter_name : str: The name of the parameter whose attributes and values are to be retrieved. This should be a valid parameter name within the specified analysis.

Returns

list[tuple[str, str]]: A list of tuples where each tuple contains: - The name of the attribute (str). - The value of the attribute (str).

def get_circuit_parameter(session: Session, circuit_parameter: str) ‑> list[tuple[str, str]]

Retrieve the attributes and their values for a specified circuit parameter.

This function sends a command to the Spectre session to list all attributes associated with a specified circuit parameter. It then parses the command output and returns a list of tuples, where each tuple contains an attribute name and its corresponding value.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
circuit_parameter : str: The name of the circuit parameter whose attributes and values are to be retrieved. This should be a valid circuit parameter name within the current Spectre session.

Returns

list[tuple[str, str]]: A list of tuples where each tuple contains: - The name of the attribute (str). - The value of the attribute (str).

def get_instance_parameter(session: Session, instance_name: str, instance_parameter: str) ‑> list[tuple[str, str]]

Retrieve the attributes and their values for a specified parameter of an instance.

This function sends a command to the Spectre session to list all attributes associated with a specific parameter of a given instance. It then parses the command output and returns a list of tuples, where each tuple contains an attribute name and its corresponding value.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
instance_name : str: The name of the instance whose parameter attributes are to be retrieved. This should be a valid instance name within the current Spectre session.
instance_parameter : str: The name of the parameter whose attributes and values are to be retrieved. This should be a valid parameter name within the specified instance.

Returns

list[tuple[str, str]]: A list of tuples where each tuple contains: - The name of the attribute (str). - The value of the attribute (str).

def get_parameter(session: Session, param: str) ‑> float

Retrieve the value of a specified netlist parameter in the Spectre session.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
param : str: The name of the netlist parameter whose value is to be retrieved.

Returns

float: The current value of the specified netlist parameter.

def get_parameters(session: Session, params: Iterable[str]) ‑> Dict[str, float]

Retrieve the values of a set of netlist parameters in the Spectre session.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
params : Iterable[str]: An iterable of strings, where each string is the name of a netlist parameter whose value is to be retrieved.

Returns

Dict[str, float]: A dictionary where the keys are the names of the specified parameters and the values are the corresponding parameter values retrieved from the netlist.

def get_yaml(file_name: str) ‑> dict

Load and return a YAML file.

Parameters

file_name : str: The name of the YAML file

Returns

dict: A dictionary containing the configuration data loaded from the YAML file.

Raises

FileNotFoundError: If the specified configuration file does not exist.

def list_analyses(session: Session) ‑> list[str]

Retrieve all simulation analyses from the current interactive Spectre session.

This function sends a command to the Spectre session to list all available simulation analyses. It then parses the command output and returns a list of analysis names.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.

Returns

list[str]: A list of strings where each string is the name of a simulation analysis available in the current Spectre session.

def list_analysis_parameters(session: Session, analysis_name: str) ‑> list[str]

Retrieve a list of parameters for a specified analysis in the current Spectre session.

This function sends a command to the Spectre session to list all parameters associated with a specified analysis. It then parses the command output and returns a list of parameter names.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
analysis_name : str: The name of the analysis for which to list the parameters. This should be a valid analysis name within the current Spectre session.

Returns

list[str]: A list of strings where each string is the name of a parameter associated with the specified analysis in the current Spectre session.

def list_analysis_types(session: Session) ‑> list[tuple[str, str]]

Retrieve all available analysis types in the current Spectre session.

This function sends a command to the Spectre session to retrieve detailed information about a specific analysis type (in this case, "ac"). It then parses the command output to extract and return a list of analysis types and their descriptions.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.

Returns

list[tuple[str, str]]: A list of tuples, where each tuple contains: - The name of the analysis type as the first element (str). - A description about the analysis type as the second element (str).

def list_circuit_parameters(session: Session) ‑> list[str]

Retrieve a list of all circuit parameters in the current Spectre session.

This function sends a command to the Spectre session to list all available circuit parameters. It then parses the command output and returns a list of parameter names.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.

Returns

list[str]: A list of strings where each string is the name of a circuit parameter available in the current Spectre session.

def list_instance_parameters(session: Session, instance_name: str) ‑> list[tuple[str, str]]

Retrieve the parameters and their values for a specified instance.

This function sends a command to the Spectre session to list all parameters associated with a specific instance. It then parses the command output and returns a list of tuples, where each tuple contains a parameter name and its corresponding value.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
instance_name : str: The name of the instance whose parameters are to be retrieved. This should be a valid instance name within the current Spectre session.

Returns

list[tuple[str, str]]: A list of tuples where each tuple contains: - The name of the parameter (str). - The value of the parameter (str).

def list_instances(session: Session) ‑> list[str]

Retrieve a list of all components inthe circuit.

This function sends a command to the Spectre session to list all available instances. It then parses the command output and returns a list of instance names.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.

Returns

list[str]: A list of strings where each string is the name of an component or instance available in the current Spectre session.

def list_nets(session: Session) ‑> list[str]

Retrieve a list of all nets in the circuit.

This function sends a command to the Spectre session to list all available nets. It then parses the command output and returns a list of net names.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.

Returns

list[str]: A list of strings where each string is the name of a net available in the current Spectre session.

def log_fifo(log_path: str) ‑> str

Create fifo buffer for spectre log file

def netlist_to_tmp(netlist: str) ‑> str

Write a netlist to a temporary file

def raw_tmp(net_path: str) ‑> str

Raw simulation results in /tmp

def read_results(raw_file: str, offset: int = 0) ‑> Dict[str, pandas.core.frame.DataFrame]

Read simulation results

def run_all(session: Session) ‑> Dict[str, pandas.core.frame.DataFrame]

Run all simulation analyses in the Spectre session and retrieve the results.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.

Returns

Dict[str, DataFrame]: A dictionary where the keys are the names of the analyses, and the values are pandas DataFrames containing the results of each analysis.

def run_analysis(session: Session, analysis: str) ‑> Dict[str, pandas.core.frame.DataFrame]

Run a specific analysis in the active Spectre session.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
analysis : str: The name of the analysis to be run. This should correspond to an analysis that is recognized by the Spectre session.

Returns

Dict[str, DataFrame]: A dictionary where the keys are the names of the analysis results, and the values are pandas DataFrames containing the data from each result.

def run_command(session: Session, command: str) ‑> bool

Execute an arbitrary SCL command within an active Spectre session.

This internal function sends a specified command to the Spectre process and checks the process's response. It returns True if the command was successful based on the process's output, and False otherwise. If an error is detected, a warning is issued indicating that Spectre might have crashed.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session includes the process handle (repl) and expected output prompt.
command : str: The SCL command to be executed in the Spectre session.

Returns

bool: True if the command was executed successfully (i.e., the expected prompt was received after the command). False if the command execution did not result in the expected output.

Raises

RuntimeError: If the Spectre session is no longer active (i.e., the process has terminated), making it impossible to execute the command.

Warns

RuntimeWarning: If the Spectre process does not return the expected prompt, indicating that the process might have crashed.

def set_analysis_parameter(session: Session, analysis_name: str, parameter_name: str, attribute_name: str, value: str) ‑> bool

Set the value of a specific attribute for a parameter in a given analysis.

This function sends a command to the Spectre session to set the value of a specified attribute for a parameter within a particular analysis. The command is constructed based on the provided analysis name, parameter name, attribute name, and the new value.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
analysis_name : str: The name of the analysis that contains the parameter to be modified. This should be a valid analysis name within the current Spectre session.
parameter_name : str: The name of the parameter whose attribute is to be set. This should be a valid parameter name within the specified analysis.
attribute_name : str: The name of the attribute to be modified. This should be a valid attribute name for the specified parameter.
value : str: The new value to set for the specified attribute.

Returns

bool: True if the command to set the attribute was successfully executed, False otherwise.

def set_circuit_parameter(session: Session, circuit_parameter: str, attribute_name: str, value: str) ‑> bool

Set the value of a specific attribute for a circuit parameter in the current Spectre session.

This function sends a command to the Spectre session to set the value of a specified attribute for a circuit parameter. The command is constructed based on the provided circuit parameter name, attribute name, and the new value.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
circuit_parameter : str: The name of the circuit parameter whose attribute is to be set. This should be a valid circuit parameter name within the current Spectre session.
attribute_name : str: The name of the attribute to be modified. This should be a valid attribute name for the specified circuit parameter.
value : str: The new value to set for the specified attribute.

Returns

bool: True if the command to set the attribute was successfully executed, False otherwise.

def set_instance_parameter(session: Session, instance_name: str, instance_parameter: str, attribute_name: str, value: str) ‑> bool

Set the value of a specific attribute for a parameter of an instance.

This function sends a command to the Spectre session to set the value of a specified attribute for a parameter within a particular instance. The command is constructed based on the provided instance name, parameter name, attribute name, and the new value.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
instance_name : str: The name of the instance that contains the parameter to be modified. This should be a valid instance name within the current Spectre session.
instance_parameter : str: The name of the parameter whose attribute is to be set. This should be a valid parameter name within the specified instance.
attribute_name : str: The name of the attribute to be modified. This should be a valid attribute name for the specified parameter.
value : str: The new value to set for the specified attribute.

Returns

bool: True if the command to set the attribute was successfully executed, False otherwise.

def set_parameter(session: Session, param: str, value: float) ‑> bool

Change the value of a netlist parameter in the Spectre session.

This function sends a command to the Spectre session to update the value of a specified parameter in the netlist. It returns True if the parameter value was successfully changed, and False otherwise.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
param : str: The name of the netlist parameter whose value is to be changed.
value : float: The new value to be assigned to the specified parameter.

Returns

bool: True if the parameter value was successfully updated, False if the command failed or the parameter could not be changed.

def set_parameters(session: Session, params: Dict[str, float]) ‑> bool

Set the values for a list of netlist parameters in the Spectre session.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
params : Dict[str, float]: A dictionary where the keys are the names of the netlist parameters and the values are the new values to be assigned to those parameters.

Returns

bool: True if all parameters were successfully updated, False if any of the parameter updates failed.

def setup_command(path: str)

def simulate(netlist_path: str, includes: List[str] = None, raw_path: str = None, log_path: str = None, log_silent=True) ‑> Dict[str, pandas.core.frame.DataFrame]

Passes the given netlist path to spectre and reads the results in.

def simulate_netlist(netlist: str, **kwargs) ‑> Dict[str, pandas.core.frame.DataFrame]

Takes a netlist as text, creates a temporary file and simulates it. The results are read in and all temp files will be destroyed.

def start_session(net_path: str, includes: Optional[list[str]] = None, raw_path: Optional[str] = None, config_path: str = '') ‑> Session

Start a Spectre interactive session.

Parameters

net_path : str: The file path to the netlist that will be used in the Spectre session. This file must exist and be readable.
includes : List[str], optional: A list of directory paths to be included with the -I option in the Spectre command. Each path will be expanded if necessary. Defaults to None.
raw_path : str, optional: The file path where the raw output will be stored. If not provided, a temporary raw file path is generated based on the netlist file name. Defaults to None.
config_path : str, optional: Path to a yaml file that configures the spectre executable. See config.yaml as example.

Returns

Session: An instance of the Session class, representing the active Spectre session, which includes the session's configuration and the active process handle.

Raises

FileNotFoundError: If the netlist file specified by net_path does not exist.
PermissionError: If the netlist file specified by net_path is not readable.
IOError: If the Spectre session fails to start due to an input/output error with the command execution.

def stop_session(session, remove_raw: bool = False) ‑> bool

Quit the Spectre interactive session and close the terminal.

This function attempts to gracefully quit the Spectre interactive session by sending the (sclQuit) command. If Spectre refuses to exit gracefully, it forces termination of the session. Optionally, it can also remove the raw output file associated with the session.

Parameters

session : Session: An instance of the Session class representing the active Spectre session. The session contains necessary information, including the raw output file and the current offset for reading results.
remove_raw : bool, optional: If True, the raw output file associated with the session will be deleted after the session is stopped. Defaults to False.

Returns

bool: True if the session was successfully terminated (whether gracefully or by force), False otherwise.

Warns

RuntimeWarning: If the session refuses to exit gracefully and is forcibly terminated.

Classes

class Session (net_file: str, raw_file: str, repl: pyspectre.core.REPL, prompt: str, succ: str, fail: str, offset: int)

Represents an interactive Spectre session.

This class encapsulates the state and relevant information for an active Spectre session. It includes details about the netlist and raw output files, the instance managing the interaction with Spectre, and the prompts and patterns used for command success and failure detection.

Attributes

net_file : str: The path to the netlist file used in the Spectre session.
raw_file : str: The path to the raw output file generated by the Spectre session.
repl : REPL: An instance of the REPL class that handles the interactive communication with the Spectre process. This includes sending commands and receiving output.
prompt : str: The expected prompt string used to detect when the Spectre process is ready to accept the next command.
succ : str: The regular expression pattern used to identify successful command execution in the Spectre session.
fail : str: The regular expression pattern used to identify failed command execution in the Spectre session.
offset : int: The current offset used for reading results from the raw output file. This helps track the position in the file for incremental reads after each analysis.

Expand source code

@dataclass
class Session:
    """Represents an interactive Spectre session.

    This class encapsulates the state and relevant information for an active
    Spectre session. It includes details about the netlist and raw output files,
    the instance managing the interaction with Spectre,
    and the prompts and patterns used for command success and failure detection.

    Attributes
    ----------
    net_file : str
        The path to the netlist file used in the Spectre session.
    raw_file : str
        The path to the raw output file generated by the Spectre session.
    repl : REPL
        An instance of the `REPL` class that handles the interactive communication
        with the Spectre process. This includes sending commands and receiving output.
    prompt : str
        The expected prompt string used to detect when the Spectre process is ready
        to accept the next command.
    succ : str
        The regular expression pattern used to identify successful command execution
        in the Spectre session.
    fail : str
        The regular expression pattern used to identify failed command execution
        in the Spectre session.
    offset : int
        The current offset used for reading results from the raw output file. This
        helps track the position in the file for incremental reads after each analysis.
    """
    net_file: str
    raw_file: str
    repl: REPL
    prompt: str
    succ: str
    fail: str
    offset: int

Class variables

var fail : str
var net_file : str
var offset : int
var prompt : str
var raw_file : str
var repl : pyspectre.core.REPL
var succ : str