Symbolic expressions in hls4ml

[vloncar]

Description

This PR adds the ability to generate HLS code to evaluate symbolic expressions in hls4ml for people wanting to play with symbolic regression. It is very simple, it is implemented as a simple backend, leveraging everything from Vivado. The math operations come from hls_math.h. Expression handling itself and producing code is done with SymPy. There are still many things to improve, like the precision handling, accumulator types, using our lookup table-based implementations of math functions etc. But most of the expressions produced by PySR already work.

Type of change

For a new feature or function, please create an issue first to discuss it
with us before submitting a pull request.

Note: Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

Tests

The main function to convert is called convert_from_symbolic_expression, it takes a sympy expression, or a string from which a sympy expression can be built. This can also come from a PySRRegressor. For example:

# Create expression for conversion:
# 1) From PySRRegressor model
model = PySRRegressor(...)
model.fit(...)
expr = model.sympy()
# 2) From string
expr = sympy.parsing.sympy_parser.parse_expr('x0**2 + 2.5*cos(x1) - 0.5')
# 3) Build from sympy symbols
x0, x1 = sympy.symbols('x0 x1')
expr = x0**2 + 2.5*cos(x1) - 0.5
# Convert to hls4ml ModelGraph
hls_model = hls4ml.converters.convert_from_symbolic_expression(expr, n_symbols=2, precision='ap_fixed<x,y>')
# Now it's the usual
hls_model.write()
hls_model.compile()
hls_predictions = hls_model.predict(...)
hls_model.build(...)

Checklist

• I have read the guidelines for contributing.
• I have commented my code, particularly in hard-to-understand areas. - I actually didn't do this
• I have made corresponding changes to the documentation. -> Will come
• My changes generate no new warnings.
• I have added tests that prove my fix is effective or that my feature works. -> Will come

[vloncar]

This is now ready for review. I've added a basic test (we already tested many, many expressions). I am still thinking to add a page in the docs, perhaps as part of a docs PR for the new release. There will also be a notebook added to hls4ml-tutorial repo. Since this introduces a new dependency (sympy) that is rarely used in regular ML, I've added an extra installation target that will install it. For example, doing pip install hls4ml[sr] will include main hls4ml + sympy. Still not sure if pysr should be listed, since one feature is to register LUT functions with it, but in theory, the origin of expressions doesn't have to be PySR (they are just strings).