najaeda 0.1.24__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl → 0.2.0__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

najaeda/docs/source/introduction.rst

@@ -23,8 +23,7 @@ With **najaeda**, it is possible to:
 * **Prototype EDA Ideas Quickly**:
     * Use an intuitive API to experiment with new EDA concepts and workflows.
 * **Develop Custom EDA Tools**:
-    * Build fast, tailored tools for solving specific challenges
-    without relying on costly, proprietary EDA software.
+    * Build fast, tailored tools for solving specific challenges without relying on costly, proprietary EDA software.
 
 **najaeda** empowers developers to innovate, adapt, and accelerate
 their EDA processes with minimal overhead.
@@ -34,6 +33,15 @@ Information about the **najaeda** PyPI package is available at https://pypi.org/
 If you want more details about the underlying **naja** C++ library,
 please visit the **naja** GitHub repository at https://github.com/najaeda/naja .
 
+Quick Start
+===========
+
+To get started with **najaeda**, try out the interactive notebook in Google Colab:
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+   :target: https://colab.research.google.com/github/najaeda/najaeda-tutorials/blob/main/notebooks/01_getting_started.ipynb
+   :alt: Open in Colab
+
 Installation
 ------------
 **najaeda** can be easily installed using pip:

najaeda/netlist.py

@@ -12,6 +12,7 @@ import sys
 import os
 from enum import Enum
 from typing import Union, List
+from dataclasses import dataclass
 
 from najaeda import naja
 
@@ -428,9 +429,11 @@ def get_snl_term_for_ids_with_path(path, termIDs):
 
 
 class Term:
-    INPUT = naja.SNLTerm.Direction.Input
-    OUTPUT = naja.SNLTerm.Direction.Output
-    INOUT = naja.SNLTerm.Direction.InOut
+    class Direction(Enum):
+        """Enum for the direction of a term."""
+        INPUT = naja.SNLTerm.Direction.Input
+        OUTPUT = naja.SNLTerm.Direction.Output
+        INOUT = naja.SNLTerm.Direction.InOut
 
     def __init__(self, path, term):
         # self.termIDs = []
@@ -472,16 +475,18 @@ class Term:
     def __str__(self):
         term_str = ""
         path = get_snl_path_from_id_list(self.pathIDs)
+        snl_term = get_snl_term_for_ids(self.pathIDs, self.termIDs)
+        snl_term_str = snl_term.getName()
+        if snl_term.isUnnamed():
+            snl_term_str = "<unnamed>"
         if path.size() == 0:
-            term_str = get_snl_term_for_ids(self.pathIDs, self.termIDs).getName()
+            term_str = snl_term_str
         else:
-            term_str = (
-                f"{path}/{get_snl_term_for_ids(self.pathIDs, self.termIDs).getName()}"
-            )
+            term_str = f"{path}/{snl_term_str}"
         if self.is_bus():
             term_str += f"[{self.get_msb()}:{self.get_lsb()}]"
         elif self.is_bus_bit():
-            term_str += f"[{self.get_lsb()}]"
+            term_str += f"[{self.get_msb()}]"
         return term_str
 
     def __repr__(self) -> str:
@@ -571,18 +576,18 @@ class Term:
         """
         return get_snl_term_for_ids(self.pathIDs, self.termIDs).getName()
 
-    def get_direction(self) -> naja.SNLTerm.Direction:
+    def get_direction(self) -> Direction:
         """
         :return: the direction of the term.
-        :rtype: naja.SNLTerm.Direction
+        :rtype: Term.Direction
         """
         snlterm = get_snl_term_for_ids(self.pathIDs, self.termIDs)
         if snlterm.getDirection() == naja.SNLTerm.Direction.Input:
-            return Term.INPUT
+            return Term.Direction.INPUT
         elif snlterm.getDirection() == naja.SNLTerm.Direction.Output:
-            return Term.OUTPUT
+            return Term.Direction.OUTPUT
         elif snlterm.getDirection() == naja.SNLTerm.Direction.InOut:
-            return Term.INOUT
+            return Term.Direction.INOUT
 
     def __get_snl_bitnet(self, bit) -> Net:
         # single bit
@@ -646,6 +651,7 @@ class Term:
         """
         :return: the net of the term.
         :rtype: Net
+        :remark: If the term is a top level term, it will return None.
         """
         head_path = self.pathIDs.copy()
         if len(head_path) == 0:
@@ -881,7 +887,7 @@ class Instance:
         the wire a to the output of the assign and b to the input.
 
         :return: True if this is an assign. Assigns are represented with
-        anonymous Assign instances.
+        unnamed Assign instances.
         :rtype: bool
         """
         return self.__get_snl_model().isAssign()
@@ -975,17 +981,25 @@ class Instance:
     def dump_context_dot(self, path: str):
         self.__get_snl_model().dumpContextDotFile(path)
 
-    def get_child_instance(self, name: str):
+    def get_child_instance(self, names: Union[str, list]):
         """
-        :param str name: the name of the child Instance to get.
-        :return: the child Instance with the given name or None if it does not exist.
+        :param names: the name of the child instance
+            or the path to the child Instance as a list of names.
+        :return: the child Instance at the given path or None if it does not exist.
         :rtype: Instance or None
         """
-        childInst = self.__get_snl_model().getInstance(name)
-        if childInst is None:
-            return None
+        if isinstance(names, str):
+            names = [names]
+        if not names:
+            raise ValueError("Names argument cannot be empty")
+        model = self.__get_snl_model()
         path = self.pathIDs.copy()
-        path.append(childInst.getID())
+        for name in names:
+            childInst = model.getInstance(name)
+            if childInst is None:
+                return None
+            path.append(childInst.getID())
+            model = childInst.getModel()
         return Instance(path)
 
     def get_child_instances(self):
@@ -1313,11 +1327,11 @@ class Instance:
         path = naja.SNLPath(path, newSNLInstance)
         return Instance(path)
 
-    def create_term(self, name: str, direction: naja.SNLTerm.Direction) -> Term:
+    def create_term(self, name: str, direction: Term.Direction) -> Term:
         """Create a Term in this Instance with the given name and direction.
 
         :param str name: the name of the Term to create.
-        :param naja.SNLTerm.Direction direction: the direction of the Term to create.
+        :param Term.Direction direction: the direction of the Term to create.
         :return: the created Term.
         """
         path = get_snl_path_from_id_list(self.pathIDs)
@@ -1325,7 +1339,7 @@ class Instance:
             naja.SNLUniquifier(path)
             path = get_snl_path_from_id_list(self.pathIDs)
         design = self.__get_snl_model()
-        newSNLTerm = naja.SNLScalarTerm.create(design, direction, name)
+        newSNLTerm = naja.SNLScalarTerm.create(design, direction.value, name)
         return Term(path.getPathIDs(), newSNLTerm)
 
     def create_output_term(self, name: str) -> Term:
@@ -1335,7 +1349,7 @@ class Instance:
         :return: the created Term.
         :rtype: Term
         """
-        return self.create_term(name, naja.SNLTerm.Direction.Output)
+        return self.create_term(name, Term.Direction.OUTPUT)
 
     def create_input_term(self, name: str) -> Term:
         """Create an input Term in this Instance with the given name.
@@ -1344,7 +1358,7 @@ class Instance:
         :return: the created Term.
         :rtype: Term
         """
-        return self.create_term(name, naja.SNLTerm.Direction.Input)
+        return self.create_term(name, Term.Direction.INPUT)
 
     def create_inout_term(self, name: str) -> Term:
         """Create an inout Term in this Instance with the given name.
@@ -1353,22 +1367,22 @@ class Instance:
         :return: the created Term.
         :rtype: Term
         """
-        return self.create_term(name, naja.SNLTerm.Direction.InOut)
+        return self.create_term(name, Term.Direction.INOUT)
 
-    def create_bus_term(self, name: str, msb: int, lsb: int, direction) -> Term:
+    def create_bus_term(self, name: str, msb: int, lsb: int, direction: Term.Direction) -> Term:
         """Create a bus Term in this Instance with the given name, msb, lsb and direction.
 
         :param str name: the name of the Term to create.
         :param int msb: the most significant bit of the Term to create.
         :param int lsb: the least significant bit of the Term to create.
-        :param naja.SNLTerm.Direction direction: the direction of the Term to create.
+        :param Term.Direction direction: the direction of the Term to create.
         :return: the created Term.
         """
         path = get_snl_path_from_id_list(self.pathIDs)
         if path.size() > 0:
             naja.SNLUniquifier(path)
         design = self.__get_snl_model()
-        newSNLTerm = naja.SNLBusTerm.create(design, direction, msb, lsb, name)
+        newSNLTerm = naja.SNLBusTerm.create(design, direction.value, msb, lsb, name)
         return Term(self.pathIDs, newSNLTerm)
 
     def create_inout_bus_term(self, name: str, msb: int, lsb: int) -> Term:
@@ -1380,7 +1394,7 @@ class Instance:
         :return: the created Term.
         :rtype: Term
         """
-        return self.create_bus_term(name, msb, lsb, naja.SNLTerm.Direction.InOut)
+        return self.create_bus_term(name, msb, lsb, Term.Direction.INOUT)
 
     def create_output_bus_term(self, name: str, msb: int, lsb: int) -> Term:
         """Create an output bus Term in this Instance with the given name, msb and lsb.
@@ -1391,7 +1405,7 @@ class Instance:
         :return: the created Term.
         :rtype: Term
         """
-        return self.create_bus_term(name, msb, lsb, naja.SNLTerm.Direction.Output)
+        return self.create_bus_term(name, msb, lsb, Term.Direction.OUTPUT)
 
     def create_input_bus_term(self, name: str, msb: int, lsb: int) -> Term:
         """Create an input bus Term in this Instance with the given name, msb and lsb.
@@ -1402,7 +1416,7 @@ class Instance:
         :return: the created Term.
         :rtype: Term
         """
-        return self.create_bus_term(name, msb, lsb, naja.SNLTerm.Direction.Input)
+        return self.create_bus_term(name, msb, lsb, Term.Direction.INPUT)
 
     def create_net(self, name: str) -> Net:
         """Create a scalar Net in this Instance with the given name.
@@ -1436,13 +1450,21 @@ class Instance:
         newSNLNet = naja.SNLBusNet.create(model, msb, lsb, name)
         return Net(path, newSNLNet)
 
-    def dump_verilog(self, path: str, name: str):
+    def dump_verilog(self, path: str):
         """Dump the verilog of this instance.
 
-        :param str path: the path where to dump the verilog.
-        :param str name: the name of the verilog file.
+        :param str path: the file path where to dump the verilog.
+        :rtype: None
+        :raises ValueError: if the path does not end with .v.
+        :raises FileNotFoundError: if the directory of the path does not exist.
         """
-        self.__get_snl_model().dumpVerilog(path, name)
+        # path should be a file path of the form "path/to/file.v"
+        if not path.endswith(".v"):
+            raise ValueError("The path must end with .v")
+        dir_path = os.path.dirname(path) or "."
+        if not os.path.exists(dir_path):
+            raise FileNotFoundError(f"The directory {dir_path} does not exist")
+        self.__get_snl_model().dumpVerilog(dir_path, os.path.basename(path))
 
     def get_truth_table(self):
         """
@@ -1461,6 +1483,15 @@ def __get_top_db() -> naja.NLDB:
     return naja.NLUniverse.get().getTopDB()
 
 
+def reset():
+    """Reset the environment by deleting everything.
+    :rtype: None
+    """
+    u = naja.NLUniverse.get()
+    if u is not None:
+        u.destroy()
+
+
 def get_top():
     """
     :return: the top Instance.
@@ -1485,9 +1516,10 @@ def create_top(name: str) -> Instance:
     return Instance()
 
 
+@dataclass
 class VerilogConfig:
-    def __init__(self, keep_assigns=True):
-        self.keep_assigns = keep_assigns
+    keep_assigns: bool = True
+    allow_unknown_designs: bool = False
 
 
 def load_verilog(files: Union[str, List[str]], config: VerilogConfig = None) -> Instance:
@@ -1496,6 +1528,8 @@ def load_verilog(files: Union[str, List[str]], config: VerilogConfig = None) ->
     :param files: a list of verilog files to load or a single file.
     :param config: the configuration to use when loading the files.
     :return: the top Instance.
+    :rtype: Instance
+    :raises Exception: if no files are provided.
     """
     if isinstance(files, str):
         files = [files]
@@ -1505,7 +1539,11 @@ def load_verilog(files: Union[str, List[str]], config: VerilogConfig = None) ->
         config = VerilogConfig()  # Use default settings
     start_time = time.time()
     logging.info(f"Loading verilog: {', '.join(files)}")
-    __get_top_db().loadVerilog(files, keep_assigns=config.keep_assigns)
+    __get_top_db().loadVerilog(
+        files,
+        keep_assigns=config.keep_assigns,
+        allow_unknown_designs=config.allow_unknown_designs
+    )
     execution_time = time.time() - start_time
     logging.info(f"Loading done in {execution_time:.2f} seconds")
     return get_top()
@@ -1515,6 +1553,8 @@ def load_liberty(files: Union[str, List[str]]):
     """Load liberty files.
 
     :param files: a list of liberty files to load or a single file.
+    :rtype: None
+    :raises Exception: if no liberty files are provided.
     """
     if isinstance(files, str):
         files = [files]
@@ -1531,6 +1571,9 @@ def load_primitives(name: str):
 
     - xilinx
     - yosys
+    :param str name: the name of the primitives library to load.
+    :raises ValueError: if the name is not recognized.
+    :rtype: None
     """
     if name == "xilinx":
         from najaeda.primitives import xilinx
@@ -1590,14 +1633,18 @@ def get_model_name(id: tuple[int, int, int]) -> str:
 
 
 def apply_dle():
-    """Apply the DLE (Dead Logic Elimination) to the top design."""
+    """Apply the DLE (Dead Logic Elimination) to the top design.
+    :rtype: None
+    """
     top = naja.NLUniverse.get().getTopDesign()
     if top is not None:
         naja.NLUniverse.get().applyDLE()
 
 
 def apply_constant_propagation():
-    """Apply constant propagation to the top design."""
+    """Apply constant propagation to the top design.
+    :rtype: None
+    """
     top = naja.NLUniverse.get().getTopDesign()
     if top is not None:
         naja.NLUniverse.get().applyConstantPropagation()

najaeda/stats.py

@@ -207,19 +207,19 @@ def compute_instance_stats(instance, instances_stats):
 
 def compute_instance_terms(instance, instance_stats):
     for term in instance.get_terms():
-        if term.get_direction() == netlist.Term.INPUT:
+        if term.get_direction() == netlist.Term.Direction.INPUT:
             instance_stats.terms["inputs"] = instance_stats.terms.get("inputs", 0) + 1
             bit_terms = sum(1 for _ in term.get_bits())
             instance_stats.bit_terms["inputs"] = (
                 instance_stats.bit_terms.get("inputs", 0) + bit_terms
             )
-        elif term.get_direction() == netlist.Term.OUTPUT:
+        elif term.get_direction() == netlist.Term.Direction.OUTPUT:
             instance_stats.terms["outputs"] = instance_stats.terms.get("outputs", 0) + 1
             bit_terms = sum(1 for _ in term.get_bits())
             instance_stats.bit_terms["outputs"] = (
                 instance_stats.bit_terms.get("outputs", 0) + bit_terms
             )
-        elif term.get_direction() == netlist.Term.INOUT:
+        elif term.get_direction() == netlist.Term.Direction.INOUT:
             instance_stats.terms["inouts"] = instance_stats.terms.get("inouts", 0) + 1
             bit_terms = sum(1 for _ in term.get_bits())
             instance_stats.bit_terms["inouts"] = (

{najaeda-0.1.24.dist-info → najaeda-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: najaeda
-Version: 0.1.24
+Version: 0.2.0
 Summary: Naja EDA Python package
 Author-Email: Naja Authors <contact@keplertech.io>
 License: Apache License 2.0
@@ -19,16 +19,16 @@ Project-URL: Homepage, https://github.com/najaeda/naja
 Requires-Python: >=3.8
 Description-Content-Type: text/x-rst
 
-Naja EDA Python Package
+najaeda Python Package
 =======================
 
-Naja EDA is a Python package that provides data structures and APIs for developing post-synthesis Electronic Design Automation (EDA) algorithms.
+najaeda is a Python package that provides data structures and APIs for developing post-synthesis Electronic Design Automation (EDA) algorithms.
 
-Naja EDA provides a powerful yet simple framework designed to help software
+najaeda provides a powerful yet simple framework designed to help software
 and hardware developers efficiently navigate and manipulate electronic
 design automation (EDA) workflows.
 
-With Naja EDA, you can:
+With najaeda, you can:
 
 * Explore Netlists with Ease:
 
@@ -51,10 +51,10 @@ With Naja EDA, you can:
 
   * Build fast, tailored tools for solving specific challenges without relying on costly, proprietary EDA software.
 
-Naja EDA empowers developers to innovate, adapt, and accelerate their EDA
+najaeda empowers developers to innovate, adapt, and accelerate their EDA
 processes with minimal overhead.
 
-Naja EDA is the Python counterpart of the `Naja C++ project <https://github.com/najaeda/naja>`_.
+najaeda is the Python counterpart of the `Naja C++ project <https://github.com/najaeda/naja>`_.
 
 If you’re interested in this project, please consider starring it on GitHub.
 Feel free to reach out to us anytime at `contact@keplertech.io <mailto:contact@keplertech.io>`_.
@@ -68,6 +68,15 @@ Install Naja EDA using pip:
 
     pip install najaeda
 
+Quick Start
+-----------
+
+To quickly explore what **najaeda** can do, launch the interactive tutorial notebook on Google Colab:
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+   :target: https://colab.research.google.com/github/najaeda/najaeda-tutorials/blob/main/notebooks/01_getting_started.ipynb
+   :alt: Open in Colab
+
 Documentation
 -------------
 

{najaeda-0.1.24.dist-info → najaeda-0.2.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-najaeda-0.1.24.dist-info/WHEEL,sha256=qWe43I_ziyqlu2SouxbZAN4VQzvapKrxWUcRsva4KM8,158
-najaeda-0.1.24.dist-info/METADATA,sha256=lDGwE7Obzgqwy7l70oK7xEsyYsisAYE1pQJwvbcUV_A,3046
-najaeda-0.1.24.dist-info/RECORD,,
-najaeda-0.1.24.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-najaeda-0.1.24.dist-info/licenses/AUTHORS,sha256=7NYEGDAX_1QZvCCHfq8YVXC5ZbwH_pbNI8DcSmm70GU,377
-najaeda/libnaja_python.so,sha256=W5b4kuolBGgBGsdrapX1k0mDgCN4FcIOTCe--cXyMJg,1885729
-najaeda/libnaja_nl.so,sha256=jo5MHqPetOFnO5VElmM1bXtna9lk1RCuiU_ScPF97ak,1646832
-najaeda/naja.so,sha256=jt9wzlm-8EnhndE2JYkOpZCZKFwM8n73aDKl5GSWS50,206521
+najaeda-0.2.0.dist-info/WHEEL,sha256=qWe43I_ziyqlu2SouxbZAN4VQzvapKrxWUcRsva4KM8,158
+najaeda-0.2.0.dist-info/METADATA,sha256=641yOlolPMHaHlGtIdpSZj-Z_UMRIPQIQaMGqdoFlns,3383
+najaeda-0.2.0.dist-info/RECORD,,
+najaeda-0.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+najaeda-0.2.0.dist-info/licenses/AUTHORS,sha256=7NYEGDAX_1QZvCCHfq8YVXC5ZbwH_pbNI8DcSmm70GU,377
+najaeda/libnaja_python.so,sha256=ONio-iM7c0wZWYQguNMeRRtsHNL1d6Jfh8eKp4VTd8E,1886289
+najaeda/libnaja_nl.so,sha256=1hb7dG4c3T9nu-tne4xKQBP7aBysGi8XBULYgGO4WLc,1646856
+najaeda/naja.so,sha256=WULLz9EYYjyorxBQw7jjvvMzNiHdeFGa2YZJ5r8ACYI,206521
 najaeda/pandas_stats.py,sha256=yOb4ka965U7rN4D6AwvSGmRyeT_O7Ed-5cmT8BFbfeo,1070
-najaeda/stats.py,sha256=wackXsf0x24ic9v-UifECHj4t5yveUWssMDZp2B057A,16187
-najaeda/libnaja_bne.so,sha256=41X1JqKAY6ydVaLZ6NI1qSJgC1MBcIkrCLq0z5nCjNU,272577
+najaeda/stats.py,sha256=SJ9rca0Z6ldNAFOjU7DPO2hfx1zq-9Bec0Rx_oLasJo,16217
+najaeda/libnaja_bne.so,sha256=ejZf2Zl2AXQagN41HIj8x-3oeoyEffcPTPR0YeY40ng,272577
 najaeda/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-najaeda/libnaja_opt.so,sha256=l7VnRKnJRRy7IVVNTNjXILZrpgYFes6IlCJ0wK1dOAA,348881
-najaeda/netlist.py,sha256=ZFL00PMhc2pl_uu9_c3_lj65gSjD93zYvfbEFBLZhjg,54309
+najaeda/libnaja_opt.so,sha256=OaKUGukDZekGp-yF__ZWbBpF1cnvvtEFzbaRMegzp8M,348713
+najaeda/netlist.py,sha256=by21s-ZgGPYunPDHDmnuAA8E_Z9ZRD5tbyck5NrwoxI,55865
 najaeda/net_visitor.py,sha256=P_esjibYb-wBDuF-AyF7es9sJYw1Ha8RhTPu-qKe7G4,1940
 najaeda/libnaja_dnl.so,sha256=zkSbBWj0qCH6wE2gueif9tKoj6xrN7p9Gk01pHUkGBE,276041
 najaeda/instance_visitor.py,sha256=JMsPSQaWNiDjxS05rxg83a0PIsrOIuTi9G35hkwdibs,1530
@@ -26,7 +26,7 @@ najaeda/docs/source/netlist_classes.rst,sha256=Zrha9MQVEdEwxmP2zhgC0K3iioZXXerze
 najaeda/docs/source/examples.rst.in,sha256=4ZStOA3N5VHbKZgdn2kaEQZL7wPoJwODS2E1BO54uFY,2091
 najaeda/docs/source/equipotential.rst,sha256=0MDi-4fPEsX7K_ezWj5DB3mCalnhqN-sicYbQKYQfNc,335
 najaeda/docs/source/preprocessor.py,sha256=TK4LsTdNbv2dxkKQaJ7cEyo9PU5v_56vlrFCJYIPKf8,2625
-najaeda/docs/source/introduction.rst,sha256=kE4qxEJCgcAswiT3rIJS21oBYIMg1cyT_rKmOzQgvsI,2095
+najaeda/docs/source/introduction.rst,sha256=nvxL5OQ-SeVWuTF6CY93iPt7S5ReXvqk5D9bW36CUUs,2416
 najaeda/docs/source/common_classes.rst,sha256=o20u3mcpFYINwy0sVdye90ZPMQcPqoH3V4ERKcG7SZI,181
 najaeda/docs/source/net.rst,sha256=i6YEir8ZOldSY8-UmPxgVJ4Ot3y-Q6seRkBr2H-KmXc,732
 najaeda/docs/source/index.rst,sha256=80VMfeEGHObnOUXRBxIzISQsG_HNkgT-pUpsDZsCfOY,387