Skip to content

netlist_carpentry.core.netlist_elements.mixins.evaluation

Mixin for signal evaluation of a module.

Classes:

EvaluationMixin

Bases: ModuleBaseMixin

Methods:

  • evaluate –

    Performs the breadth-first evaluation of the module.

  • set_name –

    Sets the name of this object to the given value by updating its hierarchical path.

  • change_mutability –

    Change the mutability of this Module instance.

  • copy_object –

    Creates a new object of this type and copies the contents of this object into the new one.

  • normalize_metadata –

    Performs normalization of this element's metadata.

  • valid_module_path –

    Checks whether the given element path is a valid module path.

  • is_in_module –

    Checks whether an element with the given path exists within this module.

  • get_from_path –

    Retrieves the NetlistElement from the given ElementPath.

Attributes:

name instance-attribute 

name: str

The name of the element.

!!! Do not modify this variable after instantiating it. Use NetlistElement.set_name() instead. Modifying this variable might lead to inconsistencies later on.

parameters class-attribute instance-attribute 

parameters: TypedParams = {}

Attributes of a netlist element. Can be user-defined, or e. g. by Yosys (such as WIDTH for some instances).

metadata class-attribute instance-attribute 

metadata: MetadataMixin = MetadataMixin()

Metadata of a netlist element.

Can be user-defined, or e. g. by Yosys (such as src for the HDL source). Is also grouped by categories, i.e. all metadata from Yosys can be accessed via Module.metadata["yosys"], or via Module.metadata.yosys, which both return a dictionary of all metadata. Read the documentation of MetaDataMixin for more information.

path property 

path: ModulePath

Returns the ModulePath of the netlist element.

The ModulePath object is constructed using the element's type and its raw hierarchical path.

Returns:

  • ModulePath ( ModulePath ) –

    The hierarchical path of the netlist element.

type property 

type: EType

The type of the element, which is a module.

hierarchy_level property 

hierarchy_level: int

The level of hierarchy of the element in the design.

The hierarchy level is the number of separators in the element's raw path. For example, a top-level instance has a hierarchy level of 0, while a direct submodule instance has a hierarchy level of 1.

Returns:

  • int ( int ) –

    The hierarchy level of the element.

has_circuit property 

has_circuit: bool

Whether this netlist element has a defined circuit it belongs to.

Tries to access self.circuit and returns whether the call was successful. Can be used instead of a try-except clause around the call to NetlistElement.circuit.

locked property 

locked: bool

True if this NetlistElement instance is locked (i.e. it is currently structurally unchangeable), False if it is mutable.

Can be changed via NetlistElement.change_mutability(bool).

Immutability is used to prevent accidental changes to the design.

is_placeholder_instance property 

is_placeholder_instance: bool

A placeholder represents an element that does not have a specific path.

True if this NetlistElement instance represents a placeholder, False otherwise.

can_carry_signal property 

can_carry_signal: bool

Whether this exact object is able to receive, pass or hold signal values.

True for ports (as they drive or receive values) and wires (as they pass the signals from driver to load ports) as well as their respective segments. False for instances and modules.

instances property 

instances: CustomDict[str, Instance]

Returns the instances of this module as a dictionary.

In the dictionary, the key is the instance's name and the value is the associated instance object.

instances_by_types property 

instances_by_types: DefaultDict[str, List[Instance]]

Returns a dictionary where keys are instance types and values are lists of instances of that type.

This method groups all instances in the module by their respective instance types.

ports property 

ports: CustomDict[str, Port[Module]]

Returns the ports of this module as a dictionary.

In the dictionary, the key is the port's name and the value is the associated port object.

wires property 

wires: CustomDict[str, Wire]

Returns the wires of this module as a dictionary.

In the dictionary, the key is the wire's name and the value is the associated wire object.

input_ports property 

input_ports: List[Port[Module]]

Returns a list of input ports in the module.

This property filters the ports based on their direction, returning only those with an input direction.

output_ports property 

output_ports: List[Port[Module]]

Returns a list of output ports in the module.

This property filters the ports based on their direction, returning only those with an output direction.

instances_with_constant_inputs property 

instances_with_constant_inputs: List[Instance]

A list of Instance objects where at least one input port is tied to a constant.

submodules property 

submodules: List[Instance]

A list of submodule instances in the module.

primitives property 

primitives: List[Instance]

A list of instances marked as primitive in the module.

gatelib_primitives property 

gatelib_primitives: List[Instance]

A list of primitive instances in the module that are based on gates from the gate library.

evaluate 

evaluate() -> None

Performs the breadth-first evaluation of the module.

This method evaluates the module in a breadth-first manner, starting from the input ports. It uses a queue to keep track of the elements that need to be evaluated next. The evaluation process involves evaluating each element (either an instance or a wire segment) and adding its successors to the queue. The process continues until all elements have been evaluated.

This method is needed for the overall evaluation of the module, as it ensures that all elements are properly evaluated in the correct hierarchical order.

set_name 

set_name(new_name: str) -> None

Sets the name of this object to the given value by updating its hierarchical path.

To also update the path names of objects that are part of this object (e.g. segments), overwrite NetlistElement._set_name_recursively, which is called by this method. By doing so, the paths of all contained objects can be updated accordingly.

Parameters:

  • new_name

    (str) –

    The new name to set to the object.

change_mutability 

change_mutability(is_now_locked: bool, recursive: bool = False) -> Self

Change the mutability of this Module instance.

Parameters:

  • is_now_locked

    (bool) –

    The new value for this module's mutability. True means, the module is now immutable; False means, the module is mow mutable.

  • recursive

    (bool, default: False ) –

    Whether to also update mutability for all subordinate elements, e.g. instances, ports and wires that are part of this module. Defaults to False.

Returns:

  • Module ( Self ) –

    This instance with its mutability changed.

copy_object 

copy_object(new_name: str) -> NetlistElement

Creates a new object of this type and copies the contents of this object into the new one.

Requires a new name to be specified. If a parent module exists: - The name must still be available in the parent module (i.e. no wire, port or instance with this name exists). - The new object is added to the respective dictionary.

When copying wires, ports or instances, the resulting copy is unconnected and must be connected manually afterwards.

Parameters:

  • new_name

    (str) –

    The name for the newly created copy.

Returns:

normalize_metadata 

normalize_metadata(
    include_empty: bool = False,
    sort_by: Literal["path", "category"] = "path",
    filter: Callable[[str, NESTED_DICT], bool] = lambda cat, md: True,
) -> METADATA_DICT

Performs normalization of this element's metadata.

This method simplifies the metadata of this object by re-formatting the metadata dictionary, mainly used when exporting the metadata. This is to ensure a coherent and unambiguous output by integrating the hierarchical path of this object (and all nested objects, if any). The dictionary can be sorted by paths (then the main dictionary key is the hierarchical path of the objects) or by category (in which case the main keys are the dictionary names). The dictionary can also be filtered by providing a callable that evaluates to a boolean value for which it may take metadata categories and the associated metadata dictionary, consisting of the metadata keys and associated metadata values.

Parameters:

  • include_empty

    (bool, default: False ) –

    Whether to include objects without metadata into the normalized dictionary, in which case the value is just an empty dictionary. Defaults to False.

  • sort_by

    (Literal['path', 'category'], default: 'path' ) –

    Whether the hierarchical path or the metadata categories should be the main dictionary keys. Defaults to 'path'.

  • filter

    (Callable[[str, NESTED_DICT], bool], default: lambda cat, md: True ) –

    A filter function that takes two parameters, where the first represents the metadata category and the second represents the metadata dictionary. Defaults to lambda cat, md: True, which evaluates to True for all elements and thus does not filter anything.

Returns:

  • METADATA_DICT ( METADATA_DICT ) –

    A normalized metadata dictionary containing the metadata of this element and all nested objects.

valid_module_path 

valid_module_path(path: ElementPath) -> bool

Checks whether the given element path is a valid module path.

Parameters:

Returns:

  • bool ( bool ) –

    True if the path is valid, False otherwise.

is_in_module 

is_in_module(path: ElementPath) -> bool

Checks whether an element with the given path exists within this module.

Parameters:

  • path

    (ElementPath) –

    The path of the element to be searched for.

Returns:

  • bool ( bool ) –

    True if the element is found within the module, False otherwise.

get_from_path 

get_from_path(path: InstancePath) -> Instance

get_from_path(path: PortPath) -> T_PORT

get_from_path(path: PortSegmentPath) -> PortSegment

get_from_path(path: WirePath) -> Wire

get_from_path(path: WireSegmentPath) -> WireSegment

get_from_path(path: ElementPath) -> NetlistElement

get_from_path(path: T_PATH_TYPES) -> Union[NetlistElement, T_MODULE_PARTS]

Retrieves the NetlistElement from the given ElementPath.

If the path points to outside of this module (i.e. the element, to which the path points, is not part of this module), returns None.

Parameters:

  • path

    (T_PATH_TYPES) –

    The path to the element.

Returns:

  • Union[NetlistElement, T_MODULE_PARTS] –

    A NetlistElement matching the given path) if it is part of this module and has been found, otherwise raises an error.

Raises: