`converters` local package

Presentation

converters is a local package built to be imported by a component’s Parameter Converter script. While the generic cases are handled in the parent class, each component implementation should have a ParameterConverter class to convert the node’s parameters to its implementation appropriate format. This script is listed in the implementation’s .comp, in generators/libraries. ___

Content

1. `base.py`

This is the base class from which all parameter converters have to inherit. The following generic class methods are generic and do not need to be instantiated for each component:

all_params_present Checks that all parameters from the reference implementation are in the current node.
all_params_consistent Checks that parameters are consistent with the parameter definition (value range, arithmetic type, dimensions if relevant…)

The get_implementation_parameters is a component-specific method. While the Converter parent class in

2. `init.py`

This is the file that sets up the imports and packages. Using CMCore, it looks at the files linked in the component’s generator libraries, and tries to . If that file contains a class called after the component,

Usage

1. Importing the package

For the parameter converter to be able to import the base Converter class, we have to add the common python libraries path to the system’s path first:

import sys
import os
# Set the GAP_SDK_HOME directory
# This assumes that the GAP SDK environment has been sourced. When possible,
# use a path relative to your source file to avoid having to source the
# GAP SDK environment.
gap_sdk_home = pathlib.Path(os.env.get("GAP_SDK_HOME"))
# Set the converters parent directory
converters_dir = gap_sdk_home / "tools/audio-framework/utils"
sys.path.append(converters_dir.as_posix())
from converters import Converter

2. Using the package

Instantiate a Converter class by passing it a CMCore node, to which a valid implementation template has been set:

# Instantiate a CMCore node
my_node = cmcore.Node("my_node")
# Set implementation template
my_node.set_template("fir/gap9_fc_fir/gap9_fc_fir.comp")

# Call FIR converter
my_node_converter = converters.fir(my_node)

Linking the component to its parameter converter library

Each component has to link to its own parameter converter in its component description file. The Audio Mapping Tool will then look through all the files listed in generator['libraries'] for a class that inherit from the base Converter class.

component:
    name: fir
    description_image: fir.png
    generator:
        libraries:
            -   <path/to/parameter/converter.py>

Creating a `parameter_converter` for a component

To create a parameter_converter file for a component, one has to: 1. Create it at the location of the model. 2. Import the converters package 3. Create a class bearing the component’s name and inheriting from converters.Converter 4. Create a method called get_implementation_parameters within that child class, which returns the parameters converted for the appropriate implementation.

Here is a snippet of such a class, for which the content of the get_implementation_parameters method has to be modified.

class my_new_component(base.Converter):
    def get_implementation_parameter(self):
        if not self.all_params_present():
            raise RuntimeError(
                "Not all input parameters are present. Will not be able to convert "
                f"parameters for node {self.name}, "
                f"implementation {implementation_name}."
            )
        if not self.all_params_consistent():
            raise RuntimeError(
                "Inconsistent input parameters. The correct conversion of the "
                f"parameters for node {self.node} "
                f"implementation {implementation_name} cannot be guaranteed."
            )

        match implementation_name:
            case "gap9_sfu_my_new_component":
                # do something
            case "gap9_cluster_my_new_component":
                # do something different
            case "gap9_fc_my_new_component":
                # do something else
            case _:
                raise RuntimeError(
                    f"Unknown implementation: `{implementation_name}` "
                    f"for node {self.name}."
                )
        return parameters

converters local package