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.

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.

join

Merges outputs from a list of input tasks.

minimum

Selects the task with the minimum metric score from a list of inputs.

maximum

Selects the task with the maximum metric score from a list of inputs.

mux

Selects a task from a list of inputs.

verify

Tests an assertion on a list of input tasks.

Utility functions:

archive

Archive a job directory.

audit_manifest

Verifies the integrity of the post-run compilation manifest.

calc_area

Calculates the area of a rectilinear diearea.

calc_yield

Calculates raw die yield.

calc_dpw

Calculates dies per wafer.

check_checklist

Check items in a checklist.

check_manifest

Verifies the integrity of the pre-run compilation manifest.

check_logfile

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

clock

Clock configuration helper function.

create_cmdline

Creates an SC command line interface.

find_files

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

find_function

Returns a function attribute from a module on disk.

find_result

Returns the absolute path of a compilation result.

grep

Emulates the Unix grep command on a string.

hash_files

Generates hash values for a list of parameter files.

list_metrics

Returns a list of all metrics in the schema.

list_steps

Returns an ordered list of flowgraph steps.

load_flow

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

load_lib

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

load_pdk

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

load_target

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

merge_manifest

Merges an external manifest with the current compilation manifest.

read_file

Read file defined in schema.

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.

write_manifest

Writes the compilation manifest to a file.

write_flowgraph

Renders and saves the compilation flowgraph to a file.

class siliconcompiler.core.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, cfg=None, field='value')

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.

  • cfg (dict) – Alternate dictionary to access in place of self.cfg

  • field (str) – Parameter field to set.

Examples

>>> chip.add('source', 'hello.v')
Adds the file 'hello.v' to the list of sources.
archive(step=None, index=None, all_files=False)

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 argumnets specified. By default, all steps and indices in the flowgraph are archived. By default, only the outputs directory content and the log file are archived.

Parameters
  • step (str) – Step to archive.

  • index (str) – Index to archive

  • all_files (bool) – If True, all files are archived.

audit_manifest()

Verifies the integrity of the post-run compilation manifest.

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

Audit checks performed include:

  • Time stamps

  • File modifications

  • Error and warning policy

  • IP and design origin

  • User access

  • License terms

  • Version checks

Returns

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

Example

>>> chip.audit_manifest()
Audits the Chip object manifest and returns 0 if successful.
calc_area()

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

Returns

Design area (float).

Examples

>>> area = chip.calc_area()
calc_dpw()

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.

Returns

Number of gross dies per wafer (int).

Examples

>>> dpw = chip.calc_dpw()
Variable dpw gets gross dies per wafer value based on the chip manifest.
calc_yield(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

model (string) – Model to use for calculation (poisson or murphy)

Returns

Design yield percentage (float).

Examples

>>> yield = chip.calc_yield()
Yield variable gets yield value based on the chip manifest.
check_checklist(standard, items=None, check_ok=False)

Check items in a checklist.

Checks the status of items in a checklist for the standard provided. If a specific list of items is unspecified, all items are checked.

All items have an associated ‘task’ parameter, which indicates which tasks can be used to automatically validate the item. For an item to be checked, all tasks must satisfy the item’s criteria, unless waivers are provided. In addition, that task must have generated EDA report files for each metric in the criteria.

For items without an associated task, the only requirement is that at least one report has been added to that item.

When ‘check_ok’ is True, every item must also have its ‘ok’ parameter set to True, indicating that a human has reviewed the item.

Parameters
  • standard (str) – Standard to check.

  • items (list of str) – Items to check from standard.

  • check_ok (bool) – Whether to check item ‘ok’ parameter.

Returns

Status of item check.

Examples

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

Verifies that paths to all files in manifest are valid.

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

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

Reads the content of the step’s log file and compares the content found in step ‘regex’ parameter. The matches are stored in the file ‘reports/<design>.<suffix>’ in the run directory. The matches are printed to STDOUT if display is set to True.

Parameters
  • step (str) – Task step name (‘syn’, ‘place’, etc)

  • jobname (str) – Jobid directory name

  • index (str) – Task index

  • display (bool) – If True, printes matches to STDOUT.

Examples

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

Verifies the integrity of the pre-run compilation manifest.

Checks the validity of the current schema manifest in memory to ensure that the design has been properly set up prior to running compilation. The function is called inside the run() function but can also be called separately. Checks performed by the check_manifest() function include:

  • Has a flowgraph been defined?

  • Does the manifest satisfy the schema requirement field settings?

  • Are all flowgraph input names legal step/index pairs?

  • Are the tool parameter setting requirements met?

Returns

Returns True if the manifest is valid, else returns False.

Examples

>>> manifest_ok = chip.check_manifest()
Returns True of the Chip object dictionary checks out.
clock(pin, period, jitter=0)

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’, name, ‘pin’] [‘datasheet’, name, ‘period’] [‘datasheet’, name, ‘jitter’]

Parameters
  • pin (str) – Full hiearchical path to clk pin.

  • period (float) – Clock period specified in ns.

  • jitter (float) – Clock jitter specified in ns.

Examples

>>> chip.clock('clk, period=1.0)

Create a clock named ‘clk’ with a 1.0ns period.

create_cmdline(progname, description=None, switchlist=None, input_map=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. fpga_partname

  3. load_target(‘target’)

  4. read_manifest([cfg])

  5. all other switches

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’, …] keypaths based on their file extension. If None, the CLI will not accept positional source arguments.

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': 'verilog'})
All sources ending in .v will be stored in ['input', 'verilog']
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.
find_files(*keypath, cfg=None, missing_ok=False, job=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.

  • cfg (dict) – Alternate dictionary to access in place of the default chip object schema dictionary.

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

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('source')
Returns a list of absolute paths to source files, as specified in
the schema.
find_function(modulename, funcname, moduletype=None)

Returns a function attribute from a module on disk.

Searches the SC root directory and the ‘scpath’ parameter for the modulename provided and imports the module if found. If the funcname provided is found in the module, a callable function attribute is returned, otherwise None is returned.

The function assumes the following directory structure:

  • tools/modulename/modulename.py

  • flows/modulename.py

  • pdks/modulname.py

If the moduletype is None, the module paths are search in the order: ‘targets’->’flows’->’tools’->’pdks’->’libs’->’checklists’):

Supported functions include:

  • targets (make_docs, setup)

  • pdks (make_docs, setup)

  • flows (make_docs, setup)

  • tools (make_docs, setup, check_version, runtime_options, pre_process, post_process)

  • libs (make_docs, setup)

Parameters
  • modulename (str) – Name of module to import.

  • funcname (str) – Name of the function to find within the module.

  • moduletype (str) – Type of module (flows, pdks, libs, checklists, targets).

Examples

>>> setup_pdk = chip.find_function('freepdk45', 'setup', 'pdks')
>>> setup_pdk()
Imports the freepdk45 module and runs the setup_pdk function
find_result(filetype, step, jobname=None, index='0')

Returns the absolute path of a compilation result.

Utility function that returns the absolute path to a results file based on the provided arguments. The result directory structure is:

<dir>/<design>/<jobname>/<step>/<index>/outputs/<design>.filetype

Parameters
  • filetype (str) – File extension (.v, .def, etc)

  • step (str) – Task step name (‘syn’, ‘place’, etc)

  • jobname (str) – Jobid directory name

  • index (str) – Task index

Returns

Returns absolute path to file.

Examples

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

Returns the absolute path to the manifest.

get(*keypath, field='value', job=None, cfg=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.

  • cfg (dict) – Alternate dictionary to access in place of the default chip object schema dictionary.

Returns

Value found for the keypath and field provided.

Examples

>>> foundry = chip.get('pdk', 'foundry')
Returns the name of the foundry from the PDK.
getdict(*keypath, cfg=None)

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

  • cfg (dict) – Alternate dictionary to access in place of self.cfg

Returns

A schema dictionary

Examples

>>> pdk = chip.getdict('pdk')
Returns the complete dictionary found for the keypath 'pdk'
getkeys(*keypath, cfg=None, 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

  • cfg (dict) – Alternate dictionary to access in place of self.cfg

  • 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.
>>> keylist = chip.getkeys()
Returns all list of all keypaths in the schema.
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 Creates a directed edge from place to cts.
grep(args, line)

Emulates the Unix grep command on a string.

Emulates the behavior of the Unix grep command that is etched into our muscle memory. Partially implemented, not all features supported. The function returns None if no match is found.

Parameters
  • arg (string) – Command line arguments for grep command

  • line (string) – Line to process

Returns

Result of grep command (string).

hash_files(*keypath, algo='sha256', update=True)

Generates hash values for a list of parameter files.

Generates a a hash value for each file found in the keypath. If the update variable is True, the has values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘values’ parameter field.

Files are located using the find_files() function.

The file hash calculation is performed basd on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.

Parameters
  • *keypath (str) – Keypath to parameter.

  • algo (str) – Algorithm to use for file hash calculation

  • update (bool) – If True, the hash values are recorded in the chip object manifest.

Returns

A list of hash values.

Examples

>>> hashlist = hash_files('sources')
 Hashlist gets list of hash values computed from 'sources' files.
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_library(lib_chip)

Import a Chip object into current Chip as a library.

Parameters

lib_chip (Chip) – An instance of Chip to import.

join(*tasks)

Merges outputs from a list of input tasks.

Parameters

tasks (list) – List of input tasks specified as (step,index) tuples.

Returns

Input list

Examples

>>> select = chip.join([('lvs','0'), ('drc','0')])

Select gets the list [(‘lvs’,’0’), (‘drc’,’0’)]

list_metrics()

Returns a list of all metrics in the schema.

list_steps(flow=None)

Returns an ordered list of flowgraph steps.

All step keys from the flowgraph dictionary are collected and the distance from the root node (ie. without any inputs defined) is measured for each step. The step list is then sorted based on the distance from root and returned.

Returns

A list of steps sorted by distance from the root node.

Example

>>> steplist = chip.list_steps()
Variable steplist gets list of steps sorted by distance from root.
load_checklist(name)

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

The function searches the $SCPATH for checklist/<name>/<name>.py and runs the setup function in that module if found.

Parameters

name (str) – Module name

Examples

>>> chip.load_checklist('oh_tapeout')
Loads the 'oh_tapeout' checklist
load_flow(name)

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

The function searches the $SCPATH for flows/<name>.py and runs the setup function in that module if found.

Parameters

name (str) – Module name

Examples

>>> chip.load_flow('asicflow')
Loads the 'asicflow' flow
load_lib(name)

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

The function searches the $SCPATH for libs/<name>.py and runs the setup function in that module if found.

Parameters

name (str) – Module name

Examples

>>> chip.load_lib('nangate45')
Loads the 'nangate45' library
load_pdk(name)

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

The function searches the $SCPATH for pdks/<name>.py and runs the setup function in that module if found.

Parameters

name (str) – Module name

Examples

>>> chip.load_pdk('freepdk45_pdk')
Loads the 'freepdk45' pdk
load_target(name)

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

The function searches the $SCPATH for targets/<name>.py and runs the setup function in that module if found.

Parameters
  • name (str) – Module name

  • flow (str) – Target flow to

Examples

>>> chip.load_target('freepdk45_demo')
Loads the 'freepdk45_demo' target
maximum(*tasks)

Selects the task with the maximum metric score from a list of inputs.

Sequence of operation:

  1. Check list of input tasks to see if all metrics meets goals

  2. Check list of input tasks to find global min/max for each metric

  3. Select MAX value if all metrics are met.

  4. Normalize the min value as sel = (val - MIN) / (MAX - MIN)

  5. Return normalized value and task name

Meeting metric goals takes precedence over compute metric scores. Only goals with values set and metrics with weights set are considered in the calculation.

Parameters

tasks (list) – List of input tasks specified as (step,index) tuples.

Returns

tuple containing

  • score (float): Maximum score.

  • task (tuple): Task with minimum score

Examples

>>> (score, task) = chip.maximum([('place','0'),('place','1')])
merge_manifest(cfg, job=None, clobber=True, clear=True, check=False)

Merges an external 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
  • 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

  • partial (bool) – If True, perform a partial merge, only merging keypaths that may have been updated during run().

Examples

>>> chip.merge_manifest('my.pkg.json')

Merges all parameters in my.pk.json into the Chip object

minimum(*tasks)

Selects the task with the minimum metric score from a list of inputs.

Sequence of operation:

  1. Check list of input tasks to see if all metrics meets goals

  2. Check list of input tasks to find global min/max for each metric

  3. Select MIN value if all metrics are met.

  4. Normalize the min value as sel = (val - MIN) / (MAX - MIN)

  5. Return normalized value and task name

Meeting metric goals takes precedence over compute metric scores. Only goals with values set and metrics with weights set are considered in the calculation.

Parameters

tasks (list) – List of input tasks specified as (step,index) tuples.

Returns

tuple containing

  • score (float): Minimum score

  • task (tuple): Task with minimum score

Examples

>>> (score, task) = chip.minimum([('place','0'),('place','1')])
mux(*tasks, **selector)

Selects a task from a list of inputs.

The selector criteria provided is used to create a custom function for selecting the best step/index pair from the inputs. Metrics and weights are passed in and used to select the step/index based on the minimum or maximum score depending on the ‘op’ argument.

The function can be used to bypass the flows weight functions for the purpose of conditional flow execution and verification.

Parameters
  • *steps (str) – List of steps to verify

  • **selector – Key value selection criteria.

Returns

True if all assertions hold True for all steps.

Example

>>> sel_stepindex = chip.mux(['route'], wirelength=0)
Selects the routing stepindex with the shortest wirelength.
node(flow, step, tool, index=0)

Creates a flowgraph node.

Creates a flowgraph node by binding a tool to a task. A task is defined as the combination of a step and index. A tool can be an external exeuctable 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:

[‘flowgraph’, flow, step, index, ‘tool’, tool] [‘flowgraph’, flow, step, index, ‘weight’, metric]

Parameters
  • flow (str) – Flow name

  • step (str) – Task step name

  • tool (str) – Tool (or builtin function) to associate with task.

  • index (int) – Task index

Examples

>>> chip.node('asicflow', 'place', 'openroad', index=0)
Creates a task with step='place' and index=0 and binds it to the 'openroad' tool.
nop(*task)

A no-operation that passes inputs to outputs.

Parameters

task (list) – Input task specified as a (step,index) tuple.

Returns

Input task

Examples

>>> select = chip.nop(('lvs','0'))

Select gets the tuple [(‘lvs’,0’)]

pipe(flow, plan)

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

read_file(filename, step='import', index='0')

Read file defined in schema. (WIP)

read_lef(path, pdkname, stackup)

Reads tech LEF and imports data into schema.

This function reads layer information from a provided tech LEF and uses it to fill out the ‘pdk’, <pdkname>, ‘grid’ keypaths of the current chip object.

Parameters
  • path (str) – Path to LEF file.

  • pdkname (str) – Name of PDK associated with LEF file.

  • stackup (str) – Stackup associated with LEF file.

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

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

run()

Executes tasks in a flowgraph.

The run function sets up tools and launches runs for every index in a step defined by a steplist. The steplist is taken from the schema steplist parameter if defined, otherwise the steplist is defined as the list of steps within the schema flowgraph dictionary. 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, cfg=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.

  • cfg (dict) – Alternate dictionary to access in place of self.cfg

Examples

>>> chip.set('design', 'top')
Sets the name of the design to 'top'
show(filename=None, extra_options=None)

Opens a graphical viewer for the filename provided.

The show function opens the filename specified using a viewer tool selected based on the file suffix and the ‘showtool’ schema setup. The ‘showtool’ parameter binds tools with file suffixes, enabling the automated dynamic loading of tool setup functions from siliconcompiler.tools.<tool>/<tool>.py. 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 directory.

The show() command can also be used to display content from an SC schema .json filename provided. In this case, the SC schema is converted to html and displayed as a ‘dashboard’ in the browser.

Filenames with .gz and .zip extensions are automatically unpacked before being displayed.

Parameters

filename – Name of file to display

Examples

>>> show('build/oh_add/job0/export/0/outputs/oh_add.gds')
Displays gds file with a viewer assigned by 'showtool'
>>> show('build/oh_add/job0/export/0/outputs/oh_add.pkg.json')
Displays manifest in the browser
summary(steplist=None, show_all_indices=False)

Prints a summary of the compilation manifest.

Metrics from the flowgraph steps, or steplist 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.
update()

Update the chip dependency graph.

  1. Finds all packages in the local cache

  2. Fetches all packages in the remote registry

  3. Creates a dependency graph based on current chip dependencies and dependencies read from dependency json objects.

  4. If autoinstall is set, copy registry packages to local cache.

  5. Error out if package is not found in local cache or in registry.

  6. Error out if autoinstall is set and registry package is missing.

valid(*args, valid_keypaths=None, quiet=True, default_valid=False)

Checks validity of a keypath.

Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.

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

  • valid_keypaths (list of list) – List of valid keypaths as lists. If None, check against all keypaths in the schema.

  • quiet (bool) – If True, don’t display warnings for invalid keypaths.

Returns

Boolean indicating validity of keypath.

Examples

>>> check = chip.valid('design')
Returns True.
>>> check = chip.valid('blah')
Returns False.
verify(*tasks, **assertion)

Tests an assertion on a list of input tasks.

The provided steplist is verified to ensure that all assertions are True. If any of the assertions fail, False is returned. Assertions are passed in as kwargs, with the key being a metric and the value being a number and an optional conditional operator. The allowed conditional operators are: >, <, >=, <=

Parameters
  • *steps (str) – List of steps to verify

  • **assertion (str='str') – Assertion to check on metric

Returns

True if all assertions hold True for all steps.

Example

>>> pass = chip.verify(['drc','lvs'], errors=0)
Pass is True if the error metrics in the drc, lvs steps is 0.
write_depgraph(filename)

Writes the package dependency tree to disk.

Supported graphical render formats include png, svg, gif, pdf and a few others. (see https://graphviz.org for more information).

Supported text formats include .md, .rst. (see the Linux ‘tree’ command for more information).

write_flowgraph(filename, flow=None, fillcolor='#ffffff', fontcolor='#000000', fontsize='14', border=True, landscape=False)

Renders and saves the compilation flowgraph to a file.

The chip object flowgraph is traversed to create a graphviz (*.dot) file comprised of node, edges, and labels. The dot file is a graphical representation of the flowgraph useful for validating the correctness of the execution flow graph. The dot file is then converted to the appropriate picture or drawing format based on the filename suffix provided. Supported output render formats include png, svg, gif, pdf and a few others. For more information about the graphviz project, see see https://graphviz.org/

Parameters
  • filename (filepath) – Output filepath

  • flow (str) – Name of flowgraph to render

  • fillcolor (str) – Node fill RGB color hex value

  • fontcolor (str) – Node font RGB color hex value

  • fontsize (str) – Node text font size

  • border (bool) – Enables node border if True

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

Examples

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

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, essential non-empty parameters 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
exception siliconcompiler.core.SiliconCompilerError(message)

Minimal Exception wrapper used to raise sc runtime errors.