2. Schema API#
This chapter describes all public methods in the SiliconCompiler Schema Python API. Refer to the User Guide for architecture concepts and the glossary for terminology and keyword definitions.
2.1. Useful APIs#
Base schema:
Sets a schema parameter field. |
|
Adds item(s) to a schema parameter list. |
|
Returns a parameter field from the schema. |
|
Returns a tuple of schema dictionary keys. |
|
Returns a schema dictionary. |
|
Checks validity of a keypath. |
|
Unsets a schema parameter. |
|
Remove a schema parameter and its subparameters. |
|
Writes the manifest to a file. |
|
Reads a manifest from disk and replaces the current data with the data in the file. |
|
Create a new schema based on the provided source files. |
Editing schema:
Inserts a |
|
Removes a keypath from the schema. |
|
Finds an item in the schema. |
2.2. Project Classes#
- class siliconcompiler.project.Project(design: Design | str | None = None)[source]#
Bases:
PathSchemaBase,CommandLineSchema,BaseSchemaThe Project class is the core object in SiliconCompiler, representing a complete hardware design project. It manages design parameters, libraries, flowgraphs, metrics, and provides methods for compilation, data collection, and reporting.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_alias(src_dep: Design | str, src_fileset: str, alias_dep: Design | str | None, alias_fileset: str | None, clobber: bool = False)[source]#
Adds an aliased fileset mapping to the project.
This method allows you to redirect a fileset reference from a source library/fileset to a different destination library/fileset. This is useful for substituting design components or test environments without modifying the original design.
- Parameters:
src_dep (Union[Design, str]) – The source design library (object or name) from which the fileset is being aliased.
src_fileset (str) – The name of the source fileset to alias.
alias_dep (Optional[Union[Design, str]]) – The destination design library (object or name) to which the fileset is being redirected. Can be None or an empty string to indicate deletion.
alias_fileset (Optional[str]) – The name of the destination fileset. Can be None or an empty string to indicate deletion of the fileset reference.
clobber (bool) – If True, any existing alias for (src_dep, src_fileset) will be overwritten. If False, the alias will be added. Defaults to False.
- Raises:
TypeError – If src_dep or alias_dep are not valid types (string or Design).
KeyError – If alias_dep is a string but the corresponding library is not loaded.
ValueError – If src_fileset is not found in src_dep, or if alias_fileset is not found in alias_dep (when alias_fileset is not None).
- add_dep(obj)[source]#
Adds a dependency object (e.g., a Design, Flowgraph, or Checklist) to the project.
This method intelligently adds various types of schema objects to the project’s internal structure. It also handles recursive addition of dependencies if the added object itself is a DependencySchema.
- Parameters:
obj (Union[Design, Flowgraph, Checklist, List, Set, Tuple]) – The dependency object(s) to add. Can be a single schema object or a collection (list, set, tuple) of schema objects.
- Raises:
NotImplementedError – If the type of the object is not supported.
- add_fileset(fileset: List[str] | str, clobber: bool = False)[source]#
Adds one or more filesets to be used in this project.
Filesets are collections of related files within a design. This method allows you to specify which filesets from the selected design library should be included in the current project context.
- Parameters:
- Raises:
TypeError – If fileset is not a string or a list/tuple/set of strings.
ValueError – If any of the specified filesets are not found in the currently selected design.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- check_manifest() bool[source]#
Performs a comprehensive check of the project’s manifest (configuration) for consistency and validity.
The checks are performed against a resolved copy of this project, so the configuration that
Project.run()would actually execute is what gets validated. Values that a run would infer, such as the design fileset or the ASIC main library, are therefore not reported as errors, but the inference itself is still reported as a warning. This project is left unmodified.- Returns:
True if the manifest is valid and all checks pass, False otherwise.
- Return type:
- classmethod convert(obj: Project) TProject[source]#
Converts a project from one type to another (e.g., Project to Sim).
- classmethod create_cmdline(progname: str | None = None, description: str | None = None, switchlist: List[str] | Set[str] | None = None, version: str | None = None, print_banner: bool = True, use_cfg: bool = False, use_sources: bool = True) TCmdSchema[source]#
Creates an SC command line interface.
Exposes parameters in the SC schema as command line switches, simplifying creation of SC apps with a restricted set of schema parameters exposed at the command line. The order of command line switch settings parsed from the command line is as follows:
read_manifest (-cfg), if specified by use_cfg
read commandline inputs
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.
- 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.
version (str) – version of this program.
print_banner (bool) – if True, will print the siliconcompiler banner
use_cfg (bool) – if True, add and parse the -cfg flag
use_sources (bool) – if True, add positional arguments for files
- Returns:
new project object
Examples
>>> schema.create_cmdline(progname='sc-show',switchlist=['-input','-cfg']) Creates a command line interface for 'sc-show' app.
>>> schema.create_cmdline(progname='sc')
- property design: Design#
Returns the design object associated with the project.
- Returns:
The Design schema object for the current project.
- Return type:
- Raises:
ValueError – If the design name is not set.
KeyError – If the design has not been loaded into the project’s libraries.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- find_result(filetype: str | None = None, step: str | None = None, index: str = '0', directory: str = 'outputs', filename: str | None = None) str | None[source]#
Returns the absolute path of a compilation result file.
This utility function constructs and returns the absolute path to a result file based on the provided arguments. The typical result directory structure is: <build_dir>/<design_name>/<job_name>/<step>/<index>/<directory>/<design>.<filetype>
- Parameters:
filetype (str, optional) – The file extension (e.g., ‘v’, ‘def’, ‘gds’). Required if filename is not provided.
step (str) – The name of the task step (e.g., ‘syn’, ‘place’). Required.
index (str, optional) – The task index within the step. Defaults to “0”.
directory (str, optional) – The node directory within the step to search (e.g., ‘outputs’, ‘reports’). Defaults to “outputs”.
filename (str, optional) – The exact filename to search for. If provided, filetype is ignored for constructing the path. Defaults to None.
- Returns:
The absolute path to the found file, or None if the file is not found.
- Return type:
- Raises:
ValueError – If step is not provided, or if [option,fileset] is not set when filename is not provided.
Examples
>>> # Get path to gate-level Verilog from synthesis step >>> vg_filepath = project.find_result('vg', step='syn')
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_filesets(library: Design | str | None = None, filesets: List[str] | None = None) List[Tuple[Design, str]][source]#
Returns the filesets selected for this project, resolving any aliases.
This method retrieves the filesets defined in
[option,fileset]and applies any aliases specified in[option,alias]to return the effective list of filesets and their parent libraries.- Parameters:
- Returns:
A list of tuples, where each tuple contains the parent library (Design) and the fileset name (str).
- Return type:
- Raises:
KeyError – If an alias points to a library that is not loaded.
- get_flow(name: str | None = None) Flowgraph[source]#
Retrieves a flowgraph by name.
The name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.- Parameters:
name (str, optional) – The full or partial (prefix) name of the flowgraph to retrieve. If None, the currently selected flowgraph (
[option,flow]) is used.- Returns:
The Flowgraph object corresponding to the resolved name.
- Return type:
- Raises:
KeyError – If no flow is currently selected (when name is None), if no loaded flowgraph matches the given name, or if a partial name matches more than one loaded flowgraph.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- history(job: str) Project[source]#
Returns a mutable reference to a historical job record as a Project object.
- property logger: Logger#
Returns the logger for this project.
- Returns:
The project-specific logger instance.
- Return type:
- property name: str#
Returns the name of the design.
- Returns:
The name of the top-level design.
- Return type:
- property option: OptionSchema#
Provides access to the top-level options schema.
This property is the entry point for configuring global and job-specific parameters that control the compiler’s behavior, such as flow control, logging, and build settings.
- Returns:
The schema object for top-level options.
- Return type:
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- run() TProject[source]#
Executes the compilation flow defined in the project’s flowgraph.
The run method orchestrates the entire compilation process. It starts by initializing the dashboard and then hands off execution to a Scheduler (or ClientScheduler for remote runs). The scheduler manages the step-by-step execution of tasks defined in the flowgraph, respecting dependencies and handling errors.
After the scheduler completes, the dashboard is updated with the final run status, and non-global job parameters are reset. The method returns a Project object representing the completed job’s history.
- Returns:
- A mutable reference to the completed job’s record in the
project history.
- Return type:
Examples
>>> project.run() # Executes the flow, and returns a project object for the completed job.
- set(*args, field='value', clobber=True, step=None, index=None)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_design(design: Design | str)[source]#
Sets the active design for this project.
This method allows you to specify the primary design that the project will operate on. If a Design object is provided, it is first added as a dependency.
- set_flow(flow: Flowgraph | str)[source]#
Sets the active flowgraph for this project.
This method allows you to specify the sequence of steps and tasks (the flow) that the project will execute. If a Flowgraph object is provided, it is first added as a dependency.
When given a string, the name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.
- show(filename: str | None = None, screenshot: bool = False, extension: str | None = None, tool: str | None = None, open: bool = False) str | None[source]#
Opens a graphical viewer for a specified file or the last generated layout.
The show function identifies an appropriate viewer tool based on the file’s extension and the registered showtools. Display settings and technology-specific viewing configurations are read from the project’s in-memory schema. All temporary rendering and display files are stored in a dedicated _show_<jobname> directory within the build directory.
If no filename is provided, the method attempts to automatically find the last generated layout file in the build directory based on supported extensions from registered showtools.
- Parameters:
filename (str, optional) – The path to the file to display. If None, the system attempts to find the most recent layout file. Defaults to None.
screenshot (bool) – If True, the operation is treated as a screenshot request, using ScreenshotTask instead of ShowTask. Defaults to False.
extension (str, optional) – The specific file extension to search for when automatically finding a file (e.g., ‘gds’, ‘lef’). Used only if filename is None. Defaults to None.
tool (str, optional) – The name of the specific showtool to use for displaying the file. If not provided, the tool is selected based on the file extension.
open (bool) – If True, the file is opened with an OpenTask (e.g. an interactive tool session) instead of being rendered with a ShowTask. Mutually exclusive with screenshot. Defaults to False.
- Returns:
- The path to the generated screenshot file if screenshot is True,
otherwise None.
- Return type:
Examples
>>> # Display a specific GDS file >>> project.show('build/my_design/job0/write_gds/0/outputs/my_design.gds')
>>> # Automatically find and show the last generated layout >>> project.show()
- snapshot(path: str | None = None, jobname: str | None = None, display: bool = True) None[source]#
Creates a snapshot image summarizing a job’s progress and key information.
This function generates a PNG image that provides a visual overview of the compilation job.
- Parameters:
path (str, optional) – The file path where the snapshot image should be saved. If not provided, it defaults to <job_directory>/<design_name>.png.
jobname (str, optional) – The job to snapshot. If not provided, the value in
[option,jobname]will be used.display (bool, optional) – If True, the generated image will be opened for viewing if the system supports it and option,nodisplay is False. Defaults to True.
- Raises:
ValueError – If there is no history to snapshot.
Examples
>>> project.snapshot() # Creates a snapshot image in the default location for the last run.
- summary(jobname: str | None = None, fd: TextIO | None = None) None[source]#
Prints a summary of the compilation manifest and results.
Metrics from the specified job are printed out on a per-step basis.
- Parameters:
jobname (str, optional) – The name of the job to summarize. If not provided, the value in
[option,jobname]will be used.fd (TextIO, optional) – If provided, prints the summary to this file descriptor instead of stdout.
- Raises:
ValueError – If there is no history to summarize.
Examples
>>> project.summary() # Prints a summary of the last run to stdout.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the configured fileset dependency graph to a file.
Shows the project’s design and its configured filesets, with any aliases resolved and reflected in the graph.
- Parameters:
Examples
>>> project.write_depgraph('mydump.png') Renders the fileset dependency graph and writes the result to a png file.
- class siliconcompiler.ASIC(design=None)[source]#
Bases:
ProjectThe ASIC class extends the base Project class to provide specialized functionality and schema parameters for Application-Specific Integrated Circuit (ASIC) design flows.
It includes specific constraints (timing, component, pin, area) and ASIC-related options such as PDK selection, main logic library, additional ASIC libraries, delay models, and routing layer limits.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_alias(src_dep: Design | str, src_fileset: str, alias_dep: Design | str | None, alias_fileset: str | None, clobber: bool = False)[source]#
Adds an aliased fileset mapping to the project.
This method allows you to redirect a fileset reference from a source library/fileset to a different destination library/fileset. This is useful for substituting design components or test environments without modifying the original design.
- Parameters:
src_dep (Union[Design, str]) – The source design library (object or name) from which the fileset is being aliased.
src_fileset (str) – The name of the source fileset to alias.
alias_dep (Optional[Union[Design, str]]) – The destination design library (object or name) to which the fileset is being redirected. Can be None or an empty string to indicate deletion.
alias_fileset (Optional[str]) – The name of the destination fileset. Can be None or an empty string to indicate deletion of the fileset reference.
clobber (bool) – If True, any existing alias for (src_dep, src_fileset) will be overwritten. If False, the alias will be added. Defaults to False.
- Raises:
TypeError – If src_dep or alias_dep are not valid types (string or Design).
KeyError – If alias_dep is a string but the corresponding library is not loaded.
ValueError – If src_fileset is not found in src_dep, or if alias_fileset is not found in alias_dep (when alias_fileset is not None).
- add_asiclib(library: StdCellLibrary | str, clobber: bool = False)[source]#
Adds one or more ASIC logic libraries to be used in the project.
These libraries are typically used for optimization during the ASIC flow, complementing the main library.
- Parameters:
library (Union[StdCellLibrary, str]) – The standard cell library object or its name (string) to add.
clobber (bool) – If True, existing ASIC libraries will be replaced by the new ones. If False, new libraries will be added to the existing list. Defaults to False.
- Returns:
The result of adding the parameter to the schema.
- Return type:
Any
- Raises:
TypeError – If the provided library is not a string or a StdCellLibrary object.
- add_dep(obj)[source]#
Adds a dependency object to the ASIC project, with specialized handling for PDK and standard cell libraries.
This method extends the base Project.add_dep functionality. If the object is a StdCellLibrary or PDK, it is inserted into the project’s library schema, potentially clobbering existing entries. For other dependency types, it defers to the parent class’s add_dep method. It also ensures that internal dependencies are imported.
- Parameters:
(Union[ (obj) – StdCellLibrary, PDK, Design, Flowgraph, Checklist, List, Set, Tuple
]) – The dependency object(s) to add.
- add_fileset(fileset: List[str] | str, clobber: bool = False)[source]#
Adds one or more filesets to be used in this project.
Filesets are collections of related files within a design. This method allows you to specify which filesets from the selected design library should be included in the current project context.
- Parameters:
- Raises:
TypeError – If fileset is not a string or a list/tuple/set of strings.
ValueError – If any of the specified filesets are not found in the currently selected design.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- check_manifest() bool[source]#
Performs a comprehensive check of the project’s manifest (configuration) for consistency and validity.
The checks are performed against a resolved copy of this project, so the configuration that
Project.run()would actually execute is what gets validated. Values that a run would infer, such as the design fileset or the ASIC main library, are therefore not reported as errors, but the inference itself is still reported as a warning. This project is left unmodified.- Returns:
True if the manifest is valid and all checks pass, False otherwise.
- Return type:
- property constraint: ASICConstraint#
Provides access to the project’s ASIC design constraints.
- Returns:
The schema object containing all design constraints.
- Return type:
- classmethod convert(obj: Project) TProject[source]#
Converts a project from one type to another (e.g., Project to Sim).
- classmethod create_cmdline(progname: str | None = None, description: str | None = None, switchlist: List[str] | Set[str] | None = None, version: str | None = None, print_banner: bool = True, use_cfg: bool = False, use_sources: bool = True) TCmdSchema[source]#
Creates an SC command line interface.
Exposes parameters in the SC schema as command line switches, simplifying creation of SC apps with a restricted set of schema parameters exposed at the command line. The order of command line switch settings parsed from the command line is as follows:
read_manifest (-cfg), if specified by use_cfg
read commandline inputs
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.
- 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.
version (str) – version of this program.
print_banner (bool) – if True, will print the siliconcompiler banner
use_cfg (bool) – if True, add and parse the -cfg flag
use_sources (bool) – if True, add positional arguments for files
- Returns:
new project object
Examples
>>> schema.create_cmdline(progname='sc-show',switchlist=['-input','-cfg']) Creates a command line interface for 'sc-show' app.
>>> schema.create_cmdline(progname='sc')
- property design: Design#
Returns the design object associated with the project.
- Returns:
The Design schema object for the current project.
- Return type:
- Raises:
ValueError – If the design name is not set.
KeyError – If the design has not been loaded into the project’s libraries.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- find_result(filetype: str | None = None, step: str | None = None, index: str = '0', directory: str = 'outputs', filename: str | None = None) str | None[source]#
Returns the absolute path of a compilation result file.
This utility function constructs and returns the absolute path to a result file based on the provided arguments. The typical result directory structure is: <build_dir>/<design_name>/<job_name>/<step>/<index>/<directory>/<design>.<filetype>
- Parameters:
filetype (str, optional) – The file extension (e.g., ‘v’, ‘def’, ‘gds’). Required if filename is not provided.
step (str) – The name of the task step (e.g., ‘syn’, ‘place’). Required.
index (str, optional) – The task index within the step. Defaults to “0”.
directory (str, optional) – The node directory within the step to search (e.g., ‘outputs’, ‘reports’). Defaults to “outputs”.
filename (str, optional) – The exact filename to search for. If provided, filetype is ignored for constructing the path. Defaults to None.
- Returns:
The absolute path to the found file, or None if the file is not found.
- Return type:
- Raises:
ValueError – If step is not provided, or if [option,fileset] is not set when filename is not provided.
Examples
>>> # Get path to gate-level Verilog from synthesis step >>> vg_filepath = project.find_result('vg', step='syn')
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_filesets(library: Design | str | None = None, filesets: List[str] | None = None) List[Tuple[Design, str]][source]#
Returns the filesets selected for this project, resolving any aliases.
This method retrieves the filesets defined in
[option,fileset]and applies any aliases specified in[option,alias]to return the effective list of filesets and their parent libraries.- Parameters:
- Returns:
A list of tuples, where each tuple contains the parent library (Design) and the fileset name (str).
- Return type:
- Raises:
KeyError – If an alias points to a library that is not loaded.
- get_flow(name: str | None = None) Flowgraph[source]#
Retrieves a flowgraph by name.
The name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.- Parameters:
name (str, optional) – The full or partial (prefix) name of the flowgraph to retrieve. If None, the currently selected flowgraph (
[option,flow]) is used.- Returns:
The Flowgraph object corresponding to the resolved name.
- Return type:
- Raises:
KeyError – If no flow is currently selected (when name is None), if no loaded flowgraph matches the given name, or if a partial name matches more than one loaded flowgraph.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- history(job: str) Project[source]#
Returns a mutable reference to a historical job record as a Project object.
- property logger: Logger#
Returns the logger for this project.
- Returns:
The project-specific logger instance.
- Return type:
- property name: str#
Returns the name of the design.
- Returns:
The name of the top-level design.
- Return type:
- property option: OptionSchema#
Provides access to the top-level options schema.
This property is the entry point for configuring global and job-specific parameters that control the compiler’s behavior, such as flow control, logging, and build settings.
- Returns:
The schema object for top-level options.
- Return type:
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- run() TProject[source]#
Executes the compilation flow defined in the project’s flowgraph.
The run method orchestrates the entire compilation process. It starts by initializing the dashboard and then hands off execution to a Scheduler (or ClientScheduler for remote runs). The scheduler manages the step-by-step execution of tasks defined in the flowgraph, respecting dependencies and handling errors.
After the scheduler completes, the dashboard is updated with the final run status, and non-global job parameters are reset. The method returns a Project object representing the completed job’s history.
- Returns:
- A mutable reference to the completed job’s record in the
project history.
- Return type:
Examples
>>> project.run() # Executes the flow, and returns a project object for the completed job.
- set(*args, field='value', clobber=True, step=None, index=None)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_asic_delaymodel(model: str)[source]#
Set the timing delay model used for ASIC timing analysis.
- Parameters:
model (str) – Delay model name (e.g., “nldm”, “ccs”).
- set_asic_routinglayers(min: str = None, max: str = None)[source]#
Sets the minimum and/or maximum metal layers to be used for automated place and route in the ASIC flow.
- set_design(design: Design | str)[source]#
Sets the active design for this project.
This method allows you to specify the primary design that the project will operate on. If a Design object is provided, it is first added as a dependency.
- set_flow(flow: Flowgraph | str)[source]#
Sets the active flowgraph for this project.
This method allows you to specify the sequence of steps and tasks (the flow) that the project will execute. If a Flowgraph object is provided, it is first added as a dependency.
When given a string, the name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.
- set_mainlib(library: StdCellLibrary | str)[source]#
Sets the main standard cell library for the ASIC project.
This library is typically the primary logic library used during the ASIC flow. If a StdCellLibrary object is provided, it is first added as a dependency.
- Parameters:
library (Union[StdCellLibrary, str]) – The standard cell library object or its name (string) to be set as the main library.
- Returns:
The result of setting the parameter in the schema.
- Return type:
Any
- Raises:
TypeError – If the provided library is not a string or a StdCellLibrary object.
- set_pdk(pdk: PDK | str)[source]#
Sets the Process Design Kit (PDK) for the ASIC project.
The PDK defines the technology-specific information required for ASIC compilation. If a PDK object is provided, it is first added as a dependency.
- show(filename: str | None = None, screenshot: bool = False, extension: str | None = None, tool: str | None = None, open: bool = False) str | None[source]#
Opens a graphical viewer for a specified file or the last generated layout.
The show function identifies an appropriate viewer tool based on the file’s extension and the registered showtools. Display settings and technology-specific viewing configurations are read from the project’s in-memory schema. All temporary rendering and display files are stored in a dedicated _show_<jobname> directory within the build directory.
If no filename is provided, the method attempts to automatically find the last generated layout file in the build directory based on supported extensions from registered showtools.
- Parameters:
filename (str, optional) – The path to the file to display. If None, the system attempts to find the most recent layout file. Defaults to None.
screenshot (bool) – If True, the operation is treated as a screenshot request, using ScreenshotTask instead of ShowTask. Defaults to False.
extension (str, optional) – The specific file extension to search for when automatically finding a file (e.g., ‘gds’, ‘lef’). Used only if filename is None. Defaults to None.
tool (str, optional) – The name of the specific showtool to use for displaying the file. If not provided, the tool is selected based on the file extension.
open (bool) – If True, the file is opened with an OpenTask (e.g. an interactive tool session) instead of being rendered with a ShowTask. Mutually exclusive with screenshot. Defaults to False.
- Returns:
- The path to the generated screenshot file if screenshot is True,
otherwise None.
- Return type:
Examples
>>> # Display a specific GDS file >>> project.show('build/my_design/job0/write_gds/0/outputs/my_design.gds')
>>> # Automatically find and show the last generated layout >>> project.show()
- snapshot(path: str | None = None, jobname: str | None = None, display: bool = True) None[source]#
Creates a snapshot image summarizing a job’s progress and key information.
This function generates a PNG image that provides a visual overview of the compilation job.
- Parameters:
path (str, optional) – The file path where the snapshot image should be saved. If not provided, it defaults to <job_directory>/<design_name>.png.
jobname (str, optional) – The job to snapshot. If not provided, the value in
[option,jobname]will be used.display (bool, optional) – If True, the generated image will be opened for viewing if the system supports it and option,nodisplay is False. Defaults to True.
- Raises:
ValueError – If there is no history to snapshot.
Examples
>>> project.snapshot() # Creates a snapshot image in the default location for the last run.
- summary(jobname: str | None = None, fd: TextIO | None = None) None[source]#
Prints a summary of the compilation manifest and results.
Metrics from the specified job are printed out on a per-step basis.
- Parameters:
jobname (str, optional) – The name of the job to summarize. If not provided, the value in
[option,jobname]will be used.fd (TextIO, optional) – If provided, prints the summary to this file descriptor instead of stdout.
- Raises:
ValueError – If there is no history to summarize.
Examples
>>> project.summary() # Prints a summary of the last run to stdout.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the configured fileset dependency graph to a file.
Shows the project’s design and its configured filesets, with any aliases resolved and reflected in the graph.
- Parameters:
Examples
>>> project.write_depgraph('mydump.png') Renders the fileset dependency graph and writes the result to a png file.
- class siliconcompiler.FPGA(design=None)[source]#
Bases:
ProjectA class for managing FPGA projects, inheriting from the base Project class.
This class extends the base project with FPGA-specific schema for constraints, metrics, and device selection. It provides methods to configure and validate
an FPGA design project.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_alias(src_dep: Design | str, src_fileset: str, alias_dep: Design | str | None, alias_fileset: str | None, clobber: bool = False)[source]#
Adds an aliased fileset mapping to the project.
This method allows you to redirect a fileset reference from a source library/fileset to a different destination library/fileset. This is useful for substituting design components or test environments without modifying the original design.
- Parameters:
src_dep (Union[Design, str]) – The source design library (object or name) from which the fileset is being aliased.
src_fileset (str) – The name of the source fileset to alias.
alias_dep (Optional[Union[Design, str]]) – The destination design library (object or name) to which the fileset is being redirected. Can be None or an empty string to indicate deletion.
alias_fileset (Optional[str]) – The name of the destination fileset. Can be None or an empty string to indicate deletion of the fileset reference.
clobber (bool) – If True, any existing alias for (src_dep, src_fileset) will be overwritten. If False, the alias will be added. Defaults to False.
- Raises:
TypeError – If src_dep or alias_dep are not valid types (string or Design).
KeyError – If alias_dep is a string but the corresponding library is not loaded.
ValueError – If src_fileset is not found in src_dep, or if alias_fileset is not found in alias_dep (when alias_fileset is not None).
- add_dep(obj)[source]#
Adds a dependency to the project.
If the dependency is an FPGADevice object, it is registered as a library. Otherwise, the request is passed to the parent class’s implementation.
- Parameters:
obj – The dependency object to add. Can be an FPGADevice instance or another type supported by the base Project class.
- add_fileset(fileset: List[str] | str, clobber: bool = False)[source]#
Adds one or more filesets to be used in this project.
Filesets are collections of related files within a design. This method allows you to specify which filesets from the selected design library should be included in the current project context.
- Parameters:
- Raises:
TypeError – If fileset is not a string or a list/tuple/set of strings.
ValueError – If any of the specified filesets are not found in the currently selected design.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- check_manifest() bool[source]#
Performs a comprehensive check of the project’s manifest (configuration) for consistency and validity.
The checks are performed against a resolved copy of this project, so the configuration that
Project.run()would actually execute is what gets validated. Values that a run would infer, such as the design fileset or the ASIC main library, are therefore not reported as errors, but the inference itself is still reported as a warning. This project is left unmodified.- Returns:
True if the manifest is valid and all checks pass, False otherwise.
- Return type:
- property constraint: FPGAConstraint#
Provides access to the project’s FPGA design constraints.
- Returns:
The schema object containing all design constraints.
- Return type:
- classmethod convert(obj: Project) TProject[source]#
Converts a project from one type to another (e.g., Project to Sim).
- classmethod create_cmdline(progname: str | None = None, description: str | None = None, switchlist: List[str] | Set[str] | None = None, version: str | None = None, print_banner: bool = True, use_cfg: bool = False, use_sources: bool = True) TCmdSchema[source]#
Creates an SC command line interface.
Exposes parameters in the SC schema as command line switches, simplifying creation of SC apps with a restricted set of schema parameters exposed at the command line. The order of command line switch settings parsed from the command line is as follows:
read_manifest (-cfg), if specified by use_cfg
read commandline inputs
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.
- 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.
version (str) – version of this program.
print_banner (bool) – if True, will print the siliconcompiler banner
use_cfg (bool) – if True, add and parse the -cfg flag
use_sources (bool) – if True, add positional arguments for files
- Returns:
new project object
Examples
>>> schema.create_cmdline(progname='sc-show',switchlist=['-input','-cfg']) Creates a command line interface for 'sc-show' app.
>>> schema.create_cmdline(progname='sc')
- property design: Design#
Returns the design object associated with the project.
- Returns:
The Design schema object for the current project.
- Return type:
- Raises:
ValueError – If the design name is not set.
KeyError – If the design has not been loaded into the project’s libraries.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- find_result(filetype: str | None = None, step: str | None = None, index: str = '0', directory: str = 'outputs', filename: str | None = None) str | None[source]#
Returns the absolute path of a compilation result file.
This utility function constructs and returns the absolute path to a result file based on the provided arguments. The typical result directory structure is: <build_dir>/<design_name>/<job_name>/<step>/<index>/<directory>/<design>.<filetype>
- Parameters:
filetype (str, optional) – The file extension (e.g., ‘v’, ‘def’, ‘gds’). Required if filename is not provided.
step (str) – The name of the task step (e.g., ‘syn’, ‘place’). Required.
index (str, optional) – The task index within the step. Defaults to “0”.
directory (str, optional) – The node directory within the step to search (e.g., ‘outputs’, ‘reports’). Defaults to “outputs”.
filename (str, optional) – The exact filename to search for. If provided, filetype is ignored for constructing the path. Defaults to None.
- Returns:
The absolute path to the found file, or None if the file is not found.
- Return type:
- Raises:
ValueError – If step is not provided, or if [option,fileset] is not set when filename is not provided.
Examples
>>> # Get path to gate-level Verilog from synthesis step >>> vg_filepath = project.find_result('vg', step='syn')
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_filesets(library: Design | str | None = None, filesets: List[str] | None = None) List[Tuple[Design, str]][source]#
Returns the filesets selected for this project, resolving any aliases.
This method retrieves the filesets defined in
[option,fileset]and applies any aliases specified in[option,alias]to return the effective list of filesets and their parent libraries.- Parameters:
- Returns:
A list of tuples, where each tuple contains the parent library (Design) and the fileset name (str).
- Return type:
- Raises:
KeyError – If an alias points to a library that is not loaded.
- get_flow(name: str | None = None) Flowgraph[source]#
Retrieves a flowgraph by name.
The name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.- Parameters:
name (str, optional) – The full or partial (prefix) name of the flowgraph to retrieve. If None, the currently selected flowgraph (
[option,flow]) is used.- Returns:
The Flowgraph object corresponding to the resolved name.
- Return type:
- Raises:
KeyError – If no flow is currently selected (when name is None), if no loaded flowgraph matches the given name, or if a partial name matches more than one loaded flowgraph.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- history(job: str) Project[source]#
Returns a mutable reference to a historical job record as a Project object.
- property logger: Logger#
Returns the logger for this project.
- Returns:
The project-specific logger instance.
- Return type:
- property name: str#
Returns the name of the design.
- Returns:
The name of the top-level design.
- Return type:
- property option: OptionSchema#
Provides access to the top-level options schema.
This property is the entry point for configuring global and job-specific parameters that control the compiler’s behavior, such as flow control, logging, and build settings.
- Returns:
The schema object for top-level options.
- Return type:
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- run() TProject[source]#
Executes the compilation flow defined in the project’s flowgraph.
The run method orchestrates the entire compilation process. It starts by initializing the dashboard and then hands off execution to a Scheduler (or ClientScheduler for remote runs). The scheduler manages the step-by-step execution of tasks defined in the flowgraph, respecting dependencies and handling errors.
After the scheduler completes, the dashboard is updated with the final run status, and non-global job parameters are reset. The method returns a Project object representing the completed job’s history.
- Returns:
- A mutable reference to the completed job’s record in the
project history.
- Return type:
Examples
>>> project.run() # Executes the flow, and returns a project object for the completed job.
- set(*args, field='value', clobber=True, step=None, index=None)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_design(design: Design | str)[source]#
Sets the active design for this project.
This method allows you to specify the primary design that the project will operate on. If a Design object is provided, it is first added as a dependency.
- set_flow(flow: Flowgraph | str)[source]#
Sets the active flowgraph for this project.
This method allows you to specify the sequence of steps and tasks (the flow) that the project will execute. If a Flowgraph object is provided, it is first added as a dependency.
When given a string, the name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.
- set_fpga(fpga: str | FPGADevice)[source]#
Sets the target FPGA device for the project.
This method can accept either an FPGADevice object or a string representing the name of the FPGA device. If an object is provided, it is first added as a dependency.
- Parameters:
fpga (FPGADevice or str) – The FPGADevice device to target.
- Raises:
TypeError – If the provided fpga is not an FPGADevice object or a string.
- show(filename: str | None = None, screenshot: bool = False, extension: str | None = None, tool: str | None = None, open: bool = False) str | None[source]#
Opens a graphical viewer for a specified file or the last generated layout.
The show function identifies an appropriate viewer tool based on the file’s extension and the registered showtools. Display settings and technology-specific viewing configurations are read from the project’s in-memory schema. All temporary rendering and display files are stored in a dedicated _show_<jobname> directory within the build directory.
If no filename is provided, the method attempts to automatically find the last generated layout file in the build directory based on supported extensions from registered showtools.
- Parameters:
filename (str, optional) – The path to the file to display. If None, the system attempts to find the most recent layout file. Defaults to None.
screenshot (bool) – If True, the operation is treated as a screenshot request, using ScreenshotTask instead of ShowTask. Defaults to False.
extension (str, optional) – The specific file extension to search for when automatically finding a file (e.g., ‘gds’, ‘lef’). Used only if filename is None. Defaults to None.
tool (str, optional) – The name of the specific showtool to use for displaying the file. If not provided, the tool is selected based on the file extension.
open (bool) – If True, the file is opened with an OpenTask (e.g. an interactive tool session) instead of being rendered with a ShowTask. Mutually exclusive with screenshot. Defaults to False.
- Returns:
- The path to the generated screenshot file if screenshot is True,
otherwise None.
- Return type:
Examples
>>> # Display a specific GDS file >>> project.show('build/my_design/job0/write_gds/0/outputs/my_design.gds')
>>> # Automatically find and show the last generated layout >>> project.show()
- snapshot(path: str | None = None, jobname: str | None = None, display: bool = True) None[source]#
Creates a snapshot image summarizing a job’s progress and key information.
This function generates a PNG image that provides a visual overview of the compilation job.
- Parameters:
path (str, optional) – The file path where the snapshot image should be saved. If not provided, it defaults to <job_directory>/<design_name>.png.
jobname (str, optional) – The job to snapshot. If not provided, the value in
[option,jobname]will be used.display (bool, optional) – If True, the generated image will be opened for viewing if the system supports it and option,nodisplay is False. Defaults to True.
- Raises:
ValueError – If there is no history to snapshot.
Examples
>>> project.snapshot() # Creates a snapshot image in the default location for the last run.
- summary(jobname: str | None = None, fd: TextIO | None = None) None[source]#
Prints a summary of the compilation manifest and results.
Metrics from the specified job are printed out on a per-step basis.
- Parameters:
jobname (str, optional) – The name of the job to summarize. If not provided, the value in
[option,jobname]will be used.fd (TextIO, optional) – If provided, prints the summary to this file descriptor instead of stdout.
- Raises:
ValueError – If there is no history to summarize.
Examples
>>> project.summary() # Prints a summary of the last run to stdout.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the configured fileset dependency graph to a file.
Shows the project’s design and its configured filesets, with any aliases resolved and reflected in the graph.
- Parameters:
Examples
>>> project.write_depgraph('mydump.png') Renders the fileset dependency graph and writes the result to a png file.
- class siliconcompiler.Lint(design: Design | str | None = None)[source]#
Bases:
ProjectA specialized Project class tailored for linting tasks.
This class can be extended with linting-specific schema parameters, methods, and flows.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_alias(src_dep: Design | str, src_fileset: str, alias_dep: Design | str | None, alias_fileset: str | None, clobber: bool = False)[source]#
Adds an aliased fileset mapping to the project.
This method allows you to redirect a fileset reference from a source library/fileset to a different destination library/fileset. This is useful for substituting design components or test environments without modifying the original design.
- Parameters:
src_dep (Union[Design, str]) – The source design library (object or name) from which the fileset is being aliased.
src_fileset (str) – The name of the source fileset to alias.
alias_dep (Optional[Union[Design, str]]) – The destination design library (object or name) to which the fileset is being redirected. Can be None or an empty string to indicate deletion.
alias_fileset (Optional[str]) – The name of the destination fileset. Can be None or an empty string to indicate deletion of the fileset reference.
clobber (bool) – If True, any existing alias for (src_dep, src_fileset) will be overwritten. If False, the alias will be added. Defaults to False.
- Raises:
TypeError – If src_dep or alias_dep are not valid types (string or Design).
KeyError – If alias_dep is a string but the corresponding library is not loaded.
ValueError – If src_fileset is not found in src_dep, or if alias_fileset is not found in alias_dep (when alias_fileset is not None).
- add_dep(obj)[source]#
Adds a dependency object (e.g., a Design, Flowgraph, or Checklist) to the project.
This method intelligently adds various types of schema objects to the project’s internal structure. It also handles recursive addition of dependencies if the added object itself is a DependencySchema.
- Parameters:
obj (Union[Design, Flowgraph, Checklist, List, Set, Tuple]) – The dependency object(s) to add. Can be a single schema object or a collection (list, set, tuple) of schema objects.
- Raises:
NotImplementedError – If the type of the object is not supported.
- add_fileset(fileset: List[str] | str, clobber: bool = False)[source]#
Adds one or more filesets to be used in this project.
Filesets are collections of related files within a design. This method allows you to specify which filesets from the selected design library should be included in the current project context.
- Parameters:
- Raises:
TypeError – If fileset is not a string or a list/tuple/set of strings.
ValueError – If any of the specified filesets are not found in the currently selected design.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- check_manifest() bool[source]#
Performs a comprehensive check of the project’s manifest (configuration) for consistency and validity.
The checks are performed against a resolved copy of this project, so the configuration that
Project.run()would actually execute is what gets validated. Values that a run would infer, such as the design fileset or the ASIC main library, are therefore not reported as errors, but the inference itself is still reported as a warning. This project is left unmodified.- Returns:
True if the manifest is valid and all checks pass, False otherwise.
- Return type:
- classmethod convert(obj: Project) TProject[source]#
Converts a project from one type to another (e.g., Project to Sim).
- classmethod create_cmdline(progname: str | None = None, description: str | None = None, switchlist: List[str] | Set[str] | None = None, version: str | None = None, print_banner: bool = True, use_cfg: bool = False, use_sources: bool = True) TCmdSchema[source]#
Creates an SC command line interface.
Exposes parameters in the SC schema as command line switches, simplifying creation of SC apps with a restricted set of schema parameters exposed at the command line. The order of command line switch settings parsed from the command line is as follows:
read_manifest (-cfg), if specified by use_cfg
read commandline inputs
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.
- 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.
version (str) – version of this program.
print_banner (bool) – if True, will print the siliconcompiler banner
use_cfg (bool) – if True, add and parse the -cfg flag
use_sources (bool) – if True, add positional arguments for files
- Returns:
new project object
Examples
>>> schema.create_cmdline(progname='sc-show',switchlist=['-input','-cfg']) Creates a command line interface for 'sc-show' app.
>>> schema.create_cmdline(progname='sc')
- property design: Design#
Returns the design object associated with the project.
- Returns:
The Design schema object for the current project.
- Return type:
- Raises:
ValueError – If the design name is not set.
KeyError – If the design has not been loaded into the project’s libraries.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- find_result(filetype: str | None = None, step: str | None = None, index: str = '0', directory: str = 'outputs', filename: str | None = None) str | None[source]#
Returns the absolute path of a compilation result file.
This utility function constructs and returns the absolute path to a result file based on the provided arguments. The typical result directory structure is: <build_dir>/<design_name>/<job_name>/<step>/<index>/<directory>/<design>.<filetype>
- Parameters:
filetype (str, optional) – The file extension (e.g., ‘v’, ‘def’, ‘gds’). Required if filename is not provided.
step (str) – The name of the task step (e.g., ‘syn’, ‘place’). Required.
index (str, optional) – The task index within the step. Defaults to “0”.
directory (str, optional) – The node directory within the step to search (e.g., ‘outputs’, ‘reports’). Defaults to “outputs”.
filename (str, optional) – The exact filename to search for. If provided, filetype is ignored for constructing the path. Defaults to None.
- Returns:
The absolute path to the found file, or None if the file is not found.
- Return type:
- Raises:
ValueError – If step is not provided, or if [option,fileset] is not set when filename is not provided.
Examples
>>> # Get path to gate-level Verilog from synthesis step >>> vg_filepath = project.find_result('vg', step='syn')
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_filesets(library: Design | str | None = None, filesets: List[str] | None = None) List[Tuple[Design, str]][source]#
Returns the filesets selected for this project, resolving any aliases.
This method retrieves the filesets defined in
[option,fileset]and applies any aliases specified in[option,alias]to return the effective list of filesets and their parent libraries.- Parameters:
- Returns:
A list of tuples, where each tuple contains the parent library (Design) and the fileset name (str).
- Return type:
- Raises:
KeyError – If an alias points to a library that is not loaded.
- get_flow(name: str | None = None) Flowgraph[source]#
Retrieves a flowgraph by name.
The name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.- Parameters:
name (str, optional) – The full or partial (prefix) name of the flowgraph to retrieve. If None, the currently selected flowgraph (
[option,flow]) is used.- Returns:
The Flowgraph object corresponding to the resolved name.
- Return type:
- Raises:
KeyError – If no flow is currently selected (when name is None), if no loaded flowgraph matches the given name, or if a partial name matches more than one loaded flowgraph.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- history(job: str) Project[source]#
Returns a mutable reference to a historical job record as a Project object.
- property logger: Logger#
Returns the logger for this project.
- Returns:
The project-specific logger instance.
- Return type:
- property name: str#
Returns the name of the design.
- Returns:
The name of the top-level design.
- Return type:
- property option: OptionSchema#
Provides access to the top-level options schema.
This property is the entry point for configuring global and job-specific parameters that control the compiler’s behavior, such as flow control, logging, and build settings.
- Returns:
The schema object for top-level options.
- Return type:
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- run() TProject[source]#
Executes the compilation flow defined in the project’s flowgraph.
The run method orchestrates the entire compilation process. It starts by initializing the dashboard and then hands off execution to a Scheduler (or ClientScheduler for remote runs). The scheduler manages the step-by-step execution of tasks defined in the flowgraph, respecting dependencies and handling errors.
After the scheduler completes, the dashboard is updated with the final run status, and non-global job parameters are reset. The method returns a Project object representing the completed job’s history.
- Returns:
- A mutable reference to the completed job’s record in the
project history.
- Return type:
Examples
>>> project.run() # Executes the flow, and returns a project object for the completed job.
- set(*args, field='value', clobber=True, step=None, index=None)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_design(design: Design | str)[source]#
Sets the active design for this project.
This method allows you to specify the primary design that the project will operate on. If a Design object is provided, it is first added as a dependency.
- set_flow(flow: Flowgraph | str)[source]#
Sets the active flowgraph for this project.
This method allows you to specify the sequence of steps and tasks (the flow) that the project will execute. If a Flowgraph object is provided, it is first added as a dependency.
When given a string, the name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.
- show(filename: str | None = None, screenshot: bool = False, extension: str | None = None, tool: str | None = None, open: bool = False) str | None[source]#
Opens a graphical viewer for a specified file or the last generated layout.
The show function identifies an appropriate viewer tool based on the file’s extension and the registered showtools. Display settings and technology-specific viewing configurations are read from the project’s in-memory schema. All temporary rendering and display files are stored in a dedicated _show_<jobname> directory within the build directory.
If no filename is provided, the method attempts to automatically find the last generated layout file in the build directory based on supported extensions from registered showtools.
- Parameters:
filename (str, optional) – The path to the file to display. If None, the system attempts to find the most recent layout file. Defaults to None.
screenshot (bool) – If True, the operation is treated as a screenshot request, using ScreenshotTask instead of ShowTask. Defaults to False.
extension (str, optional) – The specific file extension to search for when automatically finding a file (e.g., ‘gds’, ‘lef’). Used only if filename is None. Defaults to None.
tool (str, optional) – The name of the specific showtool to use for displaying the file. If not provided, the tool is selected based on the file extension.
open (bool) – If True, the file is opened with an OpenTask (e.g. an interactive tool session) instead of being rendered with a ShowTask. Mutually exclusive with screenshot. Defaults to False.
- Returns:
- The path to the generated screenshot file if screenshot is True,
otherwise None.
- Return type:
Examples
>>> # Display a specific GDS file >>> project.show('build/my_design/job0/write_gds/0/outputs/my_design.gds')
>>> # Automatically find and show the last generated layout >>> project.show()
- snapshot(path: str | None = None, jobname: str | None = None, display: bool = True) None[source]#
Creates a snapshot image summarizing a job’s progress and key information.
This function generates a PNG image that provides a visual overview of the compilation job.
- Parameters:
path (str, optional) – The file path where the snapshot image should be saved. If not provided, it defaults to <job_directory>/<design_name>.png.
jobname (str, optional) – The job to snapshot. If not provided, the value in
[option,jobname]will be used.display (bool, optional) – If True, the generated image will be opened for viewing if the system supports it and option,nodisplay is False. Defaults to True.
- Raises:
ValueError – If there is no history to snapshot.
Examples
>>> project.snapshot() # Creates a snapshot image in the default location for the last run.
- summary(jobname: str | None = None, fd: TextIO | None = None) None[source]#
Prints a summary of the compilation manifest and results.
Metrics from the specified job are printed out on a per-step basis.
- Parameters:
jobname (str, optional) – The name of the job to summarize. If not provided, the value in
[option,jobname]will be used.fd (TextIO, optional) – If provided, prints the summary to this file descriptor instead of stdout.
- Raises:
ValueError – If there is no history to summarize.
Examples
>>> project.summary() # Prints a summary of the last run to stdout.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the configured fileset dependency graph to a file.
Shows the project’s design and its configured filesets, with any aliases resolved and reflected in the graph.
- Parameters:
Examples
>>> project.write_depgraph('mydump.png') Renders the fileset dependency graph and writes the result to a png file.
- class siliconcompiler.Sim(design: Design | str | None = None)[source]#
Bases:
ProjectA specialized Project class tailored for simulation tasks.
This class can be extended with simulation-specific schema parameters, methods, and flows.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_alias(src_dep: Design | str, src_fileset: str, alias_dep: Design | str | None, alias_fileset: str | None, clobber: bool = False)[source]#
Adds an aliased fileset mapping to the project.
This method allows you to redirect a fileset reference from a source library/fileset to a different destination library/fileset. This is useful for substituting design components or test environments without modifying the original design.
- Parameters:
src_dep (Union[Design, str]) – The source design library (object or name) from which the fileset is being aliased.
src_fileset (str) – The name of the source fileset to alias.
alias_dep (Optional[Union[Design, str]]) – The destination design library (object or name) to which the fileset is being redirected. Can be None or an empty string to indicate deletion.
alias_fileset (Optional[str]) – The name of the destination fileset. Can be None or an empty string to indicate deletion of the fileset reference.
clobber (bool) – If True, any existing alias for (src_dep, src_fileset) will be overwritten. If False, the alias will be added. Defaults to False.
- Raises:
TypeError – If src_dep or alias_dep are not valid types (string or Design).
KeyError – If alias_dep is a string but the corresponding library is not loaded.
ValueError – If src_fileset is not found in src_dep, or if alias_fileset is not found in alias_dep (when alias_fileset is not None).
- add_dep(obj)[source]#
Adds a dependency object (e.g., a Design, Flowgraph, or Checklist) to the project.
This method intelligently adds various types of schema objects to the project’s internal structure. It also handles recursive addition of dependencies if the added object itself is a DependencySchema.
- Parameters:
obj (Union[Design, Flowgraph, Checklist, List, Set, Tuple]) – The dependency object(s) to add. Can be a single schema object or a collection (list, set, tuple) of schema objects.
- Raises:
NotImplementedError – If the type of the object is not supported.
- add_fileset(fileset: List[str] | str, clobber: bool = False)[source]#
Adds one or more filesets to be used in this project.
Filesets are collections of related files within a design. This method allows you to specify which filesets from the selected design library should be included in the current project context.
- Parameters:
- Raises:
TypeError – If fileset is not a string or a list/tuple/set of strings.
ValueError – If any of the specified filesets are not found in the currently selected design.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- check_manifest() bool[source]#
Performs a comprehensive check of the project’s manifest (configuration) for consistency and validity.
The checks are performed against a resolved copy of this project, so the configuration that
Project.run()would actually execute is what gets validated. Values that a run would infer, such as the design fileset or the ASIC main library, are therefore not reported as errors, but the inference itself is still reported as a warning. This project is left unmodified.- Returns:
True if the manifest is valid and all checks pass, False otherwise.
- Return type:
- classmethod convert(obj: Project) TProject[source]#
Converts a project from one type to another (e.g., Project to Sim).
- classmethod create_cmdline(progname: str | None = None, description: str | None = None, switchlist: List[str] | Set[str] | None = None, version: str | None = None, print_banner: bool = True, use_cfg: bool = False, use_sources: bool = True) TCmdSchema[source]#
Creates an SC command line interface.
Exposes parameters in the SC schema as command line switches, simplifying creation of SC apps with a restricted set of schema parameters exposed at the command line. The order of command line switch settings parsed from the command line is as follows:
read_manifest (-cfg), if specified by use_cfg
read commandline inputs
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.
- 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.
version (str) – version of this program.
print_banner (bool) – if True, will print the siliconcompiler banner
use_cfg (bool) – if True, add and parse the -cfg flag
use_sources (bool) – if True, add positional arguments for files
- Returns:
new project object
Examples
>>> schema.create_cmdline(progname='sc-show',switchlist=['-input','-cfg']) Creates a command line interface for 'sc-show' app.
>>> schema.create_cmdline(progname='sc')
- property design: Design#
Returns the design object associated with the project.
- Returns:
The Design schema object for the current project.
- Return type:
- Raises:
ValueError – If the design name is not set.
KeyError – If the design has not been loaded into the project’s libraries.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- find_result(filetype: str | None = None, step: str | None = None, index: str = '0', directory: str = 'outputs', filename: str | None = None) str | None[source]#
Returns the absolute path of a compilation result file.
This utility function constructs and returns the absolute path to a result file based on the provided arguments. The typical result directory structure is: <build_dir>/<design_name>/<job_name>/<step>/<index>/<directory>/<design>.<filetype>
- Parameters:
filetype (str, optional) – The file extension (e.g., ‘v’, ‘def’, ‘gds’). Required if filename is not provided.
step (str) – The name of the task step (e.g., ‘syn’, ‘place’). Required.
index (str, optional) – The task index within the step. Defaults to “0”.
directory (str, optional) – The node directory within the step to search (e.g., ‘outputs’, ‘reports’). Defaults to “outputs”.
filename (str, optional) – The exact filename to search for. If provided, filetype is ignored for constructing the path. Defaults to None.
- Returns:
The absolute path to the found file, or None if the file is not found.
- Return type:
- Raises:
ValueError – If step is not provided, or if [option,fileset] is not set when filename is not provided.
Examples
>>> # Get path to gate-level Verilog from synthesis step >>> vg_filepath = project.find_result('vg', step='syn')
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_filesets(library: Design | str | None = None, filesets: List[str] | None = None) List[Tuple[Design, str]][source]#
Returns the filesets selected for this project, resolving any aliases.
This method retrieves the filesets defined in
[option,fileset]and applies any aliases specified in[option,alias]to return the effective list of filesets and their parent libraries.- Parameters:
- Returns:
A list of tuples, where each tuple contains the parent library (Design) and the fileset name (str).
- Return type:
- Raises:
KeyError – If an alias points to a library that is not loaded.
- get_flow(name: str | None = None) Flowgraph[source]#
Retrieves a flowgraph by name.
The name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.- Parameters:
name (str, optional) – The full or partial (prefix) name of the flowgraph to retrieve. If None, the currently selected flowgraph (
[option,flow]) is used.- Returns:
The Flowgraph object corresponding to the resolved name.
- Return type:
- Raises:
KeyError – If no flow is currently selected (when name is None), if no loaded flowgraph matches the given name, or if a partial name matches more than one loaded flowgraph.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- history(job: str) Project[source]#
Returns a mutable reference to a historical job record as a Project object.
- property logger: Logger#
Returns the logger for this project.
- Returns:
The project-specific logger instance.
- Return type:
- property name: str#
Returns the name of the design.
- Returns:
The name of the top-level design.
- Return type:
- property option: OptionSchema#
Provides access to the top-level options schema.
This property is the entry point for configuring global and job-specific parameters that control the compiler’s behavior, such as flow control, logging, and build settings.
- Returns:
The schema object for top-level options.
- Return type:
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- run() TProject[source]#
Executes the compilation flow defined in the project’s flowgraph.
The run method orchestrates the entire compilation process. It starts by initializing the dashboard and then hands off execution to a Scheduler (or ClientScheduler for remote runs). The scheduler manages the step-by-step execution of tasks defined in the flowgraph, respecting dependencies and handling errors.
After the scheduler completes, the dashboard is updated with the final run status, and non-global job parameters are reset. The method returns a Project object representing the completed job’s history.
- Returns:
- A mutable reference to the completed job’s record in the
project history.
- Return type:
Examples
>>> project.run() # Executes the flow, and returns a project object for the completed job.
- set(*args, field='value', clobber=True, step=None, index=None)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_design(design: Design | str)[source]#
Sets the active design for this project.
This method allows you to specify the primary design that the project will operate on. If a Design object is provided, it is first added as a dependency.
- set_flow(flow: Flowgraph | str)[source]#
Sets the active flowgraph for this project.
This method allows you to specify the sequence of steps and tasks (the flow) that the project will execute. If a Flowgraph object is provided, it is first added as a dependency.
When given a string, the name is resolved against the flowgraphs already loaded into the project. An exact match is preferred; if none exists, the name is treated as a prefix and matched against the loaded flowgraph names. This allows a short name to select a variant-suffixed flow, for example
"synflow"resolves to"synflow-verilog". The match must be unique: if the prefix matches more than one loaded flowgraph, a warning listing the candidates is logged and a KeyError is raised.
- show(filename: str | None = None, screenshot: bool = False, extension: str | None = None, tool: str | None = None, open: bool = False) str | None[source]#
Opens a graphical viewer for a specified file or the last generated layout.
The show function identifies an appropriate viewer tool based on the file’s extension and the registered showtools. Display settings and technology-specific viewing configurations are read from the project’s in-memory schema. All temporary rendering and display files are stored in a dedicated _show_<jobname> directory within the build directory.
If no filename is provided, the method attempts to automatically find the last generated layout file in the build directory based on supported extensions from registered showtools.
- Parameters:
filename (str, optional) – The path to the file to display. If None, the system attempts to find the most recent layout file. Defaults to None.
screenshot (bool) – If True, the operation is treated as a screenshot request, using ScreenshotTask instead of ShowTask. Defaults to False.
extension (str, optional) – The specific file extension to search for when automatically finding a file (e.g., ‘gds’, ‘lef’). Used only if filename is None. Defaults to None.
tool (str, optional) – The name of the specific showtool to use for displaying the file. If not provided, the tool is selected based on the file extension.
open (bool) – If True, the file is opened with an OpenTask (e.g. an interactive tool session) instead of being rendered with a ShowTask. Mutually exclusive with screenshot. Defaults to False.
- Returns:
- The path to the generated screenshot file if screenshot is True,
otherwise None.
- Return type:
Examples
>>> # Display a specific GDS file >>> project.show('build/my_design/job0/write_gds/0/outputs/my_design.gds')
>>> # Automatically find and show the last generated layout >>> project.show()
- snapshot(path: str | None = None, jobname: str | None = None, display: bool = True) None[source]#
Creates a snapshot image summarizing a job’s progress and key information.
This function generates a PNG image that provides a visual overview of the compilation job.
- Parameters:
path (str, optional) – The file path where the snapshot image should be saved. If not provided, it defaults to <job_directory>/<design_name>.png.
jobname (str, optional) – The job to snapshot. If not provided, the value in
[option,jobname]will be used.display (bool, optional) – If True, the generated image will be opened for viewing if the system supports it and option,nodisplay is False. Defaults to True.
- Raises:
ValueError – If there is no history to snapshot.
Examples
>>> project.snapshot() # Creates a snapshot image in the default location for the last run.
- summary(jobname: str | None = None, fd: TextIO | None = None) None[source]#
Prints a summary of the compilation manifest and results.
Metrics from the specified job are printed out on a per-step basis.
- Parameters:
jobname (str, optional) – The name of the job to summarize. If not provided, the value in
[option,jobname]will be used.fd (TextIO, optional) – If provided, prints the summary to this file descriptor instead of stdout.
- Raises:
ValueError – If there is no history to summarize.
Examples
>>> project.summary() # Prints a summary of the last run to stdout.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the configured fileset dependency graph to a file.
Shows the project’s design and its configured filesets, with any aliases resolved and reflected in the graph.
- Parameters:
Examples
>>> project.write_depgraph('mydump.png') Renders the fileset dependency graph and writes the result to a png file.
2.3. User Classes#
- class siliconcompiler.Design(name: str | None = None)[source]#
Bases:
DependencySchema,PathSchema,NamedSchemaSchema for a ‘design’.
This class inherits from
DependencySchemaandFileSetSchema, adds parameters and methods specific to describing a design, such as its top module, source filesets, and compilation settings.- active_dataroot(dataroot: str | None = None)#
Use this context to set the dataroot parameter on files and directory parameters.
- Parameters:
dataroot (str) – name of the dataroot
Example
>>> with schema.active_dataroot("lambdalib"): ... schema.set("file", "top.v") Sets the file to top.v and associates lambdalib as the dataroot.
- active_fileset(fileset: str)#
Provides a context to temporarily set an active design fileset.
This is useful for applying a set of configurations to a specific fileset without repeatedly passing its name.
- Raises:
TypeError – If fileset is not a string.
ValueError – If fileset is an empty string.
- Parameters:
fileset (str) – The name of the fileset to activate.
Example
>>> with design.active_fileset("rtl"): ... design.set_topmodule("top") # This sets the top module for the 'rtl' fileset to 'top'.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_define(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro definitions to a fileset.
- add_dep(obj: NamedSchema, clobber: bool = True) bool[source]#
Adds a module dependency to this design.
This method extends the base add_dep to prevent a design from adding a dependency on itself.
- Parameters:
obj (NamedSchema) – The dependency object to add.
clobber (bool) – If True, overwrite an existing dependency with the same name.
- Returns:
True if the dependency was added, False otherwise.
- Return type:
- Raises:
TypeError – If obj is not a NamedSchema.
ValueError – If obj has the same name as the current design.
- add_depfileset(dep: Design | str, depfileset: str | None = None, fileset: str | None = None)[source]#
Record a reference to an imported dependency’s fileset.
- Parameters:
- add_file(filename: List[Path | str] | Set[Path | str] | Tuple[Path | str, ...] | Path | str, fileset: str | None = None, filetype: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds files to a fileset.
Based on the file’s extension, this method can often infer the correct fileset and filetype. For example:
.v -> (source, verilog)
.vhd -> (source, vhdl)
.sdc -> (constraint, sdc)
.lef -> (input, lef)
.def -> (input, def)
etc.
- Parameters:
filename (Path, str, or collection) – File path (Path or str), or a collection (list, tuple, set) of file paths to add.
fileset (str) – Logical group to associate the file with.
filetype (str, optional) – Type of the file (e.g., ‘verilog’, ‘sdc’).
clobber (bool, optional) – If True, clears the list before adding the item. Defaults to False.
dataroot (str, optional) – Data directory reference name.
- Raises:
ValueError – If fileset or filetype cannot be inferred from the file extension.
- Returns:
A list of the file paths that were added.
- Return type:
Notes
This method normalizes filename to a string for consistency.
- If filetype is not specified, it is inferred from the
file extension.
- add_idir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds include directories to a fileset.
- Parameters:
- Returns:
List of include directories
- Return type:
- add_lib(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds dynamic libraries to a fileset.
- add_libdir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds dynamic library directories to a fileset.
- Parameters:
- Returns:
List of library directories.
- Return type:
- add_undefine(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro (un)definitions to a fileset.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- copy_fileset(src_fileset: str, dst_fileset: str, clobber: bool = False) None[source]#
Creates a new copy of a source fileset.
The entire configuration of the source fileset is duplicated and stored under the destination fileset’s name.
- Parameters:
- Raises:
ValueError – If the destination fileset already exists and clobber is False.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_dataroot(name: str) str[source]#
Returns absolute path to the data directory.
- Raises:
ValueError – is data directory is not found
- Parameters:
name (str) – name of the data directory to find.
- Returns:
Path to the directory root.
Examples
>>> schema.get_dataroot('siliconcompiler') Returns the path to the root of the siliconcompiler data directory.
- get_dep(name: str | None = None, hierarchy: bool = True) List[NamedSchema][source]#
Returns all dependencies associated with this object or a specific one if requested.
- get_file(fileset: str | None = None, filetype: str | None = None) List[str][source]#
Returns a list of files from one or more filesets.
- Parameters:
- Returns:
A list of resolved file paths.
- Return type:
- get_fileset(filesets: List[str] | str, alias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None) List[Tuple[Design, str]][source]#
Computes the full, recursive list of (design, fileset) tuples required for a given set of top-level filesets.
This method traverses the design’s dependency graph to resolve all depfileset entries, returning a flattened and unique list of all required sources.
- Parameters:
filesets (Union[List[str], str]) – A single fileset name or a list of fileset names to evaluate.
alias (Dict[Tuple[str, str], Tuple[Design, str]], optional) – A dictionary mapping (design_name, fileset_name) tuples to be substituted during traversal. The value should be a (Design object, new_fileset_name) tuple. This is useful for swapping out library implementations. Defaults to None.
- Returns:
A flattened, unique list of (Design, fileset) tuples representing all dependencies.
- Return type:
- get_lib(fileset: str | None = None) List[str][source]#
Returns list of dynamic libraries for a fileset.
- get_libdir(fileset: str | None = None) List[str][source]#
Returns dynamic library directories for a fileset.
- get_param(name: str, fileset: str | None = None) str[source]#
Returns value of a named fileset parameter.
- get_undefine(fileset: str | None = None) List[str][source]#
Returns undefined macros for a fileset.
- Args:
- fileset (str): Fileset name. If not provided, the active fileset is
used.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- has_dep(name: NamedSchema | str) bool[source]#
Checks if a specific dependency is present.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was found, False otherwise.
- has_file(fileset: str | None = None, filetype: str | None = None) bool[source]#
Returns true if the fileset contains files.
- Parameters:
- Returns:
True if the fileset contains files.
- Return type:
- has_idir(fileset: str | None = None) bool[source]#
Returns true if idirs are defined for the fileset
- has_libdir(fileset: str | None = None) bool[source]#
Returns true if library directories are defined for the fileset
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- property package: PackageSchema#
Gets the package schema for the design.
- Returns:
The package schema associated with this design.
- Return type:
- read_fileset(filename: str, fileset: str | None = None, fileformat: str | None = None) None[source]#
Imports filesets from a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_dep(name: str | NamedSchema) bool[source]#
Removes a previously registered module.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was removed, False if it was not found.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_dataroot(name: str = 'root', path: str | None = None, tag: str | None = None, clobber: bool = False) None[source]#
Registers a data source by name, path, and optional version tag.
This method creates a reference to a data directory, which can be a local path, a Git repository, or a remote archive. This allows other parts of the application to refer to this data source by its unique name.
- Parameters:
name (str, optional) – A unique name to identify the data source. Defaults to “root”.
path (str) – The path to the data source. This is required. It can be a local directory, a file path, a git URL, or an archive URL. If a file path is provided, its parent directory is used as the root.
tag (str, optional) – A version identifier for remote sources, such as a git commit hash, branch, or tag. Defaults to None.
clobber (bool, optional) – If True, allows overwriting an existing data source with the same name. If False (default), attempting to overwrite an existing entry will raise a ValueError.
- Raises:
ValueError – If path is not specified.
ValueError – If a data source with the given name already exists and clobber is False.
Examples
>>> # Register a remote git repository at a specific tag >>> schema.set_dataroot('siliconcompiler_data', ... 'git+https://github.com/siliconcompiler/siliconcompiler', ... tag='v1.0.0') >>> >>> # Register a local directory based on the location of a file >>> schema.set_dataroot('file_data', __file__)
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_param(name: str, value: str, fileset: str | None = None) str[source]#
Sets a named parameter for a fileset.
- set_topmodule(value: str, fileset: str | None = None) str[source]#
Sets the topmodule of a fileset.
- Parameters:
- Returns:
Topmodule name
- Return type:
Notes
first character must be letter or underscore
remaining characters can be letters, digits, or underscores
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the dependency graph to a file.
- Parameters:
Examples
>>> schema.write_depgraph('mydump.png') Renders the object dependency graph and writes the result to a png file.
- write_fileset(filename: str, fileset: Iterable[str] | str | None = None, fileformat: str | None = None, depalias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None, comments: bool = False) None[source]#
Exports filesets to a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future. Inferred from file extension if not given.
- Parameters:
- class siliconcompiler.PDK(name: str | None = None)[source]#
Bases:
ToolLibrarySchemaA schema for managing and validating Process Design Kit (PDK) configurations.
This class defines the structured parameters that constitute a PDK, such as foundry information, process node, metal stackups, and various technology files required for different EDA tools. It extends the ToolLibrarySchema to provide a standardized way of describing and accessing PDK data within the SiliconCompiler framework.
- active_dataroot(dataroot: str | None = None)#
Use this context to set the dataroot parameter on files and directory parameters.
- Parameters:
dataroot (str) – name of the dataroot
Example
>>> with schema.active_dataroot("lambdalib"): ... schema.set("file", "top.v") Sets the file to top.v and associates lambdalib as the dataroot.
- active_fileset(fileset: str)#
Provides a context to temporarily set an active design fileset.
This is useful for applying a set of configurations to a specific fileset without repeatedly passing its name.
- Raises:
TypeError – If fileset is not a string.
ValueError – If fileset is an empty string.
- Parameters:
fileset (str) – The name of the fileset to activate.
Example
>>> with design.active_fileset("rtl"): ... design.set_topmodule("top") # This sets the top module for the 'rtl' fileset to 'top'.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_aprtechfileset(tool: str, fileset: List[str] | str | None = None, clobber: bool = False)[source]#
Adds a fileset containing APR technology files.
- add_define(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro definitions to a fileset.
- add_dep(obj: NamedSchema, clobber: bool = True) bool[source]#
Adds a module dependency to this design.
This method extends the base add_dep to prevent a design from adding a dependency on itself.
- Parameters:
obj (NamedSchema) – The dependency object to add.
clobber (bool) – If True, overwrite an existing dependency with the same name.
- Returns:
True if the dependency was added, False otherwise.
- Return type:
- Raises:
TypeError – If obj is not a NamedSchema.
ValueError – If obj has the same name as the current design.
- add_depfileset(dep: Design | str, depfileset: str | None = None, fileset: str | None = None)[source]#
Record a reference to an imported dependency’s fileset.
- Parameters:
- add_devmodelfileset(tool: str, type: str, fileset: List[str] | str | None = None, clobber: bool = False)[source]#
Adds a fileset containing device model files.
- add_displayfileset(tool: str, fileset: List[str] | str | None = None, clobber: bool = False)[source]#
Adds a fileset containing display configuration files.
- add_file(filename: List[Path | str] | Set[Path | str] | Tuple[Path | str, ...] | Path | str, fileset: str | None = None, filetype: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds files to a fileset.
Based on the file’s extension, this method can often infer the correct fileset and filetype. For example:
.v -> (source, verilog)
.vhd -> (source, vhdl)
.sdc -> (constraint, sdc)
.lef -> (input, lef)
.def -> (input, def)
etc.
- Parameters:
filename (Path, str, or collection) – File path (Path or str), or a collection (list, tuple, set) of file paths to add.
fileset (str) – Logical group to associate the file with.
filetype (str, optional) – Type of the file (e.g., ‘verilog’, ‘sdc’).
clobber (bool, optional) – If True, clears the list before adding the item. Defaults to False.
dataroot (str, optional) – Data directory reference name.
- Raises:
ValueError – If fileset or filetype cannot be inferred from the file extension.
- Returns:
A list of the file paths that were added.
- Return type:
Notes
This method normalizes filename to a string for consistency.
- If filetype is not specified, it is inferred from the
file extension.
- add_idir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds include directories to a fileset.
- Parameters:
- Returns:
List of include directories
- Return type:
- add_layermapfileset(tool: str, src: str, dst: str, fileset: List[str] | str | None = None, clobber: bool = False)[source]#
Adds a fileset containing layer map files.
- Parameters:
tool (str) – The name of the tool.
src (str) – The source format or tool name.
dst (str) – The destination format or tool name.
fileset (str, optional) – The name of the fileset. Defaults to None, which uses the active fileset.
clobber (bool, optional) – If True, overwrites existing entries. Defaults to False.
- add_lib(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds dynamic libraries to a fileset.
- add_libdir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds dynamic library directories to a fileset.
- Parameters:
- Returns:
List of library directories.
- Return type:
- add_pexmodelfileset(tool: str, corner: str, fileset: List[str] | str | None = None, clobber: bool = False)[source]#
Adds a fileset containing parasitic extraction (pex) model files.
- add_runsetfileset(type: str, tool: str, name: str, fileset: List[str] | str | None = None, clobber: bool = False)[source]#
Adds a fileset containing a runset for a specific verification task.
- Parameters:
type (str) – The type of task (e.g., ‘lvs’, ‘drc’).
tool (str) – The name of the tool.
name (str) – The name of the runset.
fileset (str, optional) – The name of the fileset. Defaults to None, which uses the active fileset.
clobber (bool, optional) – If True, overwrites existing entries. Defaults to False.
- add_undefine(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro (un)definitions to a fileset.
- add_waiverfileset(type: str, tool: str, name: str, fileset: List[str] | str | None = None, clobber: bool = False)[source]#
Adds a fileset containing waiver files for a specific verification task.
- Parameters:
type (str) – The type of task (e.g., ‘lvs’, ‘drc’).
tool (str) – The name of the tool.
name (str) – The name of the waiver set.
fileset (str, optional) – The name of the fileset. Defaults to None, which uses the active fileset.
clobber (bool, optional) – If True, overwrites existing entries. Defaults to False.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- calc_dpw(diewidth: float, dieheight: float) int[source]#
Calculates dies per wafer.
Calculates the gross dies per wafer based on the design area, wafersize, wafer edge margin, and scribe lines. The calculation is done by starting at the center of the wafer and placing as many complete design footprints as possible within a legal placement area.
- Parameters:
- Returns:
Number of gross dies per wafer.
- Return type:
Examples
>>> dpw = pdk.calc_dpw(1000.0, 1500.0) # Calculates dies per wafer for a 1000x1500 um die.
- calc_yield(diearea: float, model: str = 'poisson') float[source]#
Calculates raw die yield.
Calculates the raw yield of the design as a function of design area and d0 defect density. Calculation can be done based on the poisson model (default) or the murphy model. The die area and the d0 parameters are taken from the pdk dictionary.
Poisson model: dy = exp(-area * d0/100).
Murphy model: dy = ((1-exp(-area * d0/100))/(area * d0/100))^2.
- Parameters:
diearea (float) – The area of the die in square micrometers (um^2).
model (string) – Model to use for calculation (poisson or murphy)
- Returns:
Design yield percentage.
- Return type:
Examples
>>> yield = pdk.calc_yield(1500.0) # Calculates yield for a 1500 um^2 die.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- copy_fileset(src_fileset: str, dst_fileset: str, clobber: bool = False) None[source]#
Creates a new copy of a source fileset.
The entire configuration of the source fileset is duplicated and stored under the destination fileset’s name.
- Parameters:
- Raises:
ValueError – If the destination fileset already exists and clobber is False.
- define_tool_parameter(tool: str, name: str, type: str, help: str, **kwargs)[source]#
Define a new tool parameter for the library.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_dataroot(name: str) str[source]#
Returns absolute path to the data directory.
- Raises:
ValueError – is data directory is not found
- Parameters:
name (str) – name of the data directory to find.
- Returns:
Path to the directory root.
Examples
>>> schema.get_dataroot('siliconcompiler') Returns the path to the root of the siliconcompiler data directory.
- get_dep(name: str | None = None, hierarchy: bool = True) List[NamedSchema][source]#
Returns all dependencies associated with this object or a specific one if requested.
- get_file(fileset: str | None = None, filetype: str | None = None) List[str][source]#
Returns a list of files from one or more filesets.
- Parameters:
- Returns:
A list of resolved file paths.
- Return type:
- get_fileset(filesets: List[str] | str, alias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None) List[Tuple[Design, str]][source]#
Computes the full, recursive list of (design, fileset) tuples required for a given set of top-level filesets.
This method traverses the design’s dependency graph to resolve all depfileset entries, returning a flattened and unique list of all required sources.
- Parameters:
filesets (Union[List[str], str]) – A single fileset name or a list of fileset names to evaluate.
alias (Dict[Tuple[str, str], Tuple[Design, str]], optional) – A dictionary mapping (design_name, fileset_name) tuples to be substituted during traversal. The value should be a (Design object, new_fileset_name) tuple. This is useful for swapping out library implementations. Defaults to None.
- Returns:
A flattened, unique list of (Design, fileset) tuples representing all dependencies.
- Return type:
- get_lib(fileset: str | None = None) List[str][source]#
Returns list of dynamic libraries for a fileset.
- get_libdir(fileset: str | None = None) List[str][source]#
Returns dynamic library directories for a fileset.
- get_param(name: str, fileset: str | None = None) str[source]#
Returns value of a named fileset parameter.
- get_undefine(fileset: str | None = None) List[str][source]#
Returns undefined macros for a fileset.
- Args:
- fileset (str): Fileset name. If not provided, the active fileset is
used.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- has_dep(name: NamedSchema | str) bool[source]#
Checks if a specific dependency is present.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was found, False otherwise.
- has_file(fileset: str | None = None, filetype: str | None = None) bool[source]#
Returns true if the fileset contains files.
- Parameters:
- Returns:
True if the fileset contains files.
- Return type:
- has_idir(fileset: str | None = None) bool[source]#
Returns true if idirs are defined for the fileset
- has_libdir(fileset: str | None = None) bool[source]#
Returns true if library directories are defined for the fileset
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- property package: PackageSchema#
Gets the package schema for the design.
- Returns:
The package schema associated with this design.
- Return type:
- read_fileset(filename: str, fileset: str | None = None, fileformat: str | None = None) None[source]#
Imports filesets from a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_dep(name: str | NamedSchema) bool[source]#
Removes a previously registered module.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was removed, False if it was not found.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_aprroutinglayers(min: str | None = None, max: str | None = None)[source]#
Sets the minimum and maximum routing layers for the PDK.
- set_dataroot(name: str = 'root', path: str | None = None, tag: str | None = None, clobber: bool = False) None[source]#
Registers a data source by name, path, and optional version tag.
This method creates a reference to a data directory, which can be a local path, a Git repository, or a remote archive. This allows other parts of the application to refer to this data source by its unique name.
- Parameters:
name (str, optional) – A unique name to identify the data source. Defaults to “root”.
path (str) – The path to the data source. This is required. It can be a local directory, a file path, a git URL, or an archive URL. If a file path is provided, its parent directory is used as the root.
tag (str, optional) – A version identifier for remote sources, such as a git commit hash, branch, or tag. Defaults to None.
clobber (bool, optional) – If True, allows overwriting an existing data source with the same name. If False (default), attempting to overwrite an existing entry will raise a ValueError.
- Raises:
ValueError – If path is not specified.
ValueError – If a data source with the given name already exists and clobber is False.
Examples
>>> # Register a remote git repository at a specific tag >>> schema.set_dataroot('siliconcompiler_data', ... 'git+https://github.com/siliconcompiler/siliconcompiler', ... tag='v1.0.0') >>> >>> # Register a local directory based on the location of a file >>> schema.set_dataroot('file_data', __file__)
- set_defectdensity(d0: float)[source]#
Sets the process defect density for the PDK.
- Parameters:
d0 (float) – The defect density (defects per cm^2).
- set_edgemargin(margin: float)[source]#
Sets the wafer edge keep-out margin for the PDK.
- Parameters:
margin (float) – The edge margin in millimeters.
- set_foundry(foundry: str)[source]#
Sets the foundry name for the PDK.
- Parameters:
foundry (str) – The name of the foundry.
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_node(node: float)[source]#
Sets the process node for the PDK.
- Parameters:
node (float) – The process node in nanometers.
- set_param(name: str, value: str, fileset: str | None = None) str[source]#
Sets a named parameter for a fileset.
- set_stackup(stackup: str)[source]#
Sets the metal stackup for the PDK.
- Parameters:
stackup (str) – The name of the metal stackup.
- set_topmodule(value: str, fileset: str | None = None) str[source]#
Sets the topmodule of a fileset.
- Parameters:
- Returns:
Topmodule name
- Return type:
Notes
first character must be letter or underscore
remaining characters can be letters, digits, or underscores
- set_unitcost(unitcost: float)[source]#
Sets the unit cost for the PDK.
- Parameters:
unitcost (float) – The unit cost in USD.
- set_wafersize(wafersize: float)[source]#
Sets the wafer size for the PDK.
- Parameters:
wafersize (float) – The wafer diameter in millimeters.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the dependency graph to a file.
- Parameters:
Examples
>>> schema.write_depgraph('mydump.png') Renders the object dependency graph and writes the result to a png file.
- write_fileset(filename: str, fileset: Iterable[str] | str | None = None, fileformat: str | None = None, depalias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None, comments: bool = False) None[source]#
Exports filesets to a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future. Inferred from file extension if not given.
- Parameters:
- class siliconcompiler.Flowgraph(name: str | None = None)[source]#
Bases:
NamedSchema,DocsSchemaSchema for defining and interacting with a flowgraph.
A flowgraph is a directed acyclic graph (DAG) that represents the compilation flow. Each node in the graph is a step/index pair that maps to a specific tool task, and edges represent dependencies between these tasks.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- edge(tail: str, head: str, tail_index: str | int | None = 0, head_index: str | int | None = 0) None[source]#
Creates a directed edge from a tail node to a head node.
Connects the output of a tail node (tail, tail_index) with the input of a head node (head, head_index) by adding the tail node to the ‘input’ list of the head node in the schema.
If the edge already exists, this method does nothing.
The method modifies the following parameter:
[‘<head>’, ‘<head_index>’, ‘input’]
- Parameters:
- Raises:
ValueError – If either the head or tail node is not defined in the flowgraph before calling this method.
Examples
>>> flow.node('place', 'openroad/Place') >>> flow.node('cts', 'openroad/Cts') >>> flow.edge('place', 'cts') # Creates a directed edge from ('place', '0') to ('cts', '0').
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_entry_nodes() Tuple[Tuple[str, str], ...][source]#
Collects all nodes that are entry points to the flowgraph.
Entry nodes are those with no inputs defined. The result is memoized.
- get_execution_order(reverse: bool | None = False) Tuple[Tuple[Tuple[str, str], ...], ...][source]#
Generates a topologically sorted list of nodes for execution.
This method performs a topological sort of the graph. The result is a tuple of tuples, where each inner tuple represents a “level” of nodes that can be executed in parallel (as their dependencies are met).
The result is memoized for both forward and reverse orders.
- get_exit_nodes() Tuple[Tuple[str, str], ...][source]#
Collects all nodes that are exit points of the flowgraph.
Exit nodes are those that are not inputs to any other node in the graph. The result is memoized.
- get_graph_node(step: str, index: str | int | None = None) FlowgraphNodeSchema[source]#
Get the flowgraph node for this step and index
- get_node_outputs(step: str, index: str | int) Tuple[Tuple[str, str], ...][source]#
Returns the nodes that the given node provides input to (its children).
This is the reverse of get_graph_node(step, index).get_input(). The results are computed for all nodes and memoized on the first call.
- Parameters:
- Returns:
A sorted tuple of destination nodes (step, index) that take the given node as an input.
- Return type:
- Raises:
ValueError – If the specified (step, index) is not a valid node.
- get_nodes() Tuple[Tuple[str, str], ...][source]#
Returns a sorted tuple of all nodes defined in this flowgraph.
A node is represented as a (step, index) tuple. The result is memoized for efficiency.
- get_task_module(step: str, index: str | int) Type[Task][source]#
Returns the imported Python Task class for a given task node.
- Parameters:
- Returns:
The imported Task class associated with the node.
- Return type:
Type[Task]
- Raises:
ValueError – If the node is not valid.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- graph(subflow: Flowgraph, name: str | None = None) None[source]#
Instantiates a sub-flowgraph within the current flowgraph.
This method copies all nodes and their internal connections from subflow into the current flowgraph.
If name is provided, it is used as a prefix (e.g., “core.”) for all step names from the subflow to ensure they are unique within the current flowgraph. This prefix is also applied to the internal edges to maintain the sub-flowgraph’s structure.
- Parameters:
- Raises:
ValueError – If subflow is not a Flowgraph object, or if a step from the sub-flowgraph already exists in the current graph.
- insert_node(step: str, task: Task, before_step: str, index: str | int | None = 0, before_index: str | int | None = 0) None[source]#
Inserts a new node in the graph immediately before a specified node.
The new node (step, index) is placed between the before node (before_step, before_index) and all of the before node’s original inputs. The before node’s inputs are cleared, and it is given a single input: the new node. The new node inherits all the original inputs of the before node.
- Parameters:
step (str) – Step name for the new node.
task (Task or str or Type[Task]) – Task to associate with the new node.
before_step (str) – Step name of the existing node to insert before.
index (int or str, optional) – Index for the new node. Defaults to 0.
before_index (int or str, optional) – Index of the existing node. Defaults to 0.
- Raises:
ValueError – If the before node (before_step, before_index) is not a valid node in the flowgraph.
- classmethod make_docs() TSchema | List[TSchema][source]#
Generate the documentation representation for this schema.
By default, this method returns a standard instance of the class itself. Subclasses can override this method to return a modified or different schema instance, or even a list of schemas, to customize how they appear in the generated documentation.
- Returns:
An instance or list of instances of BaseSchema that represents the schema for documentation purposes.
- node(step: str, task: Task, index: str | int | None = 0) None[source]#
Creates or updates a flowgraph node.
Creates a flowgraph node by binding a step/index pair to a specific tool task. A tool can be an external executable or one of the built-in functions in the SiliconCompiler framework (e.g., minimum, maximum, join).
If the node (step, index) already exists, its task and tool information will be updated.
The method modifies the following schema parameters for the given step and index:
[‘<step>’, ‘<index>’, ‘tool’]
[‘<step>’, ‘<index>’, ‘task’]
[‘<step>’, ‘<index>’, ‘taskmodule’]
- Parameters:
step (str) – Step name for the node. Must not contain ‘/’.
task (Task or str or Type[Task]) – The task to associate with this node. Can be a task instance, a string in the format ‘<module_path>/<ClassName>’, or a Task class type.
index (int or str, optional) – Index for the step. Defaults to 0. Must not contain ‘/’.
- Raises:
ValueError – If ‘step’ or ‘index’ are reserved names (like ‘default’ or ‘*’) or contain invalid characters (‘/’).
ValueError – If ‘task’ is not a valid Task object, string, or class.
Examples
>>> import siliconcompiler.tools.openroad as openroad >>> # Using a Task class >>> flow.node('place', openroad.Place, index=0) >>> >>> # Using a string identifier >>> flow.node('cts', 'siliconcompiler.tools.openroad/Cts', index=0) >>> >>> # Using a Task instance >>> from siliconcompiler.tools.builtin import Join >>> flow.node('join', Join(), index=0)
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_node(step: str, index: str | int | None = None) None[source]#
Removes a flowgraph node and reconnects its inputs to its outputs.
This operation effectively “stitches” the graph back together by creating new edges from all inputs of the removed node to all outputs of the removed node.
If index is None, all nodes for the given step are removed.
- Parameters:
- Raises:
ValueError – If the specified step or (step, index) is not a valid node in the flowgraph.
- rename_node(step: str, new_step: str) None[source]#
Renames a step, preserving its nodes, tasks, and connectivity.
Every node belonging to
step(all of its indices) is moved tonew_step, keeping the same indices, task bindings, goals, and input edges. All edges elsewhere in the graph that referencedstepare rewired to point atnew_step, so the topology of the flow is unchanged.This is primarily useful after
graph()when a sub-flow’s step names need to be re-badged to fit a parent flow’s naming scheme (e.g. renamingsynmintosynthesis.min) without having to prefix every step in the sub-flow.- Parameters:
- Raises:
ValueError – If
stepdoes not exist, ifnew_stepis a reserved name or contains a ‘/’, or ifnew_stepis already defined in the flowgraph.
Examples
>>> flow.node('synmin', minimum.MinimumTask()) >>> flow.rename_node('synmin', 'synthesis.min') # ('synmin', '0') is now ('synthesis.min', '0'); all edges follow.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- validate(logger: Logger | None = None) bool[source]#
Checks if the flowgraph is valid.
This method performs several checks: * All edges must point to and from valid nodes. * There should be no duplicate edges. * All nodes must have their tool, task, and taskmodule defined. * The graph must not contain any loops (it must be a DAG).
- Parameters:
logger (logging.Logger, optional) – A logger to use for reporting errors. Defaults to None.
- Returns:
True if the graph is valid, False otherwise.
- Return type:
- write_flowgraph(filename: str, fillcolor: str = '#ffffff', fontcolor: str = '#000000', background: str = 'transparent', fontsize: int | str = 14, border: bool = True, landscape: bool = False, show_io: bool | None = None) None[source]#
Renders and saves the compilation flowgraph to a file.
The flow 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
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
>>> flow.write_flowgraph('mydump.png') Renders the object flowgraph and writes the result to a png file.
- class siliconcompiler.Checklist(name: str | None = None)[source]#
Bases:
NamedSchemaA class for managing a collection of design checklist items and their verification.
This class acts as a container for multiple Criteria objects, each representing an item in a design checklist (e.g., ‘ISO D000’). It provides methods to define, access, and automatically verify these items against flow results.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check(items: Iterable[str] | None = None, check_ok: bool = False, require_reports: bool = True) bool[source]#
Checks the status of items in a checklist against flow results.
This method validates checklist items by comparing their defined criteria against metrics recorded in the chip’s history. For an item to pass, all its criteria must be met by the associated tasks, considering any waivers.
For items with automated checks (linked to a task), this method verifies that metric values from the flow run satisfy the criteria (e.g., ‘errors == 0’). It also ensures that corresponding EDA reports were generated.
For items without a task, it only checks that a report has been manually added.
- Parameters:
items (Optional[Iterable[str]]) – A list of item names to check. If None, all items in the checklist are checked. Defaults to None.
check_ok (bool) – If True, all checked items must also have their ‘ok’ parameter set to True, indicating manual review. Defaults to False.
require_reports (bool) – If True, asserts that report files exist for all automated checks. Defaults to True.
- Returns:
True if all specified checks pass, False otherwise.
- Return type:
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_criteria(name: str | None = None) Dict[str, Criteria] | Criteria[source]#
Retrieves one or all Criteria items from the checklist.
If a name is provided, it returns the specific Criteria object. If no name is provided, it returns a dictionary of all Criteria objects.
- Parameters:
name (Optional[str], optional) – The name of the item to retrieve. Defaults to None.
- Returns:
A single Criteria object or a dictionary mapping names to Criteria objects.
- Return type:
- Raises:
ValueError – If a name is provided but is not found in the checklist.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- make_criteria(name: str) Criteria[source]#
Creates a new, named Criteria item within this checklist.
- Parameters:
name (str) – The unique name for the new checklist item.
- Returns:
The newly created Criteria object.
- Return type:
- Raises:
ValueError – If a criteria item with the same name already exists.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.Task[source]#
Bases:
NamedSchema,PathSchema,DocsSchemaA schema class that defines the parameters and methods for a single task in a compilation flow.
This class provides the framework for setting up, running, and post-processing a tool. It includes methods for managing executables, versions, runtime arguments, and file I/O.
- active_dataroot(dataroot: str | None = None)#
Use this context to set the dataroot parameter on files and directory parameters.
- Parameters:
dataroot (str) – name of the dataroot
Example
>>> with schema.active_dataroot("lambdalib"): ... schema.set("file", "top.v") Sets the file to top.v and associates lambdalib as the dataroot.
- add(*args, field: str = 'value', step: str | None = None, index: int | str | None = None)[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_commandline_option(option: List[str] | str, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Add to the command line options for the task
- add_input_file(file: str | None = None, ext: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Add a required input file from the previous step in the flow.
file and ext are mutually exclusive.
- add_licenseserver(name: str, server: str, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Configures a license server connection for the tool.
This sets the environment variables that commercial EDA tools use to find their license server.
- Parameters:
name (str) – The name of the license variable (e.g., ‘LM_LICENSE_FILE’).
server (str) – The server address (e.g., ‘port@host’).
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- add_output_file(file: str | None = None, ext: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Add an output file that this task will produce
file and ext are mutually exclusive.
- add_parameter(name: str, type: str, help: str, defvalue=None, **kwargs) Parameter[source]#
Adds a custom parameter (‘var’) to the task definition.
- add_postscript(script: str, dataroot: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Adds a script to be executed after the main tool command.
This is useful for post-processing tool outputs or performing cleanup actions.
- Parameters:
script (str) – The path to the post-execution script.
dataroot (str, optional) – The data root this path is relative to. Defaults to the active package.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- add_prescript(script: str, dataroot: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Adds a script to be executed before the main tool command.
This is useful for pre-processing files or setting up the environment in ways that go beyond simple environment variables.
- Parameters:
script (str) – The path to the pre-execution script.
dataroot (str, optional) – The data root this path is relative to. Defaults to the active package.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- add_regex(type: str, regex: str, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Adds a regular expression for parsing the tool’s log file.
These regexes are used by the framework to identify errors, warnings, and metrics from the tool’s standard output.
- Parameters:
type (str) – The category of the regex (e.g., ‘error’, ‘warning’).
regex (str) – The regular expression pattern.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- add_required_key(obj: BaseSchema | str, *key: str, step: str | None = None, index: int | str | None = None)[source]#
- Adds a required keypath to the task driver. If the key is valid relative to the task object
the key will be assumed as a task key.
- add_sbom(version: str, sbom: str | List[str], dataroot: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Adds a Software Bill of Materials (SBOM) file for a tool version.
Associates a specific tool version with its corresponding SBOM file, typically in SPDX or CycloneDX format.
- Parameters:
- Returns:
The schema key that was set.
- add_version(version: List[str] | str, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Adds a supported version specifier for the tool.
SiliconCompiler checks the tool’s actual version against these specifiers to ensure compatibility. Versions should follow the PEP-440 standard (e.g., ‘>=5.6’, ‘==1.2.3’).
- Parameters:
version (str) – The version specifier string.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- add_vswitch(switch: List[str] | str, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Adds the command-line switch used to print the tool’s version.
This switch is passed to the executable to get its version string for checking.
- add_warningoff(type: str, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Adds a warning message or code to be suppressed during log parsing.
Any warning that matches a regex in this list will be ignored by the framework.
- Parameters:
type (str) – The warning message or code to suppress.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_exe_version(reported_version: str) bool[source]#
Checks if the reported version of a tool satisfies the requirements specified in the schema.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- compute_input_file_node_name(filename: str, step: str, index: str) str[source]#
Generates a unique name for an input file based on its originating node.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None)[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod find_task(project: Project) Set[TTask] | TTask[source]#
Finds registered task(s) in a project that match the calling class.
This method searches through all tasks configured in the provided project and returns those that meet specific criteria derived from the class on which this method is called. The filtering is based on three levels:
Class Type: The primary filter ensures that any found task object is an instance of the calling class (cls).
Tool Name: If the calling class (cls) implements the tool() method, the search is narrowed to tasks with that specific tool name.
Task Name: If the calling class (cls) implements the task() method, the search is further narrowed to tasks with that name.
The method conveniently returns a single object if only one match is found, or a set of objects if multiple matches are found.
- Parameters:
project (Project) – The project instance to search within.
- Returns:
A single Task instance if exactly one match is found, otherwise a set of matching Task instances.
- Return type:
- Raises:
TypeError – If the project argument is not a valid Project object.
ValueError – If no tasks matching the specified criteria are found in the project.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- generate_replay_script(filepath: str, workdir: str, include_path: bool = True) None[source]#
Generates a shell script to replay the task’s execution.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: int | str | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_commandline_options(step: str | None = None, index: int | str | None = None) List[str][source]#
Returns the command line options specified
- get_dataroot(name: str) str[source]#
Returns absolute path to the data directory.
- Raises:
ValueError – is data directory is not found
- Parameters:
name (str) – name of the data directory to find.
- Returns:
Path to the directory root.
Examples
>>> schema.get_dataroot('siliconcompiler') Returns the path to the root of the siliconcompiler data directory.
- get_exe() str | None[source]#
Determines the absolute path for the task’s executable.
- Raises:
TaskExecutableNotFound – If the executable cannot be found in the system PATH.
- Returns:
The absolute path to the executable, or None if not specified.
- Return type:
- get_exe_version(workdir: str | None = None) str | None[source]#
Gets the version of the task’s executable by running it with a version switch.
- Raises:
TaskExecutableNotFound – If the executable is not found.
NotImplementedError – If the parse_version method is not implemented.
- Parameters:
workdir (str) – The working directory to use for the version check. If None, the current working directory is used.
- Returns:
The parsed version string.
- Return type:
- get_files_from_input_nodes() Dict[str, List[Tuple[str, str]]][source]#
Returns a dictionary of files from input nodes, mapped to the node they originated from.
- get_fileset_file_keys(filetype: str) List[Tuple[Design, Tuple[str, ...]]][source]#
Collect a set of keys for a particular filetype.
- Parameters:
filetype (str) – Name of the filetype
- Returns:
list of (object, keypath)
- get_runtime_arguments() List[str][source]#
Constructs the command-line arguments needed to run the task.
- Returns:
A list of command-line arguments.
- Return type:
- get_runtime_environmental_variables(include_path: bool = True) Dict[str, str][source]#
Determines the environment variables needed for the task.
- get_tcl_variables(manifest: BaseSchema | None = None) Dict[str, str][source]#
Gets a dictionary of variables to define for the task in a Tcl manifest.
- Parameters:
manifest (BaseSchema, optional) – The manifest to retrieve values from.
- Returns:
A dictionary of variable names and their Tcl-formatted values.
- Return type:
- get_threads(step: str | None = None, index: int | str | None = None) int[source]#
Returns the number of threads requested.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- has_breakpoint() bool[source]#
Checks if a breakpoint is set for this task.
- Returns:
True if a breakpoint is active, False otherwise.
- Return type:
- has_postscript(step: str | None = None, index: int | str | None = None) bool[source]#
Checks if any post-execution scripts are configured for the task.
- has_prescript(step: str | None = None, index: int | str | None = None) bool[source]#
Checks if any pre-execution scripts are configured for the task.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- classmethod make_docs()[source]#
Generate the documentation representation for this schema.
By default, this method returns a standard instance of the class itself. Subclasses can override this method to return a modified or different schema instance, or even a list of schemas, to customize how they appear in the generated documentation.
- Returns:
An instance or list of instances of BaseSchema that represents the schema for documentation purposes.
- property node: SchedulerNode#
The scheduler node for the current runtime.
- Type:
- normalize_version(version: str) str[source]#
Normalizes a version string to a standard format. Can be overridden.
- parse_version(stdout: str) str[source]#
Parses the tool’s version from its stdout. Must be implemented by subclasses.
- post_process() None[source]#
A hook for post-processing after the main tool execution. Can be overridden.
- pre_process() None[source]#
A hook for pre-processing before the main tool execution. Can be overridden.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- record_metric(metric: str, value: int | float, source_file: List[Path | str] | Path | str | None = None, source_unit: str | None = None, quiet: bool = False)[source]#
Records a metric and associates the source file with it.
- Parameters:
Examples
>>> self.record_metric('cellarea', 500.0, 'reports/metrics.json', \ source_units='um^2') Records the metric cell area and notes the source as 'reports/metrics.json'
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- run_task(workdir: str, quiet: bool, breakpoint: bool, nice: int | None, timeout: int | None) int[source]#
Executes the task’s main process.
This method handles the full lifecycle of running the tool, including setting up the work directory, writing manifests, redirecting I/O, monitoring for timeouts, and recording metrics.
- Parameters:
- Returns:
The return code from the execution.
- Return type:
- runtime(node: SchedulerNode, step: str | None = None, index: int | str | None = None, relpath: str | None = None)#
A context manager to set the runtime information for a task.
This method creates a temporary copy of the task object with runtime information (like the current step, index, and working directories) populated from a SchedulerNode. This allows methods within the context to access runtime-specific configuration and paths.
- Parameters:
node (SchedulerNode) – The scheduler node for this runtime context.
- runtime_options() List[int | str | Path][source]#
Constructs the default runtime options for the task. Can be extended.
- select_input_nodes() List[Tuple[str, str]][source]#
Determines which preceding nodes are inputs to this task.
- set(*args, field: str = 'value', step: str | None = None, index: int | str | None = None, clobber: bool = True)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_dataroot(name: str = 'root', path: str | None = None, tag: str | None = None, clobber: bool = False) None[source]#
Registers a data source by name, path, and optional version tag.
This method creates a reference to a data directory, which can be a local path, a Git repository, or a remote archive. This allows other parts of the application to refer to this data source by its unique name.
- Parameters:
name (str, optional) – A unique name to identify the data source. Defaults to “root”.
path (str) – The path to the data source. This is required. It can be a local directory, a file path, a git URL, or an archive URL. If a file path is provided, its parent directory is used as the root.
tag (str, optional) – A version identifier for remote sources, such as a git commit hash, branch, or tag. Defaults to None.
clobber (bool, optional) – If True, allows overwriting an existing data source with the same name. If False (default), attempting to overwrite an existing entry will raise a ValueError.
- Raises:
ValueError – If path is not specified.
ValueError – If a data source with the given name already exists and clobber is False.
Examples
>>> # Register a remote git repository at a specific tag >>> schema.set_dataroot('siliconcompiler_data', ... 'git+https://github.com/siliconcompiler/siliconcompiler', ... tag='v1.0.0') >>> >>> # Register a local directory based on the location of a file >>> schema.set_dataroot('file_data', __file__)
- set_environmentalvariable(name: str, value: str, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Sets an environment variable for the tool’s execution context.
The specified variable will be set in the shell environment before the tool’s executable is launched.
- Parameters:
name (str) – The name of the environment variable (e.g., ‘PATH’).
value (str) – The value to assign to the variable.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- set_exe(exe: str | None = None, vswitch: List[str] | str | None = None, format: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Sets the executable, version switch, and script format for a tool.
This is a convenience method that bundles the configuration of a tool’s core executable properties.
- Parameters:
exe (str, optional) – The name of the tool’s executable binary.
vswitch (List[str], optional) – The command-line switch used to make the executable print its version (e.g., ‘–version’).
format (str, optional) – The format of the entry script, if any (e.g., ‘tcl’, ‘python’).
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
A list of the schema keys that were set.
- set_logdestination(type: str, dest: str, suffix: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Configures the destination for log files.
This method sets where log files are written (‘file’ or ‘api’) and can specify a custom file suffix.
- Parameters:
type (str) – The type of log (e.g., ‘report’, ‘metric’).
dest (str) – The destination, either ‘file’ or ‘api’.
suffix (str, optional) – A custom suffix for the log file name.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values.
- Returns:
A list of the schema keys that were set.
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_path(path: str, dataroot: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Sets the directory path where the tool’s executable is located.
This path is prepended to the system’s PATH environment variable during execution.
- Parameters:
path (str) – The directory path to the tool’s executable.
dataroot (str, optional) – The data root this path is relative to. Defaults to the active package.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values. Otherwise, append to them.
- Returns:
The schema key that was set.
- set_refdir(dir: Path | str, dataroot: str | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Sets the reference directory for tool scripts and auxiliary files.
This is often used by script-based tools to find helper scripts or resource files relative to the main entry script.
- Parameters:
dir (str) – The path to the reference directory.
dataroot (str, optional) – The data root this path is relative to. Defaults to the active package.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values.
- Returns:
The schema key that was set.
- set_script(script: Path | str, dataroot: str | None = Ellipsis, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Sets the main entry script for a script-based tool (e.g., a TCL script).
- Parameters:
script (str) – The path to the entry script.
dataroot (str, optional) – The data root this path is relative to. Defaults to the active package.
step (str, optional) – The step associated with this setting. Defaults to the current step.
index (str, optional) – The index associated with this setting. Defaults to the current index.
clobber (bool) – If True, overwrite existing values.
- Returns:
The schema key that was set.
- set_threads(max_threads: int | None = None, step: str | None = None, index: int | str | None = None, clobber: bool = False)[source]#
Sets the requested thread count for the task
- setup_work_directory(workdir: str, remove_exist: bool = True) None[source]#
Creates the runtime directories needed to execute a task.
- unset(*args: str, step: str | None = None, index: int | str | None = None)[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.FPGADevice(name: str = None)[source]#
Bases:
ToolLibrarySchemaA schema for configuring FPGA-related parameters.
This class extends ToolLibrarySchema to provide a structured way to define and access FPGA-specific settings like part name and LUT size.
- active_dataroot(dataroot: str | None = None)#
Use this context to set the dataroot parameter on files and directory parameters.
- Parameters:
dataroot (str) – name of the dataroot
Example
>>> with schema.active_dataroot("lambdalib"): ... schema.set("file", "top.v") Sets the file to top.v and associates lambdalib as the dataroot.
- active_fileset(fileset: str)#
Provides a context to temporarily set an active design fileset.
This is useful for applying a set of configurations to a specific fileset without repeatedly passing its name.
- Raises:
TypeError – If fileset is not a string.
ValueError – If fileset is an empty string.
- Parameters:
fileset (str) – The name of the fileset to activate.
Example
>>> with design.active_fileset("rtl"): ... design.set_topmodule("top") # This sets the top module for the 'rtl' fileset to 'top'.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_define(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro definitions to a fileset.
- add_dep(obj: NamedSchema, clobber: bool = True) bool[source]#
Adds a module dependency to this design.
This method extends the base add_dep to prevent a design from adding a dependency on itself.
- Parameters:
obj (NamedSchema) – The dependency object to add.
clobber (bool) – If True, overwrite an existing dependency with the same name.
- Returns:
True if the dependency was added, False otherwise.
- Return type:
- Raises:
TypeError – If obj is not a NamedSchema.
ValueError – If obj has the same name as the current design.
- add_depfileset(dep: Design | str, depfileset: str | None = None, fileset: str | None = None)[source]#
Record a reference to an imported dependency’s fileset.
- Parameters:
- add_file(filename: List[Path | str] | Set[Path | str] | Tuple[Path | str, ...] | Path | str, fileset: str | None = None, filetype: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds files to a fileset.
Based on the file’s extension, this method can often infer the correct fileset and filetype. For example:
.v -> (source, verilog)
.vhd -> (source, vhdl)
.sdc -> (constraint, sdc)
.lef -> (input, lef)
.def -> (input, def)
etc.
- Parameters:
filename (Path, str, or collection) – File path (Path or str), or a collection (list, tuple, set) of file paths to add.
fileset (str) – Logical group to associate the file with.
filetype (str, optional) – Type of the file (e.g., ‘verilog’, ‘sdc’).
clobber (bool, optional) – If True, clears the list before adding the item. Defaults to False.
dataroot (str, optional) – Data directory reference name.
- Raises:
ValueError – If fileset or filetype cannot be inferred from the file extension.
- Returns:
A list of the file paths that were added.
- Return type:
Notes
This method normalizes filename to a string for consistency.
- If filetype is not specified, it is inferred from the
file extension.
- add_idir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds include directories to a fileset.
- Parameters:
- Returns:
List of include directories
- Return type:
- add_lib(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds dynamic libraries to a fileset.
- add_libdir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds dynamic library directories to a fileset.
- Parameters:
- Returns:
List of library directories.
- Return type:
- add_undefine(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro (un)definitions to a fileset.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- copy_fileset(src_fileset: str, dst_fileset: str, clobber: bool = False) None[source]#
Creates a new copy of a source fileset.
The entire configuration of the source fileset is duplicated and stored under the destination fileset’s name.
- Parameters:
- Raises:
ValueError – If the destination fileset already exists and clobber is False.
- define_tool_parameter(tool: str, name: str, type: str, help: str, **kwargs)[source]#
Define a new tool parameter for the library.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_dataroot(name: str) str[source]#
Returns absolute path to the data directory.
- Raises:
ValueError – is data directory is not found
- Parameters:
name (str) – name of the data directory to find.
- Returns:
Path to the directory root.
Examples
>>> schema.get_dataroot('siliconcompiler') Returns the path to the root of the siliconcompiler data directory.
- get_dep(name: str | None = None, hierarchy: bool = True) List[NamedSchema][source]#
Returns all dependencies associated with this object or a specific one if requested.
- get_file(fileset: str | None = None, filetype: str | None = None) List[str][source]#
Returns a list of files from one or more filesets.
- Parameters:
- Returns:
A list of resolved file paths.
- Return type:
- get_fileset(filesets: List[str] | str, alias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None) List[Tuple[Design, str]][source]#
Computes the full, recursive list of (design, fileset) tuples required for a given set of top-level filesets.
This method traverses the design’s dependency graph to resolve all depfileset entries, returning a flattened and unique list of all required sources.
- Parameters:
filesets (Union[List[str], str]) – A single fileset name or a list of fileset names to evaluate.
alias (Dict[Tuple[str, str], Tuple[Design, str]], optional) – A dictionary mapping (design_name, fileset_name) tuples to be substituted during traversal. The value should be a (Design object, new_fileset_name) tuple. This is useful for swapping out library implementations. Defaults to None.
- Returns:
A flattened, unique list of (Design, fileset) tuples representing all dependencies.
- Return type:
- get_lib(fileset: str | None = None) List[str][source]#
Returns list of dynamic libraries for a fileset.
- get_libdir(fileset: str | None = None) List[str][source]#
Returns dynamic library directories for a fileset.
- get_param(name: str, fileset: str | None = None) str[source]#
Returns value of a named fileset parameter.
- get_undefine(fileset: str | None = None) List[str][source]#
Returns undefined macros for a fileset.
- Args:
- fileset (str): Fileset name. If not provided, the active fileset is
used.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- has_dep(name: NamedSchema | str) bool[source]#
Checks if a specific dependency is present.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was found, False otherwise.
- has_file(fileset: str | None = None, filetype: str | None = None) bool[source]#
Returns true if the fileset contains files.
- Parameters:
- Returns:
True if the fileset contains files.
- Return type:
- has_idir(fileset: str | None = None) bool[source]#
Returns true if idirs are defined for the fileset
- has_libdir(fileset: str | None = None) bool[source]#
Returns true if library directories are defined for the fileset
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- property package: PackageSchema#
Gets the package schema for the design.
- Returns:
The package schema associated with this design.
- Return type:
- read_fileset(filename: str, fileset: str | None = None, fileformat: str | None = None) None[source]#
Imports filesets from a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_dep(name: str | NamedSchema) bool[source]#
Removes a previously registered module.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was removed, False if it was not found.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_dataroot(name: str = 'root', path: str | None = None, tag: str | None = None, clobber: bool = False) None[source]#
Registers a data source by name, path, and optional version tag.
This method creates a reference to a data directory, which can be a local path, a Git repository, or a remote archive. This allows other parts of the application to refer to this data source by its unique name.
- Parameters:
name (str, optional) – A unique name to identify the data source. Defaults to “root”.
path (str) – The path to the data source. This is required. It can be a local directory, a file path, a git URL, or an archive URL. If a file path is provided, its parent directory is used as the root.
tag (str, optional) – A version identifier for remote sources, such as a git commit hash, branch, or tag. Defaults to None.
clobber (bool, optional) – If True, allows overwriting an existing data source with the same name. If False (default), attempting to overwrite an existing entry will raise a ValueError.
- Raises:
ValueError – If path is not specified.
ValueError – If a data source with the given name already exists and clobber is False.
Examples
>>> # Register a remote git repository at a specific tag >>> schema.set_dataroot('siliconcompiler_data', ... 'git+https://github.com/siliconcompiler/siliconcompiler', ... tag='v1.0.0') >>> >>> # Register a local directory based on the location of a file >>> schema.set_dataroot('file_data', __file__)
- set_lutsize(lut: int)[source]#
Sets the LUT size for the FPGA.
- Parameters:
lut (int) – The number of inputs for the lookup table.
- Returns:
The result of the set operation.
- Return type:
Any
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_param(name: str, value: str, fileset: str | None = None) str[source]#
Sets a named parameter for a fileset.
- set_partname(name: str)[source]#
Sets the FPGA part name.
- Parameters:
name (str) – The name of the FPGA part.
- Returns:
The result of the set operation.
- Return type:
Any
- set_topmodule(value: str, fileset: str | None = None) str[source]#
Sets the topmodule of a fileset.
- Parameters:
- Returns:
Topmodule name
- Return type:
Notes
first character must be letter or underscore
remaining characters can be letters, digits, or underscores
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the dependency graph to a file.
- Parameters:
Examples
>>> schema.write_depgraph('mydump.png') Renders the object dependency graph and writes the result to a png file.
- write_fileset(filename: str, fileset: Iterable[str] | str | None = None, fileformat: str | None = None, depalias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None, comments: bool = False) None[source]#
Exports filesets to a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future. Inferred from file extension if not given.
- Parameters:
- class siliconcompiler.StdCellLibrary(name: str | None = None)[source]#
Bases:
ToolLibrarySchemaA class for managing standard cell library schemas.
- active_dataroot(dataroot: str | None = None)#
Use this context to set the dataroot parameter on files and directory parameters.
- Parameters:
dataroot (str) – name of the dataroot
Example
>>> with schema.active_dataroot("lambdalib"): ... schema.set("file", "top.v") Sets the file to top.v and associates lambdalib as the dataroot.
- active_fileset(fileset: str)#
Provides a context to temporarily set an active design fileset.
This is useful for applying a set of configurations to a specific fileset without repeatedly passing its name.
- Raises:
TypeError – If fileset is not a string.
ValueError – If fileset is an empty string.
- Parameters:
fileset (str) – The name of the fileset to activate.
Example
>>> with design.active_fileset("rtl"): ... design.set_topmodule("top") # This sets the top module for the 'rtl' fileset to 'top'.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_asic_aprfileset(fileset: str = None)[source]#
Adds a mapping between filesets defined in the library.
- Parameters:
fileset (str) – name of the fileset
- add_asic_celllist(type: str, cells: List[str] | str)[source]#
Adds a standard cell library to the specified type.
- add_asic_libcornerfileset(corner: str, model: str, fileset: List[str] | str | None = None)[source]#
Adds a mapping between filesets a corners defined in the library.
- add_asic_pdk(pdk: str | PDK, default: bool = True)[source]#
Adds the PDK associated with this library.
- Parameters:
(class (pdk) – PDK): pdk to associate
default (bool) – if True, sets this PDK in [asic,pdk]
- add_asic_pexcornerfileset(corner: str, fileset: List[str] | str | None = None)[source]#
Adds a mapping between filesets a corners defined in the library.
- add_define(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro definitions to a fileset.
- add_dep(obj: NamedSchema, clobber: bool = True) bool[source]#
Adds a module dependency to this design.
This method extends the base add_dep to prevent a design from adding a dependency on itself.
- Parameters:
obj (NamedSchema) – The dependency object to add.
clobber (bool) – If True, overwrite an existing dependency with the same name.
- Returns:
True if the dependency was added, False otherwise.
- Return type:
- Raises:
TypeError – If obj is not a NamedSchema.
ValueError – If obj has the same name as the current design.
- add_depfileset(dep: Design | str, depfileset: str | None = None, fileset: str | None = None)[source]#
Record a reference to an imported dependency’s fileset.
- Parameters:
- add_file(filename: List[Path | str] | Set[Path | str] | Tuple[Path | str, ...] | Path | str, fileset: str | None = None, filetype: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds files to a fileset.
Based on the file’s extension, this method can often infer the correct fileset and filetype. For example:
.v -> (source, verilog)
.vhd -> (source, vhdl)
.sdc -> (constraint, sdc)
.lef -> (input, lef)
.def -> (input, def)
etc.
- Parameters:
filename (Path, str, or collection) – File path (Path or str), or a collection (list, tuple, set) of file paths to add.
fileset (str) – Logical group to associate the file with.
filetype (str, optional) – Type of the file (e.g., ‘verilog’, ‘sdc’).
clobber (bool, optional) – If True, clears the list before adding the item. Defaults to False.
dataroot (str, optional) – Data directory reference name.
- Raises:
ValueError – If fileset or filetype cannot be inferred from the file extension.
- Returns:
A list of the file paths that were added.
- Return type:
Notes
This method normalizes filename to a string for consistency.
- If filetype is not specified, it is inferred from the
file extension.
- add_idir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds include directories to a fileset.
- Parameters:
- Returns:
List of include directories
- Return type:
- add_lib(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds dynamic libraries to a fileset.
- add_libdir(value: str, fileset: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds dynamic library directories to a fileset.
- Parameters:
- Returns:
List of library directories.
- Return type:
- add_undefine(value: str, fileset: str | None = None, clobber: bool = False) List[str][source]#
Adds preprocessor macro (un)definitions to a fileset.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- copy_fileset(src_fileset: str, dst_fileset: str, clobber: bool = False) None[source]#
Creates a new copy of a source fileset.
The entire configuration of the source fileset is duplicated and stored under the destination fileset’s name.
- Parameters:
- Raises:
ValueError – If the destination fileset already exists and clobber is False.
- define_tool_parameter(tool: str, name: str, type: str, help: str, **kwargs)[source]#
Define a new tool parameter for the library.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_dataroot(name: str) str[source]#
Returns absolute path to the data directory.
- Raises:
ValueError – is data directory is not found
- Parameters:
name (str) – name of the data directory to find.
- Returns:
Path to the directory root.
Examples
>>> schema.get_dataroot('siliconcompiler') Returns the path to the root of the siliconcompiler data directory.
- get_dep(name: str | None = None, hierarchy: bool = True) List[NamedSchema][source]#
Returns all dependencies associated with this object or a specific one if requested.
- get_file(fileset: str | None = None, filetype: str | None = None) List[str][source]#
Returns a list of files from one or more filesets.
- Parameters:
- Returns:
A list of resolved file paths.
- Return type:
- get_fileset(filesets: List[str] | str, alias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None) List[Tuple[Design, str]][source]#
Computes the full, recursive list of (design, fileset) tuples required for a given set of top-level filesets.
This method traverses the design’s dependency graph to resolve all depfileset entries, returning a flattened and unique list of all required sources.
- Parameters:
filesets (Union[List[str], str]) – A single fileset name or a list of fileset names to evaluate.
alias (Dict[Tuple[str, str], Tuple[Design, str]], optional) – A dictionary mapping (design_name, fileset_name) tuples to be substituted during traversal. The value should be a (Design object, new_fileset_name) tuple. This is useful for swapping out library implementations. Defaults to None.
- Returns:
A flattened, unique list of (Design, fileset) tuples representing all dependencies.
- Return type:
- get_lib(fileset: str | None = None) List[str][source]#
Returns list of dynamic libraries for a fileset.
- get_libdir(fileset: str | None = None) List[str][source]#
Returns dynamic library directories for a fileset.
- get_param(name: str, fileset: str | None = None) str[source]#
Returns value of a named fileset parameter.
- get_undefine(fileset: str | None = None) List[str][source]#
Returns undefined macros for a fileset.
- Args:
- fileset (str): Fileset name. If not provided, the active fileset is
used.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- has_dep(name: NamedSchema | str) bool[source]#
Checks if a specific dependency is present.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was found, False otherwise.
- has_file(fileset: str | None = None, filetype: str | None = None) bool[source]#
Returns true if the fileset contains files.
- Parameters:
- Returns:
True if the fileset contains files.
- Return type:
- has_idir(fileset: str | None = None) bool[source]#
Returns true if idirs are defined for the fileset
- has_libdir(fileset: str | None = None) bool[source]#
Returns true if library directories are defined for the fileset
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- property package: PackageSchema#
Gets the package schema for the design.
- Returns:
The package schema associated with this design.
- Return type:
- read_fileset(filename: str, fileset: str | None = None, fileformat: str | None = None) None[source]#
Imports filesets from a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_dep(name: str | NamedSchema) bool[source]#
Removes a previously registered module.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was removed, False if it was not found.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_dataroot(name: str = 'root', path: str | None = None, tag: str | None = None, clobber: bool = False) None[source]#
Registers a data source by name, path, and optional version tag.
This method creates a reference to a data directory, which can be a local path, a Git repository, or a remote archive. This allows other parts of the application to refer to this data source by its unique name.
- Parameters:
name (str, optional) – A unique name to identify the data source. Defaults to “root”.
path (str) – The path to the data source. This is required. It can be a local directory, a file path, a git URL, or an archive URL. If a file path is provided, its parent directory is used as the root.
tag (str, optional) – A version identifier for remote sources, such as a git commit hash, branch, or tag. Defaults to None.
clobber (bool, optional) – If True, allows overwriting an existing data source with the same name. If False (default), attempting to overwrite an existing entry will raise a ValueError.
- Raises:
ValueError – If path is not specified.
ValueError – If a data source with the given name already exists and clobber is False.
Examples
>>> # Register a remote git repository at a specific tag >>> schema.set_dataroot('siliconcompiler_data', ... 'git+https://github.com/siliconcompiler/siliconcompiler', ... tag='v1.0.0') >>> >>> # Register a local directory based on the location of a file >>> schema.set_dataroot('file_data', __file__)
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_param(name: str, value: str, fileset: str | None = None) str[source]#
Sets a named parameter for a fileset.
- set_topmodule(value: str, fileset: str | None = None) str[source]#
Sets the topmodule of a fileset.
- Parameters:
- Returns:
Topmodule name
- Return type:
Notes
first character must be letter or underscore
remaining characters can be letters, digits, or underscores
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the dependency graph to a file.
- Parameters:
Examples
>>> schema.write_depgraph('mydump.png') Renders the object dependency graph and writes the result to a png file.
- write_fileset(filename: str, fileset: Iterable[str] | str | None = None, fileformat: str | None = None, depalias: dict[Tuple[str, str], Tuple[NamedSchema | str | None, str | Tuple[str, ...] | None]] | None = None, comments: bool = False) None[source]#
Exports filesets to a standard formatted text file.
Currently supports Verilog flist format only. Intended to support other formats in the future. Inferred from file extension if not given.
- Parameters:
2.4. Tool Extension Classes#
Classes contributed by individual tool drivers. Most extend
StdCellLibrary, PDK, or FPGADevice with
tool-specific parameters – mix the ones for the tools a library targets into
its class (see Packaging an External Library).
Only the tool-specific additions are shown below; the inherited base-class API
is documented above. The remaining groups are classes a tool’s tasks are
configured with.
2.4.1. StdCellLibrary mixins#
Mixins that extend StdCellLibrary.
- class siliconcompiler.tools.openroad.OpenROADStdCellLibrary[source]#
Bases:
StdCellLibrarySchema for defining standard cell library parameters for the OpenROAD tool.
This class extends the base StdCellLibrary to manage various settings related to physical design, such as tie cells, placement settings, routing, and power grid configuration, specifically for the OpenROAD tool.
- add_openroad_globalconnectfileset(fileset: str | List[str] = None, clobber: bool = False)[source]#
Configures the global connect fileset for the OpenROAD tool.
This method defines the fileset used for global pin connections (e.g., tying power/ground pins) in the OpenROAD flow.
- add_openroad_multibit_flipflops(cells: str | List[str], clobber: bool = False)[source]#
Adds multibit flip-flop cells to the list.
- add_openroad_powergridfileset(fileset: str | List[str] = None, clobber: bool = False)[source]#
Configures the power grid definition fileset for the OpenROAD tool.
This method defines the fileset used for generating the power grid (e.g., PDN configuration files) in the OpenROAD flow.
- add_openroad_scan_chain_cells(cells: str | List[str], clobber: bool = False)[source]#
Adds scan chain cells to the list.
- set_openroad_cell_padding(global_place: int, detailed_place: int)[source]#
Sets the cell padding for both global and detailed placement.
- set_openroad_macro_placement_halo(x: float, y: float)[source]#
Sets the halo dimensions for macro placement.
- set_openroad_placement_density(density: float)[source]#
Sets the target placement density.
- Parameters:
density (float) – The target placement density, a value between 0.0 and 1.0.
- set_openroad_tapcells_file(file: str, dataroot: str = None)[source]#
Sets the file for tap cell definitions.
- set_openroad_tiehigh_cell(cell: str, output_port: str)[source]#
Sets the tie-high cell and its output port.
- class siliconcompiler.tools.klayout.KLayoutLibrary[source]#
Bases:
StdCellLibrarySchema for defining standard cell library parameters for the KLayout tool.
This class extends the base StdCellLibrary to manage settings for KLayout, such as defining cells that are allowed to be missing from the final stream file without generating an error.
- class siliconcompiler.tools.yosys.YosysStdCellLibrary[source]#
Bases:
StdCellLibrarySchema for a standard cell library specifically for the Yosys tool.
This class extends the base StdCellLibrary to define and manage a variety of tool-specific parameters required by Yosys for synthesis and technology mapping.
- add_yosys_blackbox_fileset(fileset: str | List[str], clobber: bool = False)[source]#
Adds a fileset name to the list of blackbox filesets.
- add_yosys_synthesis_fileset(fileset: str | List[str], clobber: bool = False)[source]#
Adds a fileset name to the list of synthesis filesets.
- add_yosys_tech_map(map: str | List[str], dataroot: str = None, clobber: bool = False)[source]#
Adds a technology map file to the list of maps.
- set_yosys_abc(clock_multiplier: float, load: float)[source]#
Sets the clock multiplier and load constraints for the Yosys ABC tool.
- set_yosys_adder_map(map: str, dataroot: str = None)[source]#
Sets the file path for the adder mapping.
- set_yosys_buffer_cell(cell: str, input_port: str, output_port: str)[source]#
Sets the buffer cell and its corresponding input and output ports.
- set_yosys_driver_cell(cell: str)[source]#
Sets the driver cell for Yosys synthesis.
- Parameters:
cell (str) – The name of the driver cell.
- set_yosys_tiehigh_cell(cell: str, output_port: str)[source]#
Sets the tie-high cell and its output port.
- class siliconcompiler.tools.bambu.BambuStdCellLibrary[source]#
Bases:
StdCellLibrarySchema for a standard cell library specifically for the Bambu tool.
This class extends the base StdCellLibrary to define and manage tool-specific parameters required by Bambu, such as the device name and a clock multiplier factor.
2.4.2. PDK mixins#
Mixins that extend PDK.
- class siliconcompiler.tools.openroad.OpenROADPDK[source]#
Bases:
PDKSchema for defining technology-specific parameters for the OpenROAD tool.
This class extends the base PDK to manage various settings related to physical design, such as routing layers, pin layers, and global routing derating factors, specifically for the OpenROAD tool.
- add_openroad_pinlayers(horizontal: str | List[str] = None, vertical: str | List[str] = None, clobber: bool = False)[source]#
Adds horizontal and/or vertical pin layers.
- add_openroad_rccorrection(corner: str, layer: str, res_factor: float | None = None, cap_factor: float | None = None, clobber: bool = False)[source]#
Adds a per-layer correction factor applied to the estimated parasitics.
The factors multiply the physical
rclayerresistance/capacitance beforeset_layer_rcis called, closing the gap between OpenROAD’s pre-route estimate and signoff extraction. They do not modify the physicalrclayermodel. A factor left asNoneis recorded asNone(the caller’s value is not altered) and applied as 1.0 (no correction) at runtime, so calibrating capacitance only (the common case) leaves resistance untouched, and the default state is identical to running without any correction. The layer is identified by name only (names are unique across routing and via layers);cap_factoris ignored for via layers. Calibrate these from a survey of routed designs; see the “Calibrating the parasitic estimate (PEX)” tutorial (pex_calibration).- Parameters:
corner (str) – Name of the PEX corner the factors apply to.
layer (str) – Name of the routing or via (cut) layer.
res_factor (float, optional) – Multiplier applied to the estimated resistance. Defaults to None (not prescribed; applied as 1.0).
cap_factor (float, optional) – Multiplier applied to the estimated capacitance. Ignored for via layers. Defaults to None (not prescribed; applied as 1.0).
clobber (bool, optional) – If True, replaces the entire rccorrection set instead of adding to it. Defaults to False.
- add_openroad_rclayer(corner: str, layertype: str, layer: str, resistance: float, capacitance: float | None = None, clobber: bool = False)[source]#
Adds a per-layer parasitic estimate used to seed
set_layer_rcfor a PEX corner.These values drive pre-route parasitic estimation; they are not the signoff extraction model.
- Parameters:
corner (str) – Name of the PEX corner the values apply to.
layertype (str) – Either “routing” or “via”.
layer (str) – Name of the routing or via (cut) layer.
resistance (float) – Resistance, in Ω/μm for a minimum-width routing layer or Ω/cut for a via.
capacitance (float, optional) – Capacitance in F/μm for a minimum-width routing layer. Not applicable to vias (forced to None).
clobber (bool, optional) – If True, replaces the existing rclayer set instead of adding to it. Defaults to False.
- set_openroad_detailedroutedisableviagen(value: bool)[source]#
Enables or disables automatic via generation in the detailed router.
When set to True, the router will only use vias explicitly defined in the technology LEF, rather than generating new ones.
- Parameters:
value (bool) – The boolean value to set. True disables via generation.
- set_openroad_detailedrouteviainpinlayers(layer1: str, layer2: str)[source]#
Sets the via layers used in pin layers during detailed routing.
- set_openroad_detailedrouteviarepair(layer: str)[source]#
Specifies the via layer to repair after detailed routing.
This is used to fix issues on a specific via layer in the power delivery network (PDN) post-routing.
- Parameters:
layer (str) – The name of the via layer to repair.
- set_openroad_globalroutingderating(layer: str, derating: float, clobber: bool = False)[source]#
Sets a global routing derating factor for a specific layer.
- set_openroad_processnode(node: str)[source]#
Sets the detailed routing process node name.
- Parameters:
node (str) – The name of the process node.
- set_openroad_rclayers(signal: str = None, clock: str = None)[source]#
Sets the signal and/or clock layers for RC extraction.
- set_openroad_rcxmaxlayer(layer: str)[source]#
Sets the maximum layer for OpenRCX extraction bench generation.
This parameter defines the highest routing layer to be considered during RC extraction.
- Parameters:
layer (str) – The name of the top-most layer to be used for RC extraction.
- unset_openroad_rclayer()[source]#
Unsets all per-layer parasitic estimate values.
Clears the entire
rclayerset (the companion tounset_openroad_rccorrection()), which is the natural reset before re-seeding a freshly calibrated model.
- class siliconcompiler.tools.klayout.KLayoutPDK[source]#
Bases:
PDKSchema for defining technology-specific parameters for the KLayout tool.
This class extends the base PDK to manage settings related to KLayout, such as stream units and which layers to hide on initial display.
- add_klayout_drcparam(deck: str, param: str | List[str], clobber: bool = False)[source]#
Adds one or more parameter to the DRC deck definition.
2.4.3. FPGADevice mixins#
Mixins that extend FPGADevice.
- class siliconcompiler.tools.yosys.YosysFPGA[source]#
Bases:
FPGADeviceSchema for defining FPGA-specific parameters for the Yosys tool.
This class extends the base FPGADevice to manage various configurations and technology-specific files required for synthesizing designs onto an FPGA using Yosys, including macro libraries, technology maps, and feature sets.
- add_yosys_bramtype(name: str | List[str] = None, clobber: bool = False)[source]#
Adds a block RAM type to the list of supported BRAMs.
- add_yosys_dsptype(name: str | List[str] = None, clobber: bool = False)[source]#
Adds a DSP type to the list of supported DSPs.
- add_yosys_featureset(feature: str | List[str] = None, clobber: bool = False)[source]#
Adds a feature to the feature set.
- add_yosys_macrolib(file: str | List[str], dataroot: str = None, clobber: bool = False)[source]#
Adds a macro library file.
- Parameters:
file (Union[str, List[str]]) – The path to the macro library file or a list of paths.
dataroot (str, optional) – The data root directory. Defaults to the active package.
clobber (bool, optional) – If True, overwrites the existing list with the new file(s). If False, appends the file(s) to the list. Defaults to False.
- add_yosys_registertype(name: str | List[str] = None, clobber: bool = False)[source]#
Adds a register type to the list of supported registers.
- set_yosys_dsptechmap(file: str, options: List[str] = None, dataroot: str = None)[source]#
Sets the technology map file and optional synthesis options for DSP blocks.
- set_yosys_flipfloptechmap(file: str = None, dataroot: str = None)[source]#
Sets the technology map file for flip-flops.
- class siliconcompiler.tools.vpr.VPRFPGA[source]#
Bases:
FPGADeviceSchema for defining library parameters specifically for the VPR (Verilog Place and Route) tool.
This class extends the base FPGADevice to manage various settings related to VPR, such as device information, channel width, resource types, and input file paths for the architecture and routing graph.
- add_vpr_bramtype(name: str | List[str] = None, clobber: bool = False)[source]#
Adds one or more block RAM types to the list of supported BRAMs.
- add_vpr_dsptype(name: str | List[str] = None, clobber: bool = False)[source]#
Adds one or more DSP types to the list of supported DSPs.
- add_vpr_registertype(name: str | List[str] = None, clobber: bool = False)[source]#
Adds one or more register types to the list of supported registers.
- set_vpr_archfile(file: str, dataroot: str = None)[source]#
Sets the path to the VPR architecture file.
- set_vpr_channelwidth(width: int)[source]#
Sets the channel width for VPR routing.
- Parameters:
width (int) – The channel width value.
- set_vpr_clockmodel(model: str)[source]#
Sets the clock modeling strategy.
- Parameters:
model (str) – The name of the clock model to use (e.g., ‘ideal’, ‘route’, or ‘dedicated_network’).
- set_vpr_constraintsmap(file: str, dataroot: str = None)[source]#
Sets the path to the VPR constraints map file.
- set_vpr_devicecode(name: str)[source]#
Sets the device code for VPR.
- Parameters:
name (str) – The name or code of the device.
- class siliconcompiler.tools.opensta.OpenSTAFPGA[source]#
Bases:
FPGADeviceSchema for defining library parameters specifically for the OpenSTA tool when targeting an FPGA.
This class extends the base FPGADevice to manage various settings related to OpenSTA, specifically for passing liberty filesets.
2.4.4. KLayout operations#
Layout operations performed by the KLayout operations task. Each one is
constructed with its arguments and handed to add_klayout_operation, which
returns it bound to the task so the setters below can adjust it later.
- class siliconcompiler.tools.klayout.operations.KLayoutOperation(name: str | None = None, **values)[source]#
Bases:
objectBase class for a single KLayout layout operation.
An operation is a handle onto a group of task parameters. Constructing one records the requested values,
OperationsTask.add_klayout_operationbinds it to a task and appends it to that node’s sequence, and the setters and getters below read and write the underlying parameters. The names of those parameters are an implementation detail and are never exposed.- Parameters:
name (str, optional) – Identifier for this operation. If not provided one is allocated from the operation type.
values – Initial field values, flushed to the schema when the operation is added to a task.
- class siliconcompiler.tools.klayout.operations.Merge(file: str | List[str] | None = None, input: str | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationMerges another stream into the top cell of the current layout.
Exactly one of
fileorinputmust be provided.- Parameters:
- add_file(file: str | List[str], step: str | None = None, index: int | str | None = None)[source]#
Adds a stream file to merge.
- get_file(step: str | None = None, index: int | str | None = None) List[str][source]#
Returns the stream files to merge.
- get_input(step: str | None = None, index: int | str | None = None) str[source]#
Returns the stream provided by an input node.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- set_file(file: str | List[str], step: str | None = None, index: int | str | None = None)[source]#
Sets the stream files to merge.
- class siliconcompiler.tools.klayout.operations.Add(file: str | List[str] | None = None, input: str | None = None, name: str | None = None)[source]#
Bases:
MergeAdds another stream to the current layout as a new cell instance.
Exactly one of
fileorinputmust be provided.- Parameters:
- add_file(file: str | List[str], step: str | None = None, index: int | str | None = None)[source]#
Adds a stream file to merge.
- get_file(step: str | None = None, index: int | str | None = None) List[str][source]#
Returns the stream files to merge.
- get_input(step: str | None = None, index: int | str | None = None) str[source]#
Returns the stream provided by an input node.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- set_file(file: str | List[str], step: str | None = None, index: int | str | None = None)[source]#
Sets the stream files to merge.
- class siliconcompiler.tools.klayout.operations.Rotate(angle: int | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationRotates the layout about its lower left corner.
- Parameters:
- get_angle(step: str | None = None, index: int | str | None = None) int[source]#
Returns the rotation angle in degrees.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- class siliconcompiler.tools.klayout.operations.Flatten(name: str | None = None, **values)[source]#
Bases:
KLayoutOperationFlattens the hierarchy of the top cell.
- Parameters:
name (str, optional) – identifier for this operation.
- property optype#
Operation type identifier.
- class siliconcompiler.tools.klayout.operations.Outline(layer: int | None = None, purpose: int = 0, name: str | None = None)[source]#
Bases:
KLayoutOperationAdds a box covering the top cell bounding box on the given layer.
- Parameters:
- get_layer(step: str | None = None, index: int | str | None = None) Tuple[int, int][source]#
Returns the (layer, purpose) pair the outline is drawn on.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- class siliconcompiler.tools.klayout.operations.RenameTop(cellname: str | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationRenames the top cell.
- Parameters:
- get_cellname(step: str | None = None, index: int | str | None = None) str[source]#
Returns the name of the top cell.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- class siliconcompiler.tools.klayout.operations.AddTop(cellname: str | None = None, name: str | None = None)[source]#
Bases:
RenameTopAdds a new top cell holding an instance of the current top cell.
- Parameters:
- get_cellname(step: str | None = None, index: int | str | None = None) str[source]#
Returns the name of the top cell.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- class siliconcompiler.tools.klayout.operations.RenameCell(cells: Set[Tuple[str, str]] | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationRenames cells in the layout.
- Parameters:
- add_cell(old: str, new: str, step: str | None = None, index: int | str | None = None)[source]#
Adds a cell to act on.
- get_cells(step: str | None = None, index: int | str | None = None) Set[Tuple[str, str]][source]#
Returns the cells to act on, as (old name, new name) pairs.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- class siliconcompiler.tools.klayout.operations.SwapCell(cells: Set[Tuple[str, str]] | None = None, name: str | None = None)[source]#
Bases:
RenameCellReplaces instances of one cell with another and deletes the original.
- Parameters:
- add_cell(old: str, new: str, step: str | None = None, index: int | str | None = None)[source]#
Adds a cell to act on.
- get_cells(step: str | None = None, index: int | str | None = None) Set[Tuple[str, str]][source]#
Returns the cells to act on, as (old name, new name) pairs.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- class siliconcompiler.tools.klayout.operations.DeleteLayers(layers: Set[Tuple[int, int]] | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationDeletes all shapes on the given layers, in every cell.
- Parameters:
- add_layer(layer: int, purpose: int = 0, step: str | None = None, index: int | str | None = None)[source]#
Adds a layer to delete.
- get_layers(step: str | None = None, index: int | str | None = None) Set[Tuple[int, int]][source]#
Returns the layers to delete, as (layer, purpose) pairs.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- class siliconcompiler.tools.klayout.operations.MergeShapes(layers: Set[Tuple[int, int]] | None = None, all: bool | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationMerges overlapping shapes on the given layers, in every cell.
- Parameters:
- add_layer(layer: int, purpose: int = 0, step: str | None = None, index: int | str | None = None)[source]#
Adds a layer to merge shapes on.
- get_all(step: str | None = None, index: int | str | None = None) bool[source]#
Returns whether shapes are merged on every layer in the layout.
- get_layers(step: str | None = None, index: int | str | None = None) Set[Tuple[int, int]][source]#
Returns the layers to merge shapes on, as (layer, purpose) pairs.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- set_all(value: bool, step: str | None = None, index: int | str | None = None)[source]#
Sets whether shapes are merged on every layer in the layout.
- class siliconcompiler.tools.klayout.operations.ConvertProperty(source: Tuple[int, int] | None = None, property: int | str | None = None, dest: Tuple[int, int] | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationConverts a stream property into text labels on the design.
- Parameters:
- get_dest(step: str | None = None, index: int | str | None = None) Tuple[int, int][source]#
Returns the (layer, purpose) pair the labels are written to.
- get_property(step: str | None = None, index: int | str | None = None) str[source]#
Returns the stream property to convert.
- get_source(step: str | None = None, index: int | str | None = None) Tuple[int, int][source]#
Returns the (layer, purpose) pair holding the property.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
- set_dest(layer: int, purpose: int = 0, step: str | None = None, index: int | str | None = None)[source]#
Sets the layer the labels are written to.
- set_property(property: int | str, step: str | None = None, index: int | str | None = None)[source]#
Sets the stream property to convert.
- class siliconcompiler.tools.klayout.operations.Write(filename: str | None = None, name: str | None = None)[source]#
Bases:
KLayoutOperationWrites the current state of the layout to an output file.
Every node writes its final layout automatically, so this is only needed to capture an intermediate state part way through a sequence.
- Parameters:
- get_filename(step: str | None = None, index: int | str | None = None) str[source]#
Returns the name of the output file.
- property optype#
Operation type identifier.
- property params#
Parameters owned by this operation.
2.5. ASIC Constraint Classes#
- class siliconcompiler.asic.ASICConstraint[source]#
Bases:
BaseSchemaA container for ASIC (Application-Specific Integrated Circuit) design constraints.
This class aggregates various types of constraints necessary for the physical design flow, such as timing, component placement, pin assignments, and floorplan area.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- property area: ASICAreaConstraint#
Provides access to the floorplan/area constraints.
- Returns:
The schema object for area constraints.
- Return type:
- property component: ASICComponentConstraints#
Provides access to the component placement constraints.
- Returns:
The schema object for component constraints.
- Return type:
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- property pin: ASICPinConstraints#
Provides access to pin assignment constraints.
- Returns:
The schema object for pin constraints.
- Return type:
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- property timing: ASICTimingConstraintSchema#
Provides access to the timing constraints.
- Returns:
The schema object for timing constraints.
- Return type:
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.ASICTimingConstraintSchema[source]#
Bases:
BaseSchemaManages a collection of ASIC timing scenarios for design constraints.
This class provides methods to add, retrieve, create, and remove individual
ASICTimingScenarioSchemaobjects, allowing for organized management of various timing-related constraints for different operating conditions or analysis modes.- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_mode(mode: TimingModeSchema)[source]#
Adds a timing mode to the design configuration.
This method is responsible for incorporating a new or updated timing mode into the system’s configuration. If a mode with the same name already exists, it will be overwritten (clobber=True).
- Parameters:
mode – The
TimingModeSchemaobject representing the timing mode to add. This object must have a valid name defined via its name() method.- Raises:
TypeError – If the provided mode argument is not an instance of
TimingModeSchema.ValueError – If the mode object’s name() method returns None, indicating that the mode does not have a defined name.
- add_scenario(scenario: ASICTimingScenarioSchema)[source]#
Adds a timing scenario to the design configuration.
This method is responsible for incorporating a new or updated timing scenario into the system’s configuration. If a scenario with the same name already exists, it will be overwritten (clobber=True).
- Parameters:
scenario – The
ASICTimingScenarioSchemaobject representing the timing scenario to add. This object must have a valid name defined via its name() method.- Raises:
TypeError – If the provided scenario argument is not an instance of
ASICTimingScenarioSchema.ValueError – If the scenario object’s name() method returns None, indicating that the scenario does not have a defined name.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- copy_mode(mode: str, name: str, insert: bool = True) TimingModeSchema[source]#
Copies an existing timing mode, renames it, and optionally adds it to the design.
This method retrieves the mode identified by
mode, creates a deep copy of it, and renames the copy toname. Ifinsertis True, the new mode is immediately added to the configuration.- Parameters:
- Returns:
The newly created copy of the mode.
- Return type:
- Raises:
LookupError – If the source mode specified by
modedoes not exist.
- copy_scenario(scenario: str, name: str, insert: bool = True) ASICTimingScenarioSchema[source]#
Copies an existing timing scenario, renames it, and optionally adds it to the design.
This method retrieves the scenario identified by
scenario, creates a deep copy of it, and renames the copy toname. Ifinsertis True, the new scenario is immediately added to the configuration.- Parameters:
- Returns:
The newly created copy of the scenario.
- Return type:
- Raises:
LookupError – If the source scenario specified by
scenariodoes not exist.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_mode(mode: str | None = None) TimingModeSchema | Dict[str, TimingModeSchema][source]#
Retrieves one or all timing modes from the configuration.
This method provides flexibility to fetch either a specific timing mode by its name or a collection of all currently defined modes.
- Parameters:
mode (str, optional) – The name (string) of the specific timing mode to retrieve. If this argument is omitted or set to None, the method will return a dictionary containing all available timing modes.
- Returns:
- The
TimingModeSchemaobject corresponding to the specified mode name.
- If mode is None: A dictionary where keys are mode names (str) and
values are their respective
TimingModeSchemaobjects.
- The
- Return type:
If mode is provided
- Raises:
LookupError – If a specific mode name is provided but no mode with that name is found in the configuration.
- get_scenario(scenario: str | None = None) ASICTimingScenarioSchema | Dict[str, ASICTimingScenarioSchema][source]#
Retrieves one or all timing scenarios from the configuration.
This method provides flexibility to fetch either a specific timing scenario by its name or a collection of all currently defined scenarios.
- Parameters:
scenario (str, optional) – The name (string) of the specific timing scenario to retrieve. If this argument is omitted or set to None, the method will return a dictionary containing all available timing scenarios.
- Returns:
- The
ASICTimingScenarioSchemaobject corresponding to the specified scenario name.
- If scenario is None: A dictionary where keys are scenario names (str) and
values are their respective
ASICTimingScenarioSchemaobjects.
- The
- Return type:
If scenario is provided
- Raises:
LookupError – If a specific scenario name is provided but no scenario with that name is found in the configuration.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- make_mode(mode: str) TimingModeSchema[source]#
Creates and adds a new timing mode with the specified name.
This method initializes a new
TimingModeSchemaobject with the given name and immediately adds it to the constraint configuration. It ensures that a mode with the same name does not already exist, preventing accidental overwrites.- Parameters:
mode (str) – The name for the new timing mode. This name must be a non-empty string and unique within the current configuration.
- Returns:
- The newly created
TimingModeSchema object.
- The newly created
- Return type:
TimingModeSchema- Raises:
ValueError – If the provided mode name is empty or None.
LookupError – If a mode with the specified mode name already exists in the configuration.
- make_scenario(scenario: str) ASICTimingScenarioSchema[source]#
Creates and adds a new timing scenario with the specified name.
This method initializes a new
ASICTimingScenarioSchemaobject with the given name and immediately adds it to the constraint configuration. It ensures that a scenario with the same name does not already exist, preventing accidental overwrites.- Parameters:
scenario (str) – The name for the new timing scenario. This name must be a non-empty string and unique within the current configuration.
- Returns:
- class:ASICTimingScenarioSchema: The newly created
ASICTimingScenarioSchema object.
- class:ASICTimingScenarioSchema: The newly created
- Raises:
ValueError – If the provided scenario name is empty or None.
LookupError – If a scenario with the specified scenario name already exists in the configuration.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_mode(mode: str) bool[source]#
Removes a timing mode from the design configuration.
This method deletes the specified timing mode from the system’s configuration.
- Parameters:
mode (str) – The name of the timing mode to remove. This name must be a non-empty string.
- Returns:
- True if the mode was successfully removed, False if no
mode with the given name was found.
- Return type:
- Raises:
ValueError – If the provided mode name is empty or None.
- remove_scenario(scenario: str) bool[source]#
Removes a timing scenario from the design configuration.
This method deletes the specified timing scenario from the system’s configuration.
- Parameters:
scenario (str) – The name of the timing scenario to remove. This name must be a non-empty string.
- Returns:
- True if the scenario was successfully removed, False if no
scenario with the given name was found.
- Return type:
- Raises:
ValueError – If the provided scenario name is empty or None.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.ASICTimingScenarioSchema(name: str | None = None)[source]#
Bases:
NamedSchemaRepresents a single timing scenario for ASIC design constraints.
This class encapsulates various parameters that define a specific timing scenario, such as operating voltage, temperature, library corners, PEX corners, operating mode, SDC filesets, and timing checks to be performed.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_check(check: List[str] | str, clobber: bool = False, step: str | None = None, index: int | str | None = None)[source]#
Adds a check to the design process.
- add_libcorner(libcorner: List[str] | str, clobber: bool = False, step: str | None = None, index: int | str | None = None)[source]#
Adds a library corner to the design.
- Parameters:
- add_sdcfileset(design: Design | str, fileset: str, clobber: bool = False, step: str | None = None, index: int | str | None = None)[source]#
Adds an SDC fileset for a given design.
- Parameters:
design (
Designor str) – The design object or the name of the design to associate the fileset with.fileset (str) – The name of the SDC fileset to add.
clobber (bool) – If True, existing SDC filesets for the design at the specified step/index will be overwritten. If False (default), the SDC fileset will be added.
step (str, optional) – step name.
index (str, optional) – index name.
- Raises:
TypeError – If design is not a Design object or a string, or if fileset is not a string.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_check(step: str | None = None, index: int | str | None = None) Set[str][source]#
Gets the set of checks configured for the design process.
- get_libcorner(step: str | None = None, index: int | str | None = None) Set[str][source]#
Gets the set of library corners.
- get_mode(step: str | None = None, index: int | str | None = None) str[source]#
Gets the operational mode currently set for the design.
- get_opcond(step: str | None = None, index: int | str | None = None) str[source]#
Gets the operating condition currently set for the design.
- get_pexcorner(step: str | None = None, index: int | str | None = None) str[source]#
Gets the parasitic extraction (PEX) corner currently set for the design.
- get_pin_voltage(pin: str, step: str | None = None, index: int | str | None = None) float[source]#
Gets the voltage of a specified pin.
- Parameters:
- Returns:
The voltage of the pin.
- Raises:
LookupError – If the specified pin does not have a voltage defined.
- get_sdcfileset(step: str | None = None, index: int | str | None = None) List[Tuple[str, str]][source]#
Gets the list of SDC filesets.
- get_temperature(step: str | None = None, index: int | str | None = None) float[source]#
Gets the temperature currently set for the design.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_pin_voltage(pin: str) None[source]#
Removes the voltage of a specified pin.
- Parameters:
pin (str) – The name of the pin.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_mode(mode: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the operational mode for the design.
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_opcond(opcond: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the operating condition for the design.
- set_pexcorner(pexcorner: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the parasitic extraction (PEX) corner for the design.
- set_pin_voltage(pin: str, voltage: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the voltage for a specified pin.
- set_temperature(temperature: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the temperature for the design.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.ASICAreaConstraint[source]#
Bases:
BaseSchemaManages various area-related constraints for an ASIC design.
This class provides a structured way to define and retrieve constraints related to the die area, core area, core margin, target density, and aspect ratio of the physical layout. These constraints are essential for automated floorplanning and physical design tasks.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- calc_diearea(step: str | None = None, index: int | str | None = None) float[source]#
Calculates the area of a rectilinear die.
Uses the shoelace formula to calculate the design area from the (x,y) point tuples in the ‘diearea’ parameter. If ‘diearea’ contains only two points, they are treated as the lower-left and upper-right corners of a rectangle. (Ref: https://en.wikipedia.org/wiki/Shoelace_formula)
- Parameters:
- Returns:
The calculated design area in square schema units.
- Return type:
Examples
>>> # In the context of a 'pdk' object >>> area = asic.get('constraint').calc_diearea()
- calc_floorplan_areas(step: str | None = None, index: int | str | None = None) Tuple[List[Tuple[float, float]], List[Tuple[float, float]]] | None[source]#
Resolves the die and core areas used to initialize a floorplan.
Floorplanning tools need both a die and a core outline, but only one of them has to be specified since the other can be derived from the core margin:
die area and core area: both are used as specified.
die area only: the core area is the die area inset by the core margin.
core area only: the die area is the core area outset by the core margin. The core keeps the coordinates it was given so that component placements remain valid, which means the core area has to sit at least one core margin away from the origin.
Rectilinear outlines are offset edge by edge, so a polygonal die yields a polygonal core that follows it rather than its bounding box.
A core margin of zero is assumed when the margin has not been set.
- Parameters:
- Raises:
ValueError – If the core margin does not leave a core area with a positive width and height, or if it places the die area at a negative coordinate.
- Returns:
The die and core areas, or None if neither area has been specified, in which case the floorplan must be sized from the density and aspect ratio.
- Return type:
Optional[Tuple[List[Tuple[float, float]], List[Tuple[float, float]]]]
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_aspectratio(step: str | None = None, index: int | str | None = None) float[source]#
Retrieves the current layout aspect ratio.
- get_corearea(step: str | None = None, index: int | str | None = None) List[Tuple[float, float]][source]#
Retrieves the current core area definition.
- Parameters:
- Returns:
- A list of (x, y) tuples representing
the coordinates that define the core area.
- Return type:
- get_coreboundingbox(step: str | None = None, index: int | str | None = None) Tuple[Tuple[float, float], Tuple[float, float]][source]#
Retrieves the bounding box of the core area.
- Parameters:
- Returns:
A tuple containing the lower-left and upper-right coordinates of the core area’s bounding box.
- Return type:
- get_coremargin(step: str | None = None, index: int | str | None = None) float[source]#
Retrieves the current core margin.
- get_coresize(step: str | None = None, index: int | str | None = None) Tuple[float, float][source]#
Retrieves the size (width and height) of the core area.
- get_density(step: str | None = None, index: int | str | None = None) float[source]#
Retrieves the current target layout density.
- get_diearea(step: str | None = None, index: int | str | None = None) List[Tuple[float, float]][source]#
Retrieves the current die area definition.
- Parameters:
- Returns:
- A list of (x, y) tuples representing
the coordinates that define the die area.
- Return type:
- get_dieboundingbox(step: str | None = None, index: int | str | None = None) Tuple[Tuple[float, float], Tuple[float, float]][source]#
Retrieves the bounding box of the die area.
- Parameters:
- Returns:
A tuple containing the lower-left and upper-right coordinates of the die area’s bounding box.
- Return type:
- get_diesize(step: str | None = None, index: int | str | None = None) Tuple[float, float][source]#
Retrieves the size (width and height) of the die area.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_aspectratio(aspectratio: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the layout aspect ratio.
This method validates the aspectratio input to ensure it’s a positive number.
- Parameters:
aspectratio (float) – The aspect ratio value (height / width). Must be a number greater than 0.0.
step (str, optional) – The step in a workflow to associate this setting with. Defaults to None.
index (Union[str, int], optional) – The index within a step to associate this setting with. Defaults to None.
- Raises:
TypeError – If aspectratio is not a number.
ValueError – If aspectratio is zero or negative.
- Returns:
The return value from the internal set method call.
- set_corearea(points: List[Tuple[float, float]], step: str | None = None, index: int | str | None = None)[source]#
Sets the core area using a list of points defining its boundary.
- Parameters:
points (List[Tuple[float, float]]) – A list of (x, y) tuples representing the coordinates that define the core area.
step (str, optional) – The step in a workflow to associate this setting with. Defaults to None.
index (Union[str, int], optional) – An index or identifier within a step. Defaults to None.
- Returns:
The return value from the internal set method call.
- set_corearea_rectangle(dieheight: float, diewidth: float, coremargin: float | Tuple[float, float], step: str | None = None, index: int | str | None = None)[source]#
Sets the core area as a rectangle within a die area, based on margins.
The core area is calculated by subtracting the margins from the die dimensions. Margins can be uniform (single float) or specified separately for x and y.
- Parameters:
dieheight (float) – The height of the die area. Must be > 0.
diewidth (float) – The width of the die area. Must be > 0.
coremargin (Union[float, Tuple[float, float]]) – The margin(s) to apply. - If a float, it’s applied uniformly to all four sides. - If a tuple of two floats, it’s (x_margin, y_margin).
step (str, optional) – The step in a workflow to associate this setting with. Defaults to None.
index (Union[str, int], optional) – The index within a step to associate this setting with. Defaults to None.
- Raises:
TypeError – If dieheight/diewidth are not numbers, or if coremargin is not a number or a tuple of two numbers.
ValueError – If dimensions are invalid or margins are too large.
- Returns:
The return value from the internal set_corearea method call.
- set_coremargin(coremargin: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the core margin.
This method validates the coremargin input to ensure it’s a non-negative number.
- Parameters:
coremargin (float) – The core margin value in schema units (e.g., um). Must be a number greater than or equal to 0.0.
step (str, optional) – The step in a workflow to associate this setting with. Defaults to None.
index (Union[str, int], optional) – The index within a step to associate this setting with. Defaults to None.
- Raises:
TypeError – If coremargin is not a number.
ValueError – If coremargin is negative.
- Returns:
The return value from the internal set method call.
- set_density(density: float, aspectratio: float | None = None, coremargin: float | None = None, step: str | None = None, index: int | str | None = None)[source]#
Sets the target layout density.
This method validates the density input to ensure it’s a number between 0 (exclusive) and 100 (inclusive). Optionally, it can also set the aspect ratio and core margin if provided.
- Parameters:
density (float) – The target density value (0 < density <= 100).
aspectratio (float, optional) – The aspect ratio to set. If provided, set_aspectratio will be called. Defaults to None.
coremargin (float, optional) – The core margin to set. If provided, set_coremargin will be called. Defaults to None.
step (str, optional) – The step in a workflow to associate this setting with. Defaults to None.
index (Union[str, int], optional) – The index within a step to associate this setting with. Defaults to None.
- Raises:
TypeError – If density is not a number.
ValueError – If density is not within the valid range (0, 100].
- Returns:
A list of return values from the internal set calls.
- Return type:
- set_diearea(points: List[Tuple[float, float]], step: str | None = None, index: int | str | None = None)[source]#
Sets the die area using a list of points defining its boundary.
- Parameters:
points (List[Tuple[float, float]]) – A list of (x, y) tuples representing the coordinates that define the die area.
step (str, optional) – The step in a workflow to associate this setting with. Defaults to None.
index (Union[str, int], optional) – The index within a step to associate this setting with. Defaults to None.
- Returns:
The return value from the internal set method call.
- set_diearea_rectangle(height: float, width: float, coremargin: float | Tuple[float, float] | None = None, step: str | None = None, index: int | str | None = None)[source]#
Sets the die area as a rectangle with its bottom-left corner at (0,0).
Optionally, it can also set the core area as a rectangle based on the provided core margin.
- Parameters:
height (float) – The height of the rectangular die area. Must be > 0.
width (float) – The width of the rectangular die area. Must be > 0.
coremargin (Union[float, Tuple[float, float]], optional) – The margin for the core area. Can be a single float (uniform margin) or a tuple of two floats (x, y margins). If provided, set_corearea_rectangle will be called. Defaults to None.
step (str, optional) – The step in a workflow to associate this setting with. Defaults to None.
index (Union[str, int], optional) – The index within a step to associate this setting with. Defaults to None.
- Raises:
TypeError – If height or width are not numbers.
ValueError – If height or width are zero or negative.
- Returns:
A list of return values from the internal set calls.
- Return type:
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.ASICPinConstraints[source]#
Bases:
BaseSchemaManages a collection of ASIC pin constraints.
This class provides methods to add, retrieve, create, and remove individual
ASICPinConstraintobjects, allowing for organized management of pin-level placement and property constraints.- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_pinconstraint(pin: ASICPinConstraint)[source]#
Adds a pin constraint to the design configuration.
This method incorporates a new or updated pin constraint into the system’s configuration. If a constraint with the same name already exists, it will be overwritten (clobber=True).
- Parameters:
pin – The
ASICPinConstraintobject representing the pin constraint to add. This object must have a valid name defined via its name() method.- Raises:
TypeError – If the provided pin argument is not an instance of
ASICPinConstraint.ValueError – If the pin object’s name() method returns None, indicating that the pin constraint does not have a defined name.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- copy_pinconstraint(pin: str, name: str, insert: bool = True) ASICPinConstraint[source]#
Copies an existing pin constraint, renames it, and optionally adds it to the design.
This method retrieves the pin constraint identified by
pin, creates a deep copy of it, and renames the copy toname. Ifinsertis True, the new constraint is immediately added to the configuration.- Parameters:
- Returns:
The newly created copy of the pin constraint.
- Return type:
- Raises:
LookupError – If the source pin constraint specified by
pindoes not exist.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_pinconstraint(pin: str | None = None) ASICPinConstraint | Dict[str, ASICPinConstraint][source]#
Retrieves one or all pin constraints from the configuration.
This method provides flexibility to fetch either a specific pin constraint by its name or a collection of all currently defined constraints.
- Parameters:
pin (str, optional) – The name (string) of the specific pin constraint to retrieve. If this argument is omitted or set to None, the method will return a dictionary containing all available pin constraints.
- Returns:
- The
ASICPinConstraintobject corresponding to the specified pin constraint name.
- If pin is None: A dictionary where keys are pin constraint names (str) and
values are their respective
ASICPinConstraintobjects.
- The
- Return type:
If pin is provided
- Raises:
LookupError – If a specific pin name is provided but no pin constraint with that name is found in the configuration.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- make_buspinconstraints(pins: List[str], side: int | str, layer: str | None = None, center: float | None = None, pitch: float | None = None, side_width: float | None = None, side_offset: float | None = None, step: str | None = None, index: int | str | None = None) List[ASICPinConstraint][source]#
Creates and adds pin constraints for a bus, distributing the pins evenly along a single side of the die.
The pins are laid out along the chosen side using two independent quantities: the spacing between pins and the position of the bus along the edge.
- Spacing is derived from exactly one of:
pitch: the center-to-center spacing between adjacent pins. The bus occupies a span oflen(pins) * pitch.side_width: the total span occupied by the bus. The pitch is derived asside_width / len(pins)and each pin is centered within its slot.
- Position is derived from at most one of:
center: the bus span is centered on this coordinate.side_offset: the gap between the bus and a corner of the side. A positive value measures from the near (lower/left) corner; a negative value anchors the far end of the bus to the far (upper/right) corner (e.g.-10leaves a 10um gap at the far end).neither: the bus is centered on the die edge.
If none of
center,pitch,side_widthorside_offsetare provided, the pins are placed usingside+orderonly, leaving the exact placement to the layout tool.- Parameters:
pins (List[str]) – The pin names to constrain, in order along the side.
side (Union[int, str]) – The side of the die to place the pins on (integer or ‘left’/’right’/’top’/’bottom’ and compass aliases).
layer (str, optional) – The metal layer for the pins.
center (float, optional) – Center coordinate of the bus along the side.
pitch (float, optional) – Center-to-center spacing between pins.
side_width (float, optional) – Total span occupied by the bus.
side_offset (float, optional) – Gap between the bus and a corner of the side. Positive measures from the near corner, negative from the far corner.
step (str, optional) – step name.
index (str, optional) – index name.
- Returns:
The created/updated pin constraints, ordered to match
pins.- Return type:
List[ASICPinConstraint]
- Raises:
ValueError – If
pinsis empty, if bothpitchandside_widthare given, if bothcenterandside_offsetare given, if a position is given without any spacing, or if the bus does not fit on the requested side.TypeError – If the constraint is not attached to an ASIC project.
- make_pinconstraint(pin: str) ASICPinConstraint[source]#
Creates and adds a new pin constraint with the specified name.
This method initializes a new
ASICPinConstraintobject with the given name and immediately adds it to the design configuration. It ensures that a constraint with the same name does not already exist, preventing accidental overwrites.- Parameters:
pin (str) – The name for the new pin constraint. This name must be a non-empty string and unique within the current configuration.
- Returns:
class:ASICPinConstraint: The newly created
ASICPinConstraintobject.- Raises:
ValueError – If the provided pin name is empty or None.
LookupError – If a pin constraint with the specified pin name already exists in the configuration.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_pinconstraint(pin: str) bool[source]#
Removes a pin constraint from the design configuration.
This method deletes the specified pin constraint from the system’s configuration.
- Parameters:
pin (str) – The name of the pin constraint to remove. This name must be a non-empty string.
- Returns:
- True if the pin constraint was successfully removed, False if no
pin constraint with the given name was found.
- Return type:
- Raises:
ValueError – If the provided pin name is empty or None.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.ASICPinConstraint(name: str | None = None)[source]#
Bases:
NamedSchemaRepresents a single ASIC pin constraint within the design configuration.
This class defines various constraints that can be applied to an individual ASIC pin, such as its placement, dimensions (width, length), shape, metal layer, and its relative position on the chip’s side.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_layer(step: str | None = None, index: int | str | None = None) str[source]#
Retrieves the current metal layer constraint of the pin.
- get_length(step: str | None = None, index: int | str | None = None) float[source]#
Retrieves the current length constraint of the pin.
- get_order(step: str | None = None, index: int | str | None = None) int[source]#
Retrieves the current order constraint of the pin.
- get_placement(step: str | None = None, index: int | str | None = None) Tuple[float, float][source]#
Retrieves the current placement constraint of the pin.
- get_shape(step: str | None = None, index: int | str | None = None) str[source]#
Retrieves the current shape constraint of the pin.
- get_side(step: str | None = None, index: int | str | None = None) int[source]#
Retrieves the current side constraint of the pin.
- get_width(step: str | None = None, index: int | str | None = None) float[source]#
Retrieves the current width constraint of the pin.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_layer(layer: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the metal layer constraint for the pin.
- set_length(length: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the length constraint for the pin.
- Parameters:
- Raises:
TypeError – If length is not an int or float.
ValueError – If length is not a positive value.
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_order(order: int, step: str | None = None, index: int | str | None = None)[source]#
Sets the relative order constraint for the pin on its assigned side.
- set_placement(x: float, y: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the placement constraint for the pin.
- Parameters:
x (float) – The X-coordinate for the pin’s center in micrometers (um) relative to the lower-left corner of the substrate.
y (float) – The Y-coordinate for the pin’s center in micrometers (um) relative to the lower-left corner of the substrate.
step (str, optional) – step name.
index (str, optional) – index name.
- Raises:
TypeError – If x or y is not an int or float.
- set_shape(shape: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the shape constraint for the pin.
- set_side(side: int | str, step: str | None = None, index: int | str | None = None)[source]#
Sets the side constraint for the pin, indicating where it should be placed.
- Parameters:
- Raises:
TypeError – If side is not an int or string.
ValueError – If side is an unrecognized string value or a non-positive integer.
- set_width(width: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the width constraint for the pin.
- Parameters:
- Raises:
TypeError – If width is not an int or float.
ValueError – If width is not a positive value.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.ASICComponentConstraints[source]#
Bases:
BaseSchemaManages a collection of ASIC component constraints.
This class provides methods to add, retrieve, create, and remove individual
ASICComponentConstraintobjects, allowing for organized management of component-level placement and property constraints.- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_component(component: ASICComponentConstraint)[source]#
Adds a component constraint to the design configuration.
This method incorporates a new or updated component constraint into the system’s configuration. If a constraint with the same name already exists, it will be overwritten (clobber=True).
- Parameters:
component – The
ASICComponentConstraintobject representing the component constraint to add. This object must have a valid name defined via its name() method.- Raises:
TypeError – If the provided component argument is not an instance of ASICComponentConstraint.
ValueError – If the component object’s name() method returns None, indicating that the component constraint does not have a defined name.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- copy_component(component: str, name: str, insert: bool = True) ASICComponentConstraint[source]#
Copies an existing component constraint, renames it, and optionally adds it to the design.
This method retrieves the component constraint identified by
component, creates a deep copy of it, and renames the copy toname. Ifinsertis True, the new constraint is immediately added to the configuration.- Parameters:
- Returns:
The newly created copy of the component constraint.
- Return type:
- Raises:
LookupError – If the source component constraint specified by
componentdoes not exist.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_component(component: str | None = None)[source]#
Retrieves one or all component constraints from the configuration.
This method provides flexibility to fetch either a specific component constraint by its name or a collection of all currently defined constraints.
- Parameters:
component (str, optional) – The name (string) of the specific component constraint to retrieve. If this argument is omitted or set to None, the method will return a dictionary containing all available component constraints.
- Returns:
- The
ASICComponentConstraintobject corresponding to the specified component name.
- If component is None: A dictionary where keys are component names (str) and
values are their respective
ASICComponentConstraintobjects.
- The
- Return type:
If component is provided
- Raises:
LookupError – If a specific component name is provided but no component constraint with that name is found in the configuration.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- make_component(component: str) ASICComponentConstraint[source]#
Creates and adds a new component constraint with the specified name.
This method initializes a new
ASICComponentConstraintobject with the given name and immediately adds it to the design configuration. It ensures that a constraint with the same name does not already exist, preventing accidental overwrites.- Parameters:
component (str) – The name for the new component constraint. This name must be a non-empty string and unique within the current configuration.
- Returns:
The newly created
ASICComponentConstraintobject.- Return type:
- Raises:
ValueError – If the provided component name is empty or None.
LookupError – If a component constraint with the specified component name already exists in the configuration.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_component(component: str) bool[source]#
Removes a component constraint from the design configuration.
This method deletes the specified component constraint from the system’s configuration.
- Parameters:
component (str) – The name of the component constraint to remove. This name must be a non-empty string.
- Returns:
- True if the component constraint was successfully removed, False if no
component constraint with the given name was found.
- Return type:
- Raises:
ValueError – If the provided component name is empty or None.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.ASICComponentConstraint(name: str | None = None)[source]#
Bases:
NamedSchemaRepresents a single ASIC component constraint within the design configuration.
This class defines various constraints that can be applied to an individual ASIC component instance, such as its placement, part name (cell name), keepout halo, and rotation.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_halo(step: str | None = None, index: int | str | None = None) Tuple[float, float][source]#
Retrieves the current placement keepout halo constraint of the component.
- get_partname(step: str | None = None, index: int | str | None = None) str[source]#
Retrieves the current part name (cell name) constraint of the component.
- get_placement(step: str | None = None, index: int | str | None = None) Tuple[float, float][source]#
Retrieves the current placement constraint of the component.
- get_rotation(step: str | None = None, index: int | str | None = None) str[source]#
Retrieves the current rotation constraint of the component.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_halo(x: float, y: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the placement keepout halo constraint around the component.
- Parameters:
- Raises:
TypeError – If x or y is not an int or float.
ValueError – If x or y is a negative value.
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_partname(name: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the part name (cell name) constraint for the component.
- Parameters:
- Raises:
ValueError – If name is an empty string or None.
- set_placement(x: float, y: float, step: str | None = None, index: int | str | None = None)[source]#
Sets the placement constraint for the component.
- Parameters:
x (float) – The X-coordinate for the component’s anchor point in micrometers (um) relative to the substrate origin.
y (float) – The Y-coordinate for the component’s anchor point in micrometers (um) relative to the substrate origin.
step (str, optional) – step name.
index (str, optional) – index name.
- Raises:
TypeError – If x or y is not an int or float.
- set_rotation(rotation: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the rotation constraint for the component.
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
2.6. FPGA Constraint Classes#
- class siliconcompiler.fpga.FPGAConstraint[source]#
Bases:
BaseSchemaA container for FPGA (Field-Programmable Gate Array) design constraints.
This class aggregates various types of constraints necessary for the FPGA implementation flow, such as timing, component placement, and pin assignments.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- property component: FPGAComponentConstraints#
Provides access to the component placement constraints.
- Returns:
The schema object for component constraints.
- Return type:
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- property pin: FPGAPinConstraints#
Provides access to pin assignment constraints.
- Returns:
The schema object for pin constraints.
- Return type:
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- property timing: FPGATimingConstraintSchema#
Provides access to the timing constraints.
- Returns:
The schema object for timing constraints.
- Return type:
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.FPGATimingConstraintSchema[source]#
Bases:
BaseSchemaManages a collection of FPGA timing scenarios for design constraints.
This class provides methods to add, retrieve, create, and remove individual
FPGATimingScenarioSchemaobjects, allowing for organized management of various timing-related constraints for different operating conditions or analysis modes.- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_mode(mode: TimingModeSchema)[source]#
Adds a timing mode to the design configuration.
This method is responsible for incorporating a new or updated timing mode into the system’s configuration. If a mode with the same name already exists, it will be overwritten (clobber=True).
- Parameters:
mode – The
TimingModeSchemaobject representing the timing mode to add. This object must have a valid name defined via its name() method.- Raises:
TypeError – If the provided mode argument is not an instance of
TimingModeSchema.ValueError – If the mode object’s name() method returns None, indicating that the mode does not have a defined name.
- add_scenario(scenario: FPGATimingScenarioSchema)[source]#
Adds a timing scenario to the design configuration.
This method is responsible for incorporating a new or updated timing scenario into the system’s configuration. If a scenario with the same name already exists, it will be overwritten (clobber=True).
- Parameters:
scenario – The
FPGATimingScenarioSchemaobject representing the timing scenario to add. This object must have a valid name defined via its name() method.- Raises:
TypeError – If the provided scenario argument is not an instance of
FPGATimingScenarioSchema.ValueError – If the scenario object’s name() method returns None, indicating that the scenario does not have a defined name.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- copy_mode(mode: str, name: str, insert: bool = True) TimingModeSchema[source]#
Copies an existing timing mode, renames it, and optionally adds it to the design.
This method retrieves the mode identified by
mode, creates a deep copy of it, and renames the copy toname. Ifinsertis True, the new mode is immediately added to the configuration.- Parameters:
- Returns:
The newly created copy of the mode.
- Return type:
- Raises:
LookupError – If the source mode specified by
modedoes not exist.
- copy_scenario(scenario: str, name: str, insert: bool = True) FPGATimingScenarioSchema[source]#
Copies an existing timing scenario, renames it, and optionally adds it to the design.
This method retrieves the scenario identified by
scenario, creates a deep copy of it, and renames the copy toname. Ifinsertis True, the new scenario is immediately added to the configuration.- Parameters:
- Returns:
The newly created copy of the scenario.
- Return type:
- Raises:
LookupError – If the source scenario specified by
scenariodoes not exist.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_mode(mode: str | None = None) TimingModeSchema | Dict[str, TimingModeSchema][source]#
Retrieves one or all timing modes from the configuration.
This method provides flexibility to fetch either a specific timing mode by its name or a collection of all currently defined modes.
- Parameters:
mode (str, optional) – The name (string) of the specific timing mode to retrieve. If this argument is omitted or set to None, the method will return a dictionary containing all available timing modes.
- Returns:
- The
TimingModeSchemaobject corresponding to the specified mode name.
- If mode is None: A dictionary where keys are mode names (str) and
values are their respective
TimingModeSchemaobjects.
- The
- Return type:
If mode is provided
- Raises:
LookupError – If a specific mode name is provided but no mode with that name is found in the configuration.
- get_scenario(scenario: str | None = None) FPGATimingScenarioSchema | Dict[str, FPGATimingScenarioSchema][source]#
Retrieves one or all timing scenarios from the configuration.
This method provides flexibility to fetch either a specific timing scenario by its name or a collection of all currently defined scenarios.
- Parameters:
scenario (str, optional) – The name (string) of the specific timing scenario to retrieve. If this argument is omitted or set to None, the method will return a dictionary containing all available timing scenarios.
- Returns:
- The
FPGATimingScenarioSchemaobject corresponding to the specified scenario name.
- If scenario is None: A dictionary where keys are scenario names (str) and
values are their respective
FPGATimingScenarioSchemaobjects.
- The
- Return type:
If scenario is provided
- Raises:
LookupError – If a specific scenario name is provided but no scenario with that name is found in the configuration.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- make_mode(mode: str) TimingModeSchema[source]#
Creates and adds a new timing mode with the specified name.
This method initializes a new
TimingModeSchemaobject with the given name and immediately adds it to the constraint configuration. It ensures that a mode with the same name does not already exist, preventing accidental overwrites.- Parameters:
mode (str) – The name for the new timing mode. This name must be a non-empty string and unique within the current configuration.
- Returns:
- The newly created
TimingModeSchema object.
- The newly created
- Return type:
TimingModeSchema- Raises:
ValueError – If the provided mode name is empty or None.
LookupError – If a mode with the specified mode name already exists in the configuration.
- make_scenario(scenario: str) FPGATimingScenarioSchema[source]#
Creates and adds a new timing scenario with the specified name.
This method initializes a new
FPGATimingScenarioSchemaobject with the given name and immediately adds it to the constraint configuration. It ensures that a scenario with the same name does not already exist, preventing accidental overwrites.- Parameters:
scenario (str) – The name for the new timing scenario. This name must be a non-empty string and unique within the current configuration.
- Returns:
- The newly created
FPGATimingScenarioSchema object.
- The newly created
- Return type:
- Raises:
ValueError – If the provided scenario name is empty or None.
LookupError – If a scenario with the specified scenario name already exists in the configuration.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_mode(mode: str) bool[source]#
Removes a timing mode from the design configuration.
This method deletes the specified timing mode from the system’s configuration.
- Parameters:
mode (str) – The name of the timing mode to remove. This name must be a non-empty string.
- Returns:
- True if the mode was successfully removed, False if no
mode with the given name was found.
- Return type:
- Raises:
ValueError – If the provided mode name is empty or None.
- remove_scenario(scenario: str) bool[source]#
Removes a timing scenario from the design configuration.
This method deletes the specified timing scenario from the system’s configuration.
- Parameters:
scenario (str) – The name of the timing scenario to remove. This name must be a non-empty string.
- Returns:
- True if the scenario was successfully removed, False if no
scenario with the given name was found.
- Return type:
- Raises:
ValueError – If the provided scenario name is empty or None.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.FPGATimingScenarioSchema(name: str | None = None)[source]#
Bases:
NamedSchemaRepresents a single timing scenario for FPGA design constraints.
This class encapsulates various parameters that define a specific timing scenario and operating mode.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_mode(step: str | None = None, index: int | str | None = None) str[source]#
Gets the operational mode currently set for the design.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_mode(mode: str, step: str | None = None, index: int | str | None = None)[source]#
Sets the operational mode for the design.
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.FPGAComponentConstraints[source]#
Bases:
BaseSchema- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.constraints.FPGAPinConstraints[source]#
Bases:
BaseSchema- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
2.7. Core Schema Classes#
- class siliconcompiler.schema.BaseSchema[source]#
This class maintains the access and file IO operations for the schema. It can be modified using
EditableSchema.- _from_dict(manifest: Dict, keypath: List[str] | Tuple[str, ...], version: Tuple[int, ...] | None = None, lazyload: LazyLoad = LazyLoad.ON) Tuple[Set[Tuple[str, ...]], Set[Tuple[str, ...]]][source]#
Decodes a dictionary into a schema object
- _parent(root: bool = False) BaseSchema[source]#
Returns the parent of this schema section, if root is true the root parent will be returned.
- Parameters:
root (bool) – if true, returns the root of the schemas.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.schema.EditableSchema(schema: BaseSchema)[source]#
This class provides access to modify the underlying schema. This should only be used when creating new schema entries.
- Parameters:
schema (
BaseSchema) – schema to modify
- copy() BaseSchema[source]#
Creates a copy of the schema object, disconnected from any parent schema
- insert(*args: str | BaseSchema | Parameter, clobber: bool = False) None[source]#
Inserts a
Parameteror aBaseSchemato the schema, based on the keypath and value provided in the*args.- Parameters:
args (list) – Parameter keypath followed by a item to add.
clobber (boolean) – If true, will overwrite existing value, otherwise will raise a KeyError if it is already defined.
Examples
>>> schema.insert('option', 'value', Parameter('str')) Adds the keypath [option,value] with a string parameter.
- remove(*keypath: str) None[source]#
Removes a keypath from the schema.
- Parameters:
keypath (list) – keypath to be removed.
Examples
>>> schema.remove('option', 'value') Removes the keypath [option,value] from the schema.
- class siliconcompiler.schema.SafeSchema[source]#
Bases:
BaseSchemaThis object can handle any schema without any class dependencies. This is useful when reading in a schema in an external tool.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = False) SafeSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.schema.Journal(keyprefix: List[str] | Tuple[str, ...] | None = None)[source]#
This class provides the ability to record the schema transactions:
BaseSchema.set(),BaseSchema.add(),BaseSchema.remove(),BaseSchema.unset(), andBaseSchema.get().- static access(schema: BaseSchema) Journal[source]#
Access a journal from a schema
- Parameters:
schema (
BaseSchema) – schema to replay transactions to access journal
- add_type(value: str) None[source]#
Adds a new access type to the journal record.
- Parameters:
value (str) – access type
- from_dict(manifest: List[Dict]) None[source]#
Import a journal from a manifest dictionary
- Parameters:
manifest (dict) – Manifest to decode.
- has_journaling() bool[source]#
Returns true if the schema is currently setup and is the root of the journal and has data
- record(record_type: str, key: List[str] | Tuple[str, ...], value=None, field: str | None = None, step: str | None = None, index: str | int | None = None) None[source]#
Record the schema transaction
- remove_type(value: str) None[source]#
Removes a new access type to the journal record.
- Parameters:
value (str) – access type
- replay(schema: BaseSchema) None[source]#
Replay journal into a schema
- Parameters:
schema (
BaseSchema) – schema to replay transactions to
- static replay_file(schema: BaseSchema, filepath: str) None[source]#
Replay a journal into a schema from a manifest
- Parameters:
schema (
BaseSchema) – schema to replay transactions tofilepath (path) – path to manifest
- class siliconcompiler.schema.NamedSchema(name: str | None = None)[source]#
Bases:
BaseSchemaThis object provides a named
BaseSchema.- Parameters:
name (str) – name of the schema
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.schema.Parameter(type: str, require: bool = False, defvalue=None, scope: Scope = Scope.GLOBAL, copy: bool = False, lock: bool = False, hashalgo: str = 'sha256', notes: str | None = None, unit: str | None = None, shorthelp: str | None = None, switch: List[str] | str | None = None, example: List[str] | str | None = None, help: str | None = None, pernode: PerNode = PerNode.NEVER, **kwargs)[source]#
Leaf nodes in the schema. This holds all the information for a given keypath.
- Parameters:
type (str) – type for the parameter, see
parametertype.NodeTypefor supported types.require (bool) – require field
defvalue (any) – defvalue field
scope (
Scope) – scope fieldcopy (bool) – copy field
lock (bool) – bool field
hashalgo (str) – hashalgo field
notes (str) – notes field
unit (str) – unit field
shorthelp (str) – shorthelp field
help (str) – help field
pernode (
PerNode) – pernode fieldkwargs – forwarded to default value constructor
- add(value, field: str = 'value', step: str | None = None, index: str | int | None = None) bool | List[NodeValue] | NodeValue[source]#
Adds item(s) to a list.
- Parameters:
Examples
>>> param.add('hello.v') Adds the file 'hello.v' the parameter.
- add_commandline_arguments(argparser: ArgumentParser, *keypath: str, switchlist: Set[str] | List[str] | str | None = None) Tuple[str | None, List[str] | None][source]#
Adds commandline arguments for this parameter.
- Parameters:
argparser (argparse.ArgumentParser) – argument parser to add switches to
keypath (list of str) – keypath where this parameter is located.
switchlist (list of str) – if provided will limited the switched added to those in this list
- Returns:
key for argument parsing to lookup values in. switches (list of str): list of switches added.
- Return type:
dest (str)
- basetype() str | None[source]#
Returns the underlying scalar base type name of this parameter, unwrapping any container nesting and range/enum wrappers (e.g.
[int]andint<0..>both return'int'). ReturnsNonefor heterogeneous tuples. SeeNodeType.basetype().
- property default: NodeValue | NodeSetValue | NodeListValue#
Gets a copy of the default value.
- classmethod from_dict(manifest: Dict, keypath: Tuple[str, ...], version: Tuple[int, ...] | None) Parameter[source]#
Create a new parameter based on the provided dictionary.
- get(field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns the value in a parameter field.
- Parameters:
- Returns:
Field value for the parameter.
Examples
>>> value = param.get() Returns the value stored in the parameter.
- getdict(include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
- Parameters:
include_default (boolean) – If true will include default values
values_only (boolean) – If true will only return values
- Returns:
A schema dictionary
Examples
>>> param.getdict() Returns the complete dictionary for the parameter
- gettcl(step: str | None = None, index: str | int | None = None) str | None[source]#
Returns a tcl string for this parameter.
- getvalues(return_defvalue: bool = True, return_values: bool = True) List[Tuple[Any | NodeValue | NodeSetValue | NodeListValue, str | None, str | None]][source]#
Returns all values (global and pernode) associated with a particular parameter.
Returns a list of tuples of the form (value, step, index). The list is in no particular order. For the global value, step and index are None. If return_defvalue is True, the default parameter value is added to the list in place of a global value if a global value is not set.
- has_value(step: str | None = None, index: str | int | None = None) bool[source]#
Returns whether the parameter as a value.
A value counts as set if a user has set a global value OR a value for the provided step/index.
- property is_directory: bool#
Returns true if this parameter’s type contains a
dirtype.This is true for plain
dirparameters as well as for container types whose leaf isdir(e.g.[dir],{dir}, or tuples containingdir).
- property is_file: bool#
Returns true if this parameter’s type contains a
filetype.This is true for plain
fileparameters as well as for container types whose leaf isfile(e.g.[file],{file}, or tuples containingfile).
- is_list() bool[source]#
Returns true is this parameter is a list type
Deprecated since version Use:
istype()instead, e.g.param.istype('list', 'set').
- property is_path: bool#
Returns true if this parameter’s type contains a
fileordirtype. Useful for code paths that treat files and directories the same (e.g. resolving, hashing, or copying path-like values).
- is_set(step: str | None = None, index: str | int | None = None) bool[source]#
Returns whether a user has set a value for this parameter.
A value counts as set if a user has set a global value OR a value for the provided step/index.
- istype(*types) bool[source]#
Returns true if this parameter’s top-level type is exactly one of
types.This does not recurse into container types, so
istype('int')isFalsefor a[int]parameter. SeeNodeType.istype()for the accepted checks (scalar names, the'list'/'set'/'tuple'container tokens, and'enum'/'range').
- parse_commandline_arguments(value: str, *keypath: str) Tuple[Tuple[str, ...], str | None, str | None, str][source]#
Parse and set the values provided form the commandline parser.
- set(value, field: str = 'value', step: str | None = None, index: str | int | None = None, clobber: bool = True) bool | List[NodeValue] | NodeValue[source]#
Sets a parameter field.
- Parameters:
Examples
>>> param.set('top') Sets the value to 'top'
- unset(step: str | None = None, index: str | int | None = None) bool[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- class siliconcompiler.schema.parametervalue.NodeListValue(base: NodeValue | FileNodeValue | DirectoryNodeValue)[source]#
Holds the data for a list schema type.
- Parameters:
base (
NodeValue) – base type for this list.
- add(value, field: str = 'value') Tuple[NodeValue | FileNodeValue | DirectoryNodeValue, ...][source]#
Adds the value in a specific field and ensures it has been normalized.
- Returns:
tuple of modified values
- Parameters:
value (any) – value to set
field (str) – field to set
- copy() NodeListValue[source]#
Returns a copy of this value.
- get(field: str | None = 'value')[source]#
Returns the value in the specified field
- Parameters:
field (str) – name of schema field.
- getdict() Dict[source]#
Returns a schema dictionary.
Examples
>>> value.getdict() Returns the complete dictionary for the value
- gettcl() str[source]#
Returns the tcl representation for the value
- Parameters:
field (str) – name of schema field.
- set(value, field: str = 'value') Tuple[NodeValue | FileNodeValue | DirectoryNodeValue, ...][source]#
Sets the value in a specific field and ensures it has been normalized.
- Returns:
tuple of modified values
- Parameters:
value (any) – value to set
field (str) – field to set
- property type#
Returns the type for this value
- property values: List[NodeValue | FileNodeValue | DirectoryNodeValue]#
Returns a copy of the values stored in the list
- class siliconcompiler.schema.parametervalue.NodeSetValue(base: NodeValue | FileNodeValue | DirectoryNodeValue)[source]#
Holds the data for a set schema type.
- Parameters:
base (
NodeValue) – base type for this set.
- add(value, field: str = 'value') Tuple[NodeValue | FileNodeValue | DirectoryNodeValue, ...][source]#
Adds the value in a specific field and ensures it has been normalized.
- Returns:
tuple of modified values
- Parameters:
value (any) – value to set
field (str) – field to set
- copy() NodeSetValue[source]#
Returns a copy of this value.
- get(field: str | None = 'value')[source]#
Returns the value in the specified field
- Parameters:
field (str) – name of schema field.
- getdict() Dict[source]#
Returns a schema dictionary.
Examples
>>> value.getdict() Returns the complete dictionary for the value
- gettcl() str[source]#
Returns the tcl representation for the value
- Parameters:
field (str) – name of schema field.
- property type#
Returns the type for this value
- property values: List[NodeValue | FileNodeValue | DirectoryNodeValue]#
Returns a copy of the values stored in the list
- class siliconcompiler.schema.parametervalue.NodeValue(sctype, value=None)[source]#
Holds the data for a parameter.
- Parameters:
sctype (str) – type for this value
value (any) – default value for this parameter
- add(value, field: str = 'value') NodeValue[source]#
Not valid for this datatype, will raise a ValueError
- classmethod from_dict(manifest: Dict, keypath: Tuple[str, ...], version: Tuple[int, ...] | None, sctype)[source]#
Create a new value based on the provided dictionary.
- get(field: str | None = 'value')[source]#
Returns the value in the specified field
- Parameters:
field (str) – name of schema field.
- getdict() Dict[source]#
Returns a schema dictionary.
Examples
>>> value.getdict() Returns the complete dictionary for the value
- gettcl() str[source]#
Returns the tcl representation for the value
- Parameters:
field (str) – name of schema field.
- set(value, field: str = 'value') NodeValue[source]#
Sets the value in a specific field and ensures it has been normalized.
- Returns:
self
- Parameters:
value (any) – value to set
field (str) – field to set
- sign(person: str, key: str, salt: str | None = None) None[source]#
Generate a signature for this value.
- property type#
Returns the type for this value
- class siliconcompiler.schema.parametervalue.PathNodeValue(type, value: str | Path | None = None, dataroot: str | None = None)[source]#
Bases:
NodeValueHolds the path data for a parameter.
- Parameters:
type (str) – type of path
value (any) – default value for this parameter
- add(value, field: str = 'value') NodeValue[source]#
Not valid for this datatype, will raise a ValueError
- classmethod from_dict(manifest: Dict, keypath: Tuple[str, ...], version: Tuple[int, ...] | None, sctype)[source]#
Create a new value based on the provided dictionary.
- static generate_hashed_path(path: str | Path | None, dataroot: str | None) str | None[source]#
Utility to map file to an unambiguous name based on its path.
The mapping looks like: path/to/file.ext => file_<hash(‘path/to’)>.ext
- get(field: str | None = 'value')[source]#
Returns the value in the specified field
- Parameters:
field (str) – name of schema field.
- get_hashed_filename() str | None[source]#
Utility to map file to an unambiguous name based on its path.
The mapping looks like: path/to/file.ext => file_<hash(‘path/to’)>.ext
- getdict() Dict[source]#
Returns a schema dictionary.
Examples
>>> value.getdict() Returns the complete dictionary for the value
- gettcl() str[source]#
Returns the tcl representation for the value
- Parameters:
field (str) – name of schema field.
- hash(function: str, **kwargs) str | None[source]#
Compute the hash for this path.
Keyword arguments are derived from
resolve_path().- Parameters:
function (str) – name of hashing function to use.
- static hash_directory(dirname: str | Path | None, hashobj=None, hashfunction: str | None = None) str | None[source]#
Compute the hash for this directory.
- Parameters:
dirname (path) – directory to hash
hashobj (hashlib.) – hashing object
hashfunction (str) – name of hashing function to use
- static hash_file(filename: str | Path | None, hashobj=None, hashfunction: str | None = None) str | None[source]#
Compute the hash for this file.
- Parameters:
filename (path) – file to hash
hashobj (hashlib.) – hashing object
hashfunction (str) – name of hashing function to use
- resolve_path(search: List[str] | None = None, collection_dir: str | None = None) str | None[source]#
Resolve the path of this value.
Returns the absolute path if found, otherwise raises a FileNotFoundError.
- Parameters:
search (list of paths) – list of paths to search to check for the path.
collection_dir (path) – path to collection directory.
- set(value, field: str = 'value') PathNodeValue[source]#
Sets the value in a specific field and ensures it has been normalized.
- Returns:
self
- Parameters:
value (any) – value to set
field (str) – field to set
- class siliconcompiler.schema.parametervalue.DirectoryNodeValue(value: str | Path | None = None, dataroot: str | None = None)[source]#
Bases:
PathNodeValueHolds the directory data for a parameter.
- Parameters:
value (any) – default value for this parameter
- add(value, field: str = 'value') NodeValue[source]#
Not valid for this datatype, will raise a ValueError
- classmethod from_dict(manifest: Dict, keypath: Tuple[str, ...], version: Tuple[int, ...] | None, sctype)[source]#
Create a new value based on the provided dictionary.
- static generate_hashed_path(path: str | Path | None, dataroot: str | None) str | None[source]#
Utility to map file to an unambiguous name based on its path.
The mapping looks like: path/to/file.ext => file_<hash(‘path/to’)>.ext
- get(field: str | None = 'value')[source]#
Returns the value in the specified field
- Parameters:
field (str) – name of schema field.
- get_hashed_filename() str | None[source]#
Utility to map file to an unambiguous name based on its path.
The mapping looks like: path/to/file.ext => file_<hash(‘path/to’)>.ext
- getdict() Dict[source]#
Returns a schema dictionary.
Examples
>>> value.getdict() Returns the complete dictionary for the value
- gettcl() str[source]#
Returns the tcl representation for the value
- Parameters:
field (str) – name of schema field.
- hash(function: str, **kwargs) str | None[source]#
Compute the hash for this directory.
Keyword arguments are derived from
resolve_path().- Parameters:
function (str) – name of hashing function to use.
- static hash_directory(dirname: str | Path | None, hashobj=None, hashfunction: str | None = None) str | None[source]#
Compute the hash for this directory.
- Parameters:
dirname (path) – directory to hash
hashobj (hashlib.) – hashing object
hashfunction (str) – name of hashing function to use
- static hash_file(filename: str | Path | None, hashobj=None, hashfunction: str | None = None) str | None[source]#
Compute the hash for this file.
- Parameters:
filename (path) – file to hash
hashobj (hashlib.) – hashing object
hashfunction (str) – name of hashing function to use
- resolve_path(search: List[str] | None = None, collection_dir: str | None = None) str | None[source]#
Resolve the path of this value.
Returns the absolute path if found, otherwise raises a FileNotFoundError.
- Parameters:
search (list of paths) – list of paths to search to check for the path.
collection_dir (path) – path to collection directory.
- set(value, field: str = 'value') PathNodeValue[source]#
Sets the value in a specific field and ensures it has been normalized.
- Returns:
self
- Parameters:
value (any) – value to set
field (str) – field to set
- class siliconcompiler.schema.parametervalue.FileNodeValue(value: str | Path | None = None, dataroot: str | None = None)[source]#
Bases:
PathNodeValueHolds the file data for a parameter.
- Parameters:
value (any) – default value for this parameter
- add(value, field: str = 'value') FileNodeValue[source]#
Adds the value in a specific field and ensures it has been normalized.
- Returns:
self
- Parameters:
value (any) – value to set
field (str) – field to set
- classmethod from_dict(manifest: Dict, keypath: Tuple[str, ...], version: Tuple[int, ...] | None, sctype)[source]#
Create a new value based on the provided dictionary.
- static generate_hashed_path(path: str | Path | None, dataroot: str | None) str | None[source]#
Utility to map file to an unambiguous name based on its path.
The mapping looks like: path/to/file.ext => file_<hash(‘path/to’)>.ext
- get(field: str | None = 'value')[source]#
Returns the value in the specified field
- Parameters:
field (str) – name of schema field.
- get_hashed_filename() str | None[source]#
Utility to map file to an unambiguous name based on its path.
The mapping looks like: path/to/file.ext => file_<hash(‘path/to’)>.ext
- getdict() Dict[source]#
Returns a schema dictionary.
Examples
>>> value.getdict() Returns the complete dictionary for the value
- gettcl() str[source]#
Returns the tcl representation for the value
- Parameters:
field (str) – name of schema field.
- hash(function: str, **kwargs) str | None[source]#
Compute the hash for this file.
Keyword arguments are derived from
resolve_path().- Parameters:
function (str) – name of hashing function to use.
- static hash_directory(dirname: str | Path | None, hashobj=None, hashfunction: str | None = None) str | None[source]#
Compute the hash for this directory.
- Parameters:
dirname (path) – directory to hash
hashobj (hashlib.) – hashing object
hashfunction (str) – name of hashing function to use
- static hash_file(filename: str | Path | None, hashobj=None, hashfunction: str | None = None) str | None[source]#
Compute the hash for this file.
- Parameters:
filename (path) – file to hash
hashobj (hashlib.) – hashing object
hashfunction (str) – name of hashing function to use
- resolve_path(search: List[str] | None = None, collection_dir: str | None = None) str | None[source]#
Resolve the path of this value.
Returns the absolute path if found, otherwise raises a FileNotFoundError.
- Parameters:
search (list of paths) – list of paths to search to check for the path.
collection_dir (path) – path to collection directory.
- set(value, field: str = 'value') FileNodeValue[source]#
Sets the value in a specific field and ensures it has been normalized.
- Returns:
self
- Parameters:
value (any) – value to set
field (str) – field to set
- class siliconcompiler.schema.parametertype.NodeType(sctype)[source]#
Schema type decoding and encoding class.
- Parameters:
sctype (str or
NodeType) – schema type
- static astype(spec: str | type | NodeEnumType | NodeRangeType) str | type | NodeEnumType | NodeRangeType[source]#
Resolve a friendly type token into the object used for type checks by
contains()andistype().This lets callers use plain strings everywhere instead of importing the
NodeEnumType/NodeRangeTypeclasses:'enum'resolves toNodeEnumType'range'resolves toNodeRangeType'list','set','tuple'resolve to the container classes
Scalar type names (
'int','float','str','bool','file','dir') and anything already resolved (a class, or aNodeEnumType/NodeRangeTypeinstance) are returned unchanged.
- static basetype(sctype: str | NodeType | list | set | tuple | NodeEnumType | NodeRangeType) str | None[source]#
Return the underlying scalar base type name of a type, unwrapping any container nesting (list, set, tuple) and range/enum wrappers.
Range types return their numeric base (
'int'/'float').Enum types return
'enum'.Homogeneous containers return their element base (
'[int]'->'int').Heterogeneous tuples (e.g.
'(str,int)') returnNonesince they have no single base type.
- static contains(value: str | NodeType | list | set | tuple | NodeEnumType | NodeRangeType, check: str | type | NodeEnumType | NodeRangeType) bool[source]#
Check if the type contains a specific type.
checkmay be a class (list,tuple,set,NodeEnumType,NodeRangeType) or the equivalent string token accepted byastype()(e.g.'enum','list'), as well as a scalar type name ('int','file', …).
- static istype(sctype: str | NodeType | list | set | tuple | NodeEnumType | NodeRangeType, *types: str | type | NodeEnumType | NodeRangeType) bool[source]#
Check whether the top-level type is exactly one of
types.Unlike
contains(), this does not recurse into container types, soistype('[int]', 'int')isFalsewhileistype('[int]', list)isTrue. This makes it the right check for asking “is this parameter a scalarint” without matching[int]/(int,int).Accepted checks are the scalar type names (
'int','float','str','bool','file','dir'), plus any token accepted byastype()for containers, enums and ranges ('list','set','tuple','enum','range', or the equivalent classes). Range types match their numeric base ('int'/'float') as well as'range'/NodeRangeType.
- class siliconcompiler.schema.parametertype.NodeEnumType(*values)[source]#
Type for schema data type
- property values#
Returns a set of the legal values for this enum.
- class siliconcompiler.schema.parametertype.NodeRangeType(base, *values)[source]#
Numeric range type for schema data values.
- Parameters:
base (str) – numeric base type, either ‘int’ or ‘float’.
*values – one or more range tuples of (min, max). A bound of None indicates an open-ended range on that side (e.g. (0, None) means the value must be >= 0). A fully unbounded (None, None) range is not allowed.
- property base#
Returns the base for this range.
- property values#
Returns a set of the legal values for this range.
- class siliconcompiler.schema.baseschema.LazyLoad(value)[source]#
Controls manifest loading
- FORWARD = 3#
- OFF = 1#
- ON = 2#
- class siliconcompiler.schema.parameter.Scope(value)[source]#
Enum for scope Schema parameters
- GLOBAL = 'global'#
- JOB = 'job'#
- SCRATCH = 'scratch'#
- class siliconcompiler.schema.parameter.PerNode(value)[source]#
Enum for pernode Schema parameters
- NEVER = 'never'#
- OPTIONAL = 'optional'#
- REQUIRED = 'required'#
- class siliconcompiler.schema.DocsSchema[source]#
Bases:
BaseSchemaA base class for customizing documentation generation.
This class provides a hook (make_docs) that can be overridden by subclasses to control how a schema is represented in documentation.
- classmethod make_docs() TSchema | List[TSchema][source]#
Generate the documentation representation for this schema.
By default, this method returns a standard instance of the class itself. Subclasses can override this method to return a modified or different schema instance, or even a list of schemas, to customize how they appear in the generated documentation.
- Returns:
An instance or list of instances of BaseSchema that represents the schema for documentation purposes.
2.8. Supporting Classes#
- class siliconcompiler.schema_support.dependencyschema.DependencySchema[source]#
Bases:
BaseSchemaSchema extension to add
add_dep()capability to a schema section.- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_dep(obj: NamedSchema, clobber: bool = True) bool[source]#
Adds a module to this object.
- Parameters:
obj (
NamedSchema) – Module to add.clobber (bool) – If true will insert the object and overwrite any existing with the same name.
- Returns:
True if object was imported, otherwise false.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_dep(name: str | None = None, hierarchy: bool = True) List[NamedSchema][source]#
Returns all dependencies associated with this object or a specific one if requested.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- has_dep(name: NamedSchema | str) bool[source]#
Checks if a specific dependency is present.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was found, False otherwise.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- remove_dep(name: str | NamedSchema) bool[source]#
Removes a previously registered module.
- Parameters:
name (str) – Name of the module.
- Returns:
True if the module was removed, False if it was not found.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- write_depgraph(filename: str, fontcolor: str = '#000000', background: str = 'transparent', fontsize: str = '14', border: bool = True, landscape: bool = False) None[source]#
Renders and saves the dependency graph to a file.
- Parameters:
Examples
>>> schema.write_depgraph('mydump.png') Renders the object dependency graph and writes the result to a png file.
- class siliconcompiler.schema_support.option.OptionSchema[source]#
Bases:
BaseSchemaSchema for top-level configuration options.
This class defines global and job-specific parameters that control the compiler’s behavior, such as flow control, logging, build settings, and remote execution. It provides getter and setter methods for each parameter.
- add_alias(value: List[Tuple[str, str, str, str]] | Tuple[str, str, str, str], clobber: bool = False)[source]#
Adds or sets fileset aliases.
- add_fileset(value: List[str] | str, clobber: bool = False)[source]#
Adds or sets selected design filesets.
- add_from(value: List[str] | str, clobber: bool = False)[source]#
Adds or sets the starting step(s) for execution.
- add_prune(value: List[Tuple[str, str]] | Tuple[str, str], clobber: bool = False)[source]#
Adds or sets nodes to prune from the flowgraph.
- add_to(value: List[str] | str, clobber: bool = False)[source]#
Adds or sets the ending step(s) for execution.
- get_autoissue() bool[source]#
Gets the autoissue flag.
- Returns:
The current value of the autoissue flag.
- Return type:
- get_breakpoint(step: str | None = None, index: str | None = None) bool[source]#
Checks if a breakpoint is set on a specific step.
- get_builddir() str[source]#
Gets the build directory path.
- Returns:
The path to the build directory.
- Return type:
- get_cachedir() str[source]#
Gets the path to the user cache directory.
- Returns:
The filepath to the cache directory.
- Return type:
- get_clean() bool[source]#
Gets the clean job flag.
- Returns:
True if the previous job should be cleaned up.
- Return type:
- get_continue(step: str | None = None, index: str | None = None) bool[source]#
Gets the continue-on-error flag for a step.
- get_credentials() str[source]#
Gets the path to the user credentials file.
- Returns:
The filepath to the credentials file.
- Return type:
- get_design() str[source]#
Gets the top-level design library name.
- Returns:
The name of the design.
- Return type:
- get_fileset() List[str][source]#
Gets the list of selected design filesets.
- Returns:
A list of fileset names.
- Return type:
List[str]
- get_from() List[str][source]#
Gets the list of starting steps for execution.
- Returns:
A list of step names.
- Return type:
List[str]
- get_hash() bool[source]#
Gets the file hashing flag.
- Returns:
True if file hashing is enabled.
- Return type:
- get_jobincr() bool[source]#
Gets the job name auto-increment flag.
- Returns:
True if job name auto-increment is enabled.
- Return type:
- get_nice(step: str | None = None, index: str | None = None) int[source]#
Gets the tool scheduling priority (nice level).
- get_nodashboard() bool[source]#
Gets the dashboard disable flag.
- Returns:
True if the dashboard is disabled.
- Return type:
- get_nodisplay() bool[source]#
Gets the headless execution (no-display) flag.
- Returns:
True if GUI windows are disabled.
- Return type:
- get_novercheck(step: str | None = None, index: str | None = None) bool[source]#
Gets the version checking disable flag for a step.
- get_optmode(step: str | None = None, index: str | None = None) int[source]#
Gets the optimization mode.
- get_quiet(step: str | None = None, index: str | None = None) bool[source]#
Gets the quiet execution flag for a step.
- get_remote() bool[source]#
Gets the remote processing flag.
- Returns:
True if remote processing is enabled.
- Return type:
- get_timeout(step: str | None = None, index: str | None = None) float[source]#
Gets the timeout value for a step in seconds.
- get_to() List[str][source]#
Gets the list of ending steps for execution.
- Returns:
A list of step names.
- Return type:
List[str]
- get_track(step: str | None = None, index: str | None = None) bool[source]#
Gets the provenance tracking flag for a step.
- property scheduler: SchedulerSchema#
Provides access to the scheduler sub-schema.
- Returns:
The schema object for scheduler settings.
- Return type:
- set(*args, field='value', clobber=True, step=None, index=None)[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_autoissue(value: bool)[source]#
Sets the autoissue flag.
- Parameters:
value (bool) – The desired value for the autoissue flag.
- set_breakpoint(value: bool, step: str | None = None, index: str | None = None)[source]#
Sets a breakpoint on a specific step.
- set_builddir(value: str)[source]#
Sets the build directory path.
- Parameters:
value (str) – The path to the build directory.
- set_cachedir(value: str)[source]#
Sets the path to the user cache directory.
- Parameters:
value (str) – The filepath to the cache directory.
- set_clean(value: bool)[source]#
Sets the clean job flag.
- Parameters:
value (bool) – The value to set for the clean flag.
- set_continue(value: bool, step: str | None = None, index: str | None = None)[source]#
Sets the continue-on-error flag for a step.
- set_credentials(value: str)[source]#
Sets the path to the user credentials file.
- Parameters:
value (str) – The filepath to the credentials file.
- set_design(value: str)[source]#
Sets the top-level design library name.
- Parameters:
value (str) – The name of the design.
- set_flow(value: str)[source]#
Sets the target flow name.
- Parameters:
value (str) – The name of the flow to set.
- set_hash(value: bool)[source]#
Sets the file hashing flag.
- Parameters:
value (bool) – The value to set for the hash flag.
- set_jobincr(value: bool)[source]#
Sets the job name auto-increment flag.
- Parameters:
value (bool) – The value for the job-increment flag.
- set_nice(value: int, step: str | None = None, index: str | None = None)[source]#
Sets the tool scheduling priority (nice level).
- set_nodashboard(value: bool)[source]#
Sets the dashboard disable flag.
- Parameters:
value (bool) – The value for the no-dashboard flag.
- set_nodisplay(value: bool)[source]#
Sets the headless execution (no-display) flag.
- Parameters:
value (bool) – The value to set for the no-display flag.
- set_novercheck(value: bool, step: str | None = None, index: str | None = None)[source]#
Sets the version checking disable flag for a step.
- set_optmode(value: int, step: str | None = None, index: str | None = None)[source]#
Sets the optimization mode.
- set_quiet(value: bool, step: str | None = None, index: str | None = None)[source]#
Sets the quiet execution flag for a step.
- set_remote(value: bool)[source]#
Sets the remote processing flag.
- Parameters:
value (bool) – The value to set for the remote flag.
- set_timeout(value: float, step: str | None = None, index: str | None = None)[source]#
Sets the timeout value for a step in seconds.
- set_track(value: bool, step: str | None = None, index: str | None = None)[source]#
Sets the provenance tracking flag for a step.
- write_defaults() None[source]#
Saves all non-default settings to the configuration file.
This method iterates through all parameters known to the system (via self.allkeys()). It compares the current value of each parameter against its default value.
Any parameter whose current value differs from its default is collected. This list of non-default settings is then serialized as a JSON array to the file specified by default_options_file().
If all parameters are set to their default values, the list will be empty, and no file will be written.
- class siliconcompiler.schema_support.option.SchedulerSchema[source]#
Bases:
BaseSchemaSchema for configuring job scheduler settings.
This class defines all parameters related to the job scheduler, such as the scheduler type, resource constraints (cores, memory), and notification settings. It provides getter and setter methods for each parameter to allow for easy manipulation of the configuration.
- add_msgcontact(value: List[str] | str, step: str | None = None, index: str | None = None, clobber: bool = False)[source]#
Adds or sets the contact list for scheduler event messages.
- Parameters:
value (Union[List[str], str]) – An email address or a list of them.
step (str, optional) – The flowgraph step. Defaults to None.
index (str, optional) – The flowgraph step index. Defaults to None.
clobber (bool, optional) – If True, replaces the existing contact list. If False, appends to it. Defaults to False.
- add_msgevent(value: List[str] | str, step: str | None = None, index: str | None = None, clobber: bool = False)[source]#
Adds or sets the event triggers for sending messages.
- Parameters:
value (Union[List[str], str]) – A single event or a list of events.
step (str, optional) – The flowgraph step. Defaults to None.
index (str, optional) – The flowgraph step index. Defaults to None.
clobber (bool, optional) – If True, replaces existing events. If False, appends to them. Defaults to False.
- add_options(value: List[str] | str, step: str | None = None, index: str | None = None, clobber: bool = False)[source]#
Adds or sets advanced pass-through options for the scheduler.
- Parameters:
value (Union[List[str], str]) – A single option or a list of options.
step (str, optional) – The flowgraph step. Defaults to None.
index (str, optional) – The flowgraph step index. Defaults to None.
clobber (bool, optional) – If True, replaces existing options. If False, appends to them. Defaults to False.
- get_cores(step: str | None = None, index: str | None = None) int[source]#
Gets the number of CPU cores required for the job.
- get_defer(step: str | None = None, index: str | None = None) str[source]#
Gets the deferred start time for the job.
- get_maxnodes() int[source]#
Gets the maximum number of concurrent nodes for a job.
- Returns:
The maximum number of nodes.
- Return type:
- get_maxthreads() int[source]#
Gets the maximum number of threads for each task in a job.
- Returns:
The maximum number of threads.
- Return type:
- get_memory(step: str | None = None, index: str | None = None) int[source]#
Gets the memory required for the job in megabytes.
- get_msgcontact(step: str | None = None, index: str | None = None) List[str][source]#
Gets the contact list for scheduler event messages.
- get_msgevent(step: str | None = None, index: str | None = None) List[str][source]#
Gets the event triggers for sending messages.
- get_name(step: str | None = None, index: str | None = None) str[source]#
Gets the scheduler platform name.
- get_options(step: str | None = None, index: str | None = None) List[str][source]#
Gets the advanced pass-through options for the scheduler.
- get_queue(step: str | None = None, index: str | None = None) str[source]#
Gets the scheduler queue (or partition) for the job.
- set_cores(value: int, step: str | None = None, index: str | None = None)[source]#
Sets the number of CPU cores required for the job.
- set_defer(value: str, step: str | None = None, index: str | None = None)[source]#
Sets the deferred start time for the job.
- set_maxnodes(value: int)[source]#
Sets the maximum number of concurrent nodes for a job.
- Parameters:
value (int) – The maximum number of nodes to set.
- set_maxthreads(value: int)[source]#
Sets the maximum number of threads for each task in a job.
- Parameters:
value (int) – The maximum number of threads to set.
- set_memory(value: int, step: str | None = None, index: str | None = None)[source]#
Sets the memory required for the job in megabytes.
- set_name(value: str, step: str | None = None, index: str | None = None)[source]#
Sets the scheduler platform name.
- class siliconcompiler.schema_support.cmdlineschema.CommandLineSchema[source]#
Class to provide the
create_cmdline()option to a schema object.This class should not be instantiated by itself.
Examples
- class NewSchema(BaseSchema, CommandLineSchema):
creates a new class with the commandline options available
- classmethod create_cmdline(progname: str | None = None, description: str | None = None, switchlist: List[str] | Set[str] | None = None, version: str | None = None, print_banner: bool = True, use_cfg: bool = False, use_sources: bool = True) TCmdSchema[source]#
Creates an SC command line interface.
Exposes parameters in the SC schema as command line switches, simplifying creation of SC apps with a restricted set of schema parameters exposed at the command line. The order of command line switch settings parsed from the command line is as follows:
read_manifest (-cfg), if specified by use_cfg
read commandline inputs
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.
- 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.
version (str) – version of this program.
print_banner (bool) – if True, will print the siliconcompiler banner
use_cfg (bool) – if True, add and parse the -cfg flag
use_sources (bool) – if True, add positional arguments for files
- Returns:
new project object
Examples
>>> schema.create_cmdline(progname='sc-show',switchlist=['-input','-cfg']) Creates a command line interface for 'sc-show' app.
>>> schema.create_cmdline(progname='sc')
- class siliconcompiler.schema_support.pathschema.PathSchemaBase[source]#
Bases:
BaseSchemaSchema extension to add simpler find_files and check_filepaths
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.schema_support.pathschema.PathSchema[source]#
Bases:
PathSchemaBaseSchema extension to add support for path handling with dataroots
- active_dataroot(dataroot: str | None = None)#
Use this context to set the dataroot parameter on files and directory parameters.
- Parameters:
dataroot (str) – name of the dataroot
Example
>>> with schema.active_dataroot("lambdalib"): ... schema.set("file", "top.v") Sets the file to top.v and associates lambdalib as the dataroot.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- Parameters:
filepath (path) – Initial manifest.
cfg (dict) – Initial configuration dictionary.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- get_dataroot(name: str) str[source]#
Returns absolute path to the data directory.
- Raises:
ValueError – is data directory is not found
- Parameters:
name (str) – name of the data directory to find.
- Returns:
Path to the directory root.
Examples
>>> schema.get_dataroot('siliconcompiler') Returns the path to the root of the siliconcompiler data directory.
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_dataroot(name: str = 'root', path: str | None = None, tag: str | None = None, clobber: bool = False) None[source]#
Registers a data source by name, path, and optional version tag.
This method creates a reference to a data directory, which can be a local path, a Git repository, or a remote archive. This allows other parts of the application to refer to this data source by its unique name.
- Parameters:
name (str, optional) – A unique name to identify the data source. Defaults to “root”.
path (str) – The path to the data source. This is required. It can be a local directory, a file path, a git URL, or an archive URL. If a file path is provided, its parent directory is used as the root.
tag (str, optional) – A version identifier for remote sources, such as a git commit hash, branch, or tag. Defaults to None.
clobber (bool, optional) – If True, allows overwriting an existing data source with the same name. If False (default), attempting to overwrite an existing entry will raise a ValueError.
- Raises:
ValueError – If path is not specified.
ValueError – If a data source with the given name already exists and clobber is False.
Examples
>>> # Register a remote git repository at a specific tag >>> schema.set_dataroot('siliconcompiler_data', ... 'git+https://github.com/siliconcompiler/siliconcompiler', ... tag='v1.0.0') >>> >>> # Register a local directory based on the location of a file >>> schema.set_dataroot('file_data', __file__)
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.schema_support.filesetschema.FileSetSchema[source]#
Bases:
NamedSchema,PathSchemaBaseSchema for storing and managing file sets.
This class provides methods to add, retrieve, and manage named groups of files, known as filesets.
- add(*args, field: str = 'value', step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Adds item(s) to a schema parameter list.
Adds item(s) to schema parameter list based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- Parameters:
Examples
>>> schema.add('input', 'rtl', 'verilog', 'hello.v') Adds the file 'hello.v' to the [input,rtl,verilog] key.
- add_define(value: str, clobber: bool = False) List[str][source]#
Adds preprocessor macro definitions to a fileset.
- add_depfileset(dep: str, depfileset: str | None = None)[source]#
Record a reference to an imported dependency’s fileset.
- Parameters:
- add_file(filename: List[Path | str] | Set[Path | str] | Tuple[Path | str, ...] | Path | str, filetype: str | None = None, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds files to a fileset.
Based on the file’s extension, this method can often infer the correct fileset and filetype. For example:
.v -> (source, verilog)
.vhd -> (source, vhdl)
.sdc -> (constraint, sdc)
.lef -> (input, lef)
.def -> (input, def)
etc.
- Parameters:
filename (Path, str, or collection) – File path (Path or str), or a collection (list, tuple, set) of file paths to add.
filetype (str, optional) – Type of the file (e.g., ‘verilog’, ‘sdc’).
clobber (bool, optional) – If True, clears the list before adding the item. Defaults to False.
dataroot (str, optional) – Data directory reference name.
- Raises:
ValueError – If fileset or filetype cannot be inferred from the file extension.
- Returns:
A list of the file paths that were added.
- Return type:
Notes
This method normalizes filename to a string for consistency.
- If filetype is not specified, it is inferred from the
file extension.
- add_idir(value: str, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds include directories to a fileset.
- add_libdir(value: str, clobber: bool = False, dataroot: str | None = None) List[str][source]#
Adds dynamic library directories to a fileset.
- add_undefine(value: str, clobber: bool = False) List[str][source]#
Adds preprocessor macro (un)definitions to a fileset.
- allkeys(*keypath: str, include_default: bool = True) Set[Tuple[str, ...]][source]#
Returns all keypaths in the schema as a set of tuples.
- Arg:
- keypath (list of str): Keypath prefix to search under. The
returned keypaths do not include the prefix.
- check_filepaths(ignore_keys: List[Tuple[str, ...]] | None = None) bool[source]#
Verifies that paths to all files in manifest are valid.
- Parameters:
ignore_keys (list of keypaths) – list of keypaths to ignore while checking
- Returns:
True if all file paths are valid, otherwise False.
- find_files(*keypath: str, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) List[str | None] | str | None[source]#
Returns absolute paths to files or directories based on the keypath provided.
The keypath provided must point to a schema parameter of type file, dir, or lists of either. Otherwise, it will trigger an error.
- Parameters:
missing_ok (bool) – If True, silently return None when files aren’t found. If False, print an error and set the error flag.
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
>>> schema.find_files('input', 'verilog') Returns a list of absolute paths to source files, as specified in the schema.
- classmethod from_manifest(filepath: None | str = None, cfg: None | Dict = None, lazyload: bool = True, name: str | None = None) TSchema[source]#
Create a new schema based on the provided source files.
The two arguments to this method are mutually exclusive.
- get(*keypath: str, field: str | None = 'value', step: str | None = None, index: str | int | None = None)[source]#
Returns a parameter field from the schema.
Returns a schema parameter field based on the keypath provided in the
*keypath. The returned type is consistent with the type field of the parameter. Accessing a non-existent keypath raises a KeyError.- Parameters:
field (str) – Parameter field to fetch, if None will return the
Parameterobject stored, if field is ‘schema’ the schema at this keypath will be returned.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 = schema.get('pdk', 'virtual', 'foundry') Returns the value of [pdk,virtual,foundry].
- getdict(*keypath: str, include_default: bool = True, values_only: bool = False) Dict[source]#
Returns a schema dictionary.
Searches the schema for the keypath provided and returns a complete dictionary.
- Parameters:
- Returns:
A schema dictionary
Examples
>>> pdk = schema.getdict('pdk') Returns the complete dictionary found for the keypath [pdk]
- getkeys(*keypath: str) Tuple[str, ...][source]#
Returns a tuple of schema dictionary keys.
Searches the schema for the keypath provided and returns a list of keys found, excluding the generic ‘default’ key.
- Parameters:
- Returns:
tuple of keys found for the keypath provided.
Examples
>>> keylist = schema.getkeys('pdk') Returns all keys for the [pdk] keypath.
- has_idir() bool[source]#
Returns true if idirs are defined for the fileset
- Returns:
True if the fileset contains directories.
- Return type:
- has_libdir() bool[source]#
Returns true if library directories are defined for the fileset
- Returns:
True if the fileset contains directories.
- Return type:
- hash_files(*keypath: str, update: bool = True, check: bool = True, verbose: bool = True, missing_ok: bool = False, step: str | None = None, index: int | str | None = None) str | None | List[str | None][source]#
Generates hash values for a list of parameter files.
Generates a hash value for each file found in the keypath. If existing hash values are stored, this method will compare hashes and trigger an error if there’s a mismatch. If the update variable is True, the computed hash values are recorded in the ‘filehash’ field of the parameter, following the order dictated by the files within the ‘value’ parameter field.
Files are located using the find_files() function.
The file hash calculation is performed based on the ‘algo’ setting. Supported algorithms include SHA1, SHA224, SHA256, SHA384, SHA512, and MD5.
- Parameters:
*keypath (str) – Keypath to parameter.
update (bool) – If True, the hash values are recorded in the project 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`.
- read_manifest(filepath: str) None[source]#
Reads a manifest from disk and replaces the current data with the data in the file.
- Parameters:
filename (path) – Path to a manifest file to be loaded.
Examples
>>> schema.read_manifest('mychip.json') Loads the file mychip.json into the current Schema object.
- remove(*keypath: str)[source]#
Remove a schema parameter and its subparameters.
- Parameters:
keypath (list) – Parameter keypath to clear.
- set(*args, field: str = 'value', clobber: bool = True, step: str | None = None, index: str | int | None = None) List[NodeValue] | NodeValue | None[source]#
Sets a schema parameter field.
Sets a schema parameter field based on the keypath and value provided in the
*args. New schema entries are automatically created for keypaths that overlap with ‘default’ entries.- 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.
Examples
>>> schema.set('design', 'top') Sets the [design] value to 'top'
- set_name(name: str | None) None[source]#
Set the name of this object
- Raises:
RuntimeError – if called after object name is set.
- Parameters:
name (str) – name for object
- set_topmodule(value: str) str[source]#
Sets the topmodule of a fileset.
Notes
first character must be letter or underscore
remaining characters can be letters, digits, or underscores
- unset(*keypath: str, step: str | None = None, index: str | int | None = None) None[source]#
Unsets a schema parameter.
This method effectively undoes any previous calls to
set()made to the given keypath and step/index. For parameters with required or no per-node values, unsetting a parameter always causes it to revert to its default value, and future calls toset()withclobber=Falsewill 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.
- valid(*keypath: str, default_valid: bool = False, check_complete: bool = False) bool[source]#
Checks validity of a keypath.
Checks the validity of a parameter keypath and returns True if the keypath is valid and False if invalid.
- Parameters:
- Returns:
Boolean indicating validity of keypath.
Examples
>>> check = schema.valid('design') Returns True >>> check = schema.valid('blah') Returns False. >>> check = schema.valid('metric', 'foo', '0', 'tasktime', default_valid=True) Returns True, even if "foo" and "0" aren't in current configuration.
- class siliconcompiler.flowgraph.FlowgraphNodeSchema[source]#
Bases:
BaseSchemaSchema definition for a single node within a flowgraph.
This class defines the parameters that can be set on a per-node basis, such as inputs, weights, goals, and the task to execute.
- add_args(arg: List[str] | str, clobber: bool = False)[source]#
Adds command-line arguments specific to this node.
- add_goal(metric: str, weight: float)[source]#
Sets a goal for a specific metric for this node.
Goals are used to determine if a task run is acceptable.
- add_weight(metric: str, weight: float)[source]#
Sets a weight for a specific metric for this node.
Weights are used in optimization tasks to define the “cost” of a particular metric.
- get_input() List[Tuple[str, str]][source]#
Gets the list of input nodes (dependencies) for this node.
- get_task() str[source]#
Gets the task associated with this node.
- Returns:
The name of the task (e.g., ‘place’).
- Return type:
- get_taskmodule() str[source]#
Gets the fully qualified Python module/class for this node’s task.
- Returns:
The task module string (e.g., ‘siliconcompiler.tools.openroad/Place’).
- Return type:
- get_tool() str[source]#
Gets the tool associated with this node.
- Returns:
The name of the tool (e.g., ‘openroad’).
- Return type:
- class siliconcompiler.flowgraph.RuntimeFlowgraph(base: Flowgraph, args: Tuple[str, str] | None = None, from_steps: Set[str] | List[str] | None = None, to_steps: Set[str] | List[str] | None = None, prune_nodes: Set[Tuple[str, str]] | List[Tuple[str, str]] | None = None)[source]#
Bases:
objectA runtime representation of a flowgraph for a specific execution.
This class creates a “view” of a base Flowgraph that considers runtime options such as the start step (-from), end step (-to), and nodes to exclude (-prune). It computes the precise subgraph of nodes that need to be executed for a given run.
- get_completed_nodes(record: RecordSchema | None = None) List[Tuple[str, str]][source]#
Finds all nodes in this runtime graph that have successfully completed.
- get_entry_nodes() Tuple[Tuple[str, str], ...][source]#
Returns the entry nodes for this runtime graph.
This includes user-defined -from nodes (if they are part of the graph) and any nodes whose inputs are pruned or outside the computed graph.
- get_execution_order() Tuple[Tuple[Tuple[str, str], ...], ...][source]#
Returns the execution order of the nodes in this runtime graph.
- get_exit_nodes() Tuple[Tuple[str, str], ...][source]#
Returns the exit nodes for this runtime graph.
- get_node_inputs(step: str, index: str, record: RecordSchema | None = None) List[Tuple[str, str]][source]#
Gets the inputs for a specific node in the runtime graph.
If a record object is provided, this method will traverse through any input nodes that were SKIPPED to find the true, non-skipped inputs.
- get_nodes() Tuple[Tuple[str, str], ...][source]#
Returns the nodes that are part of this runtime graph.
- get_nodes_starting_at(step: str, index: str | int) Tuple[Tuple[str, str], ...][source]#
Returns all nodes reachable from a given starting node in this runtime graph.
- static validate(flow: Flowgraph, from_steps: Set[str] | List[str] | None = None, to_steps: Set[str] | List[str] | None = None, prune_nodes: Set[Tuple[str, str]] | List[Tuple[str, str]] | None = None, logger: Logger | None = None) bool[source]#
Validates runtime options against a flowgraph.
Checks for undefined steps and ensures that pruning does not break the graph by removing all entry/exit points or creating disjoint paths.
- Parameters:
flow (Flowgraph) – The flowgraph to validate against.
from_steps (list[str], optional) – List of start steps. Defaults to None.
to_steps (list[str], optional) – List of end steps. Defaults to None.
prune_nodes (list[tuple(str,str)], optional) – List of nodes to prune. Defaults to None.
logger (logging.Logger, optional) – Logger for error reporting. Defaults to None.
- Returns:
True if the runtime configuration is valid, False otherwise.
- Return type:
- class siliconcompiler.tool.TaskError[source]#
Bases:
ExceptionError indicating that task execution cannot continue and should be terminated.
- add_note()#
Exception.add_note(note) – add a note to the exception
- with_traceback()#
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class siliconcompiler.tool.TaskTimeout(*args, timeout=None, **kwargs)[source]#
Bases:
TaskErrorError indicating a timeout has occurred during task execution.
- Parameters:
timeout (float) – The execution time in seconds at which the timeout occurred.
- add_note()#
Exception.add_note(note) – add a note to the exception
- with_traceback()#
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class siliconcompiler.tool.TaskExecutableNotFound[source]#
Bases:
TaskErrorError indicating that the required tool executable could not be found.
- add_note()#
Exception.add_note(note) – add a note to the exception
- with_traceback()#
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class siliconcompiler.schema_support.packageschema.PackageSchema[source]#
Bases:
PathSchemaA class for managing package-related schema data.
- add_author(identifier: str, name: str = None, email: str = None, organization: str = None)[source]#
Add or update author information for the package.
- add_license(name: str)[source]#
Add a license name to the package.
- Parameters:
name (str) – The name of the license.
- get_author(identifier: str = None)[source]#
Returns the author information for a specific author or all authors.
- Parameters:
identifier (str) – A unique identifier for the author, if None returns all
- get_description() str[source]#
Get the description of the package.
- Returns:
The description string.
- Return type:
- get_doc(type: str = None) List[str] | Dict[str, List[str]][source]#
Get documentation files for the package.
- Parameters:
type (str, optional) – The type of documentation to retrieve. If None, returns all documentation organized by type. Defaults to None.
- get_license() List[str][source]#
Get a list of license names associated with the package.
- Returns:
A list of license names.
- Return type:
List[str]
- get_licensefile() List[str][source]#
Get a list of license file paths associated with the package.
- Returns:
A list of file paths.
- Return type:
List[str]
- get_version() str[source]#
Get the version of the package.
- Returns:
The version string.
- Return type:
- set_description(desc: str)[source]#
Set the description of the package.
- Parameters:
desc (str) – The description string.
- class siliconcompiler.checklist.Criteria(name: str | None = None)[source]#
Bases:
NamedSchemaSchema for defining a single checklist item’s criteria.
This class holds all the configurable parameters for a specific checklist item, such as its description, requirements, validation criteria, and associated reports or waivers.
- add_criteria(value: List[str] | str, clobber: bool = False) None[source]#
Adds one or more signoff criteria to the checklist item.
- add_rationale(value: List[str] | str, clobber: bool = False) None[source]#
Adds one or more rationale codes or descriptions to the checklist item.
- add_report(value: List[str] | str, clobber: bool = False) None[source]#
Adds one or more report filepaths to the checklist item.
- add_task(value: List[Tuple[str, str, str]] | Tuple[str, str, str], clobber: bool = False) None[source]#
Adds one or more flowgraph tasks to verify the checklist item.
- Parameters:
value (Union[List[Tuple], Tuple]) – A single task tuple or a list of tuples.
clobber (bool) – If True, replaces the existing list with the new value. If False, appends to the existing list. Defaults to False.
- add_waiver(metric: str, value: List[Path | str] | Path | str, clobber: bool = False) None[source]#
Adds one or more waiver reports for a specific metric.
- get_criteria() List[str][source]#
Retrieves the list of signoff criteria.
Each criterion is a string in the format ‘metric op value’ (e.g., ‘errors == 0’).
- Returns:
A list of criteria strings.
- Return type:
List[str]
- get_dataformat() str | None[source]#
Retrieves the description of acceptable data file formats.
- Returns:
A free-text description of the data format, or None if not set.
- Return type:
Optional[str]
- get_description() str | None[source]#
Retrieves the short, one-line description of the checklist item.
- Returns:
The description string, or None if not set.
- Return type:
Optional[str]
- get_ok() bool[source]#
Retrieves the manual ‘ok’ status of the checklist item.
A value of True indicates a human has reviewed and approved the item.
- Returns:
The boolean status, or False if not set.
- Return type:
- get_rationale() List[str][source]#
Retrieves the rationale codes or descriptions for the checklist item.
- Returns:
A list of rationale strings.
- Return type:
List[str]
- get_report() List[str][source]#
Retrieves the list of report filepaths documenting validation.
- Returns:
A list of filepaths.
- Return type:
List[str]
- get_requirement() str | None[source]#
Retrieves the detailed requirement description for the checklist item.
- Returns:
The requirement description, which can be a multi-line string, or None if not set.
- Return type:
Optional[str]
- get_task() List[Tuple[str, str, str]][source]#
Retrieves the flowgraph tasks used to verify this checklist item.
Each task is represented as a tuple of (job, step, index).
- get_waiver(metric: str) List[Path | str][source]#
Retrieves waiver report files for a specific metric.
- set_dataformat(value: str | None)[source]#
Sets the description of acceptable data file formats for signoff.
- Parameters:
value (Optional[str]) – A free-text description of the data format.
- set_description(value: str | None) None[source]#
Sets the short, one-line description for the checklist item.
- Parameters:
value (Optional[str]) – The description string to set.
- class siliconcompiler.library.ToolLibrarySchema(name: str | None = None)[source]#
Bases:
DesignA class for managing tool-related library schemas.
- class siliconcompiler.schema_support.record.RecordSchema[source]#
Bases:
BaseSchemaA class for managing run record data.
- clear(step: str, index: str | int, keep: List[str] | None = None) None[source]#
Clear all saved metrics for a given step and index.
- static get_cloud_information() Dict[str, str | None][source]#
Return information about the cloud environment.
- Returns:
{ “region”: str }
- get_earliest_time(type: RecordTime) float | None[source]#
Returns the earliest recorded time.
- Parameters:
type (
RecordTime) – type of time to record
- static get_ip_information() Dict[str, str | None][source]#
Return information about the ip and mac address of this machine.
- Returns:
{ “ip”: str, “mac”: str }
- get_latest_time(type: RecordTime) float | None[source]#
Returns the last recorded time.
- Parameters:
type (
RecordTime) – type of time to record
- static get_machine_information() Dict[str, str | None][source]#
Return information about the machine.
- Returns:
{ “name”: str, “system”: str, “distro”: str, “osversion”: str, “kernelversion”: str, “arch”: str }
- get_recorded_time(step: str, index: str | int, type: RecordTime) float | None[source]#
Returns the time recorded for a given record, or None if nothing is recorded.
- Parameters:
step (str) – Step name to associate.
type (
RecordTime) – type of time to record
- static get_user_information() Dict[str, str | None][source]#
Return information about the user.
Return format: {“username”: str}
- record_python_packages() None[source]#
Record the python packages currently available in the environment.
- record_time(step: str, index: str | int, type: RecordTime) float[source]#
Record the time of the record.
- Returns:
time recorded.
- Parameters:
step (str) – Step name to associate.
type (
RecordTime) – type of time to record
- record_tool(step: str, index: str | int, info: str | List[str] | int, type: RecordTool) None[source]#
Record information about the tool used during this record.
- Parameters:
step (str) – Step name to associate.
info (any) – Information to record.
type (
RecordTool) – type of tool information being recorded
- record_userinformation(step: str, index: str | int) None[source]#
Records information about the current machine and user. Uses information from
get_machine_information(),get_user_information(),get_cloud_information(), andget_ip_information().
- class siliconcompiler.schema_support.record.RecordTime(value)[source]#
Enumeration of time record types.
- END = 'endtime'#
- START = 'starttime'#
- class siliconcompiler.schema_support.record.RecordTool(value)[source]#
Enumeration of tool record types.
- ARGS = 'toolargs'#
- EXITCODE = 'toolexitcode'#
- PATH = 'toolpath'#
- VERSION = 'toolversion'#
- class siliconcompiler.schema_support.metric.MetricSchema[source]#
Bases:
BaseSchemaSchema for storing and accessing metrics collected during a run.
This class provides a structured way to define, record, and report various metrics such as runtime, memory usage, and design quality indicators for each step of a compilation flow.
- clear(step: str, index: int | str) None[source]#
Clears all saved metrics for a given step and index.
- get_formatted_metric(metric: str, step: str, index: int | str) str[source]#
Retrieves and formats a metric for display.
Handles special formatting for memory (binary units), time, and adds SI suffixes for other float values.
- record(step: str, index: str | int, metric: str, value: float | int, unit: str | None = None)[source]#
Records a metric value for a specific step and index.
This method handles unit conversion if the metric is defined with a unit in the schema.
- Parameters:
- Returns:
The recorded value after any unit conversion.
- record_tasktime(step: str, index: str | int, record: RecordSchema)[source]#
Records the task time for a given node based on start and end times.
- Parameters:
step (str) – The step of the node.
record (RecordSchema) – The record schema containing timing data.
- Returns:
True if the time was successfully recorded, False otherwise.
- Return type:
- record_totaltime(step: str, index: str | int, flow: Flowgraph, record: RecordSchema)[source]#
Records the cumulative total time up to the end of a given node.
This method calculates the total wall-clock time by summing the durations of all previously executed parallel tasks.
- summary(headers: List[Tuple[str, str | None]], nodes: List[Tuple[str, str]] | None = None, column_width: int = 15, fd: TextIO | None = None, max_line_width: int | None = None) None[source]#
Prints a formatted summary of metrics to a file descriptor.
- Parameters:
headers (List[Tuple[str, str]]) – A list of (title, value) tuples to print in the header section of the summary.
nodes (List[Tuple[str, str]], optional) – A list of (step, index) tuples to include. Defaults to all nodes.
column_width (int, optional) – The width for each column in the table. Defaults to 15.
fd (TextIO, optional) – The file descriptor to write to. Defaults to sys.stdout.
max_line_width (int, optional) – The maximum line width for the summary table. Defaults to the terminal width or 4 times the column width, whichever is larger.
- summary_table(nodes: List[Tuple[str, str]] | None = None, column_width: int = 15, formatted: bool = True, trim_empty_metrics: bool = True) DataFrame[source]#
Generates a summary of metrics as a pandas DataFrame.
- Parameters:
nodes (List[Tuple[str, str]], optional) – A list of (step, index) tuples to include in the summary. If None, all nodes with metrics are included. Defaults to None.
column_width (int, optional) – The width for each column. Defaults to 15.
formatted (bool, optional) – If True, metric values are formatted for human readability. Defaults to True.
trim_empty_metrics (bool, optional) – If True, metrics that have no value for any of the specified nodes are excluded. Defaults to True.
- Returns:
A DataFrame containing the metric summary.
- Return type:
pandas.DataFrame
- class siliconcompiler.metrics.asic.ASICMetricsSchema[source]#
Bases:
MetricSchema
- class siliconcompiler.metrics.fpga.FPGAMetricsSchema[source]#
Bases:
MetricSchema
- class siliconcompiler.constraints.timing_mode.TimingModeSchema(name: str | None = None)[source]#
Bases:
NamedSchemaRepresents a single timing mode for design constraints.
This class encapsulates the SDC filesets used for a specific timing mode.
- add_sdcfileset(design: Design | str, fileset: str, clobber: bool = False, step: str | None = None, index: int | str | None = None)[source]#
Adds an SDC fileset for a given design.
- Parameters:
design (
Designor str) – The design object or the name of the design to associate the fileset with.fileset (str) – The name of the SDC fileset to add.
clobber (bool) – If True, existing SDC filesets for the design at the specified step/index will be overwritten. If False (default), the SDC fileset will be added.
step (str, optional) – step name.
index (str, optional) – index name.
- Raises:
TypeError – If design is not a Design object or a string, or if fileset is not a string.
2.9. Execution and settings#
- class siliconcompiler.scheduler.schedulernode.SchedulerNode(project: Project, step: str, index: str, replay: bool = False)[source]#
Bases:
objectA class for managing and executing a single node in the compilation flow graph.
This class encapsulates the state and logic required to run a specific step and index, including setting up directories, handling file I/O, executing the associated tool, and recording results.
- archive(tar: TarFile, include: List[str] | None = None, verbose: bool = False) None[source]#
Archives the node’s results into a tar file.
By default, it archives the ‘reports’ and ‘outputs’ directories and all log files. The include argument allows for custom file selection using glob patterns.
- Parameters:
tar (tarfile.TarFile) – The tarfile object to add files to.
include (List[str], optional) – A list of glob patterns to specify which files to include in the archive. Defaults to None.
verbose (bool, optional) – If True, prints archiving status messages. Defaults to None.
- check_files_changed(previous_run: SchedulerNode, previous_time: float, keys: Set[Tuple[str, ...]]) None[source]#
Checks if any specified file-based parameters have changed.
This check can be based on file hashes (if enabled) or timestamps.
- Parameters:
previous_run (SchedulerNode) – The node object from a previous run.
previous_time (float) – The timestamp of the previous run’s manifest.
keys (set of tuples) – A set of file/dir keypaths to check.
- Returns:
True if any file has changed, False otherwise.
- Return type:
- check_logfile() None[source]#
Parses the tool execution log file for patterns.
This method reads the tool’s log file (e.g., ‘synthesis.log’) and uses regular expressions defined in the schema to find and count errors, warnings, and other specified metrics. The findings are recorded in the schema and printed to the console.
- check_previous_run_status(previous_run: SchedulerNode) None[source]#
Determine whether a prior run is compatible and completed successfully for use as an incremental build starting point.
Performs compatibility checks (flow name, tool/task identity, completion status, and input-node set) against the provided previous run.
- Parameters:
previous_run (SchedulerNode) – Node object loaded from a previous run’s manifest to compare against.
- Returns:
True if the previous run completed and is compatible, False otherwise.
- Raises:
SchedulerFlowReset – If the flow name differs and a full reset is required.
- check_values_changed(previous_run: SchedulerNode, keys: Set[Tuple[str, ...]]) None[source]#
Checks if any specified schema parameter values have changed.
- Parameters:
previous_run (SchedulerNode) – The node object from a previous run.
keys (set of tuples) – A set of keypaths to check for changes.
- Returns:
True if any value has changed, False otherwise.
- Return type:
- check_version(version: str | None = None, workdir: str | None = None) Tuple[str | None, bool][source]#
Checks the version of the tool for this task.
Compares a version string against the tool’s requirements. This check is performed within the task’s specific runtime environment.
If no version is provided, this method will attempt to get the version from the task itself. The check can be skipped if the project option ‘novercheck’ is set.
- Parameters:
version – The version string to check. If None, the task’s configured version is fetched and used.
workdir – The working directory to use for the version check. If None, the current working directory is used.
- Returns:
version_str (Optional[str]): The version string that was evaluated.
check_passed (bool): True if the version is compatible or if the check was skipped, False otherwise.
- Return type:
A tuple (version_str, check_passed)
- copy_from(source: str) None[source]#
Imports the results of this node from a different job run.
This method copies the entire working directory of a node from a specified source job into the current job’s working directory. It is used for resuming or branching from a previous run.
- Parameters:
source (str) – The jobname of the source run to copy from.
- execute() None[source]#
Handles the core tool execution logic.
This method runs the pre-processing, execution, and post-processing steps for the node’s task. It manages the tool’s environment, checks for return codes, and handles log file parsing and error reporting.
- get_check_changed_keys() Tuple[Set[Tuple[str, ...]], Set[Tuple[str, ...]]][source]#
Gathers all schema keys that could trigger a re-run if changed.
This includes tool options, scripts, and required inputs specified in the task’s schema.
- get_exe_path() str | None[source]#
Gets the path to the requested executable for this task.
This method retrieves the executable path from the underlying task object. It ensures that the task’s specific runtime environment variables are set before making the call.
- Returns:
The file path to the executable, or None if not found.
- Return type:
Optional[str]
- get_log(type: str = 'exe') str[source]#
Gets the path to a specific log file for this node.
- Parameters:
type (str) – The type of log file to retrieve (‘exe’ or ‘sc’).
- Returns:
The absolute path to the log file.
- Return type:
- Raises:
ValueError – If an unknown log type is requested.
- get_manifest(input: bool = False) str[source]#
Gets the path to the input or output manifest file for this node.
- get_required_keys() Set[Tuple[str, ...]][source]#
This function walks through the ‘require’ keys and returns the keys.
- get_required_path_keys() Set[Tuple[str, ...]][source]#
This function walks through the ‘require’ keys and returns the keys that are of type path (file/dir).
- halt(msg: str | None = None, errmsg: str | None = None) None[source]#
Stops the node’s execution due to an error.
This method logs an error message, sets the node’s status to ERROR, writes the final manifest, and exits the process.
- property project_cwd: str#
The original current working directory where the process was launched.
- Type:
- property replay_script: str#
The path to the shell script for replaying this node’s execution.
- Type:
- requires_run() None[source]#
Determines if the node needs to be re-run.
This method performs a series of checks against the results of a previous run (if one exists). It checks for changes in run status, configuration parameters, and input files to decide if the node’s task can be skipped.
- Returns:
True if a re-run is required, False otherwise.
- Return type:
- run() None[source]#
Executes the full lifecycle for this node.
This method orchestrates the entire process of running a node: 1. Initializes logging and records metadata. 2. Sets up the working directory. 3. Determines and links inputs from previous nodes. 4. Writes the pre-execution manifest. 5. Validates that all inputs and parameters are ready. 6. Calls execute() to run the tool. 7. Stops journaling and returns to the original directory.
Note: Since this method may run in its own process with a separate address space, any changes made to the schema are communicated through reading/writing the project manifest to the filesystem.
- runtime()#
A context manager to temporarily switch the node’s active task.
This is used to ensure that API calls within a specific context are directed to the correct task’s schema.
- set_queue(pipe, queue) None[source]#
Configures the multiprocessing queue and pipe for inter-process communication.
This is primarily used for logging from a child process back to the parent.
- Parameters:
pipe – The pipe for sending data back to the parent process.
queue – The multiprocessing.Queue for handling log records.
- setup() bool[source]#
Runs the setup() method for the node’s assigned task.
This method prepares the task for execution. If the task’s setup() raises a TaskSkip exception, the node is marked as SKIPPED.
- setup_input_directory() None[source]#
Prepares the ‘inputs/’ directory for the node’s execution.
This method gathers output files from all preceding nodes in the flowgraph and links or copies them into the current node’s ‘inputs/’ directory. It also handles file renaming as specified by the task.
- switch_node(step: str, index: str) SchedulerNode[source]#
Creates a new SchedulerNode for a different step/index.
This allows for context switching to inspect or interact with other nodes within the same project context.
- Parameters:
- Returns:
A new SchedulerNode instance for the specified step and index.
- Return type:
- validate() bool[source]#
Performs pre-run validation checks.
This method ensures that all expected input files exist in the ‘inputs/’ directory and that all required schema parameters have been set and can be resolved correctly before the task is executed.
- Returns:
True if validation passes, False otherwise.
- Return type:
- class siliconcompiler.scheduler.slurm.SlurmSchedulerNode(project, step, index, replay=False)[source]#
Bases:
SchedulerNodeA SchedulerNode implementation for running tasks on a Slurm cluster.
This class extends the base SchedulerNode to handle the specifics of submitting a compilation step as a job to a Slurm workload manager. It prepares a run script, a manifest, and uses the ‘srun’ command to execute the step on a compute node.
- static get_configuration_directory(project)[source]#
Gets the directory for storing Slurm-related configuration files.
- static get_runtime_file_name(jobhash, step, index, ext)[source]#
Generates a standardized filename for runtime files.
- static get_slurm_partition()[source]#
Determines a default Slurm partition by querying the cluster.
- Returns:
The name of the first available Slurm partition.
- Return type:
- Raises:
RuntimeError – If the ‘sinfo’ command fails.
- class siliconcompiler.utils.settings.SettingsManager(filepath: str, logger: Logger, timeout: float = 1.0, system_filepath: str | None = None)[source]#
A class to manage user settings stored in a JSON file. Supports categories, robust error handling for malformed files, and simple get/set operations.
An optional read-only, administrator-managed system settings file can be layered underneath the user file. System settings act as defaults that the user may override, except for values the system marks with system priority, which take precedence over the user’s own value. This provides both soft defaults and administrator-enforced values from a single file (see
system_filepath).In the system file, a value is given system priority by co-locating a flag with it. Instead of a bare value, the setting is written as an object with a
"system_priority"flag (and, optionally, a"value"):{ "record": { "region": {"value": "us-east-1", "system_priority": true} }, "scheduler-slurm": { "sharedpaths": ["/nfs/tools"] } }
Here
regionis a system-priority value that the user cannot override whilesharedpathsis a plain, overridable default. The priority flag is only interpreted in the system file; a value written this way in a user file is treated as an ordinary (dictionary) value, so existing user files are unaffected.- delete(category: str, key: str | None = None)[source]#
Remove a user setting.
System-priority settings are administrator-managed and cannot be removed; such requests are ignored with a warning. Note that deletion only affects the user layer; system defaults remain in effect.
- get(category: str, key: str, default=None)[source]#
Retrieve a setting.
Resolution order:
If the key has system priority, the system value is returned (or
defaultif the system file does not define it); the user value is ignored.Otherwise, the user value is returned if present.
Otherwise, the (overridable) system default is returned if present.
Otherwise,
defaultis returned.
- get_category(category: str)[source]#
Retrieve all settings for a specific category, merging system defaults with user overrides.
System values provide the baseline, user values override them, and system-priority keys are forced back to the system value (or removed if the system file does not define them). Returns an empty dict if the category exists in neither layer.
2.10. Inheritance#
