pyibisami.ami

AMI related submodules in the PyIBIS-AMI package.

config

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.

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 insure consistency this way.)

This gets triggered by one of two things:

  1. The common model configuration information has changed, or

  2. 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.

pyibisami.ami.config.ami_config(py_file)[source]

Read in the py_file and cpp.em files, then generate: ibis, ami, and cpp files.

pyibisami.ami.config.mk_combs(dict_items)[source]

Make all combinations possible from a list of dictionary items.

Parameters:

dict_items ([(str, [T])]) – List of dictionary key/value pairs. The values are lists.

Returns:

List of all possible combinations of key values.

Return type:

[[(str, T)]]

pyibisami.ami.config.mk_model(ibis_params, ami_params, model_name, description, out_dir='.')[source]

Generate ibis, ami, and cpp files, by merging the device specific parameterization with the templates.

pyibisami.ami.config.mk_tests(test_defs, file_base_name, test_dir='test_runs')[source]

Make the test run configuration files.

pyibisami.ami.config.print_code(pname, param)[source]

Print C++ code needed to query AMI parameter tree for a particular leaf.

Parameters:

  • pname (str) – Parameter name.

  • param (dict) – Dictionary containing parameter definition fields.

pyibisami.ami.config.print_param(indent, name, param)[source]

Print AMI parameter specification. Handle nested parameters, via recursion.

Parameters:

  • indent (str) – String containing some number of spaces.

  • name (str) – Parameter name.

  • param (dict) – Dictionary containing parameter definition fields.

model

parameter

AMIParameter class definition, plus some helpers.

Original author: David Banas <capn.freako@gmail.com>

Original date: December 24, 2016

Copyright (c) 2019 David Banas; all rights reserved World wide.

exception pyibisami.ami.parameter.AMIParamError[source]

Bases: Exception

Base Exception for all AMI Parameter Errors.

class pyibisami.ami.parameter.AMIParameter(name, tags)[source]

Bases: object

IBIS-AMI model parameter.

This class encapsulates the attributes and behavior of a AMI parameter.

Parameters:

  • name (str) – The name of the AMI parameter being created.

  • tags ([(str, [a])]) –

    A list of pairs, each containing:

    • a parameter definition tag name

      (Must be one of the keys from the ‘_param_def_tag_procs’ dictionary.)

    • a list of values to be associated with that tag.

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']
property msg

Any warning messages encountered, during parameter initialization.

property pdefault

Default value of AMI parameter.

property pdescription

Description of AMI parameter.

property pformat

Value of AMI parameter ‘Format’ tag.

property plist_tip

List tips of AMI parameter.

property pmax

Maximum value of AMI parameter.

property pmin

Minimum value of AMI parameter.

property pname

Name of AMI parameter.

property ptype

Value of AMI parameter ‘Type’ tag.

property pusage

Value of AMI parameter ‘Usage’ tag.

property pvalue

Value of AMI parameter.

parser

IBIS-AMI parameter parsing and configuration utilities.

Original author: David Banas <capn.freako@gmail.com>

Original date: December 17, 2016

Copyright (c) 2019 David Banas; all rights reserved World wide.

class pyibisami.ami.parser.AMIParamConfigurator(*args: Any, **kwargs: Any)[source]

Bases: HasTraits

Customizable IBIS-AMI model parameter configurator.

This class can be configured to present a customized GUI to the user for configuring a particular IBIS-AMI model.

The intended use model is as follows:

  1. Instantiate this class only once per IBIS-AMI model invocation. When instantiating, provide the unprocessed contents of the AMI file, as a single string. This class will take care of getting that string parsed properly, and report any errors or warnings it encounters, in its ami_parsing_errors property.

  2. When you want to let the user change the AMI parameter configuration, call the open_gui member function. (Or, just call the instance as if it were executable.) The instance will then present a GUI to the user, allowing him to modify the values of any In or InOut parameters. The resultant AMI parameter dictionary, suitable for passing into the ami_params parameter of the AMIModelInitializer constructor, can be accessed, via the instance’s input_ami_params property. The latest user selections will be remembered, as long as the instance remains in scope.

The entire AMI parameter definition dictionary, which should not be passed to the AMIModelInitializer constructor, is available in the instance’s ami_param_defs property.

Any errors or warnings encountered while parsing are available, in the ami_parsing_errors property.

Parameters:

ami_file_contents_str (str) – The unprocessed contents of the AMI file, as a single string.

property ami_param_defs

The entire AMI parameter definition dictionary.

Should not be passed to AMIModelInitializer constructor!

property ami_parsing_errors

Any errors or warnings encountered, while parsing the AMI parameter definition file contents.

fetch_param(branch_names)[source]

Returns the parameter found by traversing ‘branch_names’ or None if not found.

Note: ‘branch_names’ should not begin with ‘root_name’.

fetch_param_val(branch_names)[source]

Returns the value of the parameter found by traversing ‘branch_names’ or None if not found.

Note: ‘branch_names’ should not begin with ‘root_name’.

input_ami_param(params, pname)[source]

Retrieve one AMI parameter, or dictionary of subparameters.

property input_ami_params

The dictionary of Model Specific AMI parameters of type ‘In’ or ‘InOut’, along with their user selected values.

Should be passed to AMIModelInitializer constructor.

open_gui()[source]

Present a customized GUI to the user, for parameter customization.

set_param_val(branch_names, new_val)[source]

Sets the value of the parameter found by traversing ‘branch_names’ or raises an exception if not found.

Note: ‘branch_names’ should not begin with ‘root_name’. Note: Be careful! There is no checking done here!

pyibisami.ami.parser.int2tap(x)[source]

Convert integer to tap position.

pyibisami.ami.parser.lexeme(p)[source]

Lexer for words.

pyibisami.ami.parser.make_gui_items(pname, param, first_call=False)[source]

Builds list of GUI items from AMI parameter dictionary.

pyibisami.ami.parser.parse_ami_param_defs(param_str)[source]

Parse the contents of a IBIS-AMI parameter definition file.

Parameters:

param_str (str) – 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)
Returns:

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.

Return type:

(str, dict)

pyibisami.ami.parser.proc_branch(branch)[source]

Process a branch in a AMI parameter definition tree.

That is, build a dictionary from a pair containing:

  • a parameter name, and

  • a list of either:

    • parameter definition tags, or

    • subparameters.

We distinguish between the two possible kinds of payloads, by peaking at the names of the first two items in the list and noting whether they are keys of ‘AMIParameter._param_def_tag_procs’. We have to do this twice, due to the dual use of the ‘Description’ tag and the fact that we have no guarantee of any particular ordering of subparameter branch items.

Parameters:

p (str, list) – A pair, as described above.

Returns:

A pair containing:

err_str:

String containing any errors or warnings encountered, while building the parameter dictionary.

param_dict:

Resultant parameter dictionary.

Return type:

(str, dict)