Core Modules¶

Methods:

• cut_as_integer –

  Cutting input number to integer directly (more like in hardware)

• round_to_integer –

  Mathematical Round function for number

cut_as_integer(number: float | int) -> int

cut_as_integer(number: list) -> list

cut_as_integer(number: T) -> T

round_to_integer(number: float | int) -> int

round_to_integer(number: T) -> T

Bases: Graph[T]

All iterators in this class are guaranteed to have a fixed order. That means, the order of iteration is only allowed to change when the data Tucture is altered. If the content of two GraphDelegates is the same and they were built in the same way, then their iteration order is the same as well.

Methods:

• get_edges –

  Iterator over edges in a fixed but unspecified order.

• get_predecessors –

  Iterator over node predecessors in a fixed but unspecified order.

• get_successors –

  Iterator over node successors in a fixed but unspecified order.

• iter_edges –

  Iterator over edges in a fixed but unspecified order.

• iter_nodes –

  Iterator over nodes in a fixed but unspecified order.

get_edges() -> Iterator[tuple[T, T]]

get_predecessors(node: T) -> Iterator[T]

get_successors(node: T) -> Iterator[T]

iter_edges() -> Iterator[tuple[T, T]]

iter_nodes() -> Iterator[T]

Bases: Mapping[str, Attribute]

Methods:

• merge –

  merge over nested mappings recursively

• new_with –

  replace key, value pairs in self by key, value pairs in kwargs

• update_path –

  update the entry found when following the path into nested Mappings

merge(other: Mapping) -> Self

data = dict(a=dict(b=1, c=2))
data["a"]["b"] = 3

assert data["a"]["c"] == 2

data = AttributeMapping(a=AttributeMapping(b=1, c=2))
data = data.merge(dict(a=dict(b=3)))
assert data["a"]["c"] == 2

new_with(**kwargs: Attribute) -> AttributeMapping

update_path(path: tuple[str, ...], value: Attribute) -> Self

Bases: ReadOnlyDataGraph[N, E], Graph[str, AttributeMapping], Protocol[N, E]

Note that the fact, that add_node and similar methods take an argument of type Node while the nodes and edges properties produce mappings over the generic type parameters E and N. This makes DataGraph covariant over N and E, meaning that DataGraph[SpecialNode, SpecialEdge] is a subtype of DataGraph[Node, Edge]. It also means that every implementation detail in a DataGraph implementation needs to assume that nodes and edges are of the most general Node or Edge type.

Methods:

• add_edges –

  Updates edge in case it exists already. Possibly already existing nodes remain unchanged.

• add_nodes –

  Updates node in case it exists already.

• clear –

  Get a new empty graph with attributes, nodes, edges removed.

• remove_edge –

  Will not remove nodes, even if they become isolated.

• remove_node –

  Will remove node and all connected edges.

add_edges(*args: Edge | tuple[str, str, AttributeMapping] | tuple[str, str]) -> Self

add_nodes(*args: Node | tuple[str, AttributeMapping] | str) -> Self

clear() -> Self

remove_edge(src: str, dst: str) -> Self

remove_node(node: str) -> Self

Bases: DataGraph[N, E]

Keep constructor signature when subclassing!

Methods:

• add_edge –

  Updates edge in case it exists already. Possibly already existing nodes remain unchanged.

• add_edges –

  Updates edges in case they exist already. Possibly already existing nodes remain unchanged.

• add_node –

  Updates node in case it exists already.

• add_nodes –

  Updates nodes in case they exist already.

• clear –

  Get a new empty graph with attributes, nodes, edges removed.

• remove_edge –

  Will not remove nodes, even if they become isolated.

• remove_node –

  Will remove node and all connected edges.

add_edge(
    src: str | Edge, dst: str | None = None, attributes: AttributeMapping | None = None
) -> Self

add_edges(*edges: Edge | tuple[str, str, AttributeMapping] | tuple[str, str]) -> Self

add_node(name: str | Node, attributes: AttributeMapping | None = None) -> Self

add_nodes(*nodes: Node | tuple[str, AttributeMapping] | str) -> Self

clear() -> Self

remove_edge(src: str, dst: str) -> Self

remove_node(node: str) -> Self

Deserializes to the legacy format.

The only difference is that attributes are not stored in a dedicated field but at the top-level dict. Use this if you need to load an IR from data that was serialized using the IrData data types.

Serializer for the legacy format.

The only difference is that the attributes are not saved in a dedicated field, but instead directly in the top-level dict.

Use this if you need to store the data in a format that can be read by the old IrData based implementations.

PluginLoader for Ir2Verilog passes.

The specification of a plugin.

Typically built by reading a dictionary from a toml file and building the spec using <build_plugin_spec()>>. The dataclass is only used to provide convenient access to the fields, support type checking and improve code readability.

You can achieve your goals just as well with the PluginDict dictionary. That is defined as an alias for dict[str, str | tuple[str, ...]].

Methods:

• __call__ –

  Rebuild the original pytorch model from a given IR.

__call__(
    ir_root: DataGraph,
    registry: Registry[DataGraph],
    state_dict: dict[str, Any] | None = None,
) -> Module

Turn a vhdl prototype into a template.

Resulting template will have a parameter called entity that you can set to define the name of the represented entity. Replace constants/variables/generics with add_value().

Methods:

• add_value –

  add a parameter for a generic/constant/variable/signal.

add_value(name: str) -> EntityTemplateDirector

Bases: AnalysingTemplateParameter

Find the entity in vhdl code and make its name available as a template paramter.

Assumes that there is only one entity in the provided prototype.

NOTE: Will only replace occurences where name is followed and preceded by a non-word character, ie. for an entity named 'skeleton' the occurence 'architecture rtl of skeleton is' will be replaced by 'architecture rtl of $entity is' but the occurences 'skeleton_pkg', 'skeleton;', 'skeleton-' or skeleton. will remain unaltered. IMPORTANT: This detail is likely to change in the future.

Represents an entity that we can/want instantiate.

The aggregates all the knowledge that is necessary to instantiate and use the corresponding entity programmatically, when generating vhdl code.

Automatically creates Instances from VhdlNodes based on their type field.

Bases: Node, Protocol

Extending ir.core.Node to an hdl specific node.

This node contains all knowledge that we need to create and use an instance of an hdl component. However, this becomes a little bit complicated because vhdl differentiates between

Attributes:

implementation:: The name of the implementation, e.g., entity name in vhdl or module name for verilog, will be used to derive the architecture name. E.g., if the implementation is "adder", we will instantiate the entity work.adder(rtl). CAUTION: This behaviour is subject to change. Future versions might require the full entity name

Bases: PluginLoaderBase

PluginLoader for Ir2Vhdl passes.

• depth, width
• depth, width, height

Usually width is kernel_size, depth is channels

Bases: TemplateParameter

Find a value definition and make it settable via a template parameter.

Searches for vhdl value definitions of the form identifier : type or identifier : type := and transforms them into identifier : type := $identifier.

Essentially allows to replace generics as well as variable or signal initializations.

Represents a Verilog module instance.

Aggregates all knowledge necessary to instantiate and use a Verilog module programmatically when generating code.

Methods:

• define_signals –

  Generate wire definitions for all ports.

• instantiate –

  Generate Verilog module instantiation code.

define_signals() -> Iterator[str]

instantiate() -> Iterator[str]

Bases: Node, Protocol

Extending ir.core.Node to an hdl specific node.

This node contains all knowledge that we need to create and use an instance of an hdl component. However, this becomes a little bit complicated because vhdl differentiates between

Attributes:

implementation:: The name of the implementation, e.g., entity name in vhdl or module name for verilog, will be used to derive the architecture name. E.g., if the implementation is "adder", we will instantiate the entity work.adder(rtl). CAUTION: This behaviour is subject to change. Future versions might require the full entity name

Bases: PluginLoaderBase

PluginLoader for Ir2Verilog passes.

• depth, width
• depth, width, height

Usually width is kernel_size, depth is channels

Director for building verilog templates.

Most methods correspond to verilog language constructs. Building the final template can be expensive! Typically you only want to do this once. E.g.:

from string import Template
from elasticai.creator.ir2verilog import type_handler, Code, TemplateDirector, Implementation

class _ExplodingTemplate:
    def substitute(self, params):
        raise RuntimeError("Template not initialized!")

_template = None

@type_handler
def fir_filter(impl: Implementation) -> Code:
    global _template
    if _template is None:
        _template = (
            TemplateDirector()
            .define_scoped_switch("USE_EXT_WEIGHTS", False)
            .define_scoped_switch("USE_EXT_MAC", False)
            .parameter("BITWIDTH")
            .parameter("LENGTH")
            .localparam("FILT_COEFFS")
            .localparam("NUM_MULT_UNIT")
            .add_module_name()
            .set_prototype(res.read_text(package_path, "verilog/filter_fir_full.v"))
            .build()
        )
    return _template.substitute(impl.attributes)

Methods:

• define_scoped_switch –

  Add a switch for a define that is scoped to the module name.

define_scoped_switch(name: str, default: bool) -> Self

Bases: Protocol

Protocol defining the interface for HDL code generation.

This protocol is generic over the signal type to provide static type safety. When you create a VHDL generator, signals are typed as VHDL Signal objects. When you create a Verilog generator, signals are typed as Verilog BaseWire objects.

This prevents accidentally mixing VHDL signals with Verilog instances (and vice versa) at compile time, catching errors before runtime.

from elasticai.creator.hdl_generator import create_generator, HDLLanguage
from elasticai.creator.hdl_ir import Node, Shape

# Create a generator for VHDL - returns HDLGenerator[Signal]
vhdl_gen = create_generator(HDLLanguage.VHDL)

# Create signals - returns Signal (VHDL-specific type)
clk = vhdl_gen.create_signal("clk", width=1)
data_in = vhdl_gen.create_signal("data_in", width=8)

# Create a Verilog generator - returns HDLGenerator[BaseWire]
verilog_gen = create_generator(HDLLanguage.VERILOG)

# This would be a TYPE ERROR caught by the type checker:
# vhdl_gen.create_instance(ports={"clk": verilog_gen.create_signal("clk")})

Methods:

• create_instance –

  Create a module/entity instance.

• create_null_signal –

  Create a signal/wire that doesn't need definition.

• create_signal –

  Create a signal/wire.

• create_template_director –

  Create a template director for building HDL templates.

create_instance(
    node: Node,
    generics: dict[str, str] | None = None,
    ports: dict[str, TSignal] | None = None,
) -> HDLInstance

create_null_signal(name: str) -> TSignal

create_signal(name: str, width: int | None = None) -> TSignal

gen = VHDLGenerator()
clk = gen.create_signal("clk")  # Single bit
data = gen.create_signal("data", width=8)  # 8-bit vector

create_template_director() -> HDLTemplateDirector

gen = VHDLGenerator()

prototype_code = '''
entity adder is
    generic (WIDTH : natural := 8);
    port (
        a, b : in std_logic_vector(WIDTH-1 downto 0);
        sum : out std_logic_vector(WIDTH-1 downto 0)
    );
end entity;
'''

template = (
    gen.create_template_director()
    .set_prototype(prototype_code)
    .add_parameter("WIDTH")
    .build()
)

# Use the template
code = template.substitute(entity="my_adder", WIDTH="16")

Bases: Protocol

Protocol for HDL module/entity instances.

Represents either a VHDL entity instance or a Verilog module instance.

Methods:

• define_signals –

  Generate HDL code lines to define all signals/wires used by this instance.

• instantiate –

  Generate HDL code lines to instantiate this module/entity.

Attributes:

• implementation (str) –

  The name of the module/entity being instantiated.

• name (str) –

  The instance name.

implementation: str

name: str

define_signals() -> Iterator[str]

instantiate() -> Iterator[str]

Bases: Enum

Supported HDL languages.

Bases: Protocol

Protocol for HDL signals/wires.

Represents either a VHDL signal or a Verilog wire.

Methods:

• define –

  Generate HDL code lines to define this signal/wire.

• make_instance_specific –

  Create a signal/wire with an instance-specific name.

Attributes:

• name (str) –

  The name of the signal/wire.

name: str

define() -> Iterator[str]

make_instance_specific(instance: str) -> HDLSignal

Bases: Protocol

Protocol for HDL template directors.

Provides a builder interface for creating HDL templates from prototype code.

Methods:

• add_parameter –

  Add a template parameter (generic/parameter).

• build –

  Build the final template.

• set_prototype –

  Set the prototype HDL code to use as a template base.

add_parameter(name: str) -> HDLTemplateDirector

build() -> Template

set_prototype(prototype: str) -> HDLTemplateDirector

Bases: Node, Protocol

Extending ir.core.Node to an hdl specific node.

This node contains all knowledge that we need to create and use an instance of an hdl component. However, this becomes a little bit complicated because vhdl differentiates between

Attributes:

implementation:: The name of the implementation, e.g., entity name in vhdl or module name for verilog, will be used to derive the architecture name. E.g., if the implementation is "adder", we will instantiate the entity work.adder(rtl). CAUTION: This behaviour is subject to change. Future versions might require the full entity name

• depth, width
• depth, width, height

Usually width is kernel_size, depth is channels