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:

set

Sets a schema parameter field.

add

Adds item(s) to a schema parameter list.

get

Returns a schema parameter field.

getkeys

Returns a list of schema dictionary keys.

getdict

Returns a schema dictionary.

valid

Checks validity of a keypath.

help

Returns a schema parameter description.

use

Loads a SiliconCompiler module into the current chip object.

Flowgraph execution:

run

Executes tasks in a flowgraph.

node

Creates a flowgraph node.

edge

Creates a directed edge from a tail node to a head node.

Utility functions:

archive

Archive a job directory.

audit_manifest

Verifies the integrity of the post-run compilation manifest.

calc_area

Calculates the area of a rectilinear diearea.

calc_yield

Calculates raw die yield.

calc_dpw

Calculates dies per wafer.

check_checklist

Check items in a checklist.

check_manifest

Verifies the integrity of the pre-run compilation manifest.

check_logfile

Checks logfile for patterns found in the 'regex' parameter.

clock

Clock configuration helper function.

create_cmdline

Creates an SC command line interface.

find_files

Returns absolute paths to files or directories based on the keypath provided.

find_result

Returns the absolute path of a compilation result.

grep

Emulates the Unix grep command on a string.

hash_files

Generates hash values for a list of parameter files.

nodes_to_execute

Returns an ordered list of flowgraph nodes which will be executed.

load_target

Loads a target module and runs the setup() function.

read_manifest

Reads a manifest from disk and merges it with the current compilation manifest.

show

Opens a graphical viewer for the filename provided.

summary

Prints a summary of the compilation manifest.

use

Loads a SiliconCompiler module into the current chip object.

write_manifest

Writes the compilation manifest to a file.

write_flowgraph

Renders and saves the compilation flowgraph to a file.

Tool driver utility functions:

get_libraries

Returns a list of libraries included in this step/index

add_require_input

Adds input files to the require list of the task.

get_input_files

Returns a list of files from the key input and includes files from libraries if requested.

add_frontend_requires

Adds keys to the require list for the frontend task and checks if options are set, which the current frontend does not support.

get_frontend_options

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(chip, name)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the checklist.

Examples

>>> siliconcompiler.Checklist(chip, "tapeout")
Creates a checklist object with name "tapeout".
class siliconcompiler.Chip(design, loglevel=None)#

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)#

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)#

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)#

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

audit_manifest()#

Verifies the integrity of the post-run compilation manifest.

Checks the integrity of the chip object implementation flow after the run() function has been completed. Errors, warnings, and debug messages are reported through the logger object.

Audit checks performed include:

  • Time stamps

  • File modifications

  • Error and warning policy

  • IP and design origin

  • User access

  • License terms

  • Version checks

Returns:

Returns True if the manifest has integrity, else returns False.

Example

>>> chip.audit_manifest()
Audits the Chip object manifest and returns 0 if successful.
calc_area(step=None, index=None)#

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()
calc_dpw(step=None, index=None)#

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.
calc_yield(step=None, index=None, model='poisson')#

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.
check_checklist(standard, items=None, check_ok=False)#

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.

Returns:

Status of item check.

Examples

>>> status = chip.check_checklist('iso9000', 'd000')
Returns status.
check_filepaths()#

Verifies that paths to all files in manifest are valid.

Returns:

True if all file paths are valid, otherwise False.

check_logfile(jobname=None, step=None, index='0', logfile=None, display=True)#

Checks logfile for patterns found in the ‘regex’ parameter.

Reads the content of the task’s log file and compares the content found with the task’s ‘regex’ parameter. The matches are stored in the file ‘<step>.<suffix>’ in the current directory. The matches are logged if display is set to True.

Parameters:
  • jobname (str) – Job directory name. If None, ['option', 'jobname'] is used.

  • step (str) – Task step name (‘syn’, ‘place’, etc). If None, ['arg', 'step'] is used.

  • index (str) – Task index. Default value is 0. If None, ['arg', 'index'] is used.

  • logfile (str) – Path to logfile. If None, the default task logfile is used.

  • display (bool) – If True, logs matches.

Returns:

Dictionary mapping suffixes to number of matches for that suffix’s regex.

Examples

>>> chip.check_logfile(step='place')
Searches for regex matches in the place logfile.
check_manifest()#

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')#

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.

create_cmdline(progname=None, description=None, switchlist=None, input_map=None, additional_args=None)#

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:

  1. loglevel

  2. read_manifest([cfg])

  3. read compiler inputs

  4. all other switches

  5. load_target(‘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}
property design#

Design name of chip object.

This is an immutable property.

edge(flow, tail, head, tail_index=0, head_index=0)#

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) – Index of tail node to connect

  • head_index (int) – Index of head node to connect

Examples

>>> chip.edge('place', 'cts')
Creates a directed edge from place to cts.
error(msg, fatal=False)#

Raises error.

If fatal is False and ['option', 'continue'] is set to True, this will log an error and set an internal error flag that will cause run() to quit. Otherwise, this will raise a SiliconCompilerError.

Parameters:
  • msg (str) – Message associated with error

  • fatal (bool) – Whether error is always fatal

find_files(*keypath, missing_ok=False, job=None, step=None, index=None)#

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_result(filetype, step, jobname=None, index='0')#

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

>>> manifest_filepath = chip.find_result('vg', 'syn')

Returns the absolute path to the manifest.

get(*keypath, field='value', job=None, step=None, index=None)#

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)#

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)#

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.
graph(flow, subflow, name=None)#

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'.
grep(args, line)#

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

hash_files(*keypath, update=True, step=None, index=None)#

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.

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)#

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
input(filename, fileset=None, filetype=None, iomap=None, package=None)#

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
bsv       | hll        | bsv
scala     | hll        | scala
python    | hll        | py
chisel    | config     | sbt
verilog   | rtl        | v,sv,verilog
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
xdc       | fpga       | xdc
pcf       | fpga       | pcf
Parameters:
  • fileset (str) – File grouping

  • filetype (str) – File type

  • iomap (dict of tuple(set, type)) – File set and type mapping based on file extension

load_target(module, **kwargs)#

Loads a target module and runs the setup() function.

The function searches the installed Python packages for <name> and siliconcompiler.targets.<name> and runs the setup function in that module if found.

Parameters:
  • module (str or module) – Module name

  • **kwargs (str) – Options to pass along to the target

Examples

>>> chip.load_target('freepdk45_demo', syn_np=5)
Loads the 'freepdk45_demo' target with 5 parallel synthesis tasks
node(flow, step, task, index=0)#

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) – 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.
nodes_to_execute(flow=None)#

Returns an ordered list of flowgraph nodes which will be executed. This takes the from/to options into account if flow is the current flow or None.

Returns:

A list of nodes that will get executed during run() (or a specific flow).

Example

>>> nodes = chip.nodes_to_execute()
output(filename, fileset=None, filetype=None, iomap=None)#

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
bsv       | hll        | bsv
scala     | hll        | scala
python    | hll        | py
chisel    | config     | sbt
verilog   | rtl        | v,sv,verilog
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
xdc       | fpga       | xdc
pcf       | fpga       | pcf
Parameters:
  • fileset (str) – File grouping

  • filetype (str) – File type

  • iomap (dict of tuple(set, type)) – File set and type mapping based on file extension

pipe(flow, plan)#

Creates a pipeline based on an order list of key values pairs.

read_manifest(filename, job=None, clear=True, clobber=True)#

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_package_source(name, path, ref=None, clobber=True)#

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_package_source('siliconcompiler_data',
        'git+https://github.com/siliconcompiler/siliconcompiler',
        'dependency-caching-rebase')
run()#

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.

Examples

>>> run()
Runs the execution flow defined by the flowgraph dictionary.
set(*args, field='value', clobber=True, step=None, index=None, package=None)#

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)#

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 ‘showtool’ schema setup. The ‘showtool’ parameter binds tools with file suffixes, enabling the automated dynamic loading of tool setup functions. 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/export/0/outputs/oh_add.gds')
Displays gds file with a viewer assigned by 'showtool'
summary(show_all_indices=False, generate_image=True, generate_html=True)#

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.

  • generate_image (bool) – If True, generates a summary image featuring a layout screenshot and a subset of metrics. Requires that the current job has an ending node that generated a PNG file.

  • generate_html (bool) – If True, generates an HTML report featuring a metrics summary table and manifest tree view. The report will include a layout screenshot if the current job has an ending node that generated a PNG file.

Examples

>>> chip.summary()
Prints out a summary of the run to stdout.
top()#

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.

Returns ['option', 'entrypoint'] if it has been set, otherwise ['design'].

unset(*keypath, step=None, index=None)#

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 to set() with clobber=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)#

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

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)#

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) –

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_flowgraph(filename, flow=None, fillcolor='#ffffff', fontcolor='#000000', fontsize='14', border=True, landscape=False)#

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

  • fontsize (str) – Node text font size

  • border (bool) – Enables node border if True

  • landscape (bool) – Renders graph in landscape layout if True

Examples

>>> chip.write_flowgraph('mydump.png')
Renders the object flowgraph and writes the result to a png file.
write_manifest(filename, prune=True, abspath=False)#

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(chip, name, package=None)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the FPGA.

Examples

>>> siliconcompiler.FPGA(chip, "lattice_ice40")
Creates a flow object with name "lattice_ice40".
class siliconcompiler.Flow(chip, name)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the flow.

Examples

>>> siliconcompiler.Flow(chip, "asicflow")
Creates a flow object with name "asicflow".
class siliconcompiler.Library(chip, name, package=None)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the library.

Examples

>>> siliconcompiler.Library(chip, "asap7sc7p5t")
Creates a library object with name "asap7sc7p5t".
class siliconcompiler.PDK(chip, name, package=None)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the PDK.

Examples

>>> siliconcompiler.PDK(chip, "asap7")
Creates a flow object with name "asap7".
class siliconcompiler.Schema(cfg=None, manifest=None, logger=None)#

Object for storing and accessing configuration values corresponding to the SiliconCompiler schema.

Most user-facing interaction with the schema should occur through an instance of Chip, but this class is available for schema manipulation tasks that don’t require the additional context of a Chip object.

The two arguments to this class are mutually exclusive. If neither are provided, the object is initialized to default values for all parameters.

Parameters:
  • cfg (dict) – Initial configuration dictionary. This may be a subtree of the schema.

  • manifest (str) – Initial manifest.

  • logger (logging.Logger) – instance of the parent logger if available

add(*args, field='value', step=None, index=None, package=None)#

Adds item(s) to a schema parameter list.

See add() for detailed documentation.

allkeys(*keypath_prefix)#

Returns all keypaths in the schema as a list of lists.

See allkeys() for detailed documentation.

copy()#

Returns deep copy of Schema object.

create_cmdline(progname, description=None, switchlist=None, input_map=None, additional_args=None, version=None, print_banner=None, input_map_handler=None, preprocess_keys=None, post_process=None, logger=None)#

Creates a Schema 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:

  1. loglevel, if available in schema

  2. read_manifest([cfg]), if available in schema

  3. read inputs with input_map_handler

  4. all other switches

  5. Run post_process

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}

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

  • version (str) – Version to report when calling with -version

  • print_banner (function) – Function callback to print command line banner

  • input_map_handler (function) – Function callback handle inputs to the input map

  • preprocess_keys (function) – Function callback to preprocess keys that need to be corrected

  • post_process (function) – Function callback to process arguments before returning

Returns:

None if additional_args is not provided, otherwise a dictionary with the

command line options detected from the additional_args

Examples

>>> schema.create_cmdline(progname='sc-show',switchlist=['-input','-cfg'])
Creates a command line interface for 'sc-show' app.
>>> schema.create_cmdline(progname='sc', input_map={'v': ('rtl', 'verilog')})
All sources ending in .v will be stored in ['input', 'rtl', 'verilog']
>>> extra = schema.create_cmdline(progname='sc',
                                  additional_args={'-demo': {'action': 'store_true'}})
Returns extra = {'demo': False/True}
get(*keypath, field='value', job=None, step=None, index=None)#

Returns a schema parameter field.

See get() for detailed documentation.

get_default(*keypath)#

Returns default value of a parameter.

Parameters:

keypath (list str) – Variable length schema key list.

getdict(*keypath)#

Returns a schema dictionary.

See getdict() for detailed documentation.

getkeys(*keypath, job=None)#

Returns a list of schema dictionary keys.

See getkeys() for detailed documentation.

history(job)#

Returns a mutable reference to [‘history’, job] as a Schema object.

If job doesn’t currently exist in history, create it with default values.

Parameters:

job (str) – Name of historical job to return.

prune()#

Remove all empty parameters from configuration dictionary.

Also deletes ‘help’ and ‘example’ keys.

read_manifest(filename, clear=True, clobber=True, allow_missing_keys=False)#

Reads a manifest from disk and merges it with the current 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.

  • clear (bool) – If True, disables append operations for list type.

  • clobber (bool) – If True, overwrites existing parameter value.

  • allow_missing_keys (bool) – If True, keys not present in current schema will be ignored.

Examples

>>> chip.read_manifest('mychip.json')
Loads the file mychip.json into the current Chip object.
record_history()#

Copies all non-empty parameters from current job into the history dictionary.

set(*args, field='value', clobber=True, step=None, index=None, package=None)#

Sets a schema parameter field.

See set() for detailed documentation.

unset(*keypath, step=None, index=None)#

Unsets a schema parameter field.

See unset() for detailed documentation.

valid(*args, default_valid=False)#

Checks validity of a keypath.

See valid() for detailed documentation.

write_tcl(fout, prefix='', step=None, index=None, template=None)#

Prints out schema as TCL dictionary

exception siliconcompiler.SiliconCompilerError(message)#

Minimal Exception wrapper used to raise sc runtime errors.

class siliconcompiler.use.Checklist(chip, name)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the checklist.

Examples

>>> siliconcompiler.Checklist(chip, "tapeout")
Creates a checklist object with name "tapeout".
class siliconcompiler.use.FPGA(chip, name, package=None)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the FPGA.

Examples

>>> siliconcompiler.FPGA(chip, "lattice_ice40")
Creates a flow object with name "lattice_ice40".
class siliconcompiler.use.Flow(chip, name)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the flow.

Examples

>>> siliconcompiler.Flow(chip, "asicflow")
Creates a flow object with name "asicflow".
class siliconcompiler.use.Library(chip, name, package=None)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the library.

Examples

>>> siliconcompiler.Library(chip, "asap7sc7p5t")
Creates a library object with name "asap7sc7p5t".
class siliconcompiler.use.PDK(chip, name, package=None)#

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:
  • chip (Chip) – A real only copy of the parent chip.

  • name (string) – Name of the PDK.

Examples

>>> siliconcompiler.PDK(chip, "asap7")
Creates a flow object with name "asap7".
class siliconcompiler.use.PackageChip(chip, name, package=None)#
add(*args, field='value', step=None, index=None, package=None)#

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.
set(*args, field='value', clobber=True, step=None, index=None, package=None)#

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'
siliconcompiler.tools._common.add_frontend_requires(chip, supports=None)#

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)#

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)#

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)#

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)#

Returns a list of libraries included in this step/index

Parameters:
  • chip (Chip) – Chip object

  • include_asic (bool) – When in [‘option’, ‘mode’] == ‘asic’ also include the asic libraries.