openlane.common API

Common Utilities Module

A number of common utility functions and classes used throughout the codebase.

class openlane.common.TclUtils

Bases: object

A collection of useful Tcl utilities.

static escape(s: str) str
Returns:

If the string can be parsed by Tcl as a single token, the string is returned verbatim.

Otherwise, the string is returned in double quotes, with any unsafe characters escaped with a backslash.

Parameters:

s (str)

Return type:

str

static join(ss: Iterable[str]) str
Parameters:

ss (Iterable[str]) – Input list

Returns:

The input list converted to a Tcl-compatible list where each element is either a single token or double-quoted (i.e. interpreted by Tcl as a single element.)

Return type:

str

openlane.common.parse_metric_modifiers(metric_name: str) Tuple[str, Mapping[str, str]]

Parses a metric name into a base and modifiers as specified in the METRICS2.1 naming convention.

Parameters:

metric_name (str) – The name of the metric as generated by a utility.

Returns:

A tuple of the base part as a string, then the modifiers as a key-value mapping.

Return type:

Tuple[str, Mapping[str, str]]

openlane.common.aggregate_metrics(input: Mapping[str, Any], aggregator_by_metric: Mapping[str, Tuple[int | float | Decimal, Callable[[Iterable[int | float | Decimal]], int | float | Decimal]] | Metric] | None = None) Dict[str, Any]

Takes a set of metrics generated according to the METRICS2.1 naming convention.

Parameters:
  • input (Mapping[str, Any]) – A mapping of strings to values of metrics.

  • aggregator_by_metric (Mapping[str, Tuple[int | float | Decimal, Callable[[Iterable[int | float | Decimal]], int | float | Decimal]] | Metric] | None) – A mapping of metric names to either: - A tuple of the initial accumulator and reducer to aggregate the values from all modifier metrics - A Metric class

Returns:

A tuple of the base part as a string, then the modifiers as a key-value mapping.

Return type:

Dict[str, Any]

class openlane.common.GenericDictEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

A JSON encoder for GenericDict objects. Also handles some types not necessarily handled by the default JSON encoder, i.e., UserString, os.PathLike, Decimals, etcetera.

It is recommended to use GenericDict.to_json() unless you know what you’re doing.

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
class openlane.common.GenericDict(copying: Mapping[KT, VT] | None = None, /, overrides: Mapping[KT, VT] | None = None)

Bases: Mapping[KT, VT]

A dictionary with generic keys and values that is compatible with Python 3.8.

Parameters:
  • copying (Mapping[KT, VT] | None) – A base Mapping object to copy values from.

  • overrides (Mapping[KT, VT] | None) – Another mapping object to override the value from copying with.

pop(key: KT, /) VT
Parameters:

key (KT) – The key to pop the value for.

Returns:

The value for key. Raises IndexError if the key does not exist. The key/value pair is then deleted from the dictionary.

Return type:

VT

copy() T

Convenience replacement for object.__class__(object), which would create a copy of the GenericDict object.

Returns:

The copy

Parameters:

self (T)

Return type:

T

to_raw_dict() dict
Returns:

A copy of the underlying Python built-in dict for this class.

Return type:

dict

get_encoder() Type[GenericDictEncoder]
Returns:

A JSON encoder handling GenericDict objects.

Return type:

Type[GenericDictEncoder]

keys()
Returns:

A set-like object providing a view of the keys of the GenericDict object.

values()
Returns:

A set-like object providing a view of the values of the GenericDict object.

items() ItemsView[KT, VT]
Returns:

A set-like object providing a view of the GenericDict object as (key, value) tuples.

Return type:

ItemsView[KT, VT]

dumps(**kwargs) str
Parameters:

kwargs – Passed to json.dumps.

Returns:

A JSON string representing the the GenericDict object.

Return type:

str

check(key: KT, /) Tuple[KT | None, VT | None]

Checks if a key exists and returns a tuple in the form (key, value).

Parameters:

key (KT) – The key in question

Returns:

If the key does not exist, the value of key will be None and so will value. If the key exists, key will be the key being checked for existence and value will be the value assigned to said key in the GenericDict object.

Do note None is a valid value for some keys, so simply checking if the second element is not None is insufficient to check whether a key exists.

Return type:

Tuple[KT | None, VT | None]

update(incoming: Mapping[KT, VT])

A convenience function to update multiple values in the GenericDict object at the same time. :param incoming: The values to update

Parameters:

incoming (Mapping[KT, VT])

update_reorder(incoming: Mapping[KT, VT])

A convenience function to update multiple values in the GenericDict object at the same time. Pre-existing keys are deleted first so the values in incoming are emplaced at the end of the dictionary.

Parameters:

incoming (Mapping[KT, VT]) – The values to update

class openlane.common.GenericImmutableDict(copying: Mapping[KT, VT] | None = None, /, *args, **kwargs)

Bases: GenericDict[KT, VT]

Parameters:

copying (Mapping[KT, VT] | None)

openlane.common.copy_recursive(input, translator: ~typing.Callable = <function idem>)

Copies any arbitrarily-deep nested structure of Mappings and/or Sequences.

Parameters:
  • input – The input nested structure

  • translator (Callable) –

    Before an object is appended, this function will be called to process the value.

    By default, idem() is called.

Returns:

The copy.

All sequences will become built-in list(s) and all mappings will become built-in dict(s).

openlane.common.idem(obj: T, *args, **kwargs) T
Returns:

the parameter obj unchanged. Useful for some lambdas.

Parameters:

obj (T)

Return type:

T

openlane.common.get_openlane_root() str

Returns the root OpenLane folder, i.e., the folder containing the __init__.py.

Return type:

str

openlane.common.get_opdks_rev() str

Gets the Open_PDKs revision confirmed compatible with this version of OpenLane.

Return type:

str

openlane.common.slugify(value: str, lower: bool = False) str
Parameters:
  • value (str) – Input string

  • lower (bool)

Returns:

The input string converted to lower case, with all characters except alphanumerics, underscores and hyphens removed, and spaces and dots converted into hyphens.

Leading and trailing whitespace is stripped.

Return type:

str

openlane.common.protected(method)

A decorator to indicate protected methods.

It dynamically adds a statement to the effect in the docstring as well as setting an attribute, protected, to True, but has no other effects.

Parameters:

f – Method to mark as protected

openlane.common.final(f)

A decorator to indicate final methods and final classes.

Use this decorator to indicate to type checkers that the decorated method cannot be overridden, and decorated class cannot be subclassed. For example:

class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # Error reported by type checker
          ...

@final
class Leaf:
    ...
class Other(Leaf):  # Error reported by type checker
    ...

There is no runtime checking of these properties.

openlane.common.mkdirp(path: str | PathLike)

Attempts to create a directory and all of its parents.

Does not fail if the directory already exists, however, it does fail if it is unable to create any of the components and/or if the path already exists as a file.

Parameters:

path (str | PathLike) – A filesystem path for the directory

class openlane.common.zip_first(a: Iterable, b: Iterable, fillvalue: Any)

Bases: object

Works like zip_longest if |a| > |b| and zip if |a| <= |b|.

Parameters:
  • a (Iterable)

  • b (Iterable)

  • fillvalue (Any)

openlane.common.format_elapsed_time(elapsed_seconds: SupportsFloat) str
Parameters:

elapsed_seconds (SupportsFloat) – Total time elapsed in seconds

Returns:

A string in the format {hours}:{minutes}:{seconds}:{milliseconds}

Return type:

str

class openlane.common.Filter(filters: Iterable[str])

Bases: object

Encapsulates commonly used wildcard-based filtering functions into an object.

Parameters:

filters (Iterable[str]) –

A list of a wildcards supporting the fnmatch spec.

The wildcards will be split into an “allow” and “deny” list based on whether the filter is prefixed with a !.

get_matching_wildcards(input: str) Generator[str, Any, None]
Parameters:

input (str) – An input to match wildcards against.

Returns:

An iterable object for all wildcards in the allow list accepting input, and all wildcards in the deny list rejecting input.

Return type:

Generator[str, Any, None]

match(input: str) bool
Parameters:

input (str) – An input string to either accept or reject

Returns:

A boolean indicating whether the input: * Has matched at least one wildcard in the allow list * Has matched exactly 0 inputs in the deny list

Return type:

bool

filter(inputs: Iterable[str]) Generator[str, Any, None]
Parameters:

inputs (Iterable[str]) – A series of inputs to filter according to the wildcards.

Returns:

An iterable object of any values in inputs that: * Have matched at least one wildcard in the allow list * Have matched exactly 0 inputs in the deny list

Return type:

Generator[str, Any, None]

openlane.common.get_latest_file(in_path: str | PathLike, filename: str) Path | None
Parameters:
  • in_path (str | PathLike) – A directory to search in

  • filename (str) – The final filename

Returns:

The latest file matching the parameters, by modification time

Return type:

Path | None

openlane.common.process_list_file(from_file: str | PathLike) List[str]

Convenience function to process text files in a .gitignore-style format, i.e., those where the lines may be:

  • A list element

  • A comment prefixed with #

  • Blank

Parameters:

from_file (str | PathLike) – The input text file.

Returns:

A list of the strings listed in the file, ignoring lines prefixed with a # and empty lines.

Return type:

List[str]

class openlane.common.Path(seq)

Bases: UserString, PathLike

A Path type for OpenLane configuration variables.

Basically just a string.

exists() bool

A convenience method calling os.path.exists()

Return type:

bool

validate(message_on_err: str = '')

Raises an error if the path does not exist.

Parameters:

message_on_err (str)

class openlane.common.ScopedFile(*, contents='')

Bases: Path

Creates a temporary file that remains valid while this variable is in scope, and is deleted upon deconstruction.

The object itself is a string pointing to that file path.

Parameters:

contents – The contents of the temporary file to create.

class openlane.common.Toolbox(tmp_dir: str)

Bases: object

An assisting object shared by a Flow and all its constituent Steps.

The toolbox may create artifacts that are cached to avoid constant re-creation between steps.

Parameters:

tmp_dir (str)

aggregate_metrics(input: Dict[str, Any], aggregator_by_metric: Dict[str, Tuple[Any, Callable[[Iterable], Any]]]) Dict[str, Any]

Deprecated since version 2.0.0b1: Use ‘aggregate_metrics’ from ‘openlane.common’

Parameters:
  • input (Dict[str, Any])

  • aggregator_by_metric (Dict[str, Tuple[Any, Callable[[Iterable], Any]]])

Return type:

Dict[str, Any]

filter_views(config: Mapping[str, Any], views_by_corner: Mapping[str, Path | Iterable[Path]], timing_corner: str | None = None) List[Path]

Given a mapping from (wildcards of) corner names to views, this function enumerates all views matching either the default timing corner or an explicitly-provided override.

Parameters:
  • config (Mapping[str, Any]) – The configuration. Used solely to extract the default corner.

  • views_by_corner (Mapping[str, Path | Iterable[Path]]) – The mapping from (wild cards) of corner names to views.

  • corner – An explicit override for the default corner. Must be a fully qualified IPVT corner.

  • timing_corner (str | None)

Returns:

The created list

Return type:

List[Path]

get_macro_views(config: Mapping[str, Any], view: DesignFormat, timing_corner: str | None = None, unless_exist: None | DesignFormat | Sequence[DesignFormat] = None) List[Path]

For Config objects (or similar Mappings) that have Macro information, this function gets all Macro views matching a certain DesignFormat for either the default timing corner or an explicitly-provided override.

Parameters:
  • config (Mapping[str, Any]) – The configuration.

  • view (DesignFormat) – The design format to return views of.

  • timing_corner (str | None) – An explicit override for the default corner set by the configuration.

  • corner – An explicit override for the default corner. Must be a fully qualified IPVT corner.

  • unless_exist (None | DesignFormat | Sequence[DesignFormat]) –

    If a Macro also has a view for these DesignFormats, do not return a result for the requested DesignFormat.

    Useful for if you want to return say, Netlists if reliable LIB files do not exist.

Returns:

A list of the Macro views matched by the process described above.

Return type:

List[Path]

get_timing_files_categorized(config: Mapping[str, Any], timing_corner: str | None = None, prioritize_nl: bool = False) Tuple[str, List[Path], List[Path], List[Tuple[str, Path]]]

Returns the lib files for a given configuration and timing corner.

Parameters:
  • config (Mapping[str, Any]) – A configuration object or a similar mapping.

  • timing_corner (str | None) –

    A fully qualified IPVT corner to get SCL libs for.

    If not specified, the value for DEFAULT_CORNER from the SCL will be used.

  • prioritize_nl (bool) –

    Do not return lib files for macros that have gate-Level Netlists and SPEF views.

    If set to false, only lib files are returned.

Returns:

A tuple of: * The name of the timing corner * A list of lib files * A list of netlists * A list of tuples of instances and SPEFs

Return type:

Tuple[str, List[Path], List[Path], List[Tuple[str, Path]]]

get_timing_files(config: Mapping[str, Any], timing_corner: str | None = None, prioritize_nl: bool = False) Tuple[str, List[str]]

Returns the lib files for a given configuration and timing corner.

Parameters:
  • config (Mapping[str, Any]) – A configuration object or a similar mapping.

  • timing_corner (str | None) –

    A fully qualified IPVT corner to get SCL libs for.

    If not specified, the value for DEFAULT_CORNER from the SCL will be used.

  • prioritize_nl (bool) –

    Do not return lib files for macros that have gate-Level Netlists and SPEF views.

    If set to false, only lib files are returned.

Returns:

A tuple of:

  • The name of the timing corner

  • A heterogeneous list of files composed of: Lib files are returned as-is, Netlists are returned as-is, and SPEF files are returned in the format {instance_name}@{spef_path}.

It is left up to the step or tool to process this list as they see fit.

Return type:

Tuple[str, List[str]]

remove_cells_from_lib(input_lib_files: FrozenSet[str], excluded_cells: FrozenSet[str]) List[str]

Creates a new lib file with some cells removed.

This function is memoized, i.e., results are cached for a specific set of inputs.

Parameters:
  • input_lib_files (FrozenSet[str]) – A frozenset of input lib files.

  • excluded_cells (FrozenSet[str]) – A frozenset of wildcards of cells to remove from the files.

Returns:

A path to the lib file with the removed cells.

Return type:

List[str]

get_lib_voltage(input_lib: str) Decimal | None

Extract the voltage from the default operating conditions of a liberty file.

Returns None if and only if the default_operating_conditions key does not exist and the number of operating conditions enumerated is not exactly 1 (one).

Parameters:

input_lib (str) – The lib file in question

Returns:

The voltage in question

Return type:

Decimal | None

class openlane.common.DRC(module: str, violations: Dict[str, Violation])

Bases: object

A primitive database representing DRC violations generated by a design.

Parameters:
  • module (str)

  • violations (Dict[str, Violation])

classmethod from_magic(report: TextIOWrapper) Tuple[DRC, int]

Parses a report generated by Magic into a DRC object.

Parameters:

report (TextIOWrapper) – A text input stream containing the report in question. You can pass the result of open("drc.rpt"), for example.

Returns:

A tuple of the DRC object and an int representing the number of DRC violations.

Return type:

Tuple[DRC, int]

dumps()
Returns:

The DRC object as a JSON string.

to_klayout_xml(out: BufferedIOBase)

Converts the DRC object to a KLayout-compatible XML database.

Parameters:

out (BufferedIOBase) – A binary output stream to the target XML file. You can pass the result of open("drc.xml",  "wb"), for example.

class openlane.common.Violation(rules: List[Tuple[str, str]], description: str, bounding_boxes: List[Tuple[decimal.Decimal, decimal.Decimal, decimal.Decimal, decimal.Decimal]] = <factory>)

Bases: object

Parameters:
  • rules (List[Tuple[str, str]])

  • description (str)

  • bounding_boxes (List[Tuple[Decimal, Decimal, Decimal, Decimal]])

openlane.common.get_tpe() ThreadPoolExecutor
Returns:

OpenLane’s global ThreadPoolExecutor. This is used to run steps, so do not use them inside steps to avoid a deadlock.

Return type:

ThreadPoolExecutor

openlane.common.set_tpe(tpe: ThreadPoolExecutor)

Allows replacing OpenLane’s global ThreadPoolExecutor with a customized one.

It will be used inside steps, so use different TPEs inside steps to avoid a deadlock.

Parameters:

tpe (ThreadPoolExecutor) – The replacement ThreadPoolExecutor

class openlane.common.RingBuffer(t: Type[VT], max: int)

Bases: Iterable[VT]

A generic ring (circular) buffer that automatically pops the element at the head when full, and emplaces a new element in its place.

Parameters:
  • t (Type[VT])

  • max (int)

Submodule

Short Description

metrics

Metrics Module