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

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}

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

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

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

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

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

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.

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

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.

change_type(*key, type=None)

Change the type of a key

Parameters:

• key (list) – Key to change.

• type (str) – New data type for this key

Examples

>>> chip.set('option', 'var', 'run_test', 'true')
>>> chip.schema.change_type('option', 'var', 'run_test', 'bool')
Changes the type of ['option', 'var', 'run_test'] to a boolean.

copy()

Returns deep copy of Schema object.

copy_key(src, dst)

Copy a parameters information from the source keypath to the destination keypath.

Parameters:

• src (list) – Key to use as source.

• dst (list) – Key to use as destination

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.

is_empty(*keypath)

Utility function to check key for an empty value.

merge_manifest(src, job=None, clobber=True, clear=True, check=False)

Merges a given manifest with the current compilation manifest.

All value fields in the provided schema dictionary are merged into the current chip object. Dictionaries with non-existent keypath produces a logger error message and raises the Chip object error flag.

Parameters:

• src (Schema) – Schema object to merge

• 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

• check (bool) – If True, checks the validity of each key

prune()

Remove all empty parameters from configuration dictionary.

Also deletes ‘help’ and ‘example’ keys.

read_journal(filename)

Reads a manifest and replays the journal

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

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.

remove(*keypath)

Remove a keypath

See remove() for detailed documentation.

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

Sets a schema parameter field.

See set() for detailed documentation.

set_default(*args)

Sets the default value of a parameter.

Parameters:

args (list str) – Variable length schema key list and value.

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

Unsets a schema parameter field.

See unset() for detailed documentation.

valid(*args, default_valid=False, job=None, check_complete=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, chip=None)

Minimal Exception wrapper used to raise sc runtime errors.

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.find_sc_file(chip, filename, missing_ok=False, search_paths=None)

Returns the absolute path for the filename provided.

Searches the for the filename provided and returns the absolute path. If no valid absolute path is found during the search, None is returned.

Shell variables (‘$’ followed by strings consisting of numbers, underscores, and digits) are replaced with the variable value.

Parameters:

• filename (str) – Relative or absolute filename.

• missing_ok (bool) – If False, error out if no valid absolute path found, rather than returning None.

• search_paths (list) – List of directories to search under instead of the defaults.

Returns:

Returns absolute path of ‘filename’ if found, otherwise returns None.

Examples

>>> chip._find_sc_file('flows/asicflow.py')
Returns the absolute path based on the sc installation directory.

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

Default input file map for SC with filesets and extensions

siliconcompiler.utils.get_file_ext(filename)

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

siliconcompiler.utils.get_hashed_filename(path, package=None, hash=<built-in function openssl_sha1>)

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/file’)>.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.