najaeda 0.1.24__cp313-cp313t-macosx_11_0_arm64.whl → 0.1.25__cp313-cp313t-macosx_11_0_arm64.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 = []
@@ -571,18 +574,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 +649,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:
@@ -975,17 +979,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 +1325,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 +1337,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 +1347,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 +1356,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 +1365,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 +1392,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 +1403,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 +1414,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 +1448,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 +1481,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 +1514,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 +1526,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 +1537,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 +1551,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 +1569,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 +1631,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.1.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: najaeda
-Version: 0.1.24
+Version: 0.1.25
 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.1.25.dist-info}/RECORD

@@ -1,19 +1,19 @@
-najaeda-0.1.24.dist-info/RECORD,,
-najaeda-0.1.24.dist-info/WHEEL,sha256=K65AJzICMUVN6ED5A5fm1lV1nZZqwk4MGF2oXTxJaVw,115
-najaeda-0.1.24.dist-info/METADATA,sha256=lDGwE7Obzgqwy7l70oK7xEsyYsisAYE1pQJwvbcUV_A,3046
-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/netlist.py,sha256=ZFL00PMhc2pl_uu9_c3_lj65gSjD93zYvfbEFBLZhjg,54309
-najaeda/libnaja_nl.dylib,sha256=jORWEYW9nyFqhPabqspY2MnHdXNEPabSDQa4P9TYhpk,739824
+najaeda-0.1.25.dist-info/RECORD,,
+najaeda-0.1.25.dist-info/WHEEL,sha256=K65AJzICMUVN6ED5A5fm1lV1nZZqwk4MGF2oXTxJaVw,115
+najaeda-0.1.25.dist-info/METADATA,sha256=gX37lYtMJ59BpS-CtFKG2bq5UCCubzjLNxC8-Xp6Ipk,3384
+najaeda-0.1.25.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+najaeda-0.1.25.dist-info/licenses/AUTHORS,sha256=7NYEGDAX_1QZvCCHfq8YVXC5ZbwH_pbNI8DcSmm70GU,377
+najaeda/netlist.py,sha256=2h7Tbl3IsCqGDdylWiVX5u-E3yoWAVi6kNb7sS7JqtA,55809
+najaeda/libnaja_nl.dylib,sha256=5995NHdDOsc66W_7HN6dbyvBCqqY3l1u97f8CI4X7mo,738240
 najaeda/pandas_stats.py,sha256=yOb4ka965U7rN4D6AwvSGmRyeT_O7Ed-5cmT8BFbfeo,1070
 najaeda/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-najaeda/naja.so,sha256=rGhZnt9hLvIYqlrbPuujMaQO662xjGYaffH0hfuqnHo,99440
+najaeda/naja.so,sha256=DFFPgU5EOfyiK3j1azRi5l8M7GWtlEo09caPybr2zAM,99440
 najaeda/net_visitor.py,sha256=P_esjibYb-wBDuF-AyF7es9sJYw1Ha8RhTPu-qKe7G4,1940
-najaeda/libnaja_opt.dylib,sha256=5SAY5qqe7QALr2iZP8u8g3KN8Dn4qej9SrcL1hpE6iw,196416
-najaeda/libnaja_python.dylib,sha256=jAVOg8uYkm_wBeZin5AJgQI3W_dmpTL3uLc_1_JxfRY,925744
-najaeda/stats.py,sha256=wackXsf0x24ic9v-UifECHj4t5yveUWssMDZp2B057A,16187
+najaeda/libnaja_opt.dylib,sha256=DueaGAzPtgYg5Xn3eVl6cvCMpY2oj_SZqF3uV2iBHb8,212720
+najaeda/libnaja_python.dylib,sha256=r3WP4xrPu_GtfYYhedey2M5S2hXQCGsW0VltuHUFQ58,942752
+najaeda/stats.py,sha256=SJ9rca0Z6ldNAFOjU7DPO2hfx1zq-9Bec0Rx_oLasJo,16217
 najaeda/instance_visitor.py,sha256=JMsPSQaWNiDjxS05rxg83a0PIsrOIuTi9G35hkwdibs,1530
-najaeda/libnaja_bne.dylib,sha256=4lVFVXUHKBvqhK5bRnk4HEPvPqnrfH3q0mTtoB2FccY,136624
+najaeda/libnaja_bne.dylib,sha256=pLbGUnDr5PSGXbA8wKD-pqEyQIWHbiCb1icPpxRYrWE,136416
 najaeda/libnaja_dnl.dylib,sha256=zWsiT-RPDJz9koiDDUHqGNFzSFz7x2SmlIo5PTLkTUs,145936
 najaeda/native/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 najaeda/native/stats.py,sha256=t50hhE9pEFNtlssjES0A-K9TsO_2ZSUAb-e9L3Rt6yc,13063
@@ -30,7 +30,7 @@ najaeda/docs/source/examples.rst.in,sha256=4ZStOA3N5VHbKZgdn2kaEQZL7wPoJwODS2E1B
 najaeda/docs/source/common_classes.rst,sha256=o20u3mcpFYINwy0sVdye90ZPMQcPqoH3V4ERKcG7SZI,181
 najaeda/docs/source/equipotential.rst,sha256=0MDi-4fPEsX7K_ezWj5DB3mCalnhqN-sicYbQKYQfNc,335
 najaeda/docs/source/netlist_classes.rst,sha256=Zrha9MQVEdEwxmP2zhgC0K3iioZXXerzeFoOz5SrOXM,132
-najaeda/docs/source/introduction.rst,sha256=kE4qxEJCgcAswiT3rIJS21oBYIMg1cyT_rKmOzQgvsI,2095
+najaeda/docs/source/introduction.rst,sha256=nvxL5OQ-SeVWuTF6CY93iPt7S5ReXvqk5D9bW36CUUs,2416
 najaeda/docs/source/api.rst,sha256=47VCPyF4Py_1cklZ3q9fmOMhqqI17rxwU_VUJETfCwY,151
 najaeda/.dylibs/libcapnp-1.1.0.dylib,sha256=l9SvRdxPrCI2mB_UitO7QjsaC7I5mq2R3rZjoIQKEYI,709328
 najaeda/.dylibs/libtbbmalloc.2.15.dylib,sha256=ORLa9YDlOcMwtcYPZoVnNTTbBpL4lHwYcfA3YCJm_xA,126688