2. Core API#
This chapter describes all public methods in the SiliconCompiler core Python API. Refer to the User Guide for architecture concepts and the Glossary for terminology and keyword definitions.
Schema access:
Sets a schema parameter field. |
|
Adds item(s) to a schema parameter list. |
|
Returns a schema parameter field. |
|
Returns a list of schema dictionary keys. |
|
Returns a schema dictionary. |
|
Checks validity of a keypath. |
|
Returns a schema parameter description. |
|
Unsets a schema parameter. |
|
Remove a schema parameter and its subparameters. |
Flowgraph execution:
Executes tasks in a flowgraph. |
|
Creates a flowgraph node. |
|
Creates a directed edge from a tail node to a head node. |
|
Remove a flowgraph node. |
Utility functions:
Archive a job directory. |
|
Check items in a checklist. |
|
Verifies the integrity of the pre-run compilation manifest. |
|
Clock configuration helper function. |
|
Collects files found in the configuration dictionary and places them in inputs/. |
|
Creates an SC command line interface. |
|
Open a session of the dashboard. |
|
Returns absolute paths to files or directories based on the keypath provided. |
|
Returns the absolute path of a compilation result. |
|
Get absolute path to work directory for a given step/index, if step/index not given, job directory is returned |
|
Generates hash values for a list of parameter files. |
|
Reads a manifest from disk and merges it with the current compilation manifest. |
|
Opens a graphical viewer for the filename provided. |
|
Prints a summary of the compilation manifest. |
|
Creates a snapshot image of the job |
|
Loads a SiliconCompiler module into the current chip object. |
|
Writes the compilation manifest to a file. |
|
Renders and saves the compilation flowgraph to a file. |
|
Calculates the area of a rectilinear diearea. |
|
Calculates raw die yield. |
|
Calculates dies per wafer. |
|
Emulates the Unix grep command on a string. |
Tool driver utility functions:
Returns a list of libraries included in this step/index |
|
Adds input files to the require list of the task. |
|
Returns a list of files from the key input and includes files from libraries if requested. |
|
Adds keys to the require list for the frontend task and checks if options are set, which the current frontend does not support. |
|
Returns a dictionary of options set for the frontend and checks if options are set, which the current frontend does not support. |
- class siliconcompiler.Checklist(*args)[source]#
Object for configuring a checklist. This is the main object used for configuration and data for a checklist within the SiliconCompiler platform.
This inherits all methods from
Chip
.- Parameters:
name (string) – Name of the checklist.
Examples
>>> siliconcompiler.Checklist("tapeout") Creates a checklist object with name "tapeout".
- class siliconcompiler.Chip(design, loglevel=None)[source]#
Object for configuring and executing hardware design flows.
This is the main object used for configuration, data, and execution within the SiliconCompiler platform.
- Parameters:
design (string) – Name of the top level chip design module.
Examples
>>> siliconcompiler.Chip(design="top") Creates a chip object with name "top".
- add(*args, field='value', step=None, index=None, package=None)[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args
. See the Schema Reference Manual for documentation of all supported keypaths. New schema dictionaries are automatically created for keypaths that overlap with ‘default’ dictionaries.The value provided must agree with the dictionary parameter ‘type’. Accessing a non-existent keypath, providing a value that disagrees with the parameter type, or using add with a scalar parameter produces a logger error message and raises the Chip object error flag.
- Parameters:
args (list) – Parameter keypath followed by a value to add.
field (str) – Parameter field to modify.
step (str) – Step name to modify for parameters that may be specified on a per-node basis.
index (str) – Index name to modify for parameters that may be specified on a per-node basis.
package (str) – Package that this file/dir depends on. Available packages are listed in the package source section of the schema.
Examples
>>> chip.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the list of sources.
- allkeys(*keypath_prefix)[source]#
Returns all keypaths in the schema as a list of lists.
- Arg:
- keypath_prefix (list str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- archive(jobs=None, step=None, index=None, include=None, archive_name=None)[source]#
Archive a job directory.
Creates a single compressed archive (.tgz) based on the design, jobname, and flowgraph in the current chip manifest. Individual steps and/or indices can be archived based on arguments specified. By default, all steps and indices in the flowgraph are archived. By default, only outputs, reports, log files, and the final manifest are archived.
- Parameters:
jobs (list of str) – List of jobs to archive. By default, archives only the current job.
step (str) – Step to archive.
index (str) – Index to archive
include (list of str) – Override of default inclusion rules. Accepts list of glob patterns that are matched from the root of individual step/index directories. To capture all files, supply “*”.
archive_name (str) – Path to the archive
- check_checklist(standard, items=None, check_ok=False, verbose=False, require_reports=True)[source]#
Check items in a checklist.
Checks the status of items in a checklist for the standard provided. If a specific list of items is unspecified, all items are checked.
All items have an associated ‘task’ parameter, which indicates which tasks can be used to automatically validate the item. For an item to be checked, all tasks must satisfy the item’s criteria, unless waivers are provided. In addition, that task must have generated EDA report files for each metric in the criteria.
For items without an associated task, the only requirement is that at least one report has been added to that item.
When ‘check_ok’ is True, every item must also have its ‘ok’ parameter set to True, indicating that a human has reviewed the item.
- Parameters:
standard (str) – Standard to check.
items (list of str) – Items to check from standard.
check_ok (bool) – Whether to check item ‘ok’ parameter.
verbose (bool) – Whether to print passing criteria.
require_reports (bool) – Whether to assert the presence of reports.
- Returns:
Status of item check.
Examples
>>> status = chip.check_checklist('iso9000', 'd000') Returns status.
- check_filepaths()[source]#
Verifies that paths to all files in manifest are valid.
- Returns:
True if all file paths are valid, otherwise False.
- check_manifest()[source]#
Verifies the integrity of the pre-run compilation manifest.
Checks the validity of the current schema manifest in memory to ensure that the design has been properly set up prior to running compilation. The function is called inside the run() function but can also be called separately. Checks performed by the check_manifest() function include:
Has a flowgraph been defined?
Does the manifest satisfy the schema requirement field settings?
Are all flowgraph input names legal step/index pairs?
Are the tool parameter setting requirements met?
- Returns:
Returns True if the manifest is valid, else returns False.
Examples
>>> manifest_ok = chip.check_manifest() Returns True of the Chip object dictionary checks out.
- clock(pin, period, jitter=0, mode='global')[source]#
Clock configuration helper function.
A utility function for setting all parameters associated with a single clock definition in the schema.
The method modifies the following schema parameters:
[‘datasheet’, ‘pin’, pin, ‘type’, mode] [‘datasheet’, ‘pin’, pin, ‘tperiod’, mode] [‘datasheet’, ‘pin’, pin, ‘tjitter’, mode]
- Parameters:
pin (str) – Full hierarchical path to clk pin.
period (float) – Clock period specified in ns.
jitter (float) – Clock jitter specified in ns.
mode (str) – Mode of operation (from datasheet).
Examples
>>> chip.clock('clk', period=1.0)
Create a clock named ‘clk’ with a 1.0ns period.
- collect(directory=None, verbose=True, whitelist=None, exclude_packages=None)[source]#
Collects files found in the configuration dictionary and places them in inputs/. The function only copies in files that have the ‘copy’ field set as true.
indexing like in run, job1
chdir package
run tool to collect files, pickle file in output/design.v
copy in rest of the files below
record files read in to schema
- Parameters:
directory (filepath) – Output filepath
verbose (bool) – Flag to indicate if logging should be used
whitelist (list[path]) – List of directories that are allowed to be collected. If a directory is is found that is not on this list a RuntimeError will be raised.
package_filter (list[str]) – List of packages to exclude from collection.
- create_cmdline(progname=None, description=None, switchlist=None, input_map=None, additional_args=None)[source]#
Creates an SC command line interface.
Exposes parameters in the SC schema as command line switches, simplifying creation of SC apps with a restricted set of schema parameters exposed at the command line. The order of command line switch settings parsed from the command line is as follows:
loglevel
read_manifest([cfg])
read compiler inputs
all other switches
use(target)
The cmdline interface is implemented using the Python argparse package and the following use restrictions apply.
Help is accessed with the ‘-h’ switch.
Arguments that include spaces must be enclosed with double quotes.
List parameters are entered individually. (ie. -y libdir1 -y libdir2)
For parameters with Boolean types, the switch implies “true”.
Special characters (such as ‘-’) must be enclosed in double quotes.
Compiler compatible switches include: -D, -I, -O{0,1,2,3}
Verilog legacy switch formats are supported: +libext+, +incdir+
- Parameters:
progname (str) – Name of program to be executed.
description (str) – Short program description.
switchlist (list of str) – List of SC parameter switches to expose at the command line. By default all SC schema switches are available. Parameter switches should be entered based on the parameter ‘switch’ field in the schema. For parameters with multiple switches, both will be accepted if any one is included in this list.
input_map (dict of str) – Dictionary mapping file extensions to input filetypes. This is used to automatically assign positional source arguments to [‘input’, ‘fileset’, …] keypaths based on their file extension. If None, the CLI will not accept positional source arguments.
additional_args (dict of dict) – Dictionary of extra arguments to add to the command line parser, with the arguments matching the argparse.add_argument() call.
- Returns:
- None if additional_args is not provided, otherwise a dictionary with the
command line options detected from the additional_args
Examples
>>> chip.create_cmdline(progname='sc-show',switchlist=['-input','-cfg']) Creates a command line interface for 'sc-show' app.
>>> chip.create_cmdline(progname='sc', input_map={'v': ('rtl', 'verilog')}) All sources ending in .v will be stored in ['input', 'rtl', 'verilog']
>>> extra = chip.create_cmdline(progname='sc', additional_args={'-demo': {'action': 'store_true'}}) Returns extra = {'demo': False/True}
- dashboard(wait=True, port=None, graph_chips=None, type=DashboardType.WEB)[source]#
Open a session of the dashboard.
The dashboard can be viewed in any webbrowser and can be accessed via: http://localhost:<port>/
- Parameters:
wait (bool) – If True, this call will wait in this method until the dashboard has been closed.
port (int) – An integer specifying which port to display the dashboard to.
graph_chips (list) – A list of dictionaries of the format {‘chip’: chip object, ‘name’: chip name}
type (enum) – A string specifying what kind of dashboard to launch. Available options: ‘cli’, ‘web’.
Examples
>>> chip.dashboard() Opens a sesison of the dashboard.
- property design#
Design name of chip object.
This is an immutable property.
- edge(flow, tail, head, tail_index=0, head_index=0)[source]#
Creates a directed edge from a tail node to a head node.
Connects the output of a tail node with the input of a head node by setting the ‘input’ field of the head node in the schema flowgraph.
The method modifies the following parameters:
[‘flowgraph’, flow, head, str(head_index), ‘input’]
- Parameters:
flow (str) – Name of flow
tail (str) – Name of tail node
head (str) – Name of head node
tail_index (int/str) – Index of tail node to connect
head_index (int/str) – Index of head node to connect
Examples
>>> chip.edge('place', 'cts') Creates a directed edge from place to cts.
- error(msg)[source]#
Raises error.
If
['option', 'continue']
is set to True, this will log an error and set an internal error flag that will cause run() to quit.- Parameters:
msg (str) – Message associated with error
- find_files(*keypath, missing_ok=False, job=None, step=None, index=None)[source]#
Returns absolute paths to files or directories based on the keypath provided.
By default, this function first checks if the keypath provided has its copy parameter set to True. If so, it returns paths to the files in the build directory. Otherwise, it resolves these files based on the current working directory and SC path.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
keypath (list str) – Variable length schema key list.
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
job (str) – Jobname to use for dictionary access in place of the current active jobname.
step (str) – Step name to access for parameters that may be specified on a per-node basis.
index (str) – Index name to access for parameters that may be specified on a per-node basis.
- Returns:
If keys points to a scalar entry, returns an absolute path to that file/directory, or None if not found. It keys points to a list entry, returns a list of either the absolute paths or None for each entry, depending on whether it is found.
Examples
>>> chip.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- find_node_file(path, step, jobname=None, index='0')[source]#
Returns the absolute path of a file from a particular node.
Utility function that returns the absolute path to a node file based on the provided arguments. The result directory structure is:
<dir>/<design>/<jobname>/<step>/<index>/<path>
- Parameters:
path (str) – Path to file inside node run directory
step (str) – Task step name (‘syn’, ‘place’, etc)
jobname (str) – Jobid directory name
index (str) – Task index
- Returns:
Returns absolute path to file.
Examples
>>> manifest_filepath = chip.find_node_file('outputs/heartbeat.vg', 'syn')
Returns the absolute path to the gate level verilog.
- find_result(filetype, step, jobname=None, index='0')[source]#
Returns the absolute path of a compilation result.
Utility function that returns the absolute path to a results file based on the provided arguments. The result directory structure is:
<dir>/<design>/<jobname>/<step>/<index>/outputs/<design>.filetype
- Parameters:
filetype (str) – File extension (v, def, etc)
step (str) – Task step name (‘syn’, ‘place’, etc)
jobname (str) – Jobid directory name
index (str) – Task index
- Returns:
Returns absolute path to file.
Examples
>>> vg_filepath = chip.find_result('vg', 'syn')
Returns the absolute path to the gate level verilog.
- get(*keypath, field='value', job=None, step=None, index=None)[source]#
Returns a schema parameter field.
Returns a schema parameter field based on the keypath provided in the
*keypath
. See the Schema Reference Manual for documentation of all supported keypaths. The returned type is consistent with the type field of the parameter. Fetching parameters with empty or undefined value files returns None for scalar types and [] (empty list) for list types. Accessing a non-existent keypath produces a logger error message and raises the Chip object error flag.- Parameters:
keypath (list str) – Variable length schema key list.
field (str) – Parameter field to fetch.
job (str) – Jobname to use for dictionary access in place of the current active jobname.
step (str) – Step name to access for parameters that may be specified on a per-node basis.
index (str) – Index name to access for parameters that may be specified on a per-node basis.
- Returns:
Value found for the keypath and field provided.
Examples
>>> foundry = chip.get('pdk', 'foundry') Returns the name of the foundry from the PDK.
- getdict(*keypath)[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary. Accessing a non-existent keypath produces a logger error message and raises the Chip object error flag.
- Parameters:
keypath (list str) – Variable length ordered schema key list
- Returns:
A schema dictionary
Examples
>>> pdk = chip.getdict('pdk') Returns the complete dictionary found for the keypath 'pdk'
- getkeys(*keypath, job=None)[source]#
Returns a list of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key. Accessing a non-existent keypath produces a logger error message and raises the Chip object error flag.
- Parameters:
keypath (list str) – Variable length ordered schema key list
job (str) – Jobname to use for dictionary access in place of the current active jobname.
- Returns:
List of keys found for the keypath provided.
Examples
>>> keylist = chip.getkeys('pdk') Returns all keys for the 'pdk' keypath.
- getworkdir(jobname=None, step=None, index=None)[source]#
Get absolute path to work directory for a given step/index, if step/index not given, job directory is returned
- Parameters:
jobname (str) – Job name
step (str) – Node step name
index (str) – Node index
- graph(flow, subflow, name=None)[source]#
Instantiates a named flow as a graph in the current flowgraph.
- Parameters:
flow (str) – Name of current flow.
subflow (str) – Name of flow to instantiate
name (str) – Name of instance
Examples
>>> chip.graph('asicflow') Instantiates a flow named 'asicflow'.
- hash_files(*keypath, update=True, check=True, verbose=True, allow_cache=False, skip_missing=False, step=None, index=None)[source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the chip object manifest.
check (bool) – If True, checks the newly computed hash against the stored hash.
verbose (bool) – If True, generates log messages.
allow_cache (bool) – If True, hashing check the cached values for specific files, if found, it will use that hash value otherwise the hash will be computed.
skip_missing (bool) – If True, hashing will be skipped when missing files are detected.
- Returns:
A list of hash values.
Examples
>>> hashlist = hash_files('input', 'rtl', 'verilog') Computes, stores, and returns hashes of files in :keypath:`input, rtl, verilog`.
- help(*keypath)[source]#
Returns a schema parameter description.
- Parameters:
*keypath (str) – Keypath to parameter.
- Returns:
A formatted multi-line help paragraph for the parameter provided.
Examples
>>> print(chip.help('asic','diearea')) Displays help information about the 'asic, diearea' parameter
- import_flist(filename, package=None)[source]#
Add input files, include directories, and defines from an flist
- Parameters:
filename (path) – Path to flist file
package (str) – name of package
- input(filename, fileset=None, filetype=None, iomap=None, step=None, index=None, package=None)[source]#
Adds file to a filset. The default behavior is to infer filetypes and filesets based on the suffix of the file extensions. The method is a wrapper function for set.add(‘input’, filset, filetype,…)
Default filetype and filset based on suffix:
filetype | fileset | suffix (case insensitive) --------------|------------|--------------------------------------------- c | hll | c,cc,cpp,c++,cp,cxx,hpp,h llvm | hll | ll bsv | hll | bsv scala | hll | scala python | hll | py chisel | config | sbt verilog | rtl | v,verilog,vh systemverilog | rtl | sv,svh vhdl | rtl | vhd,vhdl liberty | timing | lib,ccs def | layout | def lef | layout | lef gds | layout | gds,gds2,gdsii oas | layout | oas,oasis gerber | layout | gbr,gerber odb | layout | odb cdl | netlist | cdl sp | netlist | sp,spice verilog | netlist | vg vcd | waveform | vcd sdc | constraint | sdc upf | constraint | upf pcf | constraint | pcf xdc | fpga | xdc vpr_place | fpga | place vpr_route | fpga | route drc | report | lyrdb,ascii log | report | log dot | image | dot,xdot png | image | png jpeg | image | jpg,jpeg bitmap | image | bmp
- Parameters:
fileset (str) – File grouping
filetype (str) – File type
iomap (dict of tuple(set, type)) – File set and type mapping based on file extension
step (str) – Node name
index (str) – Node index
package (str) – Name of package where this file can be found
- load_target(module, **kwargs)[source]#
Loads a target module and runs the setup() function.
- Parameters:
module (module) – Module name
**kwargs (str) – Options to pass along to the target
Examples
>>> chip.use(freepdk45_demo, syn_np=5) Loads the 'freepdk45_demo' target with 5 parallel synthesis tasks
- node(flow, step, task, index=0)[source]#
Creates a flowgraph node.
Creates a flowgraph node by binding a step to a tool specific task. A tool can be an external executable or one of the built in functions in the SiliconCompiler framework). Built in functions include: minimum, maximum, join, mux, verify. The task is set to ‘step’ if unspecified.
The method modifies the following schema parameters:
[‘flowgraph’, flow, step, index, ‘tool’, tool]
[‘flowgraph’, flow, step, index, ‘task’, task]
[‘flowgraph’, flow, step, index, ‘task’, taskmodule]
[‘flowgraph’, flow, step, index, ‘weight’, metric]
- Parameters:
flow (str) – Flow name
step (str) – Step name
task (module/str) – Task to associate with this node
index (int/str) – Step index
Examples
>>> import siliconcomiler.tools.openroad.place as place >>> chip.node('asicflow', 'apr_place', place, index=0) Creates a 'place' task with step='apr_place' and index=0 and binds it to the 'openroad' tool.
- output(filename, fileset=None, filetype=None, iomap=None, step=None, index=None, package=None)[source]#
Adds file to a filset. The default behavior is to infer filetypes and filesets based on the suffix of the file extensions. The method is a wrapper function for set.add(‘output’, filset, filetype,…)
Default filetype and filset based on suffix:
filetype | fileset | suffix (case insensitive) --------------|------------|--------------------------------------------- c | hll | c,cc,cpp,c++,cp,cxx,hpp,h llvm | hll | ll bsv | hll | bsv scala | hll | scala python | hll | py chisel | config | sbt verilog | rtl | v,verilog,vh systemverilog | rtl | sv,svh vhdl | rtl | vhd,vhdl liberty | timing | lib,ccs def | layout | def lef | layout | lef gds | layout | gds,gds2,gdsii oas | layout | oas,oasis gerber | layout | gbr,gerber odb | layout | odb cdl | netlist | cdl sp | netlist | sp,spice verilog | netlist | vg vcd | waveform | vcd sdc | constraint | sdc upf | constraint | upf pcf | constraint | pcf xdc | fpga | xdc vpr_place | fpga | place vpr_route | fpga | route drc | report | lyrdb,ascii log | report | log dot | image | dot,xdot png | image | png jpeg | image | jpg,jpeg bitmap | image | bmp
- Parameters:
fileset (str) – File grouping
filetype (str) – File type
iomap (dict of tuple(set, type)) – File set and type mapping based on file extension
step (str) – Node name
index (str) – Node index
package (str) – Name of package where this file can be found
- read_manifest(filename, job=None, clear=True, clobber=True)[source]#
Reads a manifest from disk and merges it with the current compilation manifest.
The file format read is determined by the filename suffix. Currently json (.json) and yaml(.yaml) formats are supported.
- Parameters:
filename (filepath) – Path to a manifest file to be loaded.
job (str) – Specifies non-default job to merge into.
clear (bool) – If True, disables append operations for list type.
clobber (bool) – If True, overwrites existing parameter value.
Examples
>>> chip.read_manifest('mychip.json') Loads the file mychip.json into the current Chip object.
- register_showtool(extension, task)[source]#
Registers a show or screenshot task with a given extension.
- Parameters:
extension (str) – file extension
task (module) – task to use for viewing this extension
Examples
>>> from siliconcompiler.tools.klayout import show >>> chip.register_showtool('gds', show)
- register_source(name, path, ref=None, clobber=True)[source]#
Registers a package by its name with the source path and reference
Registered package sources are stored in the package section of the schema.
- Parameters:
name (str) – Package name
path (str) – Path to the sources, can be file, git url, archive url
ref (str) – Reference of the sources, can be commitid, branch name, tag
Examples
>>> chip.register_source('siliconcompiler_data', 'git+https://github.com/siliconcompiler/siliconcompiler', 'dependency-caching-rebase')
- remove(*keypath)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_node(flow, step, index=None)[source]#
Remove a flowgraph node.
- Parameters:
flow (str) – Flow name
step (str) – Step name
index (int/str) – Step index
- run(raise_exception=False)[source]#
Executes tasks in a flowgraph.
The run function sets up tools and launches runs for every node in the flowgraph starting with ‘from’ steps and ending at ‘to’ steps. From/to are taken from the schema from/to parameters if defined, otherwise from/to are defined as the entry/exit steps of the flowgraph. Before starting the process, tool modules are loaded and setup up for each step and index based on on the schema eda dictionary settings. Once the tools have been set up, the manifest is checked using the check_manifest() function and files in the manifest are hashed based on the ‘hashmode’ schema setting.
Once launched, each process waits for preceding steps to complete, as defined by the flowgraph ‘inputs’ parameter. Once a all inputs are ready, previous steps are checked for errors before the process entered a local working directory and starts to run a tool or to execute a built in Chip function.
Fatal errors within a step/index process cause all subsequent processes to exit before start, returning control to the the main program which can then exit.
- Parameters:
raise_exception (bool) – if True, will rethrow errors that the flow raises, otherwise will report the error and return False
Examples
>>> run() Runs the execution flow defined by the flowgraph dictionary.
- set(*args, field='value', clobber=True, step=None, index=None, package=None)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args
. See the Schema Reference Manual for documentation of all supported keypaths. New schema dictionaries are automatically created for keypaths that overlap with ‘default’ dictionaries. The write action is ignored if the parameter value is non-empty and the clobber option is set to False.The value provided must agree with the dictionary parameter ‘type’. Accessing a non-existent keypath or providing a value that disagrees with the parameter type produces a logger error message and raises the Chip object error flag.
- Parameters:
args (list) – Parameter keypath followed by a value to set.
field (str) – Parameter field to set.
clobber (bool) – Existing value is overwritten if True.
step (str) – Step name to set for parameters that may be specified on a per-node basis.
index (str) – Index name to set for parameters that may be specified on a per-node basis.
package (str) – Package that this file/dir depends on. Available packages are listed in the package source section of the schema.
Examples
>>> chip.set('design', 'top') Sets the name of the design to 'top'
- show(filename=None, screenshot=False, extension=None)[source]#
Opens a graphical viewer for the filename provided.
The show function opens the filename specified using a viewer tool selected based on the file suffix and the registered showtools. Display settings and technology settings for viewing the file are read from the in-memory chip object schema settings. All temporary render and display files are saved in the <build_dir>/_show_<jobname> directory.
- Parameters:
filename (path) – Name of file to display
screenshot (bool) – Flag to indicate if this is a screenshot or show
extension (str) – extension of file to show
Examples
>>> show('build/oh_add/job0/write.gds/0/outputs/oh_add.gds') Displays gds file with a viewer assigned by showtool
- snapshot(path=None, display=True)[source]#
Creates a snapshot image of the job
- Parameters:
path (str) – Path to generate the image at, if not provided will default to <job>/<design>.png
display (bool) – If True, will open the image for viewing. If
['option', 'nodisplay']
is True, this argument will be ignored.
Examples
>>> chip.snapshot() Creates a snapshot image in the default location
- summary(show_all_indices=False)[source]#
Prints a summary of the compilation manifest.
Metrics from the flowgraph nodes, or from/to parameter if defined, are printed out on a per step basis. All metrics from the metric dictionary with weights set in the flowgraph dictionary are printed out.
- Parameters:
show_all_indices (bool) – If True, displays metrics for all indices of each step. If False, displays metrics only for winning indices.
Examples
>>> chip.summary() Prints out a summary of the run to stdout.
- swap_library(org_library, new_library, step=None, index=None)[source]#
Recursively changes a library in [‘option’, ‘library’] from a previous value to a new value. If the library is not present then nothing is changed. If the new library is None, the original library will be removed.
- Parameters:
org_library (str) – Name of old library
new_library (str) – Name of new library
step (str) – Step to change, if not specified, all steps will be modified
index (str) – Index to change, if not specified, all indexes will be modified
Examples
>>> chip.swap_library('lambdalib_iolib', 'lambdalib_sky130iolib') Changes from the lambdalib_iolib to lambdalib_sky130iolib.
- top(step=None, index=None)[source]#
Gets the name of the design’s entrypoint for compilation and simulation.
This method should be used to name input and output files in tool drivers, rather than relying on chip.get(‘design’) directly.
- Parameters:
step (str) – Node step name
index (str) – Node index
Returns
['option', 'entrypoint']
if it has been set, otherwise['design']
.
- unset(*keypath, step=None, index=None)[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()
made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()
withclobber=False
will once again be able to modify the value.If you unset a particular step/index for a parameter with optional per-node values, note that the newly returned value will be the global value if it has been set. To completely return the parameter to its default state, the global value has to be unset as well.
unset()
has no effect if called on a parameter that has not been previously set.- Parameters:
keypath (list) – Parameter keypath to clear.
step (str) – Step name to unset for parameters that may be specified on a per-node basis.
index (str) – Index name to unset for parameters that may be specified on a per-node basis.
- use(module, **kwargs)[source]#
Loads a SiliconCompiler module into the current chip object.
The behavior of this function is described in the table below
Use behavior# Input type
Action
Module with setup function
Call setup() and import returned objects
A setup function
Call function() and import returned objects
Chip
Import as a library
Library
Import as a library
PDK
Import as a pdk
FPGA
Import as a fpga
Flow
Import as a flow
Checklist
Import as a checklist
- valid(*keypath, default_valid=False, job=None, check_complete=False)[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
default_valid (bool) – Whether to consider “default” in valid
False. (keypaths as a wildcard. Defaults to)
job (str) – Jobname to use for dictionary access in place of the current active jobname.
check_complete (bool) – Require the keypath be a complete path.
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = chip.valid('design') Returns True. >>> check = chip.valid('blah') Returns False. >>> check = chip.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_dependencygraph(filename, flow=None, fontcolor='#000000', color_scheme=None, background='transparent', fontsize='14', border=True, landscape=False)[source]#
Renders and saves the dependenct graph to a file.
The chip object flowgraph is traversed to create a graphviz (*.dot) file comprised of node, edges, and labels. The dot file is a graphical representation of the flowgraph useful for validating the correctness of the execution flow graph. The dot file is then converted to the appropriate picture or drawing format based on the filename suffix provided. Supported output render formats include png, svg, gif, pdf and a few others. For more information about the graphviz project, see see https://graphviz.org/
- Parameters:
filename (filepath) – Output filepath
flow (str) – Name of flowgraph to render
fontcolor (str) – Node font RGB color hex value
color_scheme (str) – Name of the color scheme to apply to the nodes. Valid choices are: “none”, “simple”, “detailed”
background (str) – Background color
fontsize (str) – Node text font size
border (bool) – Enables node border if True
landscape (bool) – Renders graph in landscape layout if True
show_io (bool) – Add file input/outputs to graph
Examples
>>> chip.write_flowgraph('mydump.png') Renders the object flowgraph and writes the result to a png file.
- write_flowgraph(filename, flow=None, fillcolor='#ffffff', fontcolor='#000000', background='transparent', fontsize='14', border=True, landscape=False, show_io=False)[source]#
Renders and saves the compilation flowgraph to a file.
The chip object flowgraph is traversed to create a graphviz (*.dot) file comprised of node, edges, and labels. The dot file is a graphical representation of the flowgraph useful for validating the correctness of the execution flow graph. The dot file is then converted to the appropriate picture or drawing format based on the filename suffix provided. Supported output render formats include png, svg, gif, pdf and a few others. For more information about the graphviz project, see see https://graphviz.org/
- Parameters:
filename (filepath) – Output filepath
flow (str) – Name of flowgraph to render
fillcolor (str) – Node fill RGB color hex value
fontcolor (str) – Node font RGB color hex value
background (str) – Background color
fontsize (str) – Node text font size
border (bool) – Enables node border if True
landscape (bool) – Renders graph in landscape layout if True
show_io (bool) – Add file input/outputs to graph
Examples
>>> chip.write_flowgraph('mydump.png') Renders the object flowgraph and writes the result to a png file.
- write_manifest(filename, prune=False, abspath=False)[source]#
Writes the compilation manifest to a file.
The write file format is determined by the filename suffix. Currently json (.json), yaml (.yaml), tcl (.tcl), and (.csv) formats are supported.
- Parameters:
filename (filepath) – Output filepath
prune (bool) – If True, only essential fields from the the Chip object schema are written to the output file.
abspath (bool) – If set to True, then all schema filepaths are resolved to absolute filepaths.
Examples
>>> chip.write_manifest('mydump.json') Prunes and dumps the current chip manifest into mydump.json
- class siliconcompiler.FPGA(*args, package=None)[source]#
Object for configuring an FPGA This is the main object used for configuration and data for a FPGA within the SiliconCompiler platform.
This inherits all methods from
Chip
.- Parameters:
name (string) – Name of the FPGA.
package (string) – Name of the data source
Examples
>>> siliconcompiler.FPGA("lattice_ice40") Creates a flow object with name "lattice_ice40".
- class siliconcompiler.Flow(*args)[source]#
Object for configuring a flow. This is the main object used for configuration and data for a flow within the SiliconCompiler platform.
This inherits all methods from
Chip
.- Parameters:
name (string) – Name of the flow.
Examples
>>> siliconcompiler.Flow("asicflow") Creates a flow object with name "asicflow".
- class siliconcompiler.FlowgraphSchema(name=None)[source]#
- edge(tail, head, tail_index=0, head_index=0)[source]#
Creates a directed edge from a tail node to a head node.
Connects the output of a tail node with the input of a head node by setting the ‘input’ field of the head node in the schema flowgraph.
The method modifies the following parameters:
[<head>,<head_index>,input]
- Parameters:
tail (str) – Name of tail node
head (str) – Name of head node
tail_index (int/str) – Index of tail node to connect
head_index (int/str) – Index of head node to connect
Examples
>>> chip.edge('place', 'cts') Creates a directed edge from place to cts.
- get_entry_nodes()[source]#
Collect all step/indices that represent the entry nodes for the flowgraph
- get_execution_order(reverse=False)[source]#
Generates a list of nodes in the order they will be executed.
- Parameters:
reverse (boolean) – if True, the nodes will be ordered from exit nodes to entry nodes.
- get_node_outputs(step, index)[source]#
Returns the nodes the given nodes provides input to.
- Parameters:
step (str) – step name
index (str/int)
- graph(subflow, name=None)[source]#
Instantiates a named flow as a graph in the current flowgraph.
- Parameters:
subflow (str) – Name of flow to instantiate
name (str) – Name of instance
Examples
>>> chip.graph(asicflow) Instantiates a flow named 'asicflow'.
- node(step, task, index=0)[source]#
Creates a flowgraph node.
Creates a flowgraph node by binding a step to a tool specific task. A tool can be an external executable or one of the built in functions in the SiliconCompiler framework). Built in functions include: minimum, maximum, join, mux, verify.
The method modifies the following schema parameters:
[<step>,<index>,tool,<tool>]
[<step>,<index>,task,<task>]
[<step>,<index>,taskmodule,<taskmodule>]
- Parameters:
step (str) – Step name
task (module/str) – Task to associate with this node
index (int/str) – Step index
Examples
>>> import siliconcomiler.tools.openroad.place as place >>> flow.node('apr_place', place, index=0) Creates a 'place' task with step='apr_place' and index=0 and binds it to the 'openroad' tool.
- remove_node(step, index=None)[source]#
Remove a flowgraph node.
- Parameters:
step (str) – Step name
index (int/str) – Step index
- validate(logger=None)[source]#
Check if flowgraph is valid.
Checks if all edges have valid nodes
Checks that there are no duplicate edges
Checks if nodes are defined properly
Checks if there are any loops present in the graph
Returns True if valid, False otherwise.
- Parameters:
logger (logging.Logger) – logger to use for reporting
- class siliconcompiler.Library(*args, package=None, auto_enable=False)[source]#
Object for configuring a library. This is the main object used for configuration and data for a library within the SiliconCompiler platform.
This inherits all methods from
Chip
.- Parameters:
name (string) – Name of the library.
package (string) – Name of the data source
auto_enable (boolean) – If True, will automatically be added to [‘option’,’library’]. This is only valid for non-logiclibs and macrolibs
Examples
>>> siliconcompiler.Library("asap7sc7p5t") Creates a library object with name "asap7sc7p5t".
- class siliconcompiler.MetricSchema[source]#
- class siliconcompiler.PDK(*args, package=None)[source]#
Object for configuring a process development kit. This is the main object used for configuration and data for a PDK within the SiliconCompiler platform.
This inherits all methods from
Chip
.- Parameters:
name (string) – Name of the PDK.
package (string) – Name of the data source
Examples
>>> siliconcompiler.PDK("asap7") Creates a flow object with name "asap7".
- class siliconcompiler.RecordSchema[source]#
- clear(step, index, keep=None)[source]#
Clear all saved metrics for a given step and index
- Parameters:
step (str) – Step name to clear.
index (str) – Index name to clear.
keep (list of str) – list of records to keep.
- static get_cloud_information()[source]#
Return information about the cloud environment.
- Return format: {
“region”: str
}
- static get_ip_information()[source]#
Return information about the ip and mac address of this machine.
- Return format: {
“ip”: str, “mac”: str
}
- static get_machine_information()[source]#
Return information about the machine.
- Return format: {
“machine”: str, “system”: str, “distro”: str, “osversion”: str, “kernelversion”: str, “arch”: str
}
- get_recorded_time(step, index, type)[source]#
Returns the time recorded for a given record.
- Parameters:
step (str) – Step name to associate.
index (str) – Index name to associate.
type (
RecordTime
) – type of time to record
- static get_user_information()[source]#
Return information about the user.
Return format: {“username”: str}
- record_python_packages()[source]#
Record the python packages currently available in the environment.
- record_time(step, index, type)[source]#
Record the time of the record.
- Returns:
time recorded.
- Parameters:
step (str) – Step name to associate.
index (str) – Index name to associate.
type (
RecordTime
) – type of time to record
- record_tool(step, index, info, type)[source]#
Record information about the tool used during this record.
- Parameters:
step (str) – Step name to associate.
index (str) – Index name to associate.
info (any) – Information to record.
type (
RecordTool
) – type of tool information being recorded
- record_userinformation(step, index)[source]#
Records information about the current machine and user. Uses information from
get_machine_information()
,get_user_information()
,get_cloud_information()
, andget_ip_information()
.- Parameters:
step (str) – Step name to associate.
index (str) – Index name to associate.
- exception siliconcompiler.SiliconCompilerError(message, chip=None)[source]#
Minimal Exception wrapper used to raise sc runtime errors.
- class siliconcompiler.ToolSchema(name=None)[source]#
- check_exe_version(reported_version)[source]#
Check if the reported version matches the versions specified in
['tool', <tool>, 'version']
.- Parameters:
reported_version (str) – version to check
- Returns:
True if the version matched, false otherwise
- generate_replay_script(filepath, workdir, include_path=True)[source]#
Generate a replay script for the task.
- Parameters:
filepath (path) – path to the file to write
workdir (path) – path to the run work directory
include_path (bool) – include path information in environmental variables
- get_exe()[source]#
Determines the absolute path for the specified executable.
- Raises:
TaskExecutableNotFound – if executable not found.
- Returns:
path to executable, or None if not specified
- get_exe_version()[source]#
Gets the version of the specified executable.
- Raises:
TaskExecutableNotFound – if executable not found.
NotImplementedError – if
parse_version()
has not be implemented.
- Returns:
version determined by
parse_version()
.
- get_runtime_command()[source]#
Constructs a subprocess run command based on tool setup.
- Raises:
TaskExecutableNotFound – if executable not found.
- Returns:
command (list)
- get_runtime_environmental_variables(include_path=True)[source]#
Determine the environmental variables needed for the task
- Parameters:
include_path (bool) – if True, includes PATH variable
- Returns:
dictionary of environmental variable to value mapping
- Return type:
dict of str
- run_task(workdir, quiet, loglevel, breakpoint, nice, timeout, run_func)[source]#
Run the task.
- Parameters:
workdir (path) – path to the run work directory
quiet (bool) – if True, execution output is suppressed
loglevel (str) – logging level
breakpoint (bool) – if True, will attempt to execute with a breakpoint
nice (int) – POSIX nice level to use in execution
timeout (int) – timeout to use for execution
run_func (method) – python method to call…
- Returns:
return code from the execution
- schema(type=None)[source]#
Get useful section of the schema.
- Parameters:
type (str) – schema section to find, if None returns the root schema.
- Returns:
schema section.
- set_runtime(chip)[source]#
Sets the runtime information needed to properly execute a task. Note: unstable API
- Parameters:
chip (
Chip
) – root schema for the runtime information
- siliconcompiler.tools._common.add_frontend_requires(chip, supports=None)[source]#
Adds keys to the require list for the frontend task and checks if options are set, which the current frontend does not support.
- Parameters:
chip (Chip) – Chip object
supports (list) – List of [‘option’, ‘*’] which the frontend supports
- siliconcompiler.tools._common.add_require_input(chip, *key, include_library_files=True)[source]#
Adds input files to the require list of the task.
- Parameters:
chip (Chip) – Chip object
key (list) – Key to check for requirements
add_library_files (bool) – When True, files from library keys will be included
- siliconcompiler.tools._common.get_frontend_options(chip, supports=None)[source]#
Returns a dictionary of options set for the frontend and checks if options are set, which the current frontend does not support.
- Parameters:
chip (Chip) – Chip object
supports (list) – List of [‘option’, ‘*’] which the frontend supports
- siliconcompiler.tools._common.get_input_files(chip, *key, add_library_files=True)[source]#
Returns a list of files from the key input and includes files from libraries if requested.
- Parameters:
chip (Chip) – Chip object
key (list) – Key to collect files from
add_library_files (bool) – When True, files from library keys will be included
- siliconcompiler.tools._common.get_libraries(chip, include_asic=True)[source]#
Returns a list of libraries included in this step/index
- Parameters:
chip (Chip) – Chip object
include_asic (bool) – include the asic libraries.
- siliconcompiler.tools._common.get_tool_task(chip, step, index, flow=None)[source]#
Helper function to get the name of the tool and task associated with a given step/index.
- siliconcompiler.tools._common.has_input_files(chip, *key, check_library_files=True)[source]#
Returns true if the specified key is set.
- Parameters:
chip (Chip) – Chip object
key (list) – Key to check
check_library_files (bool) – When True, files from library keys will be checked
- siliconcompiler.tools._common.record_metric(chip, step, index, metric, value, source, source_unit=None)[source]#
Records a metric from a given step and index.
This function ensures the metrics are recorded in the correct units as specified in the schema, additionally, this will record the source of the value if provided.
- Parameters:
step (str) – step to record the metric into
index (str) – index to record the metric into
metric (str) – metric to record
value (float/int) – value of the metric that is being recorded
source (str) – file the value came from
source_unit (str) – unit of the value, if not provided it is assumed to have no units
Examples
>>> record_metric(chip, 'floorplan', '0', 'cellarea', 500.0, 'reports/metrics.json', \ source_units='um^2') Records the metric cell area under 'floorplan0' and notes the source as 'reports/metrics.json'
- siliconcompiler.utils.format_fileset_type_table(indent=12)[source]#
Generate a table to use in the __doc__ of the input function which auto updates based on the iomap
- siliconcompiler.utils.get_cores(chip, physical=False)[source]#
Get max number of cores for this machine.
- Parameters:
physical (boolean) – if true, only count physical cores
- siliconcompiler.utils.get_default_iomap()[source]#
Default input file map for SC with filesets and extensions
- siliconcompiler.utils.get_env_vars(chip, step, index)[source]#
Returns a dictionary of environmental variables from the manifest
- siliconcompiler.utils.get_file_ext(filename)[source]#
Get base file extension for a given path, disregarding .gz.
- siliconcompiler.utils.get_hashed_filename(path, package=None)[source]#
Utility to map collected file to an unambiguous name based on its path.
The mapping looks like: path/to/file.ext => file_<hash(‘path/to’)>.ext
- siliconcompiler.utils.get_plugins(system, name=None)[source]#
Search for python modules with a specific function
- siliconcompiler.utils.grep(chip, args, line)[source]#
Emulates the Unix grep command on a string.
Emulates the behavior of the Unix grep command that is etched into our muscle memory. Partially implemented, not all features supported. The function returns None if no match is found.
- Parameters:
arg (string) – Command line arguments for grep command
line (string) – Line to process
- Returns:
Result of grep command (string).
- siliconcompiler.utils.terminate_process(pid, timeout=3)[source]#
Terminates a process and all its (grand+)children.
Based on https://psutil.readthedocs.io/en/latest/#psutil.wait_procs and https://psutil.readthedocs.io/en/latest/#kill-process-tree.
- siliconcompiler.utils.asic.calc_area(chip, step=None, index=None)[source]#
Calculates the area of a rectilinear diearea.
Uses the shoelace formulate to calculate the design area using the (x,y) point tuples from the ‘diearea’ parameter. If only diearea parameter only contains two points, then the first and second point must be the lower left and upper right points of the rectangle. (Ref: https://en.wikipedia.org/wiki/Shoelace_formula)
- Parameters:
step (str) – name of the step to calculate the area from
index (str) – name of the step to calculate the area from
- Returns:
Design area (float).
Examples
>>> area = chip.calc_area()
- siliconcompiler.utils.asic.calc_dpw(chip, step=None, index=None)[source]#
Calculates dies per wafer.
Calculates the gross dies per wafer based on the design area, wafersize, wafer edge margin, and scribe lines. The calculation is done by starting at the center of the wafer and placing as many complete design footprints as possible within a legal placement area.
- Parameters:
step (str) – name of the step use for calculation
index (str) – name of the step use for calculation
- Returns:
Number of gross dies per wafer (int).
Examples
>>> dpw = chip.calc_dpw() Variable dpw gets gross dies per wafer value based on the chip manifest.
- siliconcompiler.utils.asic.calc_yield(chip, step=None, index=None, model='poisson')[source]#
Calculates raw die yield.
Calculates the raw yield of the design as a function of design area and d0 defect density. Calculation can be done based on the poisson model (default) or the murphy model. The die area and the d0 parameters are taken from the chip dictionary.
Poisson model: dy = exp(-area * d0/100).
Murphy model: dy = ((1-exp(-area * d0/100))/(area * d0/100))^2.
- Parameters:
step (str) – name of the step use for calculation
index (str) – name of the step use for calculation
model (string) – Model to use for calculation (poisson or murphy)
- Returns:
Design yield percentage (float).
Examples
>>> yield = chip.calc_yield() Yield variable gets yield value based on the chip manifest.