Merge pull request #660 from vloncar/sr

Symbolic expressions in hls4ml

Author: jmitrevs

hls4ml/backends/__init__.py

@@ -1,6 +1,7 @@
 from hls4ml.backends.backend import Backend, get_available_backends, get_backend, register_backend  # noqa: F401
 from hls4ml.backends.fpga.fpga_backend import FPGABackend  # noqa: F401
 from hls4ml.backends.quartus.quartus_backend import QuartusBackend
+from hls4ml.backends.symbolic.symbolic_backend import SymbolicExpressionBackend
 from hls4ml.backends.vivado.vivado_backend import VivadoBackend
 from hls4ml.backends.vivado_accelerator.vivado_accelerator_backend import VivadoAcceleratorBackend
 from hls4ml.backends.vivado_accelerator.vivado_accelerator_config import VivadoAcceleratorConfig  # noqa: F401
@@ -11,3 +12,4 @@
 register_backend('VivadoAccelerator', VivadoAcceleratorBackend)
 register_backend('Vitis', VitisBackend)
 register_backend('Quartus', QuartusBackend)
+register_backend('SymbolicExpression', SymbolicExpressionBackend)

hls4ml/backends/symbolic/__init__.py

@@ -0,0 +1,172 @@
+import re
+
+from sympy.core import S
+from sympy.core.numbers import Integer
+from sympy.printing.cxx import CXX11CodePrinter
+
+from hls4ml.backends.template import FunctionCallTemplate, LayerConfigTemplate
+from hls4ml.model.layers import SymbolicExpression
+
+# Expression templates
+
+expr_function_template = 'y[{y_index}] = {expr_str};'
+
+expr_include_list = ['hls_math.h', 'nnet_utils/nnet_math.h']
+
+built_in_luts = ['sin_lut', 'cos_lut']
+
+
+class HLSCodePrinter(CXX11CodePrinter):
+    _ns = 'hls::'
+
+    def __init__(self, layer, lut_functions, use_built_in_luts=False, settings=None):
+        if lut_functions is not None:
+            if use_built_in_luts:
+                # Check if user's LUTs override built-in LUTs
+                for lut_name in lut_functions.keys():
+                    if lut_name in built_in_luts:
+                        print(f'WARNING: User-specified LUT function {lut_name} overrides built-in LUT function.')
+
+            if settings is None:
+                settings = {'user_functions': lut_functions}
+            else:
+                user_functions = settings.get('user_functions', {})
+                user_functions.update(lut_functions)
+                settings['user_functions'] = user_functions
+
+        super().__init__(settings)
+        self.layer = layer
+        self.use_built_in_luts = use_built_in_luts
+
+        for k in (
+            'Abs Sqrt exp exp2 expm1 log log10 log2 log1p Cbrt hypot fma'
+            ' loggamma sin cos tan asin acos atan atan2 sinh cosh tanh asinh acosh '
+            'atanh erf erfc loggamma gamma ceiling floor'
+        ).split():
+            setattr(HLSCodePrinter, '_print_%s' % k, HLSCodePrinter._print_math)
+
+    def _symbol_to_array(self, name):
+        return re.sub(r'([a-zA-Z]+)(\d+)', r'\1[\2]', name)
+
+    def _wrap_with_type_name(self, expr_str):
+        type_name = self.layer.types['result_t'].name
+        return f'{type_name}({expr_str})'
+
+    def _print_Integer(self, expr):
+        int_str = super()._print_Integer(expr)
+        return self._wrap_with_type_name(int_str)
+
+    def _print_Float(self, flt):
+        float_str = super()._print_Float(flt)
+        return self._wrap_with_type_name(float_str)
+
+    def _print_Rational(self, expr):
+        p, q = int(expr.p), int(expr.q)
+        p_q_str = f'{p}.0/{q}.0'
+        return self._wrap_with_type_name(p_q_str)
+
+    def _print_Pow(self, expr):
+        type_name = self.layer.types['result_t'].name
+        type_precision = self.layer.types['result_t'].precision
+        if isinstance(expr.exp, Integer):
+            l_brac, r_brac = ('(', ')') if len(expr.base.args) > 1 else ('', '')
+            if expr.exp > 1:
+                return (
+                    '('
+                    + '*'.join([l_brac + self._symbol_to_array(self._print(expr.base)) + r_brac for _ in range(expr.exp)])
+                    + ')'
+                )
+            elif expr.exp == -1:  # 1/x
+                base = l_brac + self._symbol_to_array(self._print(expr.base)) + r_brac
+                return f'hls::recip<{type_precision.width}, {type_precision.integer}>(({type_name}){base})'
+            else:
+                return super()._print_Pow(expr)
+        else:
+            base = self._print(expr.base)
+            if expr.exp == 0.5:
+                return f'{self._ns}sqrt<{type_precision.width}, {type_precision.integer}>(({type_name})({base}))'
+            elif expr.exp == S.One / 3:
+                return f'{self._ns}cbrt<{type_precision.width}, {type_precision.integer}>(({type_name})({base}))'
+            else:
+                exp = self._print(expr.exp)
+                return f'{self._ns}pow<{type_precision.width}, {type_precision.integer}>(({type_name})({base}), {exp})'
+
+    def _print_math(self, expr):
+        name = self.known_functions[expr.__class__.__name__]
+        if not isinstance(name, str):
+            for cb, fname in name:
+                if cb(*expr.args):
+                    name = fname
+                    break
+            else:
+                raise ValueError("No matching printer")
+
+        # Setting precision of math functions required some rethinking
+        # Doing e.g., hls::pow<x.width, x.iwidth>(x, y) passes C sim, but fails synthesis, need to use hls::pow<16,6>(x,y)
+        type_name = self.layer.types['result_t'].name
+        type_precision = self.layer.types['result_t'].precision
+        template = f'<{type_precision.width}, {type_precision.integer}>'
+        cast = f'({type_name})'
+        args = ', '.join(map(lambda arg: self._print(arg), expr.args))
+
+        if self.use_built_in_luts and name + '_lut' in built_in_luts:
+            ns = 'nnet::'
+            name = name + '_lut'
+            template = f'<{type_name}>'
+        else:
+            ns = self._ns
+
+        return f'{ns}{name}{template}({cast}({args}))'
+
+    def _print_Symbol(self, expr):
+        name = super()._print_Symbol(expr)
+        return self._symbol_to_array(name)
+
+
+class ExpressionFunctionTemplate(FunctionCallTemplate):
+    def __init__(self):
+        super().__init__(SymbolicExpression, include_header=expr_include_list)
+        self.template = expr_function_template
+
+    def format(self, node):
+        params = self._default_function_params(node)
+
+        lut_functions = {lut_fun.name: lut_fun.name for lut_fun in params['lut_functions']}
+        printer = HLSCodePrinter(node, lut_functions=lut_functions, use_built_in_luts=node.attributes['use_built_in_luts'])
+
+        fn_templates = []
+        for i, expr in enumerate(node.attributes['expression']):
+            params['expr_str'] = printer.doprint(expr)
+            params['y_index'] = str(i)
+            fn_templates.append(self.template.format(**params))
+
+        return fn_templates
+
+
+class ExpressionConfigTemplate(LayerConfigTemplate):
+    def __init__(self):
+        super().__init__(SymbolicExpression)
+
+    def format(self, node):
+        params = self._default_config_params(node)
+
+        lut_defs = []
+        for lut_fun in params['lut_functions']:
+            type_name = params['result_t'].name
+            if lut_fun.math_func in ['sinpi', 'cospi', 'sin', 'cos', 'asin', 'acos', 'atan', 'atan2']:
+                # We have return type overrides for these functions
+                namespace = 'nnet::'
+            else:
+                namespace = 'hls::'
+            lut_def = (
+                f'nnet::lookup_table<{type_name}, '
+                f'{lut_fun.table_size}, '
+                f'{namespace}'
+                f'{lut_fun.math_func}> '
+                f'{lut_fun.name}'
+                f'({lut_fun.range_start}, '
+                f'{lut_fun.range_end});'
+            )
+            lut_defs.append(lut_def)
+
+        return '\n'.join(lut_defs)

hls4ml/backends/symbolic/passes/__init__.py

@@ -0,0 +1,37 @@
+from hls4ml.model.layers import SymbolicExpression
+from hls4ml.model.optimizer import ConfigurableOptimizerPass
+
+
+class ValidateUserLookupTable(ConfigurableOptimizerPass):
+    '''Validates the precision of user-defined LUTs is adequate'''
+
+    def __init__(self):
+        self.raise_exception = False
+
+    def match(self, node):
+        return isinstance(node, SymbolicExpression) and len(node.get_attr('lut_functions', [])) > 0
+
+    def transform(self, model, node):
+        precision = node.get_output_variable().type.precision
+        range = 2 ** (precision.integer - precision.signed)
+        frac_step = 1 / 2**precision.fractional
+
+        for lut_fn in node.get_attr('lut_functions'):
+            lut_range = lut_fn.range_end - lut_fn.range_start
+            lut_step = lut_range / lut_fn.table_size
+
+            if lut_step < frac_step:
+                msg = f'LUT function {lut_fn.name} requires more fractional bits.'
+                if self.raise_exception:
+                    raise Exception(msg)
+                else:
+                    print('WARNING:', msg)
+
+            if lut_range > range:
+                msg = f'LUT function {lut_fn.name} requires more integer bits.'
+                if self.raise_exception:
+                    raise Exception(msg)
+                else:
+                    print('WARNING:', msg)
+
+        return False

hls4ml/backends/symbolic/passes/expr_templates.py

@@ -0,0 +1,104 @@
+import os
+import sys
+
+from hls4ml.backends import FPGABackend
+from hls4ml.model.flow import register_flow
+from hls4ml.report import parse_vivado_report
+
+
+class SymbolicExpressionBackend(FPGABackend):
+    def __init__(self):
+        super().__init__('SymbolicExpression')
+        self._register_flows()
+
+    def _register_flows(self):
+        vivado_types = [
+            'vivado:transform_types',
+        ]
+        vivado_types_flow = register_flow('specific_types', vivado_types, requires=None, backend=self.name)
+
+        validation_passes = [
+            'symbolicexpression:validate_user_lookup_table',
+        ]
+        validation_flow = register_flow('validation', validation_passes, requires=None, backend=self.name)
+
+        template_flow = register_flow('apply_templates', self._get_layer_templates, requires=None, backend=self.name)
+
+        writer_passes = ['make_stamp', 'symbolicexpression:write_hls']
+        self._writer_flow = register_flow('write', writer_passes, requires=['vivado:ip'], backend=self.name)
+
+        ip_flow_requirements = [vivado_types_flow, validation_flow, template_flow]
+        ip_flow_requirements = list(filter(None, ip_flow_requirements))
+
+        self._default_flow = register_flow('ip', None, requires=ip_flow_requirements, backend=self.name)
+
+    def get_default_flow(self):
+        return self._default_flow
+
+    def get_writer_flow(self):
+        return self._writer_flow
+
+    def create_initial_config(
+        self,
+        part='xcvu9p-flga2577-2-e',
+        clock_period=5,
+        io_type='io_parallel',
+        compiler='vivado_hls',
+        hls_include_path=None,
+        hls_libs_path=None,
+    ):
+        config = {}
+
+        config['Part'] = part if part is not None else 'xcvu9p-flga2577-2-e'
+        config['ClockPeriod'] = clock_period
+        config['IOType'] = io_type
+        config['Compiler'] = compiler if compiler is not None else 'vivado_hls'
+        if not all([hls_include_path, hls_libs_path]):
+            # Try to infer the include path from Vivado path
+            bin_path = os.popen(f'command -v {compiler}').read().strip()
+            if hls_include_path is None:
+                hls_include_path = bin_path.replace(f'/bin/{compiler}', '/include')
+                if not os.path.exists(hls_include_path + '/hls_math.h'):
+                    raise Exception(
+                        'Vivado HLS header files not found. Make sure you pass the proper path '
+                        'to the "include" directory (for example "/opt/Xilinx/Vivado/2020.1/include").'
+                    )
+            elif hls_include_path == '':
+                print(
+                    'No HLS include path provided, using HLS math functions from Python (i.e., predict()) will not work. '
+                    'Consider using only LUT approximations.'
+                )
+            if hls_libs_path is None:
+                hls_libs_path = bin_path.replace(f'/bin/{compiler}', '/lnx64')
+                if not os.path.exists(hls_libs_path + '/lib/csim/libhlsmc++-GCC46.so'):
+                    raise Exception(
+                        'Vivado HLS libraries not found. Make sure you pass the proper path '
+                        'to the "lnx64" directory (for example "/opt/Xilinx/Vivado/2020.1/lnx64").'
+                    )
+        config['HLSIncludePath'] = hls_include_path
+        config['HLSLibsPath'] = hls_libs_path
+        config['HLSConfig'] = {}
+
+        return config
+
+    def build(self, model, reset=False, csim=True, synth=True, cosim=False, validation=False, export=False, vsynth=False):
+        if 'linux' in sys.platform:
+            found = os.system('command -v vivado_hls > /dev/null')
+            if found != 0:
+                raise Exception('Vivado HLS installation not found. Make sure "vivado_hls" is on PATH.')
+
+        curr_dir = os.getcwd()
+        os.chdir(model.config.get_output_dir())
+        vivado_cmd = (
+            f'vivado_hls -f build_prj.tcl "reset={reset} '
+            f'csim={csim} '
+            f'synth={synth} '
+            f'cosim={cosim} '
+            f'validation={validation} '
+            f'export={export} '
+            f'vsynth={vsynth}"'
+        )
+        os.system(vivado_cmd)
+        os.chdir(curr_dir)
+
+        return parse_vivado_report(model.config.get_output_dir())