pyibis-ami 7.1.0__tar.gz → 7.2.0__tar.gz

{pyibis_ami-7.1.0/src/PyIBIS_AMI.egg-info → pyibis_ami-7.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pyibis-ami
-Version: 7.1.0
+Version: 7.2.0
 Summary: Facilitates working directly with IBIS-AMI DLLs from the Python command prompt.
 Author-email: David Banas <capn.freako@gmail.com>
 License: BSD

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0}/docs/source/conf.py

@@ -84,9 +84,11 @@ author = "David Banas"
 # built documents.
 #
 # The short X.Y version.
-version = "7.1"
+_ver = os.environ['PROJ_VER']
+# The short X.Y version.
+version = '.'.join(_ver.split('.')[0:2])
 # The full version, including alpha/beta/rc tags.
-release = "7.1.0"
+release = _ver
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "pyibis-ami"
 description = "Facilitates working directly with IBIS-AMI DLLs from the Python command prompt."
-version = "7.1.0"
+version = "7.2.0"
 authors = [ {name = "David Banas",     email = "capn.freako@gmail.com"}
           ]
 readme = "README.md"

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0/src/PyIBIS_AMI.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pyibis-ami
-Version: 7.1.0
+Version: 7.2.0
 Summary: Facilitates working directly with IBIS-AMI DLLs from the Python command prompt.
 Author-email: David Banas <capn.freako@gmail.com>
 License: BSD

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0}/src/PyIBIS_AMI.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ src/pyibisami/ami/generic.ibs.em
 src/pyibisami/ami/model.py
 src/pyibisami/ami/parameter.py
 src/pyibisami/ami/parser.py
+src/pyibisami/ami/reserved_parameter_names.py
 src/pyibisami/ibis/__init__.py
 src/pyibisami/ibis/file.py
 src/pyibisami/ibis/model.py

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0}/src/pyibisami/ami/model.py

@@ -481,7 +481,7 @@ class AMIModel:  # pylint: disable=too-many-instance-attributes
         ui = self.bit_time
         ts = self.sample_interval
         info_params = self.info_params
-        ignore_bits = info_params["Ignore_Bits"] if "Ignore_Bits" in info_params else 0
+        ignore_bits = info_params["Ignore_Bits"].pvalue if "Ignore_Bits" in info_params else 0
 
         # Capture/convert instance variables.
         chnl_imp = np.array(self.channel_response) * ts     # input (a.k.a. - "channel") impulse response (V/sample)

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0}/src/pyibisami/ami/parameter.py

@@ -23,65 +23,6 @@ class AMIParameter:  # pylint: disable=too-many-instance-attributes,too-few-publ
     parameter.
     """
 
-    RESERVED_PARAM_NAMES = [
-        "AMI_Version",
-        "Init_Returns_Impulse",
-        "GetWave_Exists",
-        "Use_Init_Output",
-        "Max_Init_Aggressors",
-        "Ignore_Bits",
-        "Resolve_Exists",
-        "Model_Name",
-        "Special_Param_Names",
-        "Component_Name",
-        "Signal_Name",
-        "Rx_Decision_Time",
-        "DC_Offset",
-        "Rx_Use_Clock_Input",
-        "Supporting_Files",
-        "DLL_Path",
-        "DLL_ID",
-        "Tx_Jitter",
-        "Tx_DCD",
-        "Tx_Rj",
-        "Tx_Dj",
-        "Tx_Sj",
-        "Tx_Sj_Frequency",
-        "Rx_DCD",
-        "Rx_Rj",
-        "Rx_Dj",
-        "Rx_Sj",
-        "Rx_Clock_PDF",
-        "Rx_Clock_Recovery_Mean",
-        "Rx_Clock_Recovery_Rj",
-        "Rx_Clock_Recovery_Dj",
-        "Rx_Clock_Recovery_Sj",
-        "Rx_Clock_Recovery_DCD",
-        "Rx_Receiver_Sensitivity",
-        "Rx_Noise",
-        "Rx_GaussianNoise",
-        "Rx_UniformNoise",
-        "Modulation",
-        "PAM4_Mapping",
-        "PAM4_UpperThreshold",
-        "PAM4_CenterThreshold",
-        "PAM4_LowerThreshold",
-        "PAM4_UpperEyeOffset",
-        "PAM4_CenterEyeOffset",
-        "PAM4_LowerEyeOffset",
-        "Repeater_Type",
-        "BCI_Protocol",
-        "BCI_ID",
-        "BCI_State",
-        "BCI_Message_Interval_UI",
-        "BCI_Training_UI",
-        "BCI_Training_Mode",
-        "Ts4file",
-        "Tx_V",
-        "Tx_R",
-        "Rx_R",
-    ]
-
     # Properties.
 
     # Note: They are read-only, despite the presence of apparent setters.

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0}/src/pyibisami/ami/parser.py

@@ -9,16 +9,18 @@ Copyright (c) 2019 David Banas; all rights reserved World wide.
 
 from ctypes         import c_double
 import re
-from typing         import Any, NewType, Optional, TypeAlias
+from typing         import Any, Callable, NewType, Optional, TypeAlias
 
+import numpy as np
 from numpy.typing import NDArray
 from parsec import ParseError, generate, many, regex, string
 from traits.api import Bool, Enum, HasTraits, Range, Trait, TraitType
 from traitsui.api import Group, HGroup, Item, VGroup, View
 from traitsui.menu import ModalButtons
 
-from pyibisami.ami.model     import AMIModelInitializer
-from pyibisami.ami.parameter import AMIParamError, AMIParameter
+from .model                     import AMIModelInitializer
+from .parameter                 import AMIParamError, AMIParameter
+from .reserved_parameter_names  import AmiReservedParameterName, RESERVED_PARAM_NAMES
 
 # New types and aliases.
 # Parameters  = NewType('Parameters',  dict[str, AMIParameter] | dict[str, 'Parameters'])
@@ -26,8 +28,25 @@ from pyibisami.ami.parameter import AMIParamError, AMIParameter
 # See: https://stackoverflow.com/questions/70894567/using-mypy-newtype-with-type-aliases-or-protocols
 ParamName  = NewType("ParamName", str)
 ParamValue:  TypeAlias = int | float | str | list["ParamValue"]
-Parameters:  TypeAlias = dict[ParamName, AMIParameter] | dict[ParamName, 'Parameters']
-ParamValues: TypeAlias = dict[ParamName, ParamValue]   | dict[ParamName, 'ParamValues']
+Parameters:  TypeAlias = dict[ParamName, "AMIParameter | 'Parameters'"]
+ParamValues: TypeAlias = dict[ParamName, "ParamValue   | 'ParamValues'"]
+
+AmiName = NewType("AmiName", str)
+AmiAtom: TypeAlias = bool | int | float | str
+AmiExpr: TypeAlias = "AmiAtom | 'AmiNode'"
+AmiNode: TypeAlias = tuple[AmiName, list[AmiExpr]]
+AmiNodeParser: TypeAlias = Callable[[str], AmiNode]
+AmiParser:     TypeAlias = Callable[[str], tuple[AmiName, list[AmiNode]]]  # Atoms may not exist at the root level.
+
+ParseErrMsg = NewType("ParseErrMsg", str)
+AmiRootName = NewType("AmiRootName", str)
+ReservedParamDict: TypeAlias = dict[AmiReservedParameterName, AMIParameter]
+ModelSpecificDict: TypeAlias = dict[ParamName, "AMIParameter | 'ModelSpecificDict'"]
+
+__all__ = [
+    "ParamName", "ParamValue", "Parameters", "ParamValues",
+    "AmiName", "AmiAtom", "AmiExpr", "AmiNode", "AmiNodeParser", "AmiParser",
+    "ami_parse", "AMIParamConfigurator"]
 
 #####
 # AMI parameter configurator.
@@ -77,25 +96,19 @@ class AMIParamConfigurator(HasTraits):
         # to get all the Traits/UI machinery setup correctly.
         super().__init__()
 
-        # Parse the AMI file contents, storing any errors or warnings,
-        # and customize the view accordingly.
-        err_str, param_dict = parse_ami_param_defs(ami_file_contents_str)
-        if not param_dict:
-            print("Empty dictionary returned by parse_ami_param_defs()!")
-            print(f"Error message:\n{err_str}")
-            raise KeyError("Failed to parse AMI file; see console for more detail.")
-        top_branch = list(param_dict.items())[0]
-        root_name  = top_branch[0]
-        param_dict = top_branch[1]
-        if "Reserved_Parameters" not in param_dict:
-            print(f"Error: {err_str}\nParameters: {param_dict}")
-            raise KeyError("Unable to get 'Reserved_Parameters' from the parameter set.")
-        if "Model_Specific" not in param_dict:
-            print(f"Error: {err_str}\nParameters: {param_dict}")
-            raise KeyError("Unable to get 'Model_Specific' from the parameter set.")
-        pdict = param_dict["Reserved_Parameters"].copy()
-        pdict.update(param_dict["Model_Specific"])
-        gui_items, new_traits = make_gui(pdict)
+        # Parse the AMI file contents, storing any errors or warnings, and customize the view accordingly.
+        err_str, root_name, description, reserved_param_dict, model_specific_dict = parse_ami_file_contents(ami_file_contents_str)
+        assert reserved_param_dict, ValueError(
+            "\n".join([
+                "No 'Reserved_Parameters' section found!",
+                err_str
+            ]))
+        assert model_specific_dict, ValueError(
+            "\n".join([
+                "No 'Model_Specific' section found!",
+                err_str
+            ]))
+        gui_items, new_traits = make_gui(model_specific_dict)
         trait_names = []
         for trait in new_traits:
             self.add_trait(trait[0], trait[1])
@@ -104,8 +117,9 @@ class AMIParamConfigurator(HasTraits):
         self._root_name = root_name
         self._ami_parsing_errors = err_str
         self._content = gui_items
-        self._param_dict = param_dict
-        self._info_dict = {name: p.pvalue for (name, p) in list(param_dict["Reserved_Parameters"].items())}
+        self._reserved_param_dict = reserved_param_dict
+        self._model_specific_dict = model_specific_dict
+        self._description = description
 
     def __call__(self):
         self.open_gui()
@@ -187,12 +201,13 @@ class AMIParamConfigurator(HasTraits):
         return self._ami_parsing_errors
 
     @property
-    def ami_param_defs(self) -> dict[ParamName, Any]:
+    def ami_param_defs(self) -> dict[str, ReservedParamDict | ModelSpecificDict]:
         """The entire AMI parameter definition dictionary.
 
         Should *not* be passed to ``AMIModelInitializer`` constructor!
         """
-        return self._param_dict
+        return {"Reserved_Parameters": self._reserved_param_dict,
+                "Model_Specific": self._model_specific_dict}
 
     @property
     def input_ami_params(self) -> ParamValues:
@@ -203,9 +218,9 @@ class AMIParamConfigurator(HasTraits):
         Should be passed to ``AMIModelInitializer`` constructor.
         """
 
-        res = {}
-        res[ParamName("root_name")] = self._root_name
-        params = self.ami_param_defs[ParamName("Model_Specific")]
+        res: ParamValues = {}
+        res[ParamName("root_name")] = str(self._root_name)
+        params = self._model_specific_dict
         for pname in params:
             res.update(self.input_ami_param(params, pname))
         return res
@@ -260,13 +275,13 @@ class AMIParamConfigurator(HasTraits):
     @property
     def info_ami_params(self):
         "Dictionary of *Reserved* AMI parameter values."
-        return self._info_dict
+        return self._reserved_param_dict
 
     def get_init(
         self,
         bit_time:         float,
         sample_interval:  float,
-        channel_response: NDArray[float],
+        channel_response: NDArray[np.longdouble],
         ami_params: Optional[dict[str, Any]] = None
     ) -> AMIModelInitializer:
         """
@@ -343,14 +358,25 @@ node_name = tap_ix ^ symbol  # `tap_ix` is new and gives the tap position; negat
 def node():
     "Parse AMI node."
     yield lparen
-    label = yield node_name
+    label  = yield node_name
     values = yield many(expr)
     yield rparen
     return (label, values)
 
 
+@generate("AMI file")
+def root():
+    "Parse AMI file."
+    yield lparen
+    label  = yield node_name
+    values = yield many(node)
+    yield rparen
+    return (label, values)
+
+
 expr = atom | node
-ami_defs = ignore >> node
+ami = ignore >> root
+ami_parse: AmiParser = ami.parse
 
 
 def proc_branch(branch):
@@ -428,102 +454,115 @@ def proc_branch(branch):
     return results
 
 
-def parse_ami_param_defs(param_str):  # pylint: disable=too-many-branches
-    """Parse the contents of a IBIS-AMI parameter definition file.
+def parse_ami_file_contents(  # pylint: disable=too-many-locals,too-many-branches
+    file_contents: str
+) -> tuple[ParseErrMsg, AmiRootName, str, ReservedParamDict, ModelSpecificDict]:
+    """
+    Parse the contents of an IBIS-AMI *parameter definition* (i.e. - `*.ami`) file.
 
     Args:
-        param_str (str): The contents of the file, as a single string.
+        file_contents: The contents of the file, as a single string.
 
     Example:
         ::
 
             with open(<ami_file_name>) as ami_file:
-                param_str = ami_file.read()
-                (err_str, param_dict) = parse_ami_param_defs(param_str)
+                file_contents = ami_file.read()
+                (err_str, root_name, reserved_param_dict, model_specific_param_dict) = parse_ami_file_contents(file_contents)
 
     Returns:
-        (str, dict): A pair containing:
-            err_str:
-                - None, if parser succeeds.
-                - Helpful message, if it fails.
-            param_dict: Dictionary containing parameter definitions.
-                (Empty, on failure.)
-                It has a single key, at the top level, which is the
-                model root name. This key indexes the actual
-                parameter dictionary, which has the following
-                structure::
-
-                    {
-                        'description'           :   <optional model description string>
-                        'Reserved_Parameters'   :   <dictionary of reserved parameter defintions>
-                        'Model_Specific'        :   <dictionary of model specific parameter definitions>
-                    }
-
-                The keys of the 'Reserved_Parameters' dictionary are
-                limited to those called out in the IBIS-AMI
-                specification.
-
-                The keys of the 'Model_Specific' dictionary can be
-                anything.
-
-                The values of both are either:
-                    - instances of class *AMIParameter*, or
-                    - sub-dictionaries following the same pattern.
+        A tuple containing
+
+            1. Any error message generated by the parser. (empty on success)
+
+            2. AMI file "root" name.
+
+            3. *Reserved Parameters* dictionary. (empty on failure)
+
+                - The keys of the *Reserved Parameters* dictionary are
+                limited to those called out in the IBIS-AMI specification.
+
+                - The values of the *Reserved Parameters* dictionary
+                must be instances of class ``AMIParameter``.
+
+            4. *Model Specific Parameters* dictionary. (empty on failure)
+
+                - The keys of the *Model Specific Parameters* dictionary can be anything.
+
+                - The values of the *Model Specific Parameters* dictionary
+                may be either: an instance of class ``AMIParameter``, or a nested sub-dictionary.
     """
     try:
-        res = ami_defs.parse(param_str)
+        res = ami_parse(file_contents)
     except ParseError as pe:
-        err_str = f"Expected {pe.expected} at {pe.loc()} in:\n{pe.text[pe.index:]}"
-        return err_str, {}
+        err_str = ParseErrMsg(f"Expected {pe.expected} at {pe.loc()} in:\n{pe.text[pe.index:]}")
+        return err_str, AmiRootName(""), "", {}, {}
 
     err_str, param_dict = proc_branch(res)
     if err_str:
-        return (err_str, {"res": res, "dict": param_dict})
+        return (err_str, AmiRootName(""), "", {}, {})
+    assert len(param_dict.keys()) == 1, ValueError(
+        f"Malformed AMI parameter S-exp has top-level keys: {param_dict.keys()}!")
 
     reserved_found = False
     init_returns_impulse_found = False
     getwave_exists_found = False
     model_spec_found = False
-    params = list(param_dict.items())[0][1]
+    root_name, params = list(param_dict.items())[0]
+    description = ""
+    reserved_params_dict = {}
+    model_specific_dict = {}
+    _err_str = ""
     for label in list(params.keys()):
+        tmp_params = params[label]
         if label == "Reserved_Parameters":
             reserved_found = True
-            tmp_params = params[label]
             for param_name in list(tmp_params.keys()):
-                if param_name not in AMIParameter.RESERVED_PARAM_NAMES:
-                    err_str += f"WARNING: Unrecognized reserved parameter name, '{param_name}', found in parameter definition string!\n"
+                if param_name not in RESERVED_PARAM_NAMES:
+                    _err_str += f"WARNING: Unrecognized reserved parameter name, '{param_name}', found in parameter definition string!\n"
                     continue
                 param = tmp_params[param_name]
                 if param.pname == "AMI_Version":
                     if param.pusage != "Info" or param.ptype != "String":
-                        err_str += "WARNING: Malformed 'AMI_Version' parameter.\n"
+                        _err_str += "WARNING: Malformed 'AMI_Version' parameter.\n"
                 elif param.pname == "Init_Returns_Impulse":
                     init_returns_impulse_found = True
                 elif param.pname == "GetWave_Exists":
                     getwave_exists_found = True
+            reserved_params_dict = tmp_params
         elif label == "Model_Specific":
             model_spec_found = True
+            model_specific_dict = tmp_params
         elif label == "description":
-            pass
+            description = str(tmp_params)
         else:
-            err_str += f"WARNING: Unrecognized group with label, '{label}', found in parameter definition string!\n"
+            _err_str += f"WARNING: Unrecognized group with label, '{label}', found in parameter definition string!\n"
 
     if not reserved_found:
-        err_str += "ERROR: Reserved parameters section not found! It is required."
+        _err_str += "ERROR: Reserved parameters section not found! It is required."
 
     if not init_returns_impulse_found:
-        err_str += "ERROR: Reserved parameter, 'Init_Returns_Impulse', not found! It is required."
+        _err_str += "ERROR: Reserved parameter, 'Init_Returns_Impulse', not found! It is required."
 
     if not getwave_exists_found:
-        err_str += "ERROR: Reserved parameter, 'GetWave_Exists', not found! It is required."
+        _err_str += "ERROR: Reserved parameter, 'GetWave_Exists', not found! It is required."
 
     if not model_spec_found:
-        err_str += "WARNING: Model specific parameters section not found!"
+        _err_str += "WARNING: Model specific parameters section not found!"
+
+    return (ParseErrMsg(_err_str), root_name, description, reserved_params_dict, model_specific_dict)
+
 
-    return (err_str, param_dict)
+# Legacy client code support:
+def parse_ami_param_defs(file_contents: str) -> tuple[ParseErrMsg, dict[str, Any]]:
+    "The legacy version of ``parse_ami_file_contents()``."
+    err_msg, root_name, description, reserved_params_dict, model_specific_dict = parse_ami_file_contents(file_contents)
+    return (err_msg, {root_name: {"description":         description,
+                                  "Reserved_Parameters": reserved_params_dict,
+                                  "Model_Specific":      model_specific_dict}})
 
 
-def make_gui(params: Parameters) -> tuple[Group, list[TraitType]]:
+def make_gui(params: ModelSpecificDict) -> tuple[Group, list[TraitType]]:
     """
     Builds top-level ``Group`` and list of ``Trait`` s from AMI parameter dictionary.
 

pyibis_ami-7.2.0/src/pyibisami/ami/reserved_parameter_names.py

@@ -0,0 +1,84 @@
+"""
+IBIS-AMI reserved parameter names, as a Python ``dataclass``.
+
+Original author: David Banas <capn.freako@gmail.com>
+
+Original date:   March 17, 2025
+
+Copyright (c) 2025 David Banas; all rights reserved World wide.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AmiReservedParameterName():
+    "IBIS-AMI Reserved Parameter Name"
+
+    pname: str
+
+    def __post_init__(self):
+        "Validate parameter name."
+
+        assert self.pname in RESERVED_PARAM_NAMES, ValueError(
+            f"Parameter name: {self.pname}, is not an IBIS-AMI reserved parameter name!")
+
+
+RESERVED_PARAM_NAMES = [
+    "AMI_Version",
+    "Init_Returns_Impulse",
+    "GetWave_Exists",
+    "Use_Init_Output",
+    "Max_Init_Aggressors",
+    "Ignore_Bits",
+    "Resolve_Exists",
+    "Model_Name",
+    "Special_Param_Names",
+    "Component_Name",
+    "Signal_Name",
+    "Rx_Decision_Time",
+    "DC_Offset",
+    "Rx_Use_Clock_Input",
+    "Supporting_Files",
+    "DLL_Path",
+    "DLL_ID",
+    "Tx_Jitter",
+    "Tx_DCD",
+    "Tx_Rj",
+    "Tx_Dj",
+    "Tx_Sj",
+    "Tx_Sj_Frequency",
+    "Rx_DCD",
+    "Rx_Rj",
+    "Rx_Dj",
+    "Rx_Sj",
+    "Rx_Clock_PDF",
+    "Rx_Clock_Recovery_Mean",
+    "Rx_Clock_Recovery_Rj",
+    "Rx_Clock_Recovery_Dj",
+    "Rx_Clock_Recovery_Sj",
+    "Rx_Clock_Recovery_DCD",
+    "Rx_Receiver_Sensitivity",
+    "Rx_Noise",
+    "Rx_GaussianNoise",
+    "Rx_UniformNoise",
+    "Modulation",
+    "PAM4_Mapping",
+    "PAM4_UpperThreshold",
+    "PAM4_CenterThreshold",
+    "PAM4_LowerThreshold",
+    "PAM4_UpperEyeOffset",
+    "PAM4_CenterEyeOffset",
+    "PAM4_LowerEyeOffset",
+    "Repeater_Type",
+    "BCI_Protocol",
+    "BCI_ID",
+    "BCI_State",
+    "BCI_Message_Interval_UI",
+    "BCI_Training_UI",
+    "BCI_Training_Mode",
+    "Ts4file",
+    "Tx_V",
+    "Tx_R",
+    "Rx_R",
+]

{pyibis_ami-7.1.0 → pyibis_ami-7.2.0}/src/pyibisami/common.py

@@ -20,8 +20,10 @@ Cvec: TypeAlias = npt.NDArray[Comp]
 PI:    float = 3.141592653589793238462643383279502884
 TWOPI: float = 2.0 * PI
 
-TestConfig: TypeAlias = tuple[str, tuple[dict[str, Any], dict[str, Any]]]
-TestSweep:  TypeAlias = tuple[str, str, list[TestConfig]]
+# TestConfig: TypeAlias = tuple[str, tuple[dict[str, Any], dict[str, Any]]]
+# TestSweep:  TypeAlias = tuple[str, str, list[TestConfig]]
+TestConfig = tuple[str, tuple[dict[str, Any], dict[str, Any]]]
+TestSweep = tuple[str, str, list[TestConfig]]
 
 
 def deconv_same(y: Rvec, x: Rvec) -> Rvec: