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.
unset	Unsets a schema parameter.
remove	Remove a schema parameter and its subparameters.

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.
remove_node	Remove a flowgraph node.

Utility functions:

archive	Archive a job directory.
check_checklist	Check items in a checklist.
check_manifest	Verifies the integrity of the pre-run compilation manifest.
clock	Clock configuration helper function.
collect	Collects files found in the configuration dictionary and places them in inputs/.
create_cmdline	Creates an SC command line interface.
dashboard	Open a session of the dashboard.
find_files	Returns absolute paths to files or directories based on the keypath provided.
find_result	Returns the absolute path of a compilation result.
getworkdir	Get absolute path to work directory for a given step/index, if step/index not given, job directory is returned
hash_files	Generates hash values for a list of parameter files.
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.
snapshot	Creates a snapshot image of the job
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.
calc_area	Calculates the area of a rectilinear diearea.
calc_yield	Calculates raw die yield.
calc_dpw	Calculates dies per wafer.
grep	Emulates the Unix grep command on a string.

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(*args)

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.ChecklistSchema(name=None)

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

check_checklist(standard, items=None, check_ok=False, verbose=False, require_reports=True)

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

Verifies that paths to all files in manifest are valid.

Returns:

True if all file paths are valid, otherwise False.

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.

collect(directory=None, verbose=True, whitelist=None, exclude_packages=None)

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.

1. indexing like in run, job1

2. chdir package

3. run tool to collect files, pickle file in output/design.v

4. copy in rest of the files below

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

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

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)

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)

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)

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

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

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)

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.

getbuilddir()

Get absolute path to the build directory

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.

getworkdir(jobname=None, step=None, index=None)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

Remove a schema parameter and its subparameters.

Parameters:

keypath (list) – Parameter keypath to clear.

remove_node(flow, step, index=None)

Remove a flowgraph node.

Parameters:

• flow (str) – Flow name

• step (str) – Step name

• index (int/str) – Step index

run(raise_exception=False)

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)

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

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)

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)

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)

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)

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

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)

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)

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)

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)

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)

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)

edge(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:

[<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()

Collect all step/indices that represent the entry nodes for the flowgraph

get_execution_order(reverse=False)

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_exit_nodes()

Collect all step/indices that represent the exit nodes for the flowgraph

get_node_outputs(step, index)

Returns the nodes the given nodes provides input to.

Parameters:

• step (str) – step name

• index (str/int)

get_nodes()

Returns all the nodes defined in this flowgraph

graph(subflow, name=None)

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)

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)

Remove a flowgraph node.

Parameters:

• step (str) – Step name

• index (int/str) – Step index

validate(logger=None)

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)

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

clear(step, index)

Clear all saved metrics for a given step and index

Parameters:

• step (str) – Step name to clear.

• index (str/int) – Index name to clear.

record(step, index, metric, value, unit=None)

Record a metric

Parameters:

• step (str) – step to record

• index (str/int) – index to record

• metric (str) – name of metric

• value (int/float) – value to record

• unit (str) – unit associated with value

class siliconcompiler.PDK(*args, 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:

• 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.PDKSchema(name=None, package=None)

class siliconcompiler.RecordSchema

clear(step, index, keep=None)

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

Return information about the cloud environment.

Return format: {

“region”: str

}

static get_ip_information()

Return information about the ip and mac address of this machine.

Return format: {

“ip”: str, “mac”: str

}

static get_machine_information()

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)

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

Return information about the user.

Return format: {“username”: str}

record_python_packages()

Record the python packages currently available in the environment.

record_time(step, index, type)

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)

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)

Records information about the current machine and user. Uses information from get_machine_information(), get_user_information(), get_cloud_information(), and get_ip_information().

Parameters:

• step (str) – Step name to associate.

• index (str) – Index name to associate.

record_version(step, index)

Records the versions for SiliconCompiler and python.

Parameters:

• step (str) – Step name to associate.

• index (str) – Index name to associate.

siliconcompiler.Schema

alias of SchemaTmp

exception siliconcompiler.SiliconCompilerError(message, chip=None)

Minimal Exception wrapper used to raise sc runtime errors.

class siliconcompiler.ToolSchema(name=None)

check_exe_version(reported_version)

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)

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

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

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

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)

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

logger()

Returns:

logger

node()

Returns:

step and index for the current runtime

run_task(workdir, quiet, loglevel, breakpoint, nice, timeout, run_func)

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)

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)

Sets the runtime information needed to properly execute a task. Note: unstable API

Parameters:

chip (Chip) – root schema for the runtime information

setup_work_directory(workdir, remove_exist=True)

Create the runtime directories needed to execute a task.

Parameters:

• workdir (path) – path to the run work directory

• remove_exist (bool) – if True, removes the existing directory

task()

Returns:

task name

write_task_manifest(directory, backup=True)

Write the manifest needed for the task

Parameters:

• directory (path) – directory to write the manifest into.

• backup (bool) – if True and an existing manifest is found a backup is kept.

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) – include the asic libraries.

siliconcompiler.tools._common.get_tool_task(chip, step, index, flow=None)

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)

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)

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)

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)

Get max number of cores for this machine.

Parameters:

physical (boolean) – if true, only count physical cores

siliconcompiler.utils.get_default_iomap()

Default input file map for SC with filesets and extensions

siliconcompiler.utils.get_env_vars(chip, step, index)

Returns a dictionary of environmental variables from the manifest

siliconcompiler.utils.get_file_ext(filename)

Get base file extension for a given path, disregarding .gz.

siliconcompiler.utils.get_hashed_filename(path, package=None)

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)

Search for python modules with a specific function

siliconcompiler.utils.grep(chip, 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).

siliconcompiler.utils.terminate_process(pid, timeout=3)

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)

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)

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

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.