Skip to content

netlist_carpentry.core.netlist_elements.module

Module for handling circuit modules.

Classes:

Module

Bases: GraphBuildingMixin, EvaluationMixin, ModuleBfsMixin, ModuleDfsMixin, NetlistElement, BaseModel

Methods:

  • add_instance –

    Adds an instance to the module.

  • create_instance –

    Creates an instance within this module based on the given interface definition, instance name and parameters.

  • copy_instance –

    Copies the given instance within this module.

  • refine_instance –

    Replaces an existing instance with a new one of a different type.

  • substitute_instance –

    Replaces an existing instance in the module with a new instance.

  • remove_instance –

    Removes an instance from the module.

  • get_instance –

    Retrieves an instance by its name.

  • get_instances –

    Retrieves a list of instances based on the given criteria.

  • add_port –

    Adds a port to the module.

  • create_port –

    Creates a new port within the module and connects it to the specified wire segments.

  • remove_port –

    Removes a port from the module.

  • get_port –

    Retrieves a port by its name.

  • get_ports –

    Retrieves a list of ports based on the given criteria.

  • add_wire –

    Adds a wire to the module.

  • create_wire –

    Creates a new wire within the module.

  • remove_wire –

    Removes a wire from the module.

  • get_wire –

    Retrieves a wire by its name.

  • get_wires –

    Retrieves a list of wires based on the given criteria.

  • name_occupied –

    Checks if a given identifier is already in use within the module.

  • disconnect –

    Disconnects a port segment from its connected wire segment.

  • reconnect –

    Moves (or reconnects) all existing wire connections from a source port to a target port.

  • get_edges –

    Retrieves the edges connected to a given instance.

  • get_outgoing_edges –

    Retrieves all connections associated with the output ports of a specific instance.

  • get_incoming_edges –

    Retrieves all connections associated with the input ports of a specific instance.

  • get_wire_ports –

    Retrieves the connected port segments of a given wire segment.

  • get_neighbors –

    Retrieves the neighboring port segments of a given instance.

  • get_succeeding_instances –

    Retrieves the succeeding instances of a given instance.

  • get_preceeding_instances –

    Retrieves the preceeding instances of a given instance.

  • split –

    Splits the given n-bit large instance into n 1-bit instances.

  • split_all –

    Splits all n-bit instances with the given type into n 1-bit instances.

  • make_chain –

    Forms a chain by chaining the given instances together.

  • flatten –

    Flatten this module, by replacing all submodule instances by their module definition.

  • optimize –

    Optimizes this module by removing unused wires and instances.

  • check –

    Checks this module for issues.

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

  • evaluate –

    Performs the breadth-first evaluation of the module.

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

  • dfs_paths_between –

    Performs a depth-first search (DFS) to find all paths between two given elements in the digital circuit.

  • bfs_paths_between –

    Performs a breadth-first search (BFS) to find all paths between two given elements in the digital circuit.

  • get_load_ports –

    Retrieves the load port segments of a given wire segment (i.e. the instances driven by this wire segment).

  • get_driving_ports –

    Retrieves the driving port segments of a given wire segment (i.e. the instances driving this wire segment).

  • graph –

    Builds a graph from the module by representing instances and ports as nodes, and connections between them as edges.

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.

add_instance 

add_instance(instance: T_INSTANCE) -> T_INSTANCE

Adds an instance to the module.

Parameters:

  • instance

    (Instance) –

    The instance to be added.

Returns:

  • Instance ( T_INSTANCE ) –

    the instance that was added.

create_instance 

create_instance(
    interface_definition: Type[T_INSTANCE],
    name: Optional[str] = None,
    params: Optional[Dict[str, object]] = None,
) -> T_INSTANCE

create_instance(
    interface_definition: Module,
    name: Optional[str] = None,
    params: Optional[Dict[str, object]] = None,
) -> Instance

create_instance(
    interface_definition: Union[Module, Type[T_INSTANCE]],
    name: Optional[str] = None,
    params: Optional[Dict[str, object]] = None,
) -> Instance

Creates an instance within this module based on the given interface definition, instance name and parameters.

If interface_definition is a module, this creates a submodule instance inside this module, based on the given instance name and module definition. The module is also added to the circuit if no module with this name already already exists.

If interface_definition is a class (not an instance) that extends netlist_carpentry.Instance (e.g. a gate from the internal gate library), this creates a primitive gate instance inside this module.

The instance type of the created instance is either the name of the provided module or the type of the provided instance class. The instance is thus linked to either the module definition or the type of the given instance by its own instance type.

Parameters:

  • interface_definition

    (Union[Module, Instance]) –

    The module whose interface is to be copied to the new instance. Alternatively, the primitive instance class, whose interface is to be copied to the new instance.

  • name

    (str, default: None ) –

    The target name of the instance to be created.

  • params

    (Dict[str, object], default: None ) –

    A dictionary containing parameters for the instance to be created

Returns:

  • Instance ( Instance ) –

    The instance that was created and added.

copy_instance 

copy_instance(
    instance: Union[str, Instance], new_name: str, keep_inputs: bool = False
) -> Instance

Copies the given instance within this module.

Takes either an Instance object or a string (which must be a name of an already existing instance within this module. The instance is then copied and is completely identical to the given instance (or the instance with the given name, if a string is passed instead), except for the given name. Also, all ports of the new instance are initially unconnected.

Parameters:

  • instance

    (Union[str, Instance]) –

    The instance to copy. If a string is provided, it must be the name of an instance that exists within this module.

  • new_name

    (str) –

    The new name of the copied instance. Must be a name that is not already given to another instance.

  • keep_inputs

    (bool, default: False ) –

    Whether to disconnect the input ports of the instance (so it is entirely unconnected). Defaults to True.

refine_instance 

refine_instance(
    old_instance: Union[str, Instance],
    new_type_definition: Union[Module, Type[Instance]],
) -> None

Replaces an existing instance with a new one of a different type.

This method swaps the definition of an instance while attempting to preserve its original name and port connections. It first verifies that the new module definition contains all the necessary ports used by the old instance.

The original object is removed and replaced with a new object! The old reference won't point to a valid instance anymore.

Parameters:

  • old_instance

    (Union[str, Instance]) –

    The instance to be replaced. Can be either the Instance object itself or its name (as string).

  • new_type_definition

    (Module) –

    The Module definition that the new instance should be based on.

Raises:

substitute_instance 

substitute_instance(
    old_instance: Union[str, Instance], new_instance: Instance
) -> None

Replaces an existing instance in the module with a new instance.

This method validates the existence of the instance to be replaced and ensures the new instance's name does not cause a conflict within the module.

Parameters:

  • old_instance

    (Union[str, Instance]) –

    The instance to be replaced. Can be either the instance name (str) or the Instance object itself.

  • new_instance

    (Instance) –

    The new instance (submodule or gate) to be inserted.

Raises:

remove_instance 

remove_instance(instance: Union[str, Instance]) -> None

Removes an instance from the module.

Parameters:

  • instance

    (Union[str, Instance}) –

    The name of the instance to be removed, or the Instance object itself.

get_instance 

get_instance(name: str) -> Optional[Instance]

Retrieves an instance by its name.

Guarded alternative to Module.instances[name], with fallback to return None if not found.

Parameters:

  • name

    (str) –

    The name of the instance to be retrieved.

Returns:

  • Optional[Instance] –

    Optional[Instance]: The instance with the specified name if found, otherwise None.

get_instances 

get_instances(
    *,
    name: Optional[str] = None,
    type: Optional[str] = None,
    fuzzy: bool = False,
    recursive: bool = False
) -> List[Instance]

Retrieves a list of instances based on the given criteria.

Parameters:

  • name

    (Optional[str], default: None ) –

    The name of the instance to be searched for. Defaults to None.

  • type

    (Optional[str], default: None ) –

    The type of the instance to be searched for. Defaults to None.

  • fuzzy

    (bool, default: False ) –

    Whether to perform a fuzzy search or not. Defaults to False. Fuzzy search means, the given string is used case-insensitive and substrings are accepted. If a name "inst" is given, this method will return instances named "INST", "someInst", i.e. all instances whose name contains "inst", regardless of case and pre- or suffixes.

  • recursive

    (bool, default: False ) –

    Whether to scan submodules as well. Defaults to False.

Returns:

  • List[Instance] –

    List[Instance]: A list of instances matching the specified criteria.

add_port 

add_port(port: Port[Module]) -> Port[Module]

Adds a port to the module.

Parameters:

  • port

    (Port) –

    The port to be added.

Returns:

  • Port ( Port[Module] ) –

    The port that was added.

create_port 

create_port(
    name: str,
    direction: Direction = UNKNOWN,
    width: PositiveInt = 1,
    offset: NonNegativeInt = 0,
    is_locked: bool = False,
) -> Port[Module]

Creates a new port within the module and connects it to the specified wire segments.

Returns the port object, if it was created successfully (i.e. no port with the same name exists already), or None otherwise. If the port was not created (because it already exists), the provided wire segment paths are ignored.

Parameters:

  • name

    (str) –

    The name of the port to be created.

  • direction

    (Direction, default: UNKNOWN ) –

    The direction of the port. Defaults to Direction.UNKNOWN.

  • width

    (PositiveInt, default: 1 ) –

    The width of the port. Defaults to 1, which means the port is 1 bit wide.

  • offset

    (NonNegativeInt, default: 0 ) –

    The index offset for port slices. Defaults to 0, which means the port indexing starts at 0.

  • is_locked

    (bool, default: False ) –

    Whether the port should be unchangeable after creation or not. Defaults to False.

Returns:

  • Port[Module] –

    Optional[Port]: The port if the port was successfully created and added, None otherwise (if a port with this name already exists).

remove_port 

remove_port(port: Union[str, Port[Module]]) -> None

Removes a port from the module.

Parameters:

  • port

    (Union[str, Port]) –

    The name of the port to be removed, or the Port object itself.

get_port 

get_port(name: str) -> Optional[Port[Module]]

Retrieves a port by its name.

Guarded alternative to Module.port[name], with fallback to return None if not found.

Parameters:

  • name

    (str) –

    The name of the port to be retrieved.

Returns:

  • Port ( Optional[Port[Module]] ) –

    The port with the specified name if found, otherwise None.

get_ports 

get_ports(
    *,
    name: Optional[str] = None,
    direction: Optional[Direction] = None,
    fuzzy: bool = False
) -> List[Port[Module]]

Retrieves a list of ports based on the given criteria.

Parameters:

  • name

    (Optional[str], default: None ) –

    The name of the port to be searched for. Defaults to None.

  • direction

    (Direction, default: None ) –

    The direction of the port to be searched for. Defaults to None.

  • fuzzy

    (bool, default: False ) –

    Whether to perform a fuzzy search or not. Defaults to False. Fuzzy search means, the given string is used case-insensitive and substrings are accepted. If a name "port" is given, this method will return ports named "PORT", "somePort", i.e. all ports whose name contains "port", regardless of case and pre- or suffixes.

Returns:

  • List[Port[Module]] –

    List[Port]: A list of ports matching the specified criteria.

add_wire 

add_wire(wire: Wire) -> Wire

Adds a wire to the module.

Parameters:

  • wire

    (Wire) –

    The wire to be added.

Returns:

  • Wire ( Wire ) –

    The wire that was added.

create_wire 

create_wire(
    name: Optional[str] = None,
    width: PositiveInt = 1,
    is_locked: bool = False,
    offset: NonNegativeInt = 0,
) -> Wire

Creates a new wire within the module.

Returns the wire object, if it was created successfully (i.e. no wire with the same name exists already), or None otherwise.

Parameters:

  • name

    (Optional[str], default: None ) –

    The name of the wire to be created. Defaults to None, in which case a generic wire is created. In this case, the name of the wire is _ncgen_{index}_.

  • width

    (PositiveInt, default: 1 ) –

    The number of segments in the wire. Defaults to 1.

  • is_locked

    (bool, default: False ) –

    Whether the wire should be unchangeable after creation or not. Defaults to False.

  • offset

    (NonNegativeInt, default: 0 ) –

    The offset for the segment indices. Defaults to 0.

Returns:

  • Wire –

    Optional[Wire]: The wire if the wire was successfully created and added, None otherwise (if a wire with this name already exists).

remove_wire 

remove_wire(wire: Union[str, Wire]) -> None

Removes a wire from the module.

Parameters:

  • wire

    (Union[str, Wire]) –

    The name of the wire to be removed, or the Wire object itself.

get_wire 

get_wire(name: str) -> Optional[Wire]

Retrieves a wire by its name.

Guarded alternative to Module.wires[name], with fallback to return None if not found.

Parameters:

  • name

    (str) –

    The name of the wire to be retrieved.

Returns:

  • Wire ( Optional[Wire] ) –

    The wire with the specified name if found, otherwise None.

get_wires 

get_wires(*, name: Optional[str] = None, fuzzy: bool = False) -> List[Wire]

Retrieves a list of wires based on the given criteria.

Parameters:

  • name

    (Optional[str], default: None ) –

    The name of the wire to be searched for. Defaults to None.

  • fuzzy

    (bool, default: False ) –

    Whether to perform a fuzzy search or not. Defaults to False. Fuzzy search means, the given string is used case-insensitive and substrings are accepted. If a name "wire" is given, this method will return wires named "WIRE", "someWire", i.e. all wires whose name contains "wire", regardless of case and pre- or suffixes.

Returns:

  • List[Wire] –

    List[Wire]: A list of wires matching the specified criteria.

name_occupied 

name_occupied(name: str) -> bool

Checks if a given identifier is already in use within the module.

This method verifies if the name conflicts with any existing instances, ports, or wires defined in the module's namespace.

Parameters:

  • name

    (str) –

    The string identifier to check for existence.

Returns:

  • bool –

    True if the name is already used by an instance, port, or wire;

  • bool –

    False otherwise.

disconnect 

disconnect(
    port_like: Union[PortSegmentPath, PortPath, PortSegment, T_PORT],
) -> None

Disconnects a port segment from its connected wire segment.

Parameters:

  • port_like

    (Union[PortSegmentPath, PortSegment]) –

    The path of the port segment to be disconnected, or the PortSegment itself. Also accepts ports, aqd will then disconnect the complete port.

reconnect 

reconnect(
    source: Union[PortPath, T_PORT], target: Union[PortPath, T_PORT]
) -> None

Moves (or reconnects) all existing wire connections from a source port to a target port.

This method acts as a wrapper that accepts either port objects (Port[Instance] or Port[Module]) or hierarchical paths (PortPath). It resolves any paths into their respective port objects before performing the reconnection.

In this process, the wire(s) connected to the source port are removed from the source port and connected (in the same order) to the target port. The target port must be unconnected!

Parameters:

  • source

    (Union[PortPath, T_PORT]) –

    The port (or path to the port) currently holding the connections.

  • target

    (Union[PortPath, T_PORT]) –

    The destination port (or path) where the connections should be moved.

Raises:

get_edges 

get_edges(instance: Union[str, Instance]) -> Dict[str, Dict[int, WireSegment]]

Retrieves the edges connected to a given instance.

This method returns a dictionary containing the names of ports as keys and dictionaries of wire segments as values. Each inner dictionary contains the index of a port segment as a key and the corresponding wire segment as a value.

Parameters:

  • instance

    (str) –

    The name of the instance for which to retrieve edges.

Returns:

  • Dict[str, Dict[int, WireSegment]] –

    Dict[str, Dict[int, WireSegment]]: A dictionary containing the edges connected to the given instance.

get_outgoing_edges 

get_outgoing_edges(instance_name: str) -> Dict[str, Dict[int, WireSegment]]

Retrieves all connections associated with the output ports of a specific instance.

This method filters all edges of the given instance to return only those connected to its output ports.

Parameters:

  • instance_name

    (str) –

    The name of the instance (submodule or gate) to query.

Returns:

  • Dict[str, Dict[int, WireSegment]] –

    A dictionary mapping output port names to their connections. The structure is: { port_name (str): { bit_index (int): wire_segment (WireSegment) } }

Raises:

  • KeyError –

    If instance_name does not exist in the module's instances.

get_incoming_edges 

get_incoming_edges(instance_name: str) -> Dict[str, Dict[int, WireSegment]]

Retrieves all connections associated with the input ports of a specific instance.

This method filters all edges of the given instance to return only those connected to its input ports.

Parameters:

  • instance_name

    (str) –

    The name of the instance (submodule or gate) to query.

Returns:

Raises:

  • KeyError –

    If instance_name does not exist in the module's instances.

get_wire_ports 

get_wire_ports(ws_path: WireSegmentPath) -> List[PortSegment]

Retrieves the connected port segments of a given wire segment.

Parameters:

  • ws_path

    (WireSegmentPath) –

    The path of the wire segment for which to retrieve connected port segments.

Returns:

  • List[PortSegment] –

    List[PortSegment]: A list of port segments connected to the wire segment associated with the given path.

get_neighbors 

get_neighbors(instance_name: str) -> Dict[str, Dict[int, List[PortSegment]]]

Retrieves the neighboring port segments of a given instance.

This method is needed to determine which port segments are connected to an instance. It returns a dictionary containing the names of ports as keys and dictionaries of lists of port segments (connected to this port through a wire) as values. Each inner dictionary contains the index of a port segment as a key and a list of corresponding port segments as a value. The corresponding port segments are port segments opposing the instance's port. If the instance port is an input port (i.e. a load), only the driver is considered its neighbor. If the instance port is an output port (.e. a signal driver), all loads are considered its neighbors.

Parameters:

  • instance_name

    (str) –

    The name of the instance for which to retrieve neighbors.

Returns:

  • Dict[str, Dict[int, List[PortSegment]]] –

    Dict[str, Dict[int, List[PortSegment]]]: A dictionary containing the neighboring port segments of the given instance.

get_succeeding_instances 

get_succeeding_instances(
    instance_name: str,
) -> Dict[str, Dict[int, List[Union[Instance, Port[Module]]]]]

Retrieves the succeeding instances of a given instance.

This method returns the instances that are connected to the output ports of the given instance. It is needed for various graph-based analyses and algorithms, such as depth-first search or topological sorting.

Parameters:

  • instance_name

    (str) –

    The name of the instance for which to retrieve succeeding instances.

Returns:

get_preceeding_instances 

get_preceeding_instances(
    instance_name: str,
) -> Dict[str, Dict[int, List[Union[Instance, Port[Module]]]]]

Retrieves the preceeding instances of a given instance.

This method returns the instances that are connected to the input ports of the given instance. It is needed for various graph-based analyses and algorithms, such as depth-first search or topological sorting.

Parameters:

  • instance_name

    (str) –

    The name of the instance for which to retrieve preceeding instances.

Returns:

split 

split(instance: Union[str, Instance]) -> Dict[NonNegativeInt, Instance]

Splits the given n-bit large instance into n 1-bit instances.

Replaces the n-bit large instances by calling their split method. The given instance must support splitting. This is the case for all gates, where the individual bits are independent of each other (e.g. AND gates, D-FF). Instances that do not support splitting are e.g. reduction gates and arithmetic gates.

Parameters:

  • instance

    (Union[str, Instance]) –

    The instance or the instance name (must exist in this module).

Raises:

Returns:

  • Dict[NonNegativeInt, Instance] –

    Dict[NonNegativeInt, Instance]: A dictionary, where the key is the bit index and the value is the corresponding 1-bit "instance slice" for this index.

split_all 

split_all(type: str = '', fuzzy: bool = True, recursive: bool = False) -> int

Splits all n-bit instances with the given type into n 1-bit instances.

Each instance that matches the given type (supports fuzzy search, if fuzzy is True) is split into n slices. To split all AND gates, use Module.split_all("§and"). To split all Flip-Flops, use Module.split_all("dff", fuzzy=True). This will split all DFF, ADFF, DFFE, and ADFFE.

Parameters:

  • type

    (str, default: '' ) –

    The instance type, where all instances should be split. If set to '' and fuzzy is True, all instances inside this module are split. Defaults to ''.

  • fuzzy

    (bool, default: True ) –

    Whether to perform fuzzy checks. If True, the given type string must only be a substring of the instance type. Defaults to True.

  • recursive

    (bool, default: False ) –

    Whether to perform split operation in submodules as well. Defaults to False.

Returns:

  • int ( int ) –

    The number of original instances that were split.

make_chain 

make_chain(
    instances: List[Instance], input_port: str, output_port: str
) -> Tuple[Port[Instance], Port[Instance]]

Forms a chain by chaining the given instances together.

Each instance in the given list is connected to its successor, where the given output_port string is the output port of the instance, that is connected to the input port input_port of the succeeding instance.

The (unconnected) input port of the first instance and the (unconnected) output port of the last instance are returned as a tuple, marking the ends of the chain.

Each instance must have a port with the given input and output names.

Parameters:

  • instances

    (List[Instance]) –

    The instances to chain together.

  • input_port

    (str) –

    The name of the input port that is connected to the predecessor's output port.

  • output_port

    (str) –

    The name of the output port that is connected to the successor's input port.

Raises:

Returns:

  • Tuple[Port[Instance], Port[Instance]] –

    Tuple[Port[Instance], Port[Instance]]: The input port of the first instance and the output port of the last instance, i.e. the ends of the chain.

flatten 

flatten(
    skip_name: Optional[List[str]] = None,
    skip_type: Optional[List[str]] = None,
    recursive: bool = False,
) -> None

Flatten this module, by replacing all submodule instances by their module definition.

Each submodule instance is removed and the content of the module definition is added to this module. The previous instance ports are thus connected directly to the instances inside the submodules.

Parameters:

  • skip_name

    (Optional[List[str]], default: None ) –

    Names of submodules, which should not be flattened. Defaults to None.

  • skip_type

    (Optional[List[str]], default: None ) –

    Types of submodules (i.e. module names), which should not be flattened. Defaults to None.

  • recursive

    (bool, default: False ) –

    Whether to also flatten submodules inside the submodules (i.e. make this module completely flat). Defaults to False.

optimize 

optimize() -> bool

Optimizes this module by removing unused wires and instances.

More optimization algorithms may be implemented in the future.

Returns:

  • bool ( bool ) –

    True if any changes were made, False otherwise.

check 

check() -> 'CheckReport'

Checks this module for issues.

Returns:

  • CheckReport ( 'CheckReport' ) –

    A report with all found issues. bool(CheckReport) returns True if there are issues, and False otherwise.

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:

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.

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:

dfs_paths_between 

dfs_paths_between(
    start: ElementPath, end: ElementPath, max_paths: int = 1
) -> Set[Tuple[ElementPath, ...]]

Performs a depth-first search (DFS) to find all paths between two given elements in the digital circuit.

Parameters:

  • start

    (ElementPath) –

    The starting point of the path.

  • end

    (ElementPath) –

    The ending point of the path.

  • max_paths

    (int, default: 1 ) –

    How many occurrences to find. Set to -1 to find all occurrences. Defaults to 1.

Returns:

  • Set[Tuple[ElementPath, ...]] –

    Set[Tuple[ElementPath, ...]]: A set of tuples, where each tuple represents a path from the start to the end element.

bfs_paths_between 

bfs_paths_between(
    start: ElementPath, end: ElementPath, return_first_only: bool = True
) -> Set[Tuple[ElementPath, ...]]

Performs a breadth-first search (BFS) to find all paths between two given elements in the digital circuit.

Parameters:

  • start

    (ElementPath) –

    The starting point of the path.

  • end

    (ElementPath) –

    The ending point of the path.

  • return_first_only

    (bool, default: True ) –

    Whether to only return the first occurrence, or all found paths. Defaults to True.

Returns:

  • Set[Tuple[ElementPath, ...]] –

    Set[Tuple[ElementPath, ...]]: A set of tuples, where each tuple represents a path from the start to the end element.

get_load_ports 

get_load_ports(ws_path: WireSegmentPath) -> List[PortSegment]

Retrieves the load port segments of a given wire segment (i.e. the instances driven by this wire segment).

Parameters:

  • ws_path

    (WireSegmentPath) –

    The path of the wire segment for which to retrieve load ports.

Returns:

  • List[PortSegment] –

    List[PortSegment]: A list of port segments being load of the wire segment associated with the given path.

get_driving_ports 

get_driving_ports(ws_path: WireSegmentPath) -> List[PortSegment]

Retrieves the driving port segments of a given wire segment (i.e. the instances driving this wire segment).

For each wire segment, the list of driving ports should contain exactly one entry, otherwise driver conflicts will arise.

Parameters:

  • ws_path

    (WireSegmentPath) –

    The path of the wire segment for which to retrieve driving ports.

Returns:

  • List[PortSegment] –

    List[PortSegment]: A list of port segments driving the wire segment associated with the given path.

graph 

graph() -> ModuleGraph

Builds a graph from the module by representing instances and ports as nodes, and connections between them as edges.

The module graph represents the connectivity between instances and ports within a module. The method iterates over all instances and ports in the module. For each instance or port, it adds a node to the graph with relevant information (e.g., name, type). Then, for each wire segment, it adds an edge between the corresponding nodes representing the driver and load of that wire segment.

Returns:

  • ModuleGraph ( ModuleGraph ) –

    A graph object representing the connectivity of the module.