bag.simulation.core

Module Contents

Classes

TestbenchManager	A class that creates and setups up a testbench for simulation, then save the result.
MeasurementManager	A class that handles circuit performance measurement.
DesignSpecs	A class that parses the design specification file.
DesignManager	A class that manages instantiating design instances and running simulations.

Functions

_get_env_param_value(→ numpy.ndarray)

class bag.simulation.core.TestbenchManager(sim: Optional[bag.simulation.base.SimAccess], work_dir: pathlib.Path, tb_name: str, impl_lib: str, specs: Mapping[str, Any], sim_view_list: Optional[Sequence[Tuple[str, str]]], env_list: Optional[Sequence[str]], precision: int = 6, logger: Optional[pybag.core.FileLogger] = None)

Bases: abc.ABC

A class that creates and setups up a testbench for simulation, then save the result.

This class is used by MeasurementManager to run simulations.

Parameters:

• sim (SimAccess) – the simulator interface object.

• work_dir (Path) – working directory path.

• tb_name (str) – testbench name.

• impl_lib (str) – unused. Remain for backward compatibility.

• specs (Mapping[str, Any]) – testbench specs.

• sim_view_list (Optional[Sequence[Tuple[str, str]]]) – unused. Remain for backward compatibility.

• env_list (Optional[Sequence[str]]) – unused. Remain for backward compatibility.

• precision (int) – numeric precision in simulation netlist generation.

• logger (Optional[FileLogger]) – the logger object.

Notes

The specification dictionary for all testbenches have the following entries:

sim_envsSequence[str]

list of simulation environments.

sim_paramsMapping[str, Any]

simulation parameters dictionary.

swp_infoUnion[Sequence[Any], Mapping[str, Any]]

Optional. the parameter sweep data structure.

sim_options: Mapping[str, Any]

Optional. Simulator-specific options.

monte_carlo_params: Mapping[str, Any]

Optional. If specified, will run Monte Carlo with the given parameters.

property logger: pybag.core.FileLogger

property specs: Dict[str, Any]

property swp_info: Union[Sequence[Any], Mapping[str, Any]]

property sim_params: Dict[str, Union[float, str]]

Simulation parameters dictionary, can be modified.

Type:

Dict[str, Union[float, str]]

property env_params: Dict[str, Dict[str, float]]

property num_sim_envs: int

property sim_envs: Sequence[str]

property tb_netlist_path: pathlib.Path

property sim_netlist_path: pathlib.Path

property work_dir: pathlib.Path

property precision: int

property sweep_shape: Tuple[int, Ellipsis]

abstract classmethod get_schematic_class() → Type[bag.design.module.Module]

classmethod get_sweep_shape(num_envs: int, swp: Union[Sequence[Any], Mapping[str, Any]]) → Tuple[int, Ellipsis]

abstract get_netlist_info() → bag.simulation.data.SimNetlistInfo

Returns the netlist information object.

Returns:

netlist_info – the simulation netlist information object.

Return type:

SimNetlistInfo

set_sim_envs(env_list: Sequence[str]) → None

set_swp_info(new_swp: Union[Sequence[Any], Mapping[str, Any]]) → None

commit() → None

Commit changes to specs dictionary. Perform necessary initialization.

pre_setup(sch_params: Optional[Mapping[str, Any]]) → Optional[Mapping[str, Any]]

Override to perform any operations prior to calling the setup() function.

Parameters:

sch_params – the testbench schematic parameters. None means the previous testbench will be reused. This dictionary should not be modified.

Returns:

the schematic parameters to use. Could be a modified copy of the original.

Return type:

new_params

print_results(data: bag.simulation.data.SimData) → None

Override to print results.

get_netlist_info_dict() → Dict[str, Any]

Returns a dictionary representing the SimNetlistInfo object.

This is a helper function that performs common boiler-plate setup (set corners, swp_info, sim_params, etc.)

get_env_param_value(name: str, sim_envs: Sequence[str]) → numpy.ndarray

get_sim_param_value(val: Union[float, str]) → float

get_param_value(name: str, data: bag.simulation.data.SimData) → numpy.ndarray

get_calculator(data: bag.simulation.data.SimData) → bag.util.math.Calculator

get_sim_param_string(val: Union[float, str]) → str

update(work_dir: pathlib.Path, tb_name: str, sim: Optional[bag.simulation.base.SimAccess] = None) → None

Update the working directory and testbench name.

This method allows you to reuse the same testbench manager objects for different testbenches.

setup(sch_db: bag.design.database.ModuleDB, sch_params: Optional[Mapping[str, Any]], cv_info_list: List[Any], cv_netlist_list: List[pathlib.Path], gen_sch: bool = True, work_dir: Optional[pathlib.Path] = None, tb_name: str = '', va_cvinfo_list: Optional[List[Any]] = None) → None

async async_simulate() → None

simulate() → None

load_sim_data() → bag.simulation.data.SimData

log(msg: str, level: pybag.enum.LogLevel = LogLevel.INFO) → None

error(msg: str) → None

bag.simulation.core._get_env_param_value(sim_envs: Sequence[str], data_shape: Tuple[int, Ellipsis], val_table: Mapping[str, float]) → numpy.ndarray

class bag.simulation.core.MeasurementManager(sim: bag.simulation.base.SimAccess, dir_path: pathlib.Path, meas_name: str, impl_lib: str, specs: Dict[str, Any], wrapper_lookup: Dict[str, str], sim_view_list: Sequence[Tuple[str, str]], env_list: Sequence[str], precision: int = 6)

Bases: abc.ABC

A class that handles circuit performance measurement.

This class handles all the steps needed to measure a specific performance metric of the device-under-test. This may involve creating and simulating multiple different testbenches, where configuration of successive testbenches depends on previous simulation results. This class reduces the potentially complex measurement tasks into a few simple abstract methods that designers simply have to implement.

Parameters:

• sim (SimAccess) – the simulator interface object.

• dir_path (Path) – Simulation data directory.

• meas_name (str) – measurement setup name.

• impl_lib (str) – implementation library name.

• specs (Dict[str, Any]) – the measurement specification dictionary.

• wrapper_lookup (Dict[str, str]) – the DUT wrapper cell name lookup table.

• sim_view_list (Sequence[Tuple[str, str]]) – simulation view list

• env_list (Sequence[str]) – simulation environments list.

• precision (int) – numeric precision in simulation netlist generation.

property specs: Dict[str, Any]

property data_dir: pathlib.Path

property sim_envs: Sequence[str]

abstract get_initial_state() → str

Returns the initial FSM state.

get_testbench_info(state: str, prev_output: Optional[Dict[str, Any]]) → Tuple[str, str, Dict[str, Any], Optional[Dict[str, Any]]]

Get information about the next testbench.

Override this method to perform more complex operations.

Parameters:

• state (str) – the current FSM state.

• prev_output (Optional[Dict[str, Any]]) – the previous post-processing output.

Returns:

• tb_name (str) – cell name of the next testbench. Should incorporate self.meas_name to avoid collision with testbench for other designs.

• tb_type (str) – the next testbench type.

• tb_specs (Dict[str, Any]) – the testbench specification dictionary.

• tb_params (Optional[Dict[str, Any]]) – the next testbench schematic parameters. If we are reusing an existing testbench, this should be None.

abstract process_output(state: str, data: bag.simulation.data.SimData, tb_manager: TestbenchManager) → Tuple[bool, str, Dict[str, Any]]

Process simulation output data.

Parameters:

• state (str) – the current FSM state

• data (SimData) – simulation data dictionary.

• tb_manager (TestbenchManager) – the testbench manager object.

Returns:

• done (bool) – True if this measurement is finished.

• next_state (str) – the next FSM state.

• output (Dict[str, Any]) – a dictionary containing post-processed data.

get_testbench_name(tb_type: str) → str

Returns a default testbench name given testbench type.

async async_measure_performance(sch_db: Optional[bag.design.database.ModuleDB], dut_cvi_list: List[Any], dut_netlist: Optional[pathlib.Path], load_from_file: bool = False, gen_sch: bool = True) → Dict[str, Any]

A coroutine that performs measurement.

The measurement is done like a FSM. On each iteration, depending on the current state, it creates a new testbench (or reuse an existing one) and simulate it. It then post-process the simulation data to determine the next FSM state, or if the measurement is done.

Parameters:

• sch_db (Optional[ModuleDB]) –

  the schematic database.

  if load_from_file is True, this can be None. as it will not be used unless necessary.

• dut_cvi_list (List[str]) –

  cv_info for DUT cell netlist

  if load_from_file is True, this will not be used unless necessary.

• dut_netlist (Optional[Path]) –

  netlist of DUT cell

  if load_from_file is True, this will not be used unless necessary.

• load_from_file (bool) – If True, then load existing simulation data instead of running actual simulation.

• gen_sch (bool) – True to create testbench schematics.

Returns:

output – the last dictionary returned by process_output().

Return type:

Dict[str, Any]

measure_performance(sch_db: Optional[bag.design.database.ModuleDB], dut_cvi_list: List[Any], dut_netlist: Optional[pathlib.Path], load_from_file: bool = False, gen_sch: bool = True) → Dict[str, Any]

get_state_output(state: str) → Dict[str, Any]

Get the post-processed output of the given state.

get_testbench_specs(tb_type: str) → Dict[str, Any]

Helper method to get testbench specifications.

get_default_tb_sch_params(tb_type: str) → Dict[str, Any]

Helper method to return a default testbench schematic parameters dictionary.

This method loads default values from specification file, the fill in dut_lib and dut_cell for you.

Parameters:

tb_type (str) – the testbench type.

Returns:

sch_params – the default schematic parameters dictionary.

Return type:

Dict[str, Any]

class bag.simulation.core.DesignSpecs(spec_file: str, spec_dict: Optional[Dict[str, Any]] = None)

A class that parses the design specification file.

property root_dir: pathlib.Path

property swp_var_list: bag.util.immutable.ImmutableList[str]

property dut_lib: str

property dut_cell: str

property impl_lib: str

property env_list: List[str]

property view_name: str

property dsn_basename: str

property summary_fname: str

property specs: Dict[str, Any]

property create_layout: bool

property first_params: Dict[str, Any]

get_data_dir(dsn_name: str, meas_type: str) → pathlib.Path

Returns the data directory path for the given measurement.

get_swp_values(var: str) → List[Any]

Returns a list of valid sweep variable values.

Parameter

varstr

the sweep variable name.

returns:

val_list – the sweep values of the given variable.

rtype:

List[Any]

swp_combo_iter() → Iterable[Tuple[Any, Ellipsis]]

Returns an iterator of schematic parameter combinations we sweep over.

Returns:

combo_iter – an iterator of tuples of schematic parameters values that we sweep over.

Return type:

Iterable[Tuple[Any, …]]

dsn_param_iter() → Iterable[Tuple[str, Dict[str, Any]]]

Returns an iterator of design cell name and the parameter dictionary.

dsn_name_iter() → Iterable[str]

get_layout_class() → Type[bag.layout.template.TemplateBase]

get_design_name(combo_list: Sequence[Any]) → str

_get_params(combo_list: Sequence[Any]) → Dict[str, Any]

class bag.simulation.core.DesignManager(prj: bag.core.BagProject, spec_file: str = '', spec_dict: Optional[Dict[str, Any]] = None, sch_db: Optional[bag.design.database.ModuleDB] = None, lay_db: Optional[bag.layout.template.TemplateDB] = None)

A class that manages instantiating design instances and running simulations.

This class provides various methods to allow you to sweep design parameters and generate multiple instances at once. It also provides methods for running simulations and helps you interface with TestbenchManager instances.

Parameters:

• prj (BagProject) – The BagProject instance.

• spec_file (str) – the specification file name or the data directory.

property info: DesignSpecs

Return the specification dictionary.

classmethod load_state(prj: bag.core.BagProject, root_dir: str) → DesignManager

Create the DesignManager instance corresponding to data in the given directory.

classmethod get_wrapper_name(dut_name: str, wrapper_name: str) → str

Returns the wrapper cell name corresponding to the given DUT.

async extract_design(lib_name: str, dsn_name: str, rcx_params: Optional[Dict[str, Any]], netlist: Optional[pathlib.Path]) → pathlib.Path

A coroutine that runs LVS/RCX on a given design.

Parameters:

• lib_name (str) – library name.

• dsn_name (str) – design cell name.

• rcx_params (Optional[Dict[str, Any]]) – extraction parameters dictionary.

• netlist (Path) – CDL netlist path

Returns:

rcx_netlist – extracted netlist path

Return type:

Path

async verify_design(lib_name: str, dsn_name: str, dut_cvi_list: List[Any], dut_netlist: pathlib.Path, load_from_file: bool = False, gen_sch: bool = True) → None

Run all measurements on the given design.

Parameters:

• lib_name (str) – library name.

• dsn_name (str) – design cell name.

• dut_cvi_list (List[str]) – cv_info for DUT cell netlist

• dut_netlist (Path) – netlist of DUT cell

• load_from_file (bool) – If True, then load existing simulation data instead of running actual simulation.

• gen_sch (bool) – True to create testbench schematics.

async main_task(lib_name: str, dsn_name: str, rcx_params: Optional[Dict[str, Any]], dut_cv_info_list: List[str], dut_cdl_netlist: pathlib.Path, dut_sim_netlist: pathlib.Path, extract: bool = True, measure: bool = True, load_from_file: bool = False, gen_sch: bool = True, mismatch: bool = False) → None

The main coroutine.

characterize_designs(generate: bool = True, measure: bool = True, load_from_file: bool = False, gen_sch: bool = True, mismatch: bool = False) → None

Sweep all designs and characterize them.

Parameters:

• generate (bool) – If True, create schematic/layout and run LVS/RCX.

• measure (bool) – If True, run all measurements.

• load_from_file (bool) – If True, measurements will load existing simulation data instead of running simulations.

• gen_sch (bool) – If True, schematics will be generated.

• mismatch (bool) – If True, add mismatch offset voltage sources to netlist

get_result(dsn_name: str) → Dict[str, Any]

Returns the measurement result summary dictionary.

Parameters:

dsn_name (str) – the design name.

Returns:

result – the result dictionary.

Return type:

Dict[str, Any]

test_layout(gen_sch: bool = True) → None

Create a test schematic and layout for debugging purposes

create_designs(gen_sch: bool = True, flat_sch_netlist: bool = False) → List[Tuple[str, List[Any], pathlib.Path, pathlib.Path]]

Create DUT schematics/layouts.

create_dut_schematics(name_param_iter: Iterable[Tuple[str, Dict[str, Any]]], gen_wrappers: bool = True, gen_sch: bool = True, flat_sch_netlist: bool = False) → List[Tuple[str, List[Any], pathlib.Path, pathlib.Path]]

create_dut_layouts(name_param_iter: Iterable[Tuple[str, Dict[str, Any]]]) → Sequence[Tuple[str, Dict[str, Any]]]

Create multiple layouts