pyibis-ami 7.1.0__py3-none-any.whl

pyibisami/__init__.py

@@ -0,0 +1,22 @@
+"""A package of Python modules, used to configure and test IBIS-AMI models.
+
+.. moduleauthor:: David Banas <capn.freako@gmail.com>
+
+Original Author: David Banas <capn.freako@gmail.com>
+
+Original Date:   3 July 2012
+
+Copyright (c) 2012 by David Banas; All rights reserved World wide.
+"""
+
+from importlib.metadata import version as _get_version
+
+# Set PEP396 version attribute
+try:
+    __version__ = _get_version("PyIBIS-AMI")
+except Exception as err:  # pylint: disable=broad-exception-caught
+    __version__ = f"{err} (dev)"
+
+__date__ = "October 12, 2023"
+__authors__ = "David Banas & David Patterson"
+__copy__ = "Copyright (c) 2012 David Banas, 2019 David Patterson"

pyibisami/__main__.py

@@ -0,0 +1,7 @@
+"""A package of Python modules, used to configure and test IBIS-AMI models."""
+
+print("pyibisami is a package of sub-modules, and is not directly executable.")
+print("Perhaps, you meant:")
+print("    - pyibisami.ami.config")
+print("    - pyibisami.tools.run_tests")
+raise RuntimeError("pyibisami is not executable.")

pyibisami/ami/config.py

@@ -0,0 +1,297 @@
+#! /usr/bin/env python
+
+"""IBIS-AMI model source code, AMI file, and IBIS file configuration utility.
+
+Original author: David Banas
+
+Original date:   February 26, 2016
+
+Copyright (c) 2016 David Banas; all rights reserved World wide.
+
+**Note:** The following use model has been deprecated!
+The preferred approach is to make *executable* model configurators,
+which draw what they need from this module.
+
+This script gets called from a makefile, when any of the following need rebuilding:
+
+* a C++ source code file
+* a ``*.AMI`` file
+* a ``*.IBS`` file
+* a ``*.TST`` file (a dummy place-holder indicating that the test run config. files have been made)
+
+All files will be rebuilt.
+(We rebuild all files, because it doesn't take very long, and we can
+ensure consistency this way.)
+
+This gets triggered by one of two things:
+
+#. The common model configuration information has changed, or
+#. One of the EmPy template files was updated.
+
+The idea here is that the ``*.IBS`` file, the ``*.AMI`` file, the C++ source file,
+and the test run configuration files should be configured from a common model
+configuration file, so as to ensure consistency between them all.
+"""
+
+import importlib.util
+from datetime import date
+from pathlib import Path
+from typing import Any, NewType
+
+import click
+import em
+
+ParamDict      = NewType("ParamDict",      dict[str, Any])
+NamedParamDict = NewType("NamedParamDict", tuple[str, ParamDict])
+TestDefinition = NewType("TestDefinition", tuple[str, NamedParamDict, NamedParamDict, str])
+
+param_types = {
+    "INT": {"c_type": "int", "ami_type": "Integer", "getter": "get_param_int"},
+    "FLOAT": {"c_type": "double", "ami_type": "Float", "getter": "get_param_float"},
+    "TAP": {"c_type": "double", "ami_type": "Tap", "getter": "get_param_float"},
+    "BOOL": {"c_type": "bool", "ami_type": "Boolean", "getter": "get_param_bool"},
+    "STRING": {"c_type": "char *", "ami_type": "String", "getter": "get_param_str"},
+}
+
+
+def print_param(indent, name, param):  # pylint: disable=too-many-branches
+    """Print AMI parameter specification. Handle nested parameters, via
+    recursion.
+
+    Args:
+        indent (str): String containing some number of spaces.
+        name (str): Parameter name.
+        param (dict): Dictionary containing parameter definition fields.
+    """
+
+    print(indent, f"({name}")
+    if "subs" in param:
+        for key in param["subs"]:
+            print_param(indent + "    ", key, param["subs"][key])
+        if "description" in param:
+            print(indent + "    ", f"(Description {param['description']})")
+    else:
+        for fld_name, fld_key in [
+            ("Usage", "usage"),
+            ("Type", "type"),
+            ("Format", "format"),
+            ("Default", "default"),
+            ("Description", "description"),
+        ]:
+            # Trap the special cases.
+            if fld_name == "Type":
+                print(indent, "    (Type", param_types[param["type"]]["ami_type"], ")")
+            elif fld_name == "Default":
+                if param["format"] == "Value":
+                    pass
+            elif fld_name == "Format":
+                if param["format"] == "Value":
+                    print(indent, "    (Value", param["default"], ")")
+                elif param["format"] == "List":
+                    print(indent, "    (List", end=" ")
+                    for item in param["values"]:
+                        print(item, end=" ")
+                    print(")")
+                    print(indent, "    (List_Tip", end=" ")
+                    for item in param["labels"]:
+                        print(item, end=" ")
+                    print(")")
+                else:
+                    print(indent, f"    ({param['format']}", param["default"], param["min"], param["max"], ")")
+            # Execute the default action.
+            else:
+                print(indent, f"    ({fld_name}", param[fld_key], ")")
+    print(indent, ")")
+
+
+def print_code(pname, param):
+    """Print C++ code needed to query AMI parameter tree for a particular leaf.
+
+    Args:
+        pname (str): Parameter name.
+        param (dict): Dictionary containing parameter definition fields.
+    """
+
+    print("       ", f'node_names.push_back("{pname}");')
+    if "subs" in param:
+        for key in param["subs"]:
+            print_code(key, param["subs"][key])
+    else:
+        if param["usage"] == "In" or param["usage"] == "InOut":
+            ptype = param["type"]
+            print(f"        {param_types[ptype]['c_type']} {pname};")
+            if ptype == "BOOL":
+                print(f"        {pname} = {param_types[ptype]['getter']}(node_names, {param['default'].lower()});")
+            else:
+                print(f"        {pname} = {param_types[ptype]['getter']}(node_names, {param['default']});")
+    print("       ", "node_names.pop_back();")
+
+
+def mk_model(
+    ibis_params: ParamDict,
+    ami_params: ParamDict,
+    model_name: str,
+    description: str,
+    out_dir: str = "."
+) -> None:
+    """
+    Generate ibis, ami, and cpp files, by merging the
+    device specific parameterization with the templates.
+
+    Args:
+        ibis_params: Dictionary of IBIS model parameter definitions.
+        ami_params: Dictionary of AMI parameter definitions.
+        model_name: Name given to IBIS model.
+        description: Model description.
+
+    Keyword Args:
+        out_dir: Directory in which to place created files.
+            Default: "."
+    """
+
+    py_file = (Path(out_dir).resolve() / model_name).with_suffix(".py")
+    # Configure the model files.
+    for ext in ["cpp", "ami", "ibs"]:
+        out_file = py_file.with_suffix(f".{ext}")
+        if ext == "ami":
+            em_file = Path(__file__).parent.joinpath("generic.ami.em")
+        elif ext == "ibs":
+            em_file = Path(__file__).parent.joinpath("generic.ibs.em")
+        else:
+            em_file = out_file.with_suffix(".cpp.em")
+
+        print(f"Building '{out_file}' from '{em_file}'...")
+        with open(out_file, "w", encoding="utf-8") as o_file:
+            interpreter = em.Interpreter(
+                output=o_file,
+                globals={
+                    "ami_params": ami_params,
+                    "ibis_params": ibis_params,
+                    "param_types": param_types,
+                    "model_name": model_name,
+                    "description": description,
+                    "date": str(date.today()),
+                },
+            )
+            try:
+                with open(em_file, "rt", encoding="utf-8") as in_file:
+                    interpreter.file(in_file)
+            finally:
+                interpreter.shutdown()
+
+
+def ami_config(py_file):
+    """
+    Read in ``py_file`` and cpp.em files, then generate: ibis, ami, and cpp files.
+
+    Args:
+        py_file: name of model configuration file (<stem>.py)
+
+    Notes:
+        1. This function is deprecated! Instead, make your model configurator executable
+        and import what you need from this module. This is much cleaner.
+    """
+
+    file_base_name = Path(py_file).stem
+
+    # Read model configuration information.
+    print(f"Reading model configuration information from file: {py_file}.")
+    spec = importlib.util.spec_from_file_location(file_base_name, py_file)
+    cfg = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(cfg)
+
+    mk_model(cfg.ibis_params, cfg.ami_params, cfg.kFileBaseName, cfg.kDescription, out_dir=Path(py_file).parent)
+
+
+def mk_combs(dict_items: list[tuple[str, Any]]) -> list[list[tuple[str, Any]]]:
+    """
+    Make all combinations possible from a list of dictionary items.
+
+    Args:
+        dict_items: List of dictionary key/value pairs.
+            The values are lists.
+
+    Return:
+        List of all possible combinations of key values.
+    """
+    if not dict_items:
+        return [
+            [],
+        ]
+    head, *tail = dict_items
+    k, vs = head
+    kvals = [(k, v) for v in vs]
+    return [[kval] + rest for kval in kvals for rest in mk_combs(tail)]
+
+
+def mk_tests(  # pylint: disable=too-many-locals
+    test_defs: dict[str, TestDefinition],
+    file_base_name: str,
+    test_dir: str = "test_runs"
+) -> None:
+    """
+    Make the test run configuration files.
+
+    Args:
+        test_defs: Dictionary of test sweep definitions.
+        file_base_name: Stem name for test run definition files.
+
+    Keyword Args:
+        test_dir: Directory in which to place the created test run definition files.
+            Default: "test_runs/"
+    """
+
+    pname = Path(test_dir).resolve()
+    pname.mkdir(exist_ok=True)
+    pname = (pname / file_base_name).resolve()
+    pname.mkdir(exist_ok=True)
+    for fname in test_defs.keys():
+        desc, ami_defs, sim_defs, ref_fstr = test_defs[fname]
+        ami_str, ami_dict = ami_defs
+        sim_str, sim_dict = sim_defs
+        with open((pname / fname).with_suffix(".run"), "w", encoding="utf-8") as f:
+            f.write(desc + "\n")
+            for ami_comb in mk_combs(list(ami_dict.items())):
+                for sim_comb in mk_combs(list(sim_dict.items())):
+                    pdict = dict(ami_comb)
+                    pdict.update(dict(sim_comb))
+                    f.write(f"\n('{ami_str.format(pdict=pdict)}_{sim_str.format(pdict=pdict)}', \\\n")
+                    f.write(f"  ({{'root_name': '{file_base_name}', \\\n")
+                    for k, v in ami_comb:
+                        f.write(f"    '{k}': {v}, \\\n")
+                    f.write("   }, \\\n")
+                    if sim_comb:
+                        head, *tail = sim_comb
+                        k, v = head
+                        f.write(f"   {{'{k}': {v}, \\\n")
+                        for k, v in tail:
+                            f.write(f"    '{k}': {v}, \\\n")
+                        f.write("   } \\\n")
+                    f.write("  ), \\\n")
+                    if ref_fstr:
+                        f.write(f"  '{ref_fstr.format(pdict=pdict)}', \\\n")
+                    f.write(")\n")
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("py_file", type=click.Path(exists=True, resolve_path=True))
+@click.version_option()
+def main(py_file):
+    """
+    Configure IBIS-AMI model C++ source code, IBIS model, and AMI file.
+    This command generates three files based off the input config file.
+    It expects a .cpp.em file to be located in the same directory so that it can
+    generate a cpp file from the config file and template file.
+
+    Args:
+       py_file: name of model configuration file (*.py)
+
+    Notes:
+        1. This command is deprecated! Instead, make your model configurator executable
+        and import what you need from this module. This is much cleaner.
+    """
+    ami_config(py_file)
+
+
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

pyibisami/ami/generic.ami.em

@@ -0,0 +1,20 @@
+(@model_name
+
+    (Description "@description")
+
+@{
+import sys
+from pyibisami.ami import config as ac
+
+for (sec_name, sec_key) in [('Reserved_Parameters', 'reserved'), ('Model_Specific', 'model')]:
+    print("    (%s" % sec_name)
+    for param_name in ami_params[sec_key]:
+        param = ami_params[sec_key][param_name]
+        try:
+            ac.print_param("        ", param_name, param)
+        except Exception as e:
+            e.args += (param_name,)
+            raise
+    print("    )")
+}
+)

pyibisami/ami/generic.ibs.em

@@ -0,0 +1,139 @@
+@{
+from numpy import array
+
+version           = ibis_params['version']
+file_name         = ibis_params['file_name']
+file_rev          = ibis_params['file_rev']
+copyright         = ibis_params['copyright']
+source            = ibis_params['source']
+component         = ibis_params['component']
+manufacturer      = ibis_params['manufacturer']
+r_pkg             = ibis_params['r_pkg']
+l_pkg             = ibis_params['l_pkg']
+c_pkg             = ibis_params['c_pkg']
+model_name        = ibis_params['model_name']
+model_type        = ibis_params['model_type']
+c_comp            = ibis_params['c_comp']
+c_ref             = ibis_params['c_ref']
+v_ref             = ibis_params['v_ref']
+v_meas            = ibis_params['v_meas']
+r_ref             = ibis_params['r_ref']
+temperature_range = ibis_params['temperature_range']
+voltage_range     = ibis_params['voltage_range']
+impedance         = ibis_params['impedance']
+slew_rate         = ibis_params['slew_rate']
+}
+
+[IBIS Ver]   @(version)
+[File Name]  @(file_name)
+[File Rev]   @(file_rev)
+
+[Date]       @(date)
+
+[Source]     @(source)
+
+[Disclaimer]
+THIS MODEL IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS MODEL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+[Notes]
+This IBIS file was generated using the template file: "generic.ibs.em".
+
+[Copyright]    @(copyright)
+[Component]    @(component)
+[Manufacturer] @(manufacturer)
+
+[Package]
+
+@{
+print("R_pkg    %5.2f    %5.2f    %5.2f"  % (r_pkg[0],         r_pkg[1],         r_pkg[2]))
+print("L_pkg    %5.2fn   %5.2fn   %5.2fn" % (l_pkg[0] * 1.e9,  l_pkg[1] * 1.e9,  l_pkg[2] * 1.e9))
+print("C_pkg    %5.2fp   %5.2fp   %5.2fp" % (c_pkg[0] * 1.e12, c_pkg[1] * 1.e12, c_pkg[2] * 1.e12))
+}
+
+[Pin]  signal_name        model_name            R_pin  L_pin  C_pin
+1p     Tx_1_P             @(model_name)
+1n     Tx_1_N             @(model_name)
+2p     Tx_2_P             @(model_name)
+2n     Tx_2_N             @(model_name)
+3p     Tx_3_P             @(model_name)
+3n     Tx_3_N             @(model_name)
+
+[Diff_Pin] inv_pin vdiff tdelay_typ tdelay_min tdelay_max
+1p           1n     0.1V     NA         NA         NA
+2p           2n     0.1V     NA         NA         NA
+3p           3n     0.1V     NA         NA         NA
+
+[Model]   @(model_name)
+Model_type   @(model_type)
+
+@{
+print("C_comp    %5.2fp   %5.2fp   %5.2fp" % (c_comp[0] * 1.e12, c_comp[1] * 1.e12, c_comp[2] * 1.e12))
+if(model_type == 'Output'):
+    print("Cref  = {}".format(c_ref))
+    print("Vref  = {}".format(v_ref))
+    print("Vmeas = {}".format(v_meas))
+    print("Rref  = {}".format(r_ref))
+else:
+    print("Vinl = {}".format(voltage_range[0] / 2. - 0.025))
+    print("Vinh = {}".format(voltage_range[0] / 2. + 0.025))
+}
+
+[Algorithmic Model]
+Executable linux_gcc4.1.2_32          @(model_name)_x86.so         @(model_name).ami
+Executable linux_gcc4.1.2_64          @(model_name)_x86_amd64.so   @(model_name).ami
+Executable Windows_VisualStudio_32    @(model_name)_x86.dll        @(model_name).ami
+Executable Windows_VisualStudio_64    @(model_name)_x86_amd64.dll  @(model_name).ami
+[End Algorithmic Model]
+
+@{
+print("[Temperature_Range]    %5.1f    %5.1f    %5.1f" % (temperature_range[0], temperature_range[1], temperature_range[2]))
+print("[Voltage_Range]        %5.2f    %5.2f    %5.2f" % (voltage_range[0],     voltage_range[1],     voltage_range[2]))
+}
+
+@{
+if(model_type == 'Output'):
+    print("[Pulldown]")
+    print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (-1. * voltage_range[0], -10., -10., -10.))
+    for v in [k * voltage_range[0] for k in range(2)]:
+        i = v / array(impedance)
+        print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (v, i[0], i[1], i[2]))
+    print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (2. * voltage_range[0], 10., 10., 10.))
+
+    print("[Pullup]")
+    print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (-1. * voltage_range[0], 10., 10., 10.))
+    for v in [k * voltage_range[0] for k in range(2)]:
+        i = -1. * v / array(impedance)
+        print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (v, i[0], i[1], i[2]))
+    print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (2. * voltage_range[0], -10., -10., -10.))
+
+    print("[Ramp]")
+    dv = 0.6 * array([v * 50. / (50. + z) for (v, z) in zip(voltage_range, impedance)])
+    dt = 1.e12 * dv / array(slew_rate)
+    print("dV/dt_r    %5.3f/%5.2fp    %5.3f/%5.2fp    %5.3f/%5.2fp" % (dv[0], dt[0], dv[1], dt[1], dv[2], dt[2]))
+    print("dV/dt_f    %5.3f/%5.2fp    %5.3f/%5.2fp    %5.3f/%5.2fp" % (dv[0], dt[0], dv[1], dt[1], dv[2], dt[2]))
+    print("")
+else:
+    print("[GND Clamp]")
+    print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (-1. * voltage_range[0], -10., -10., -10.))
+    for v in [k * voltage_range[0] for k in range(3)]:
+        i = v / array(impedance) / 2
+        print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (v, i[0], i[1], i[2]))
+    print("")
+    print("[Power Clamp]")
+    print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (-1. * voltage_range[0], 10., 10., 10.))
+    for v in [k * voltage_range[0] for k in range(3)]:
+        i = v / array(impedance) / 2
+        print("%-5.2f    %-10.3e    %-10.3e    %-10.3e" % (v, -i[0], -i[1], -i[2]))
+    print("")
+}
+
+[END]